StaleTime class sealed

How long fetched data counts as fresh — the staleTime option.

Fresh data is served from the cache without a fetch; stale data is still served, but a refetch trigger (a new observer mounting, the app regaining focus, the network coming back, an invalidation) fetches it again.

Like every option value in this package, a stale time is a const sealed value rather than a number or a magic string. Dart has no union types, so each option that TanStack Query types as number | 'static' | function is a small sealed family here. An option field left null means "not configured" and takes the client's default; "off" is always a value of its own (StaleTime.zero, RetryPolicy.never, RefetchInterval.off), never a null.

Default: StaleTime.zero — data is stale the moment it arrives.

The variants:

staleTime: StaleTime.zero                                // the default
staleTime: const StaleTime.duration(Duration(minutes: 5)) // fresh 5 min
staleTime: StaleTime.infinite  // never stale by time; invalidation works
staleTime: StaleTime.static    // never stale, never refetched by triggers
staleTime: StaleTime.dynamic(
  (query) => query.state.data == null
      ? StaleTime.zero
      : const StaleTime.duration(Duration(minutes: 1)),
)

A switch over a resolved value covers StaleTimeDuration, StaleTimeStatic, StaleTimeInfinite and StaleTimeDynamic.

Annotations

• @immutable

Constructors

StaleTime.duration(Duration duration)

Fresh for duration after the fetch that produced the data (TanStack Query: staleTime: ms).

const

factory

StaleTime.dynamic(StaleTime compute(Query<Object?> query))

Computed per query, from its current state (TanStack Query: staleTime: (query) => …).

const

factory

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

isStaticFor(Query<Object?> query) → bool

Whether this resolves to StaleTime.static for query — the one thing that separates it from StaleTime.infinite: a static query is skipped by refetchQueries and by every refetch trigger, and outranks an invalidation.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

resolve(Query<Object?> query) → Duration?

Resolves this to a plain duration for query. null means "never stale by time", which both StaleTime.static and StaleTime.infinite are.

resolveFor(Query<Object?> query) → StaleTime

This with any StaleTime.dynamic layer peeled off for query, so the result is one of StaleTimeDuration, StaleTimeStatic or StaleTimeInfinite.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Constants

infinite → const StaleTime

Never stale by time, but still refetched when asked — by an invalidation or an explicit refetch (TanStack Query: staleTime: Infinity, which has no Duration equivalent).

static → const StaleTime

Never stale and, while an observer holds the query, never refetched by any trigger (TanStack Query: staleTime: 'static').

zero → const StaleTime

Stale the moment it arrives — the default (TanStack Query: staleTime: 0).