nextExpiresAt method

  1. @override
  2. @server
  3. @client
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
@server
@client
Future<DateTime?> nextExpiresAt() async {
  DateTime? min;
  for (final fields in _expiryKeysCache.values) {
    final exp = fields[expiresAt];
    if (exp == null) continue;
    if (min == null || exp.isBefore(min)) min = exp;
  }
  return min;
}