@kontsedal/olas-core 0.0.1-rc.1 → 0.0.1

package/src/query/client.ts

@@ -1,6 +1,7 @@
 import type { DevtoolsEmitter } from '../devtools'
 import { dispatchError, type ErrorHandler } from '../errors'
 import { type Signal, signal } from '../signals'
+import { isAbortError } from '../utils'
 import { Entry } from './entry'
 import { subscribeReconnect, subscribeWindowFocus } from './focus-online'
 import { InfiniteEntry, type InfiniteQuery, type InfiniteQuerySpec } from './infinite'
@@ -51,7 +52,16 @@ export class ClientEntry<T> {
     callArgs: readonly unknown[],
     keyArgs: readonly unknown[],
     spec: QuerySpec<any, T>,
-    hydrated?: { data: T; lastUpdatedAt: number },
+    hydrated: { data: T; lastUpdatedAt: number } | undefined,
+    /**
+     * Prepared by `QueryClient.bindEntry` (which is the only construction
+     * site). When the query has a `queryId`, the closure calls back into
+     * `QueryClient.emitSetData` with `source: 'fetch'` after every
+     * successful fetch. We accept it pre-built rather than reach into the
+     * client from here because `emitSetData` is `private` on `QueryClient`
+     * — restricting the access path is the whole point.
+     */
+    onFetchSuccess: ((data: T) => void) | undefined,
   ) {
     this.client = client
     this.query = query
@@ -87,6 +97,7 @@ export class ClientEntry<T> {
                 }),
             }
           : undefined,
+      onSuccessData: onFetchSuccess,
     })
   }
 
@@ -218,6 +229,13 @@ export class InfiniteClientEntry<TPage, TItem, PageParam> {
     callArgs: readonly unknown[],
     keyArgs: readonly unknown[],
     spec: InfiniteQuerySpec<any, PageParam, TPage, TItem>,
+    /**
+     * Prepared by `QueryClient.bindInfiniteEntry`. When the infinite query
+     * has a `queryId`, the closure calls back into `QueryClient.emitSetData`
+     * with `kind: 'infinite', source: 'fetch'` after every successful page
+     * write (initial, next, prev). Mirrors `ClientEntry.onFetchSuccess`.
+     */
+    onFetchSuccess: ((pages: TPage[]) => void) | undefined,
   ) {
     this.client = client
     this.query = query
@@ -237,6 +255,11 @@ export class InfiniteClientEntry<TPage, TItem, PageParam> {
       staleTime: spec.staleTime,
       retry: spec.retry as RetryPolicy | undefined,
       retryDelay: spec.retryDelay as RetryDelay | undefined,
+      // Fire SetDataEvent { kind: 'infinite', source: 'fetch' } whenever a
+      // fetch settles successfully. Plugins (e.g. entity normalization) use
+      // this to walk the pages and update their normalized stores. Mirrors
+      // the regular `ClientEntry`'s `onFetchSuccess` closure plumbing.
+      onSuccessData: onFetchSuccess,
     })
   }
 
@@ -394,6 +417,9 @@ export class QueryClient {
       applyRemoteInvalidate(queryId, keyArgs) {
         self.applyRemoteInvalidate(queryId, keyArgs)
       },
+      setEntryData(queryId, keyArgs, updater) {
+        self.setEntryData(queryId, keyArgs, updater)
+      },
       subscribedKeys(queryId) {
         return self.subscribedKeysFor(queryId)
       },
@@ -412,11 +438,29 @@ export class QueryClient {
     }
   }
 
+  /**
+   * Emit a `SetDataEvent` to every installed plugin. The `source` field
+   * tells layered plugins where the write originated:
+   * - `'set'`: explicit `client.setData`, including mutations and plugin-
+   *   initiated `setEntryData` calls (e.g. entity backpropagation).
+   * - `'fetch'`: a query fetcher resolved successfully (`Entry.applySuccess`
+   *   reaches this through `onSuccessData`), or hydrated data was first
+   *   bound (a per-tab arrival of pre-fetched data; cross-tab skips
+   *   `'fetch'` so this stays a per-tab concern).
+   * - `'remote'`: `applyRemoteSetData` — cross-tab / server-push. Mirrors
+   *   `isRemote === true`.
+   *
+   * Private — fetcher-success emission goes through the `onFetchSuccess`
+   * closure that `bindEntry` builds and hands to each new `ClientEntry`.
+   * Hydrated emission goes through this method directly from `bindEntry`.
+   * Mutation / remote paths call it from within QueryClient methods.
+   */
   private emitSetData(
     query: AnyQuery | AnyInfiniteQuery,
     keyArgs: readonly unknown[],
     data: unknown,
     kind: 'data' | 'infinite',
+    source: 'set' | 'fetch' | 'remote',
   ): void {
     if (this.plugins.length === 0) return
     const queryId = query.__spec.queryId
@@ -427,6 +471,7 @@ export class QueryClient {
       data,
       kind,
       isRemote: this.applyingRemote,
+      source,
     }
     for (const plugin of this.plugins) {
       if (plugin.onSetData) {
@@ -521,12 +566,54 @@ export class QueryClient {
     this.applyingRemote = true
     try {
       entry.entry.setData(() => data as never)
-      this.emitSetData(internal, entry.keyArgs, data, 'data')
+      this.emitSetData(internal, entry.keyArgs, data, 'data', 'remote')
     } finally {
       this.applyingRemote = false
     }
   }
 
+  /**
+   * Local-originated `setData` keyed by `queryId + keyArgs`. Plugin-facing
+   * (exposed via `QueryClientPluginApi.setEntryData`); used by the
+   * `@kontsedal/olas-entities` plugin to backpropagate entity patches into
+   * every query holding the entity, without forcing the plugin to recover
+   * the original `callArgs`.
+   *
+   * Drops silently in the same cases as `applyRemoteSetData` (unknown
+   * queryId / infinite query / no local entry). Emits `SetDataEvent` with
+   * `isRemote: false`, `source: 'set'` — cross-tab WILL rebroadcast.
+   */
+  setEntryData(
+    queryId: string,
+    keyArgs: readonly unknown[],
+    updater: (prev: unknown) => unknown,
+  ): void {
+    const query = lookupRegisteredQuery(queryId)
+    if (!query) return
+    const hash = stableHash(keyArgs)
+    if (query.__olas === 'query') {
+      const internal = query as unknown as AnyQuery
+      const map = this.maps.get(internal)
+      if (!map) return
+      const entry = map.get(hash)
+      if (!entry) return
+      entry.entry.setData(updater as (prev: unknown) => never)
+      this.emitSetData(internal, entry.keyArgs, entry.entry.data.peek(), 'data', 'set')
+      return
+    }
+    // Infinite query. The plugin's `SetDataEvent.data` for `kind: 'infinite'`
+    // is `TPage[]` (the pages array), so the same path-based walk + write
+    // mechanics apply — we just route through `InfiniteEntry.setData` and
+    // re-emit with `kind: 'infinite'`.
+    const internal = query as unknown as AnyInfiniteQuery
+    const map = this.infiniteMaps.get(internal)
+    if (!map) return
+    const entry = map.get(hash)
+    if (!entry) return
+    entry.entry.setData(updater as (prev: unknown[] | undefined) => unknown[])
+    this.emitSetData(internal, entry.keyArgs, entry.entry.pages.peek(), 'infinite', 'set')
+  }
+
   applyRemoteInvalidate(queryId: string, keyArgs: readonly unknown[]): void {
     const query = lookupRegisteredQuery(queryId)
     if (!query) return
@@ -542,6 +629,9 @@ export class QueryClient {
       // Emit AFTER kicking off invalidate so plugins reading entry state see
       // post-invalidation values, mirroring setData's emit-after-write order.
       entry.entry.invalidate().catch((err) => {
+        // Two rapid invalidates on the same key supersede each other, which
+        // raises AbortError. That's not a cache error — swallow.
+        if (isAbortError(err)) return
         dispatchError(this.onError, err, {
           kind: 'cache',
           controllerPath: [],
@@ -555,7 +645,19 @@ export class QueryClient {
   }
 
   hydrate(state: DehydratedState): void {
-    if (state.version !== 1) return
+    if (state.version !== 1) {
+      // Silent drop hid schema-bumped payloads. Warn so a future spec bump is
+      // detectable from the client side without code archaeology.
+      if (__DEV__) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[olas] hydrate(): unsupported state.version =',
+          state.version,
+          '— expected 1. Dropping payload; cache will fetch fresh.',
+        )
+      }
+      return
+    }
     for (const entry of state.entries) {
       const hash = stableHash(entry.key)
       this.hydratedData.set(hash, {
@@ -653,6 +755,17 @@ export class QueryClient {
       if (tasks.length === 0) return
       await Promise.all(tasks)
     }
+    // The 100-iteration safety bound exists so a pathological setup that
+    // keeps starting new fetches doesn't lock the dehydrate path. Warn so
+    // it's surfaced — silent success would let an SSR dehydrate ship an
+    // incomplete payload looking like a clean one.
+    if (__DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[olas] waitForIdle(): exited via the 100-iteration safety bound — ' +
+          'the cache or mutations keep restarting. The dehydrate payload may be incomplete.',
+      )
+    }
   }
 
   bindEntry<Args extends unknown[], T>(query: Query<Args, T>, args: Args): ClientEntry<T> {
@@ -670,12 +783,40 @@ export class QueryClient {
     if (!entry) {
       const hydrated = this.hydratedData.get(hash) as { data: T; lastUpdatedAt: number } | undefined
       if (hydrated) this.hydratedData.delete(hash)
-      entry = new ClientEntry<T>(this, internal, args, keyArgs, internal.__spec, hydrated)
+      // Build the fetcher-success emitter here so `emitSetData` can stay
+      // `private` — `ClientEntry` doesn't reach back into the client to call
+      // it; the closure captures (query, keyArgs, this) in this scope and
+      // is consumed by `Entry.onSuccessData` from inside `applySuccess`.
+      const onFetchSuccess: ((data: T) => void) | undefined =
+        internal.__spec.queryId != null
+          ? (data) => this.emitSetData(internal, keyArgs, data, 'data', 'fetch')
+          : undefined
+      entry = new ClientEntry<T>(
+        this,
+        internal,
+        args,
+        keyArgs,
+        internal.__spec,
+        hydrated,
+        onFetchSuccess,
+      )
       map.set(hash, entry as ClientEntry<unknown>)
       // The entry is created without an immediate subscriber (callers like
       // `prefetch`/`setData`/`invalidate` reach `bindEntry` first; subscribing
       // callers then call `acquire()` right after, which clears the gc timer).
       entry.scheduleGcIfOrphan()
+      // Hydrated data lands in `initialData` on the new Entry — `applySuccess`
+      // is never called, so plugins observing fetch results (entities, ...)
+      // would otherwise miss every hydrated row. Emit a SetDataEvent with
+      // `source: 'fetch'` here once the entry is registered (and the plugin
+      // is already init'd, since the QueryClient constructor runs hydrate →
+      // plugin init before any subscriber can reach bindEntry). The fetch
+      // source is correct for layered consumers: each tab hydrates
+      // independently, so cross-tab's "skip 'fetch'" gate continues to do
+      // the right thing.
+      if (hydrated !== undefined) {
+        this.emitSetData(internal, keyArgs, hydrated.data, 'data', 'fetch')
+      }
     }
     return entry
   }
@@ -708,6 +849,7 @@ export class QueryClient {
       this.devtools?.emit({ type: 'cache:invalidated', queryKey: keyArgs })
     }
     entry.entry.invalidate().catch((err) => {
+      if (isAbortError(err)) return
       dispatchError(this.onError, err, {
         kind: 'cache',
         controllerPath: [],
@@ -727,6 +869,7 @@ export class QueryClient {
         this.devtools?.emit({ type: 'cache:invalidated', queryKey: entry.keyArgs })
       }
       entry.entry.invalidate().catch((err) => {
+        if (isAbortError(err)) return
         dispatchError(this.onError, err, {
           kind: 'cache',
           controllerPath: [],
@@ -747,7 +890,7 @@ export class QueryClient {
     // Read the post-update value to broadcast — plugins want the new state,
     // not the updater function (which would be uncloneable across
     // BroadcastChannel).
-    this.emitSetData(entry.query, entry.keyArgs, entry.entry.data.peek(), 'data')
+    this.emitSetData(entry.query, entry.keyArgs, entry.entry.data.peek(), 'data', 'set')
     return snapshot
   }
 
@@ -767,12 +910,22 @@ export class QueryClient {
     const hash = stableHash(keyArgs)
     let entry = map.get(hash) as InfiniteClientEntry<TPage, TItem, unknown> | undefined
     if (!entry) {
+      // Mirror the regular-query plumbing in `bindEntry`: build the
+      // SetDataEvent emitter here so `emitSetData` stays private. The
+      // closure captures (query, keyArgs, this) and is consumed by
+      // `InfiniteEntry.onSuccessData` from inside each successful page
+      // batch (initial, next, prev).
+      const onFetchSuccess: ((pages: TPage[]) => void) | undefined =
+        internal.__spec.queryId != null
+          ? (pages) => this.emitSetData(internal, keyArgs, pages, 'infinite', 'fetch')
+          : undefined
       entry = new InfiniteClientEntry<TPage, TItem, unknown>(
         this,
         internal,
         args,
         keyArgs,
         internal.__spec,
+        onFetchSuccess,
       )
       map.set(hash, entry as InfiniteClientEntry<unknown, unknown, unknown>)
       entry.scheduleGcIfOrphan()
@@ -805,6 +958,7 @@ export class QueryClient {
     const entry = map.get(hash)
     if (!entry) return
     entry.entry.invalidate().catch((err) => {
+      if (isAbortError(err)) return
       dispatchError(this.onError, err, {
         kind: 'cache',
         controllerPath: [],
@@ -820,6 +974,7 @@ export class QueryClient {
     if (!map) return
     for (const entry of map.values()) {
       entry.entry.invalidate().catch((err) => {
+        if (isAbortError(err)) return
         dispatchError(this.onError, err, {
           kind: 'cache',
           controllerPath: [],
@@ -837,7 +992,7 @@ export class QueryClient {
   ): Snapshot {
     const entry = this.bindInfiniteEntry(query, args)
     const snapshot = entry.entry.setData(updater)
-    this.emitSetData(entry.query, entry.keyArgs, entry.entry.pages.peek(), 'infinite')
+    this.emitSetData(entry.query, entry.keyArgs, entry.entry.pages.peek(), 'infinite', 'set')
     return snapshot
   }
 

package/src/query/define.ts

@@ -72,6 +72,13 @@ export function defineQuery<Args extends unknown[], T>(spec: QuerySpec<Args, T>)
       if (!first) {
         return Promise.reject(new Error('[olas] prefetch called before any root has subscribed'))
       }
+      if (__DEV__ && clients.size > 1) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[olas] query.prefetch() is ambiguous when multiple roots are registered; ' +
+            'using an arbitrary root. Call `root.prefetch(query, args)` (or per-root) to be explicit.',
+        )
+      }
       return first.prefetch(query as Query<Args, T>, args)
     },
   } satisfies QueryInternal<Args, T>
@@ -145,6 +152,13 @@ export function defineInfiniteQuery<Args extends unknown[], PageParam, TPage, TI
       if (!first) {
         return Promise.reject(new Error('[olas] prefetch called before any root has subscribed'))
       }
+      if (__DEV__ && clients.size > 1) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[olas] infiniteQuery.prefetch() is ambiguous when multiple roots are registered; ' +
+            'using an arbitrary root. Call `root.prefetch(query, args)` (or per-root) to be explicit.',
+        )
+      }
       return first.prefetchInfinite(query as InfiniteQuery<Args, TPage, TItem>, args)
     },
   } satisfies InfiniteQueryInternal<Args, TPage, TItem>

package/src/query/entry.ts

@@ -1,5 +1,5 @@
 import { batch, type Signal, signal } from '../signals'
-import { isAbortError } from '../utils'
+import { abortableSleep, isAbortError } from '../utils'
 import type { AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
 
 export type EntryEvents = {
@@ -16,6 +16,21 @@ export type EntryOptions<T> = {
   retry?: RetryPolicy
   retryDelay?: RetryDelay
   events?: EntryEvents
+  /**
+   * Fired after a successful fetch result is written to `data`. Used by the
+   * `QueryClient` to emit a plugin-visible `SetDataEvent` with
+   * `source: 'fetch'` (devtools events live on `events` above). Distinct
+   * from `events.onFetchSuccess`, which carries timing info for the
+   * devtools bus.
+   *
+   * Privileged closure — set up by `ClientEntry` to call
+   * `client.emitSetData(...)`, which already individually try/catches every
+   * plugin via `callPlugin` and routes thrown exceptions through `onError`
+   * with `kind: 'plugin'`. Not wrapped here; an exception escaping this
+   * callback is a programming error in core (not a plugin) and SHOULD
+   * surface so the bug is visible.
+   */
+  onSuccessData?: (data: T) => void
 }
 
 type SnapshotRecord<T> = {
@@ -51,7 +66,16 @@ export class Entry<T> {
   private nextSnapshotId = 0
   private disposed = false
   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.
+  private readonly onSuccessData: ((data: unknown) => void) | undefined
   private fetchStartTime = 0
+  /**
+   * Promises returned by `firstValue()` that haven't settled. Rejected on
+   * `dispose()` so awaiters (most notably `prefetch` and `subscription.firstValue`)
+   * don't hang when the controller tree is torn down mid-fetch.
+   */
+  private pendingFirstValueRejects: Array<(err: unknown) => void> = []
 
   constructor(options: EntryOptions<T>) {
     this.fetcherProvider = options.fetcher
@@ -59,11 +83,31 @@ export class Entry<T> {
     this.retry = options.retry ?? 0
     this.retryDelay = options.retryDelay ?? 1000
     this.events = options.events ?? {}
+    this.onSuccessData = options.onSuccessData as ((data: unknown) => void) | undefined
     this.data = signal<T | undefined>(options.initialData)
     if (options.initialData !== undefined) {
       this.status = signal<AsyncStatus>('success')
-      this.scheduleStaleness()
-      this.isStale.set(this.staleTime === 0)
+      // For hydrated data, derive `isStale` from the *actual* age of the
+      // payload, not the timer alone — otherwise a payload older than
+      // `staleTime` would read `isStale === false` until the (fresh, full-
+      // length) timer fires. `isStaleNow()` already does this correctly for
+      // the subscribe-time refetch check; mirror that here for the signal.
+      if (this.staleTime === 0) {
+        this.isStale.set(true)
+      } else {
+        const last = options.initialUpdatedAt
+        const alreadyStale = last === undefined || Date.now() - last >= this.staleTime
+        this.isStale.set(alreadyStale)
+        // Only schedule a timer if the data isn't already stale. If it is,
+        // there's nothing to wait for.
+        if (!alreadyStale) {
+          const remaining = this.staleTime - (Date.now() - (last as number))
+          this.staleTimer = setTimeout(() => {
+            this.staleTimer = null
+            if (!this.disposed) this.isStale.set(true)
+          }, remaining)
+        }
+      }
     } else {
       this.status = signal<AsyncStatus>('idle')
     }
@@ -151,6 +195,7 @@ export class Entry<T> {
     } catch {
       // devtools handlers must not break the program.
     }
+    this.onSuccessData?.(result)
     return result
   }
 
@@ -241,19 +286,10 @@ export class Entry<T> {
     }
   }
 
-  finalizeSnapshot(snapshot: Snapshot): void {
-    const id = snapshotIds.get(snapshot)
-    if (id === undefined) return
-    const record = this.snapshots.find((s) => s.live && s.id === id)
-    if (!record) return
-    record.live = false
-    this.snapshots = this.snapshots.filter((s) => s !== record)
-    if (!this.snapshots.some((s) => s.live)) {
-      this.hasPendingMutations.set(false)
-    }
-  }
-
   firstValue(): Promise<T> {
+    if (this.disposed) {
+      return Promise.reject(new DOMException('Entry disposed', 'AbortError'))
+    }
     if (this.status.peek() === 'success') {
       return Promise.resolve(this.data.peek() as T)
     }
@@ -261,13 +297,19 @@ export class Entry<T> {
       return Promise.reject(this.error.peek())
     }
     return new Promise<T>((resolve, reject) => {
+      const tracked = (err: unknown): void => {
+        this.pendingFirstValueRejects = this.pendingFirstValueRejects.filter((f) => f !== tracked)
+        reject(err)
+      }
+      this.pendingFirstValueRejects.push(tracked)
       const unsub = this.status.subscribe((s) => {
         if (s === 'success') {
           unsub()
+          this.pendingFirstValueRejects = this.pendingFirstValueRejects.filter((f) => f !== tracked)
           resolve(this.data.peek() as T)
         } else if (s === 'error') {
           unsub()
-          reject(this.error.peek())
+          tracked(this.error.peek())
         }
       })
     })
@@ -292,31 +334,11 @@ export class Entry<T> {
     }
     this.currentAbort?.abort()
     this.currentAbort = null
-  }
-}
-
-const snapshotIds = new WeakMap<Snapshot, number>()
-
-export function tagSnapshot(snapshot: Snapshot, id: number): Snapshot {
-  snapshotIds.set(snapshot, id)
-  return snapshot
-}
-
-function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal.aborted) {
-      reject(new DOMException('Aborted', 'AbortError'))
-      return
+    if (this.pendingFirstValueRejects.length > 0) {
+      const disposed = new DOMException('Entry disposed', 'AbortError')
+      const rejects = this.pendingFirstValueRejects
+      this.pendingFirstValueRejects = []
+      for (const fn of rejects) fn(disposed)
     }
-    const timer = setTimeout(() => {
-      signal.removeEventListener('abort', onAbort)
-      resolve()
-    }, ms)
-    const onAbort = () => {
-      clearTimeout(timer)
-      signal.removeEventListener('abort', onAbort)
-      reject(new DOMException('Aborted', 'AbortError'))
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-  })
+  }
 }