@kontsedal/olas-core 0.0.6 → 0.1.0

package/src/query/infinite.ts

@@ -1,8 +1,16 @@
 import { batch, computed, type Signal, signal } from '../signals'
 import type { ReadSignal } from '../signals/types'
 import { abortableSleep, isAbortError } from '../utils'
+import { subscribeReconnect } from './focus-online'
 import { structuralShare } from './structural-share'
-import type { AsyncState, AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
+import type {
+  AsyncState,
+  AsyncStatus,
+  NetworkMode,
+  RetryDelay,
+  RetryPolicy,
+  Snapshot,
+} from './types'
 
 /**
  * Configuration for `defineInfiniteQuery({ ... })`. Spec §5.7, §20.4.
@@ -37,6 +45,10 @@ export type InfiniteQuerySpec<Args extends unknown[], PageParam, TPage, TItem =
   keepPreviousData?: boolean
   retry?: RetryPolicy
   retryDelay?: RetryDelay
+  /** See `QuerySpec.networkMode`. Defaults to `'online'`. */
+  networkMode?: NetworkMode
+  /** See `QuerySpec.structuralShare`. Applies to the head-page refresh. */
+  structuralShare?: boolean
   /**
    * Stable identifier used by `QueryClientPlugin`s (`@kontsedal/olas-cross-tab`,
    * etc.). Infinite queries do NOT propagate cross-tab in v1 — the
@@ -45,10 +57,12 @@ export type InfiniteQuerySpec<Args extends unknown[], PageParam, TPage, TItem =
    */
   queryId?: string
   /**
-   * Opt into cross-tab sync. No effect for infinite queries in v1 (see
-   * `queryId` doc above).
+   * Accepted for API symmetry, but infinite queries do NOT propagate
+   * cross-tab: peers can't apply page-array payloads (core's remote-apply
+   * paths early-return for infinite defs). The `'infinite'` / `'both'` values
+   * were removed in T6.4; infinite cross-tab is tracked in `BACKLOG.md`.
    */
-  crossTab?: boolean
+  crossTab?: boolean | 'data'
 }
 
 /**
@@ -60,6 +74,11 @@ export type InfiniteQuery<Args extends unknown[], TPage, _TItem> = {
   invalidate(...args: Args): void
   invalidateAll(): void
   setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): Snapshot
+  /** Cancel the in-flight fetch (initial/refetch or paging) for a key. See
+   *  `Query.cancel` (spec §5, §6.4). */
+  cancel(...args: Args): void
+  /** Cancel in-flight fetches for every keyed entry of this infinite query. */
+  cancelAll(): void
   prefetch(...args: Args): Promise<TPage>
 }
 
@@ -80,6 +99,8 @@ export type InfiniteQuerySubscription<TPage, TItem> = AsyncState<TPage[]> & {
   isFetchingPreviousPage: ReadSignal<boolean>
   fetchNextPage: () => Promise<void>
   fetchPreviousPage: () => Promise<void>
+  /** Cancel this subscription's in-flight fetch (if any). See `Query.cancel`. */
+  cancel: () => void
 }
 
 /**
@@ -99,6 +120,9 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
   readonly isStale: Signal<boolean> = signal(true)
   readonly lastUpdatedAt: Signal<number | undefined> = signal(undefined)
   readonly hasPendingMutations: Signal<boolean> = signal(false)
+  /** True while a fetch is parked waiting for reconnect (online-mode defer).
+   *  See spec §5.5, T3.5. Mirrors `Entry.isPaused`. */
+  readonly isPaused: Signal<boolean> = signal(false)
 
   readonly isFetchingNextPage: Signal<boolean> = signal(false)
   readonly isFetchingPreviousPage: Signal<boolean> = signal(false)
@@ -110,7 +134,14 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
   private currentFetchId = 0
   private currentAbort: AbortController | null = null
   private staleTimer: ReturnType<typeof setTimeout> | null = null
-  private snapshots: Array<{ id: number; prev: TPage[]; live: boolean }> = []
+  /** Set by `markStale()` (invalidate without fetch). See `Entry.forcedStale`. */
+  private forcedStale = false
+  private snapshots: Array<{
+    id: number
+    prev: TPage[]
+    prevParams: PageParam[]
+    live: boolean
+  }> = []
   private nextSnapshotId = 0
   private disposed = false
   /** Mirrors `Entry.pendingFirstValueRejects` — see that field for context. */
@@ -127,7 +158,15 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     | undefined
   private readonly staleTime: number
   private readonly retry: RetryPolicy
-  private readonly retryDelay: RetryDelay
+  private readonly retryDelay: RetryDelay | undefined
+  private readonly networkMode: NetworkMode
+  private readonly structuralShareEnabled: boolean
+  private reconnectUnsub: (() => void) | null = null
+  private deferredResolvers: Array<{
+    direction: 'initial' | 'next' | 'prev'
+    resolve: () => void
+    reject: (err: unknown) => void
+  }> = []
   private readonly itemsOf?: (page: TPage) => TItem[]
   /**
    * Mirrors `Entry.onSuccessData`. Fires from `applyFetchSuccess`-equivalent
@@ -146,6 +185,8 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     staleTime?: number
     retry?: RetryPolicy
     retryDelay?: RetryDelay
+    networkMode?: NetworkMode
+    structuralShare?: boolean
     onSuccessData?: (pages: TPage[]) => void
   }) {
     this.fetcher = opts.fetcher
@@ -155,7 +196,9 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     this.itemsOf = opts.itemsOf
     this.staleTime = opts.staleTime ?? 0
     this.retry = opts.retry ?? 0
-    this.retryDelay = opts.retryDelay ?? 1000
+    this.retryDelay = opts.retryDelay
+    this.networkMode = opts.networkMode ?? 'online'
+    this.structuralShareEnabled = opts.structuralShare ?? true
     this.onSuccessData = opts.onSuccessData
     this.pageParams = signal<PageParam[]>([])
     this.data = computed(() => {
@@ -185,53 +228,136 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     })
   }
 
-  /** Initial / refetch — drops all pages and fetches starting from initialPageParam. */
+  /**
+   * Initial load / refetch. On the initial load (no pages yet) this fetches
+   * the first page. On a refetch of an already-loaded entry (interval,
+   * invalidate, focus/reconnect) it **refetches every currently-loaded page**
+   * sequentially, re-deriving each page's param from the freshly-fetched data
+   * via `getNextPageParam` — matching TanStack and avoiding the old
+   * "collapse to page one" truncation that dropped every loaded page but the
+   * first on each refetch (T3.7). Pages/params update atomically at the end,
+   * so subscribers never observe a mid-refetch truncation flash.
+   */
   startFetch(): Promise<TPage> {
     if (this.disposed) return Promise.reject(new Error('Entry disposed'))
+    if (this.networkMode === 'online' && this.isOffline()) {
+      return this.scheduleDeferredFetch('initial') as Promise<TPage>
+    }
     const myId = ++this.currentFetchId
     this.currentAbort?.abort()
     const abort = new AbortController()
     this.currentAbort = abort
 
-    const previouslyHadPages = this.pages.peek().length > 0
+    const previousPages = this.pages.peek()
     batch(() => {
       this.status.set('pending')
       this.isFetching.set(true)
-      this.isLoading.set(!previouslyHadPages)
+      this.isLoading.set(previousPages.length === 0)
+      this.isPaused.set(false)
     })
 
-    return this.runFetch(
-      myId,
-      abort.signal,
-      this.initialPageParam,
-      (page, param) => {
-        if (myId !== this.currentFetchId || this.disposed) return
-        // Structurally share with the previous first-page on refresh, so
-        // unchanged pages keep their refs. We only share the head page —
-        // initial fetch wipes the rest of the array by definition.
-        const prevPages = this.pages.peek()
-        const sharedPage =
-          prevPages.length > 0 ? structuralShare(prevPages[0] as TPage, page) : page
-        batch(() => {
-          this.pages.set([sharedPage])
-          this.pageParams.set([param])
-          this.error.set(undefined)
-          this.status.set('success')
-          this.isLoading.set(false)
-          this.isFetching.set(false)
-          this.lastUpdatedAt.set(Date.now())
-          this.isStale.set(this.staleTime === 0)
-        })
-        if (this.staleTime > 0) this.scheduleStaleness()
-        this.onSuccessData?.(this.pages.peek())
-      },
-      'initial',
-    )
+    return this.runRefetchAll(myId, abort.signal, Math.max(1, previousPages.length), previousPages)
+  }
+
+  /**
+   * Fetch `targetCount` pages from `initialPageParam`, chaining each next param
+   * via `getNextPageParam` from the freshly-fetched pages. Applies the query's
+   * retry policy per page. Stops early if the dataset shrank (a page yields
+   * `getNextPageParam === null`). Writes pages/params in ONE batch at the end;
+   * a per-page failure keeps the existing pages and surfaces the error; a
+   * supersede/dispose throws `AbortError` without writing.
+   */
+  private async runRefetchAll(
+    myId: number,
+    signal: AbortSignal,
+    targetCount: number,
+    previousPages: TPage[],
+  ): Promise<TPage> {
+    const newPages: TPage[] = []
+    const newParams: PageParam[] = []
+    let pageParam: PageParam = this.initialPageParam
+    try {
+      for (let i = 0; i < targetCount; i++) {
+        let attempt = 0
+        while (true) {
+          if (myId !== this.currentFetchId || this.disposed) {
+            throw new DOMException('Superseded', 'AbortError')
+          }
+          try {
+            const page = await this.fetcher({ pageParam, signal })
+            if (myId !== this.currentFetchId || this.disposed) {
+              throw new DOMException('Superseded', 'AbortError')
+            }
+            newPages.push(page)
+            newParams.push(pageParam)
+            break
+          } catch (err) {
+            if (myId !== this.currentFetchId || this.disposed || isAbortError(err)) throw err
+            const shouldRetry =
+              typeof this.retry === 'number' ? attempt < this.retry : this.retry(attempt, err)
+            if (!shouldRetry) {
+              batch(() => {
+                this.error.set(err)
+                this.status.set('error')
+                this.isLoading.set(false)
+                this.isFetching.set(false)
+              })
+              throw err
+            }
+            const delay = this.computeRetryDelay(attempt)
+            await abortableSleep(delay, signal)
+            attempt += 1
+          }
+        }
+        const next = this.getNextPageParam(newPages[newPages.length - 1] as TPage, newPages)
+        if (next === null) break
+        pageParam = next
+      }
+      if (myId !== this.currentFetchId || this.disposed) {
+        throw new DOMException('Superseded', 'AbortError')
+      }
+      // Structurally share the head page so an unchanged first page keeps its
+      // ref (downstream `computed`s / React snapshots don't thrash).
+      const finalPages =
+        previousPages.length > 0 && this.structuralShareEnabled && newPages.length > 0
+          ? [structuralShare(previousPages[0] as TPage, newPages[0] as TPage), ...newPages.slice(1)]
+          : newPages
+      batch(() => {
+        this.pages.set(finalPages)
+        this.pageParams.set(newParams)
+        this.error.set(undefined)
+        this.status.set('success')
+        this.isLoading.set(false)
+        this.isFetching.set(false)
+        this.lastUpdatedAt.set(Date.now())
+        this.isStale.set(this.staleTime === 0)
+      })
+      this.forcedStale = false // fresh pages clear a prior markStale() (T3.9)
+      if (this.staleTime > 0) this.scheduleStaleness()
+      this.onSuccessData?.(this.pages.peek())
+      return finalPages[0] as TPage
+    } finally {
+      // Status repair (T3.3): a superseded refetch must never leave the entry
+      // wedged at 'pending' when data is present and nothing is fetching. The
+      // superseder owns the final status; this only fires for the terminal
+      // fetch of a supersede chain. Never clobbers a real 'error'.
+      if (
+        !this.disposed &&
+        this.status.peek() === 'pending' &&
+        !this.isFetching.peek() &&
+        this.pages.peek().length > 0
+      ) {
+        this.status.set('success')
+      }
+    }
   }
 
   fetchNextPage(): Promise<void> {
     if (this.disposed) return Promise.reject(new Error('Entry disposed'))
     if (this.isFetchingNextPage.peek()) return Promise.resolve()
+    if (this.networkMode === 'online' && this.isOffline()) {
+      return this.scheduleDeferredFetch('next') as Promise<void>
+    }
     const ps = this.pages.peek()
     if (ps.length === 0) {
       return this.startFetch().then(() => {})
@@ -257,6 +383,11 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
         batch(() => {
           this.pages.set([...this.pages.peek(), page])
           this.pageParams.set([...this.pageParams.peek(), param])
+          this.error.set(undefined)
+          // A successful page op owns the terminal status: restore 'success'
+          // so paging that superseded a mid-flight full refetch (which left
+          // status at 'pending') can't wedge the entry / Suspense (T3.3).
+          this.status.set('success')
           this.isFetchingNextPage.set(false)
           this.isFetching.set(false)
           this.lastUpdatedAt.set(Date.now())
@@ -271,6 +402,9 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     if (this.disposed) return Promise.reject(new Error('Entry disposed'))
     if (this.isFetchingPreviousPage.peek()) return Promise.resolve()
     if (!this.getPreviousPageParam) return Promise.resolve()
+    if (this.networkMode === 'online' && this.isOffline()) {
+      return this.scheduleDeferredFetch('prev') as Promise<void>
+    }
     const ps = this.pages.peek()
     if (ps.length === 0) {
       return this.startFetch().then(() => {})
@@ -296,6 +430,10 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
         batch(() => {
           this.pages.set([page, ...this.pages.peek()])
           this.pageParams.set([param, ...this.pageParams.peek()])
+          this.error.set(undefined)
+          // A successful page op owns the terminal status — see fetchNextPage
+          // (T3.3).
+          this.status.set('success')
           this.isFetchingPreviousPage.set(false)
           this.isFetching.set(false)
           this.lastUpdatedAt.set(Date.now())
@@ -345,8 +483,7 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
             })
             throw err
           }
-          const delay =
-            typeof this.retryDelay === 'function' ? this.retryDelay(attempt) : this.retryDelay
+          const delay = this.computeRetryDelay(attempt)
           await abortableSleep(delay, signal)
           attempt += 1
         }
@@ -361,6 +498,20 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
         batch(() => {
           if (direction === 'next') this.isFetchingNextPage.set(false)
           if (direction === 'prev') this.isFetchingPreviousPage.set(false)
+          // Status repair (T3.3): a superseded fetch must never leave the
+          // entry wedged at 'pending' when data is present and nothing is
+          // fetching. The superseding fetch normally owns the final status
+          // (its onSuccess sets 'success'); this is the safety net for the
+          // terminal fetch of a supersede chain. Only repair 'pending' — never
+          // clobber a real 'error' — and only when no fetch is still running.
+          if (
+            !this.disposed &&
+            this.status.peek() === 'pending' &&
+            !this.isFetching.peek() &&
+            this.pages.peek().length > 0
+          ) {
+            this.status.set('success')
+          }
         })
       }
     }
@@ -370,12 +521,19 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     return this.startFetch()
   }
 
-  invalidate(): Promise<TPage> {
+  /** Force stale without fetching — see `Entry.markStale` (spec §5.7, 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<TPage> {
+    this.markStale()
     return this.startFetch()
   }
 
@@ -387,32 +545,99 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     })
   }
 
-  setData(updater: (prev: TPage[] | undefined) => TPage[]): Snapshot {
+  /** Cancel an in-flight fetch (initial/refetch or paging) without touching
+   *  pages. Supersedes + aborts the current request, then restores a settled
+   *  status. No-op when idle. Mirrors `Entry.cancel` (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.isFetchingNextPage.set(false)
+      this.isFetchingPreviousPage.set(false)
+      this.status.set(this.pages.peek().length > 0 ? 'success' : 'idle')
+    })
+  }
+
+  setData(updater: (prev: TPage[] | undefined) => TPage[], opts?: { track?: boolean }): Snapshot {
     if (this.disposed) {
       return { rollback: () => {}, finalize: () => {} }
     }
     const prev = this.pages.peek()
+    const prevParams = this.pageParams.peek()
     const next = updater(prev.length === 0 ? undefined : prev)
-    const id = this.nextSnapshotId++
-    const record = { id, prev, live: true }
-    this.snapshots.push(record)
+    // `track: false` is a canonical cache write (plugin/remote/entities
+    // backprop) — no optimistic snapshot, no `hasPendingMutations` flip. See
+    // `Entry.setData` for the full rationale. Default `true` keeps the
+    // optimistic-update path (`query.setData` in `onMutate`).
+    const track = opts?.track ?? true
+    // Snapshot BOTH pages and pageParams so rollback restores a consistent
+    // pair. Without `prevParams`, an optimistic insert would shift `pages`
+    // permanently out of sync with `pageParams` on rollback — and any
+    // subsequent `fetchNextPage`/`getNextPageParam` would operate on the
+    // wrong head.
+    const record = track ? { id: this.nextSnapshotId++, prev, prevParams, live: true } : null
+    if (record) this.snapshots.push(record)
+
+    // If the updater changed the page count, trim or pad pageParams so the
+    // two arrays stay length-aligned. Padding uses the last known param,
+    // which is the safest neutral choice — the caller of `setData` should
+    // re-key via a real fetch (or use a future param-aware overload) if
+    // the new page needs a fresh param.
+    let nextParams: PageParam[] = prevParams
+    if (next.length !== prevParams.length) {
+      if (next.length < prevParams.length) {
+        nextParams = prevParams.slice(0, next.length)
+      } else {
+        const pad = prevParams[prevParams.length - 1]
+        nextParams = prevParams.slice()
+        for (let i = prevParams.length; i < next.length; i++) {
+          nextParams.push(pad as PageParam)
+        }
+      }
+    }
 
     batch(() => {
       this.pages.set(next)
+      if (nextParams !== prevParams) this.pageParams.set(nextParams)
       if (this.status.peek() === 'idle' || this.status.peek() === 'pending') {
         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.pages.set(record.prev)
-          this.snapshots = this.snapshots.filter((s) => s.id !== id)
+          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 pair
+              // (pages + params stay length-aligned — see the snapshot note).
+              this.pages.set(record.prev)
+              this.pageParams.set(record.prevParams)
+            } else {
+              // Not the top: leave current pages/params alone and thread this
+              // layer's baseline down onto the next layer, so a later
+              // top-rollback lands on the correct pre-everything pages instead
+              // of resurrecting this layer's delta (chain-splice — T3.1, spec
+              // §6.4). Mirrors `Entry.setData`.
+              const below = this.snapshots[i + 1] as (typeof this.snapshots)[number]
+              below.prev = record.prev
+              below.prevParams = record.prevParams
+            }
+            this.snapshots.splice(i, 1)
+          }
           this.hasPendingMutations.set(this.snapshots.some((s) => s.live))
         })
       },
@@ -457,11 +682,72 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
   }
 
   isStaleNow(): boolean {
+    if (this.forcedStale) return true
     const last = this.lastUpdatedAt.peek()
     if (last === undefined) return true
     return Date.now() - last >= this.staleTime
   }
 
+  private computeRetryDelay(attempt: number): number {
+    const d = this.retryDelay
+    // Exponential backoff default when retries are on but no retryDelay given
+    // (mirrors Entry.computeDelay — T3.9).
+    if (d === undefined) return Math.min(1000 * 2 ** attempt, 30_000)
+    return typeof d === 'function' ? d(attempt) : d
+  }
+
+  private isOffline(): boolean {
+    return typeof navigator !== 'undefined' && navigator.onLine === false
+  }
+
+  private scheduleDeferredFetch(direction: 'initial' | 'next' | 'prev'): Promise<unknown> {
+    // Parked waiting for reconnect (T3.5). Cleared when a fetch actually
+    // starts (`startFetch` batch) or on drain.
+    this.isPaused.set(true)
+    if (this.reconnectUnsub === null) {
+      this.reconnectUnsub = subscribeReconnect(() => this.drainDeferred())
+    }
+    return new Promise<void>((resolve, reject) => {
+      this.deferredResolvers.push({ direction, resolve, reject })
+    })
+  }
+
+  private drainDeferred(): void {
+    if (this.deferredResolvers.length === 0) return
+    if (this.disposed) return
+    this.isPaused.set(false)
+    const pending = this.deferredResolvers
+    this.deferredResolvers = []
+    if (this.reconnectUnsub !== null) {
+      this.reconnectUnsub()
+      this.reconnectUnsub = null
+    }
+    // Collapse multiple deferrals of the same direction into one real fetch.
+    // Order matters: initial first (it may produce data the others need),
+    // then prev / next.
+    const seen = new Set<'initial' | 'next' | 'prev'>()
+    const order: Array<'initial' | 'next' | 'prev'> = ['initial', 'prev', 'next']
+    for (const d of pending) {
+      seen.add(d.direction)
+    }
+    const run = async () => {
+      for (const dir of order) {
+        if (!seen.has(dir)) continue
+        if (dir === 'initial') await this.startFetch()
+        else if (dir === 'next') await this.fetchNextPage()
+        else await this.fetchPreviousPage()
+      }
+    }
+    run().then(
+      () => {
+        for (const p of pending) p.resolve()
+      },
+      (err) => {
+        for (const p of pending) p.reject(err)
+      },
+    )
+  }
+
   private scheduleStaleness(): void {
     if (this.staleTimer != null) clearTimeout(this.staleTimer)
     if (this.staleTime > 0) {
@@ -481,6 +767,24 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     }
     this.currentAbort?.abort()
     this.currentAbort = null
+    // A disposed entry is idle — reset the in-flight flags so `waitForIdle`
+    // can't hang on a fetch racing dispose (T3.9). Mirrors `Entry.dispose`.
+    batch(() => {
+      this.isFetching.set(false)
+      this.isLoading.set(false)
+      this.isFetchingNextPage.set(false)
+      this.isFetchingPreviousPage.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/keys.ts

@@ -1,7 +1,7 @@
 /**
  * Stable string hash of a key tuple. Two equal-by-content args produce the
  * same string regardless of property iteration order. Handles primitives,
- * arrays, plain objects, Date.
+ * arrays, plain objects, Date, BigInt, NaN, ±Infinity.
  *
  * Functions and symbols throw — keys must be serializable so distinct
  * subscribers can share entries.
@@ -10,19 +10,50 @@ export function stableHash(args: readonly unknown[]): string {
   return JSON.stringify(args, replacer)
 }
 
-const replacer = (_key: string, value: unknown): unknown => {
+// A regular `function` (not an arrow) so `this` is bound to the holder object
+// by `JSON.stringify`. Critical: `JSON.stringify` applies `toJSON()` to a value
+// BEFORE calling the replacer, so the `value` argument for a `Date` is already
+// its ISO string and a class instance with a `toJSON` is already its serialized
+// form — inspecting `value` would miss both (the old arrow did, making the Date
+// tag and the class-instance throw dead code: `stableHash([date])` collided
+// with `stableHash([date.toISOString()])`). Reading the RAW property off the
+// holder (`this[key]`) recovers the true pre-`toJSON` value. Spec §5.4; T3.8.
+const replacer = function (this: unknown, key: string, _value: unknown): unknown {
+  const value = (this as Record<string, unknown>)[key]
   if (typeof value === 'function') {
     throw new Error('[olas] query keys cannot contain functions')
   }
   if (typeof value === 'symbol') {
     throw new Error('[olas] query keys cannot contain symbols')
   }
+  if (typeof value === 'bigint') {
+    // JSON has no bigint; serialize as a tagged string so `1n` and `'1'`
+    // don't collide. The tag survives round-trips for debugging.
+    return { __bigint: value.toString() }
+  }
+  if (typeof value === 'number') {
+    // `JSON.stringify(NaN)` → `'null'` and likewise for Infinity, which
+    // would collide with a literal `null` key. Tag them explicitly.
+    if (Number.isNaN(value)) return '__nan__'
+    if (value === Number.POSITIVE_INFINITY) return '__+inf__'
+    if (value === Number.NEGATIVE_INFINITY) return '__-inf__'
+    return value
+  }
   if (value === undefined) return '__undefined__'
   if (value instanceof Date) return { __date: value.toISOString() }
   if (value instanceof Map || value instanceof Set) {
     throw new Error('[olas] query keys cannot contain Map/Set — use arrays/objects')
   }
   if (value && typeof value === 'object' && !Array.isArray(value)) {
+    // Reject class instances (proto !== Object.prototype): two `new MyKey(1)`
+    // calls would serialize identically to `{}` and collide. Plain objects
+    // pass through with sorted keys.
+    const proto = Object.getPrototypeOf(value)
+    if (proto !== null && proto !== Object.prototype) {
+      throw new Error(
+        `[olas] query keys cannot contain class instances (got ${proto.constructor?.name ?? 'unknown'}) — pass plain object/array data`,
+      )
+    }
     const sorted: Record<string, unknown> = {}
     for (const k of Object.keys(value).sort()) {
       sorted[k] = (value as Record<string, unknown>)[k]

package/src/query/local.ts

@@ -79,6 +79,9 @@ class LocalCacheImpl<T> implements LocalCache<T> {
   get hasPendingMutations(): ReadSignal<boolean> {
     return this.entry.hasPendingMutations
   }
+  get isPaused(): ReadSignal<boolean> {
+    return this.entry.isPaused
+  }
 
   refetch = (): Promise<T> => this.entry.refetch()
   reset = (): void => this.entry.reset()