@kontsedal/olas-core 0.0.6 → 0.1.0

package/src/query/entry.ts

@@ -1,7 +1,8 @@
 import { batch, type Signal, signal } from '../signals'
 import { abortableSleep, isAbortError } from '../utils'
+import { subscribeReconnect } from './focus-online'
 import { structuralShare } from './structural-share'
-import type { AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
+import type { AsyncStatus, NetworkMode, RetryDelay, RetryPolicy, Snapshot } from './types'
 
 export type EntryEvents = {
   onFetchStart?: () => void
@@ -16,6 +17,8 @@ export type EntryOptions<T> = {
   initialUpdatedAt?: number | undefined
   retry?: RetryPolicy
   retryDelay?: RetryDelay
+  networkMode?: NetworkMode
+  structuralShare?: boolean
   events?: EntryEvents
   /**
    * Fired after a successful fetch result is written to `data`. Used by the
@@ -55,17 +58,37 @@ export class Entry<T> {
   readonly lastUpdatedAt: Signal<number | undefined>
   readonly hasPendingMutations: Signal<boolean> = signal(false)
   readonly isStale: Signal<boolean> = signal(true)
+  /** True while a fetch is parked waiting for reconnect (online-mode defer or
+   *  offlineFirst network-error park). See spec §5.5, T3.5. */
+  readonly isPaused: Signal<boolean> = signal(false)
 
   fetcherProvider: () => (signal: AbortSignal) => Promise<T>
   private staleTime: number
   private retry: RetryPolicy
-  private retryDelay: RetryDelay
+  private retryDelay: RetryDelay | undefined
+  private networkMode: NetworkMode
+  private structuralShareEnabled: boolean
   private currentFetchId = 0
   private currentAbort: AbortController | null = null
   private staleTimer: ReturnType<typeof setTimeout> | null = null
+  /** Set by `markStale()` (invalidate without fetch); forces `isStaleNow()`
+   *  true until the next successful fetch clears it. Spec §5.7, T3.9. */
+  private forcedStale = false
   private snapshots: Array<SnapshotRecord<T>> = []
   private nextSnapshotId = 0
   private disposed = false
+  /** Subscribers to reconnect — installed lazily when a deferred fetch lands. */
+  private reconnectUnsub: (() => void) | null = null
+  /**
+   * Set of deferred-fetch resolvers waiting for reconnect (online mode).
+   * Stored at `unknown` to keep `Entry<T>` covariant in `T` — same trick as
+   * `onSuccessData`. Each resolver is fed the same value from
+   * `applySuccess`, which is `T`, then cast at the fan-out call site.
+   */
+  private deferredResolvers: Array<{
+    resolve: (value: unknown) => void
+    reject: (reason?: unknown) => void
+  }> = []
   private readonly events: EntryEvents
   // Stored at `unknown` (not `T`) to keep `Entry<T>` covariant in `T`. The
   // callback only forwards the value through; Entry never inspects it.
@@ -82,7 +105,11 @@ export class Entry<T> {
     this.fetcherProvider = options.fetcher
     this.staleTime = options.staleTime ?? 0
     this.retry = options.retry ?? 0
-    this.retryDelay = options.retryDelay ?? 1000
+    // Left undefined when not given so `computeDelay` can pick the exponential
+    // default only when retries are actually enabled (T3.9).
+    this.retryDelay = options.retryDelay
+    this.networkMode = options.networkMode ?? 'online'
+    this.structuralShareEnabled = options.structuralShare ?? true
     this.events = options.events ?? {}
     this.onSuccessData = options.onSuccessData as ((data: unknown) => void) | undefined
     this.data = signal<T | undefined>(options.initialData)
@@ -119,6 +146,13 @@ export class Entry<T> {
     if (this.disposed) {
       return Promise.reject(new Error('Entry disposed'))
     }
+    // `online` mode: defer until reconnect when the browser thinks we're
+    // offline. Don't touch status — the UI keeps showing last-known data.
+    // `always` / `offlineFirst` proceed to the fetcher; `offlineFirst` will
+    // re-handle a network rejection inside the catch path.
+    if (this.networkMode === 'online' && this.isOffline()) {
+      return this.scheduleDeferredFetch()
+    }
     const myId = ++this.currentFetchId
     this.currentAbort?.abort()
     const abort = new AbortController()
@@ -129,6 +163,7 @@ export class Entry<T> {
       this.status.set('pending')
       this.isFetching.set(true)
       this.isLoading.set(!previouslyHadData)
+      this.isPaused.set(false)
     })
 
     this.fetchStartTime = Date.now()
@@ -141,6 +176,49 @@ export class Entry<T> {
     return this.runWithRetry(myId, abort)
   }
 
+  private isOffline(): boolean {
+    return typeof navigator !== 'undefined' && navigator.onLine === false
+  }
+
+  private scheduleDeferredFetch(): Promise<T> {
+    // Parked waiting for reconnect — surface it so the UI can show "waiting
+    // for network" instead of a silent `idle` (T3.5). Cleared when the fetch
+    // actually starts (`startFetch` batch) or settles.
+    this.isPaused.set(true)
+    // Lazy-install one reconnect listener for the entry. Cleared on dispose
+    // and on the first successful drain. Each call appends a fresh resolver.
+    if (this.reconnectUnsub === null) {
+      this.reconnectUnsub = subscribeReconnect(() => this.drainDeferred())
+    }
+    return new Promise<T>((resolve, reject) => {
+      this.deferredResolvers.push({
+        resolve: resolve as (value: unknown) => void,
+        reject,
+      })
+    })
+  }
+
+  private drainDeferred(): void {
+    if (this.deferredResolvers.length === 0) return
+    if (this.disposed) return
+    const pending = this.deferredResolvers
+    this.deferredResolvers = []
+    // One real fetch fans out to every pending resolver. Tearing down the
+    // reconnect listener avoids accumulating listeners across many deferrals.
+    if (this.reconnectUnsub !== null) {
+      this.reconnectUnsub()
+      this.reconnectUnsub = null
+    }
+    this.startFetch().then(
+      (value) => {
+        for (const p of pending) p.resolve(value)
+      },
+      (err) => {
+        for (const p of pending) p.reject(err)
+      },
+    )
+  }
+
   private async runWithRetry(myId: number, abort: AbortController): Promise<T> {
     let attempt = 0
     while (true) {
@@ -158,6 +236,18 @@ export class Entry<T> {
         if (myId !== this.currentFetchId || this.disposed || isAbortError(err)) {
           throw err
         }
+        // offlineFirst: a network-shaped failure while offline parks the entry
+        // (wait for reconnect, then retry) instead of surfacing the error. A
+        // `fetch()` network failure surfaces as a `TypeError`; `AbortError` is
+        // already handled above. Spec §5.5, T3.5.
+        if (this.networkMode === 'offlineFirst' && this.isOffline() && err instanceof TypeError) {
+          batch(() => {
+            this.isFetching.set(false)
+            this.isLoading.set(false)
+            this.status.set(this.data.peek() !== undefined ? 'success' : 'idle')
+          })
+          return this.scheduleDeferredFetch()
+        }
         if (!this.shouldRetry(attempt, err)) {
           return this.applyFailure(err)
         }
@@ -177,6 +267,10 @@ export class Entry<T> {
 
   private computeDelay(attempt: number): number {
     const d = this.retryDelay
+    // Default to exponential backoff (capped at 30s) when `retry > 0` but no
+    // `retryDelay` was given — a constant 1s default hammered a flapping
+    // backend on every attempt (T3.9). Explicit number/function still wins.
+    if (d === undefined) return Math.min(1000 * 2 ** attempt, 30_000)
     return typeof d === 'function' ? d(attempt) : d
   }
 
@@ -184,9 +278,20 @@ export class Entry<T> {
     // Structurally share with the previous value so unchanged sub-trees
     // keep their `===` identity. Downstream `computed`s and React snapshots
     // stop thrashing on no-op refetches. Bails on Maps/Sets/class instances
-    // — see `structural-share.ts`.
+    // — see `structural-share.ts`. Disabled per-query via `structuralShare:
+    // false` for large payloads where the O(payload) walk costs more than
+    // the re-render savings.
     const prev = this.data.peek() as T | undefined
-    const shared = prev === undefined ? result : structuralShare(prev, result)
+    const shared =
+      prev === undefined || !this.structuralShareEnabled ? result : structuralShare(prev, result)
+    // Rebase live optimistic snapshots onto the fresh server truth: a
+    // subsequent rollback should restore to THIS value, not the pre-fetch
+    // baseline the snapshot captured before the fetch resolved. Without this,
+    // a fetch landing during an optimistic mutation, then that mutation
+    // failing, resurrects pre-fetch data (spec §6.4, T3.4).
+    if (this.snapshots.length > 0) {
+      for (const s of this.snapshots) s.prev = shared
+    }
     batch(() => {
       this.data.set(shared)
       this.error.set(undefined)
@@ -196,6 +301,7 @@ export class Entry<T> {
       this.lastUpdatedAt.set(Date.now())
       this.isStale.set(this.staleTime === 0)
     })
+    this.forcedStale = false // fresh data clears a prior markStale() (T3.9)
     if (this.staleTime > 0) this.scheduleStaleness()
     try {
       this.events.onFetchSuccess?.(Date.now() - this.fetchStartTime)
@@ -235,12 +341,75 @@ export class Entry<T> {
     return this.startFetch()
   }
 
-  invalidate(): Promise<T> {
+  /**
+   * Apply a server-supplied data + timestamp without going through the
+   * fetcher path. Used by streaming SSR hydration: each `<Suspense>` boundary
+   * that resolves on the server pushes its entry's data to the client, and
+   * the client routes it through here so the entry transitions to `success`
+   * without burning the user's fetcher.
+   *
+   * Distinct from `setData`: no Snapshot returned (no rollback semantics —
+   * this is canonical data, not an optimistic patch), no
+   * `hasPendingMutations` flip, and `lastUpdatedAt` honors the supplied
+   * server timestamp instead of `Date.now()`. Also bumps `currentFetchId`
+   * so any in-flight fetch supersedes itself rather than overwriting the
+   * fresher hydrated value.
+   */
+  applyHydration(data: T, lastUpdatedAt: number): void {
+    if (this.disposed) return
+    // Bump fetch id: an inflight fetcher will now lose the supersede check
+    // in `runWithRetry` and won't write its (likely-stale) result.
+    this.currentFetchId += 1
+    this.currentAbort?.abort()
+    this.currentAbort = null
+    if (this.staleTimer !== null) {
+      clearTimeout(this.staleTimer)
+      this.staleTimer = null
+    }
+    const alreadyStale = this.staleTime === 0 || Date.now() - lastUpdatedAt >= this.staleTime
+    batch(() => {
+      this.data.set(data)
+      this.error.set(undefined)
+      this.status.set('success')
+      this.isLoading.set(false)
+      this.isFetching.set(false)
+      this.lastUpdatedAt.set(lastUpdatedAt)
+      this.isStale.set(alreadyStale)
+    })
+    if (!alreadyStale && this.staleTime > 0) {
+      const remaining = this.staleTime - (Date.now() - lastUpdatedAt)
+      this.staleTimer = setTimeout(() => {
+        this.staleTimer = null
+        if (!this.disposed) this.isStale.set(true)
+      }, remaining)
+    }
+    this.onSuccessData?.(data)
+    // Resolve any awaiters parked in firstValue / promise.
+    if (this.pendingFirstValueRejects.length > 0) {
+      // First-value awaiters are subscribed to `this.status`; the batched
+      // `status.set('success')` above wakes them through the normal
+      // subscribe path. We don't need to do anything else here.
+    }
+  }
+
+  /**
+   * Force this entry stale WITHOUT fetching. `isStaleNow()` returns true until
+   * the next successful fetch clears the flag, so the next subscriber refetches.
+   * Used by `client.invalidate` for subscriber-less entries — spec §5.7 says
+   * invalidate refetches only IF subscribed (T3.9).
+   */
+  markStale(): void {
+    if (this.disposed) return
     if (this.staleTimer != null) {
       clearTimeout(this.staleTimer)
       this.staleTimer = null
     }
+    this.forcedStale = true
     this.isStale.set(true)
+  }
+
+  invalidate(): Promise<T> {
+    this.markStale()
     return this.startFetch()
   }
 
@@ -252,15 +421,53 @@ export class Entry<T> {
     })
   }
 
-  setData(updater: (prev: T | undefined) => T): Snapshot {
+  /**
+   * Cancel an in-flight fetch without touching `data`. Aborts the current
+   * request and supersedes it (bumps `currentFetchId` so its result can never
+   * land), then restores a settled status: `'success'` if data exists, else
+   * `'idle'`. No-op when nothing is fetching. This is the primitive behind
+   * `query.cancel(...)` / `subscription.cancel()`: the canonical optimistic
+   * recipe cancels outgoing refetches before an optimistic `setData` so a
+   * stale response can't clobber the optimistic value (spec §5, §6.4). T3.4.
+   */
+  cancel(): void {
+    if (this.disposed || !this.isFetching.peek()) return
+    this.currentFetchId += 1
+    this.currentAbort?.abort()
+    this.currentAbort = null
+    batch(() => {
+      this.isFetching.set(false)
+      this.isLoading.set(false)
+      this.status.set(this.data.peek() !== undefined ? 'success' : 'idle')
+    })
+  }
+
+  /**
+   * Write data into the entry.
+   *
+   * `track` (default `true`) is the optimistic-update path: it pushes a
+   * snapshot record and flips `hasPendingMutations`, so the returned
+   * `Snapshot.rollback()` can restore the pre-write baseline and
+   * `finalize()` commits it. This is what `query.setData(...)` inside a
+   * mutation's `onMutate` uses (spec §6.4).
+   *
+   * `track: false` is a canonical cache write — cross-tab receive, entities
+   * backprop, realtime patches (spec §13.2). It updates the data signal but
+   * pushes NO snapshot and does NOT flip `hasPendingMutations`, so a
+   * fire-and-forget plugin write can't wedge the pending flag at `true`
+   * forever. Returns a no-op `Snapshot`.
+   */
+  setData(updater: (prev: T | undefined) => T, opts?: { track?: boolean }): Snapshot {
     if (this.disposed) {
       return { rollback: () => {}, finalize: () => {} }
     }
     const prev = this.data.peek()
     const next = updater(prev)
-    const id = this.nextSnapshotId++
-    const record: SnapshotRecord<T> = { id, prev, live: true }
-    this.snapshots.push(record)
+    const track = opts?.track ?? true
+    const record: SnapshotRecord<T> | null = track
+      ? { id: this.nextSnapshotId++, prev, live: true }
+      : null
+    if (record) this.snapshots.push(record)
 
     batch(() => {
       this.data.set(next)
@@ -268,18 +475,37 @@ export class Entry<T> {
         this.status.set('success')
       }
       this.lastUpdatedAt.set(Date.now())
-      this.hasPendingMutations.set(true)
+      if (record) this.hasPendingMutations.set(true)
     })
 
+    if (!record) {
+      return { rollback: () => {}, finalize: () => {} }
+    }
+    const id = record.id
     return {
       rollback: () => {
         if (!record.live || this.disposed) return
         record.live = false
         batch(() => {
-          this.data.set(record.prev as T)
-          this.snapshots = this.snapshots.filter((s) => s.id !== id)
-          const anyLive = this.snapshots.some((s) => s.live)
-          this.hasPendingMutations.set(anyLive)
+          const i = this.snapshots.indexOf(record)
+          if (i !== -1) {
+            if (i === this.snapshots.length - 1) {
+              // Top of the stack: restore this layer's captured baseline as
+              // the current data.
+              this.data.set(record.prev as T)
+            } else {
+              // Not the top: leave the currently-displayed value alone and
+              // thread this layer's baseline down onto the next layer, so a
+              // later top-rollback lands on the correct pre-everything value
+              // instead of resurrecting this layer's delta (chain-splice —
+              // T3.1, spec §6.4). Out-of-order rollback of all layers now
+              // returns to the original pre-mutation value.
+              const below = this.snapshots[i + 1] as SnapshotRecord<T>
+              below.prev = record.prev
+            }
+            this.snapshots.splice(i, 1)
+          }
+          this.hasPendingMutations.set(this.snapshots.some((s) => s.live))
         })
       },
       finalize: () => {
@@ -327,6 +553,7 @@ export class Entry<T> {
    * Used by the query client to decide whether to refetch on subscribe.
    */
   isStaleNow(): boolean {
+    if (this.forcedStale) return true
     const last = this.lastUpdatedAt.peek()
     if (last === undefined) return true
     return Date.now() - last >= this.staleTime
@@ -341,6 +568,23 @@ export class Entry<T> {
     }
     this.currentAbort?.abort()
     this.currentAbort = null
+    // A disposed entry is idle. Reset the in-flight flags so `waitForIdle`
+    // (which waits on `isFetching`) can't hang when a fetch races dispose — the
+    // aborted fetcher's applySuccess/applyFailure never runs to clear them (T3.9).
+    batch(() => {
+      this.isFetching.set(false)
+      this.isLoading.set(false)
+    })
+    if (this.reconnectUnsub !== null) {
+      this.reconnectUnsub()
+      this.reconnectUnsub = null
+    }
+    if (this.deferredResolvers.length > 0) {
+      const disposed = new DOMException('Entry disposed', 'AbortError')
+      const pending = this.deferredResolvers
+      this.deferredResolvers = []
+      for (const p of pending) p.reject(disposed)
+    }
     if (this.pendingFirstValueRejects.length > 0) {
       const disposed = new DOMException('Entry disposed', 'AbortError')
       const rejects = this.pendingFirstValueRejects

package/src/query/focus-online.ts

@@ -14,9 +14,6 @@ type Sub = () => void
 const focusSubs = new Set<Sub>()
 const onlineSubs = new Set<Sub>()
 
-let focusInstalled = false
-let onlineInstalled = false
-
 function fireFocus(): void {
   for (const fn of focusSubs) {
     try {
@@ -37,37 +34,82 @@ function fireOnline(): void {
   }
 }
 
-function ensureFocusInstalled(): void {
+// A tab-return commonly fires BOTH `focus` and `visibilitychange` in the same
+// tick. Coalesce them into a single `fireFocus` via a microtask flag so
+// subscribers refetch once, not twice (T3.9).
+let focusScheduled = false
+function scheduleFocus(): void {
+  if (focusScheduled) return
+  focusScheduled = true
+  queueMicrotask(() => {
+    focusScheduled = false
+    fireFocus()
+  })
+}
+
+function onVisibilityChange(): void {
+  if (document.visibilityState === 'visible') scheduleFocus()
+}
+
+let focusInstalled = false
+let onlineInstalled = false
+
+function installFocus(): void {
   if (focusInstalled) return
   if (typeof window === 'undefined') return
-  window.addEventListener('focus', fireFocus)
+  window.addEventListener('focus', scheduleFocus)
   if (typeof document !== 'undefined') {
-    document.addEventListener('visibilitychange', () => {
-      if (document.visibilityState === 'visible') fireFocus()
-    })
+    document.addEventListener('visibilitychange', onVisibilityChange)
   }
   focusInstalled = true
 }
 
-function ensureOnlineInstalled(): void {
+function uninstallFocus(): void {
+  if (!focusInstalled) return
+  if (typeof window === 'undefined') return
+  window.removeEventListener('focus', scheduleFocus)
+  if (typeof document !== 'undefined') {
+    document.removeEventListener('visibilitychange', onVisibilityChange)
+  }
+  focusInstalled = false
+}
+
+function installOnline(): void {
   if (onlineInstalled) return
   if (typeof window === 'undefined') return
   window.addEventListener('online', fireOnline)
   onlineInstalled = true
 }
 
+function uninstallOnline(): void {
+  if (!onlineInstalled) return
+  if (typeof window === 'undefined') return
+  window.removeEventListener('online', fireOnline)
+  onlineInstalled = false
+}
+
 export function subscribeWindowFocus(fn: Sub): () => void {
-  ensureFocusInstalled()
+  installFocus()
   focusSubs.add(fn)
   return () => {
     focusSubs.delete(fn)
+    if (focusSubs.size === 0) uninstallFocus()
   }
 }
 
 export function subscribeReconnect(fn: Sub): () => void {
-  ensureOnlineInstalled()
+  installOnline()
   onlineSubs.add(fn)
   return () => {
     onlineSubs.delete(fn)
+    if (onlineSubs.size === 0) uninstallOnline()
   }
 }
+
+/** Test-only — force-detach global listeners regardless of subscriber state. */
+export function __resetFocusOnlineForTests(): void {
+  focusSubs.clear()
+  onlineSubs.clear()
+  uninstallFocus()
+  uninstallOnline()
+}