Auth Query Lifecycle Management#

Primary modules: client/session-atom.ts · client/query.ts

This subsystem manages client-side authentication state using nanostores atoms. It handles four interrelated concerns: race condition prevention, duplicate-fetch deduplication, zombie subscription cleanup after unmount-remount cycles, and stable reference preservation to avoid spurious re-renders.

Core Types#

AuthQueryState<T> is the shape of every auth query atom's value:

useAuthQuery is the generic atom factory for non-session queries. The session-specific variant is getSessionAtom(), which has a richer deduplication model built on top of useAuthQuery's primitives.

Single Atom-Owned Session Fetch Architecture#

PR #8760 established that the session atom is the sole writer of session state. The refresh manager (session-refresh.ts) acts only as a trigger coordinator, calling fetchSession() but never directly mutating atom state. This eliminates write conflicts between concurrent code paths.

getSessionAtom() initializes the atom with isPending: true and creates a $signal atom for external notifications. Each $signal emission increments sessionRevision and zeroes freshUntil 1, forcing the next mount to revalidate.

Race Condition Prevention: SessionFlight Deduplication#

fetchSession() tracks in-flight requests via a module-level SessionFlight object 2:

type SessionFlight = {
  cancel: () => void;
  promise: Promise<SessionFetchOutcome>;
  revision: number;
};

Every call to fetchSession() cancels the current flight (flight?.cancel()) and creates a new AbortController 3. After settlement, settleFlight() no-ops if flight !== request — preventing stale closures from overwriting state 4.

fetchSessionOnMount() applies two guards before starting a new fetch:

1. In-flight reuse — if flight.revision === sessionRevision, the mount joins the existing promise instead of starting a new request. This handles React Suspense retries that fire multiple concurrent mounts (PR #10676, PR #10769) 5.
2. Freshness window — after a successful fetch, freshUntil is set to min(now + SESSION_MOUNT_DEDUPE_INTERVAL, sessionExpiry). Mounts within this window resolve immediately without a network call 6. SESSION_MOUNT_DEDUPE_INTERVAL is aligned to nanostores' STORE_UNMOUNT_DELAY 7.

Inside executeSessionFetch(), signal.aborted is rechecked after every await point 8. If needsRefresh is set on the initial GET response, a follow-up POST /get-session is issued on the same signal 9.

Zombie Atom Cleanup: useAuthQuery Mount Guard#

useAuthQuery's onMount callback manages three flags to prevent zombie subscriptions and duplicate fetches across unmount-remount cycles 10:

• isMounted — set true on mount, false in cleanup. Guards post-unmount state writes.
• isInitialized — local to each mount cycle. The first initAtom listener notification sets this and calls fetchOnMount(); subsequent notifications call fn() directly. A setTimeout(..., 0) fallback sets it if no listener fires 11. This is the pattern from PR #9078 that prevents mount-storm fetches.
• isMountFetchPending / shouldRefetchAfterPending — if a mount fetch is running when a remount occurs, the refetch is queued as shouldRefetchAfterPending = true and fired after the current fetch settles 12. PR #10379 introduced this to fix the "permanently stale after one unmount" regression reported in #10363.

The cleanup return 13 sets isMounted = false, cancels the timeout, and removes all initAtom listener subscriptions, preventing stale subscriptions from accumulating.

Stable Reference Preservation & Equality Gating#

Two mechanisms prevent spurious re-renders:

1. Stable data reference — on success, both useAuthQuery 14 and executeSessionFetch 15 use isJsonEqual() to compare the new response to the current atom value. If deeply equal, the existing object reference is reused.

2. Equality-gated atom writes — withEquality() hooks into nanostores' onSet event. If the new AuthQueryState is structurally equivalent to the current value (via isSessionAtomEqual or isAuthQueryStateEqual), the write is aborted and no listeners fire 16 17. For useAuthQuery, withEquality is registered inside onMount so it is tied to the active-subscriber lifetime 18.

Error Handling Semantics#

$sessionSignal and Request Storms#

$sessionSignal ($signal) is a nanostores atom<boolean> that external callers (sign-in, sign-out, user update) toggle to notify the session atom of changes. Each emission increments sessionRevision and zeroes freshUntil, ensuring revalidation on the next mount 1.

A known issue (#11160) is that rapid $sessionSignal emissions have no damping: each triggers fetchSession(), which cancels the in-flight request and issues a new one, producing a burst of aborted requests. The freshUntil freshness window mitigates this only after the first settled fetch.

Key Source Files#

Key PRs#