deadline_future 🏁 #

A time-bounded Future that never throws TimeoutException.
Returns the freshest data available — live, cached, or a static fallback — instead of crashing.

The Problem #

// ❌ Dart's built-in Future.timeout — "all or nothing"
try {
  final price = await fetchPrice().timeout(const Duration(seconds: 2));
} on TimeoutException {
  // The result was discarded even if it arrived 1ms later.
  // You must handle the exception every single time.
}

In real-time apps this is painful: every slow network spike crashes the UI, every late response is wasted, and you have no visibility into why the fallback was used.

The Solution #

// ✅ deadline_future — three-tier graceful fallback
final result = await fetchPrice().withDeadline(
  const Duration(seconds: 2),
  fallback: lastKnownPrice,      // 🛡️ tier 3: static safety net
  cacheKey: 'btc_price',         // 💾 tier 2: automatic smart cache
  cacheTtl: const Duration(minutes: 5),
  onTimeout: () => showSpinner(), // called the moment deadline hits
  context: 'BTC price widget',   // appears in logs & exceptions
);

// result is ALWAYS available — never null, never an exception
switch (result.source) {
  case DeadlineResultSource.completed:
    print('✅ Live  — ${result.actualDuration!.inMilliseconds}ms');
  case DeadlineResultSource.cached:
    print('💾 Cached — showing last known value');
  case DeadlineResultSource.fallback:
    print('🛡️  Fallback — network is struggling');
}

if (result.isDegraded) showStaleBadge(); // one-liner UI indicator
updatePrice(result.value);               // always works

Resolution Strategy #

withDeadline(deadline, fallback: F, cacheKey: K)
          │
          ├─ Future completes in time?      → ✅ live result
          │                                    (stored in cache for next time)
          │
          ├─ Timeout + cache[K] valid?      → 💾 cached result
          │
          ├─ Timeout + F != null?           → 🛡️  fallback result
          │
          └─ Timeout + nothing available?   → 🔴 DeadlineExceededException

Self-healing cache: even after a timeout, the original Future keeps running. When it finally completes, its value is stored in the cache — automatically improving the next call.

Installation #

dependencies:
  deadline_future: ^0.1.0

dart pub get

Quick-start Recipes #

Minimal — static fallback only #

final result = await fetchUserProfile().withDeadline(
  const Duration(seconds: 2),
  fallback: UserProfile.guest(),
);
print(result.value.displayName); // always available

Smart cache — best for repeated calls #

// First call: Future wins → cached.
await fetchBtcPrice().withDeadline(
  const Duration(seconds: 2),
  cacheKey: 'btc',
  cacheTtl: const Duration(minutes: 5),
);

// Second call: network degraded → served from cache.
final r = await fetchBtcPrice().withDeadline(
  const Duration(milliseconds: 300),
  cacheKey: 'btc',
  fallback: 0.0,
);

Duration shorthand #

// Clean, readable deadlines:
await fetch().withDeadline(3.seconds);
await fetch().withDeadline(500.milliseconds);
await fetch().withDeadline(2.minutes);

Batch concurrent calls #

final results = await [fetchBtc(), fetchEth(), fetchSol()]
    .withDeadlineAll(
      const Duration(milliseconds: 500),
      cacheKeys: ['btc', 'eth', 'sol'],
      fallback: 0.0,
      onTimeout: (i) => print('Feed $i timed out'),
    );

Exception handling #

try {
  await myFuture.withDeadline(const Duration(seconds: 1));
} on DeadlineExceededException catch (e) {
  // Only thrown when NO cache entry AND NO fallback exist.
  print('Exceeded ${e.deadline.inMilliseconds}ms — ${e.context}');
} on InvalidDeadlineDurationException {
  // Synchronous guard against Duration.zero / negative values.
}

Global configuration (app startup) #

void main() {
  DeadlineConfig.enableGlobalCache = true;
  DeadlineConfig.defaultCacheTtl   = const Duration(minutes: 10);
  DeadlineConfig.maxCacheEntries   = 500;
  DeadlineConfig.logLevel          = kDebugMode
      ? DeadlineLogLevel.info
      : DeadlineLogLevel.silent;
  runApp(const MyApp());
}

API Reference #

Future<T>.withDeadline() #

Returns: Future<DeadlineResult<T>>

DeadlineResult<T> #

DeadlineConfig (static) #

Comparison Table #

* Only thrown as a last resort — cache and fallback are checked first.

Ideal Use Cases #

• 📈 Crypto / stock price feeds — show last known price while refreshing
• 💬 Chat heads — display cached messages while server is slow
• 📊 Live dashboards — partial data is better than blank panels
• 🏟️ Sports scores — stale score with "updating..." badge
• 🔄 Retry wrappers — compose with withDeadline for per-attempt limits
• 🌐 Any API call where "stale but available" beats "fresh but crashed"

Testing #

dart test

Run the examples:

dart run example/main.dart

Run the benchmarks:

dart run benchmark/throughput_bench.dart

License #

BSD-3-Clause © 2026 deadline_future contributors