deadline_future library

deadline_future β€” Graceful deadline handling for Dart Futures.

Instead of crashing with TimeoutException, this package provides a three-tier fallback strategy:

  1. Live result β€” Future completed before the deadline. βœ…
  2. Cached result β€” Timeout hit, but a previous successful value is available in the built-in smart cache. πŸ’Ύ
  3. Static fallback β€” Timeout hit, cache empty, use a user-supplied default value. πŸ›‘οΈ

If none of the above apply, a DeadlineExceededException is thrown β€” never a raw TimeoutException.

Quick start

import 'package:deadline_future/deadline_future.dart';

final result = await fetchBtcPrice().withDeadline(
  const Duration(seconds: 2),
  fallback: 65_000.0,
  cacheKey: 'btc_price',
  cacheTtl: const Duration(minutes: 5),
  onTimeout: () => print('⚠️  deadline hit β€” using fallback/cache'),
  context: 'BTC price widget',
);

if (result.isDegraded) {
  showStaleIndicator();   // data came from cache or fallback
}
displayPrice(result.value); // always has a value β€” never crashes

Global configuration (call once at app start)

DeadlineConfig.enableGlobalCache = true;
DeadlineConfig.defaultCacheTtl  = const Duration(minutes: 10);
DeadlineConfig.logLevel          = DeadlineLogLevel.info;

Classes

DeadlineConfig
Global configuration for the deadline_future package.
DeadlineResult<T>
An immutable container returned by Future.withDeadline.

Enums

DeadlineLogLevel
Controls how much information deadline_future prints to stdout.
DeadlineResultSource
Describes where the resolved value inside a DeadlineResult came from.

Extensions

DeadlineDuration on int
Concise Duration constructors on int.
DeadlineFutureExtension on Future<T>
Core extension that adds deadline-aware resolution to any Future<T>.
DeadlineFutureListExtension on List<Future<T>>
Applies withDeadline to every element of a List<Future<T>> with a shared deadline and configuration.

Exceptions / Errors

DeadlineCacheException
Thrown when an internal cache operation fails unexpectedly.
DeadlineExceededException
Thrown when the deadline elapsed and neither a cached value nor a static fallback was available to satisfy the call.
DeadlineFutureException
Base class for all exceptions thrown by deadline_future.
InvalidDeadlineDurationException
Thrown synchronously when the deadline Duration passed to withDeadline is zero or negative.