nextExpiresAt method

  1. @override
Future<DateTime?> nextExpiresAt()
override

Smallest non-null expiry instant across all entries, or null if no entry has one set. Drives expiry-cron wake-up: a caller can sleep until the returned time, then call peekExpired or deleteExpiredKeys to drain.

The returned instant may be in the past (there are already-expired keys awaiting a sweep); callers driving a timer should clamp to max(returned, now).

Snapshot semantics: best-effort with respect to concurrent mutations — the returned value reflects state at some point during the call, with no serialisation guarantee.

MUST be O(1)-or-better than a full-store scan on any backend bundled with this package (Hive backends answer from an in-memory expiry index; SQL backends index the expiry column and answer with SELECT MIN(...)).

Implementation

@override
Future<DateTime?> nextExpiresAt() async {
  DateTime? min;
  for (final expiry in _expiryIndex.values) {
    if (min == null || expiry.isBefore(min)) min = expiry;
  }
  return min;
}