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

package/src/query/infinite.ts

@@ -1,7 +1,7 @@
 import { batch, computed, type Signal, signal } from '../signals'
 import type { ReadSignal } from '../signals/types'
-import { isAbortError } from '../utils'
-import type { AsyncState, AsyncStatus, RetryDelay, RetryPolicy } from './types'
+import { abortableSleep, isAbortError } from '../utils'
+import type { AsyncState, AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
 
 /**
  * Configuration for `defineInfiniteQuery({ ... })`. Spec §5.7, §20.4.
@@ -58,9 +58,7 @@ export type InfiniteQuery<Args extends unknown[], TPage, _TItem> = {
   readonly __olas: 'infiniteQuery'
   invalidate(...args: Args): void
   invalidateAll(): void
-  setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): {
-    rollback: () => void
-  }
+  setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): Snapshot
   prefetch(...args: Args): Promise<TPage>
 }
 
@@ -83,8 +81,6 @@ export type InfiniteQuerySubscription<TPage, TItem> = AsyncState<TPage[]> & {
   fetchPreviousPage: () => Promise<void>
 }
 
-import type { Snapshot } from './types'
-
 /**
  * Holds an array of pages plus their pageParams. Supports fetchNextPage /
  * fetchPreviousPage / invalidate (drops all pages). Race-protected.
@@ -116,6 +112,8 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
   private snapshots: Array<{ id: number; prev: TPage[]; live: boolean }> = []
   private nextSnapshotId = 0
   private disposed = false
+  /** Mirrors `Entry.pendingFirstValueRejects` — see that field for context. */
+  private pendingFirstValueRejects: Array<(err: unknown) => void> = []
 
   private readonly fetcher: (pageCtx: {
     pageParam: PageParam
@@ -130,6 +128,13 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
   private readonly retry: RetryPolicy
   private readonly retryDelay: RetryDelay
   private readonly itemsOf?: (page: TPage) => TItem[]
+  /**
+   * Mirrors `Entry.onSuccessData`. Fires from `applyFetchSuccess`-equivalent
+   * branches AFTER `pages.set(...)` settles. Used by `InfiniteClientEntry`
+   * to emit `SetDataEvent { kind: 'infinite', source: 'fetch' }` for
+   * `QueryClientPlugin`s (e.g. entity normalization).
+   */
+  private readonly onSuccessData?: (pages: TPage[]) => void
 
   constructor(opts: {
     fetcher: (pageCtx: { pageParam: PageParam; signal: AbortSignal }) => Promise<TPage>
@@ -140,6 +145,7 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     staleTime?: number
     retry?: RetryPolicy
     retryDelay?: RetryDelay
+    onSuccessData?: (pages: TPage[]) => void
   }) {
     this.fetcher = opts.fetcher
     this.initialPageParam = opts.initialPageParam
@@ -149,6 +155,7 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     this.staleTime = opts.staleTime ?? 0
     this.retry = opts.retry ?? 0
     this.retryDelay = opts.retryDelay ?? 1000
+    this.onSuccessData = opts.onSuccessData
     this.pageParams = signal<PageParam[]>([])
     this.data = computed(() => {
       const ps = this.pages.value
@@ -209,6 +216,7 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
           this.isStale.set(this.staleTime === 0)
         })
         if (this.staleTime > 0) this.scheduleStaleness()
+        this.onSuccessData?.(this.pages.peek())
       },
       'initial',
     )
@@ -246,6 +254,7 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
           this.isFetching.set(false)
           this.lastUpdatedAt.set(Date.now())
         })
+        this.onSuccessData?.(this.pages.peek())
       },
       'next',
     ).then(() => {})
@@ -284,6 +293,7 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
           this.isFetching.set(false)
           this.lastUpdatedAt.set(Date.now())
         })
+        this.onSuccessData?.(this.pages.peek())
       },
       'prev',
     ).then(() => {})
@@ -297,38 +307,54 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     direction: 'initial' | 'next' | 'prev',
   ): Promise<TPage> {
     let attempt = 0
-    while (true) {
-      if (myId !== this.currentFetchId || this.disposed) {
-        throw new DOMException('Superseded', 'AbortError')
-      }
-      try {
-        const page = await this.fetcher({ pageParam, signal })
+    let succeeded = false
+    try {
+      while (true) {
         if (myId !== this.currentFetchId || this.disposed) {
           throw new DOMException('Superseded', 'AbortError')
         }
-        onSuccess(page, pageParam)
-        return page
-      } catch (err) {
-        if (myId !== this.currentFetchId || this.disposed || isAbortError(err)) {
-          throw err
+        try {
+          const page = await this.fetcher({ pageParam, signal })
+          if (myId !== this.currentFetchId || this.disposed) {
+            throw new DOMException('Superseded', 'AbortError')
+          }
+          onSuccess(page, pageParam)
+          succeeded = true
+          return page
+        } 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)
+              if (direction === 'next') this.isFetchingNextPage.set(false)
+              if (direction === 'prev') this.isFetchingPreviousPage.set(false)
+            })
+            throw err
+          }
+          const delay =
+            typeof this.retryDelay === 'function' ? this.retryDelay(attempt) : this.retryDelay
+          await abortableSleep(delay, signal)
+          attempt += 1
         }
-        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)
-            if (direction === 'next') this.isFetchingNextPage.set(false)
-            if (direction === 'prev') this.isFetchingPreviousPage.set(false)
-          })
-          throw err
-        }
-        const delay =
-          typeof this.retryDelay === 'function' ? this.retryDelay(attempt) : this.retryDelay
-        await abortableSleep(delay, signal)
-        attempt += 1
+      }
+    } finally {
+      // Catch-all reset for the supersede/abort path. The success and explicit
+      // failure paths already reset these via `onSuccess` and the
+      // `applyFailure`-equivalent branch above; this guarantees that an
+      // aborted-mid-flight `fetchNextPage` (e.g., user calls `invalidate()`
+      // while paging) doesn't wedge the spinner.
+      if (!succeeded) {
+        batch(() => {
+          if (direction === 'next') this.isFetchingNextPage.set(false)
+          if (direction === 'prev') this.isFetchingPreviousPage.set(false)
+        })
       }
     }
   }
@@ -395,6 +421,9 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
   }
 
   firstValue(): Promise<TPage[]> {
+    if (this.disposed) {
+      return Promise.reject(new DOMException('Entry disposed', 'AbortError'))
+    }
     if (this.status.peek() === 'success') {
       return Promise.resolve(this.pages.peek())
     }
@@ -402,13 +431,19 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
       return Promise.reject(this.error.peek())
     }
     return new Promise<TPage[]>((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.pages.peek())
         } else if (s === 'error') {
           unsub()
-          reject(this.error.peek())
+          tracked(this.error.peek())
         }
       })
     })
@@ -439,24 +474,11 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
     }
     this.currentAbort?.abort()
     this.currentAbort = null
-  }
-}
-
-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 })
-  })
+  }
 }

package/src/query/mutation.ts

@@ -2,7 +2,7 @@ import type { DevtoolsEmitter } from '../devtools'
 import { dispatchError, type ErrorHandler } from '../errors'
 import { batch, type Signal, signal } from '../signals'
 import type { ReadSignal } from '../signals/types'
-import { isAbortError } from '../utils'
+import { abortableSleep, isAbortError } from '../utils'
 import type { RetryDelay, RetryPolicy, Snapshot } from './types'
 
 /**
@@ -299,7 +299,16 @@ class MutationImpl<V, R> implements Mutation<V, R> {
   reset(): void {
     if (this.disposed) return
     for (const handle of this.inflight) handle.abort.abort()
-    this.serialQueue.length = 0
+    // Reject queued serial runs so their awaiters don't hang — symmetric with
+    // `dispose()`. Without this, callers of `mutation.run(...)` on a serial
+    // mutation that get reset mid-queue wait forever.
+    if (this.serialQueue.length > 0) {
+      const aborted = new DOMException('Aborted', 'AbortError')
+      const queue = this.serialQueue
+      this.serialQueue = []
+      for (const queued of queue) queued.reject(aborted)
+    }
+    this.serialActive = false
     batch(() => {
       this.data.set(undefined)
       this.error.set(undefined)
@@ -363,22 +372,3 @@ function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
     )
   })
 }
-
-function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal.aborted) {
-      reject(new DOMException('Aborted', 'AbortError'))
-      return
-    }
-    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 })
-  })
-}

package/src/query/plugin.ts

@@ -30,10 +30,48 @@ export type QueryClientPluginApi = {
    */
   applyRemoteSetData(queryId: string, keyArgs: readonly unknown[], data: unknown): void
   applyRemoteInvalidate(queryId: string, keyArgs: readonly unknown[]): void
+  /**
+   * Apply a local-originated `setData` to the entry identified by
+   * `(queryId, keyArgs)`. The resulting plugin events fire with
+   * `isRemote: false` and `source: 'set'` — cross-tab plugins WILL
+   * rebroadcast (the write is treated as if a controller called
+   * `client.setData(...)` directly).
+   *
+   * Drops silently when the queryId is unknown, the registered query is
+   * infinite, or no local entry exists for that key. The `updater`
+   * receives the previous data (typed as `unknown` because plugins are
+   * type-erased) and returns the next.
+   *
+   * Use case: entity-normalization plugins that want to backpropagate an
+   * `entity.update(...)` patch into every query holding that entity.
+   * Mutations / optimistic updates already go through the public
+   * `client.setData` and don't need this API.
+   */
+  setEntryData(
+    queryId: string,
+    keyArgs: readonly unknown[],
+    updater: (prev: unknown) => unknown,
+  ): void
   /**
    * Snapshot of currently bound entry keys for a query (by `queryId`). Empty
    * array when the query isn't registered, has no client entries, or the
    * `queryId` doesn't match any registered query.
+   *
+   * @example
+   * ```ts
+   * // Plugin sees an incoming invalidate; only echo it outward if any local
+   * // controller is actually subscribed to that key — otherwise the message
+   * // is unilateral noise.
+   * const plugin: QueryClientPlugin = {
+   *   init(api) { this.api = api },
+   *   onInvalidate(ev) {
+   *     if (ev.isRemote) return
+   *     const subscribed = this.api.subscribedKeys(ev.queryId)
+   *     if (subscribed.length === 0) return // no local subscribers → don't send
+   *     transport.send({ type: 'invalidate', queryId: ev.queryId, keyArgs: ev.keyArgs })
+   *   },
+   * }
+   * ```
    */
   subscribedKeys(queryId: string): readonly (readonly unknown[])[]
 }
@@ -53,6 +91,18 @@ export type SetDataEvent = {
    * skip rebroadcast in that case — otherwise the message would echo back.
    */
   isRemote: boolean
+  /**
+   * Origin of the write. `'set'` covers explicit `client.setData` (mutations,
+   * optimistic updates, plugin-initiated patches). `'fetch'` fires when the
+   * query fetcher resolved successfully and wrote the result into the entry
+   * — emitted after the data signal is settled. `'remote'` is the
+   * `applyRemoteSetData` path (cross-tab / server-push); equivalent to
+   * `isRemote === true`.
+   *
+   * Layered plugins use this to decide whether to react: cross-tab broadcasts
+   * only on `'set'`, an entity-normalization plugin observes all sources.
+   */
+  source: 'set' | 'fetch' | 'remote'
 }
 
 export type InvalidateEvent = {

package/src/query/use.ts

@@ -84,7 +84,15 @@ export function createUse<Args extends unknown[], T>(
   client: QueryClient,
   query: Query<Args, T>,
   keyOrOptions?: (() => Args) | UseOptions<Args>,
-): { subscription: QuerySubscription<T>; dispose: () => void } {
+): {
+  subscription: QuerySubscription<T>
+  dispose: () => void
+  /** Suspend the subscription — release the entry (its refetchInterval +
+   *  focus/online listeners pause) without disposing it. Spec §4.1. */
+  suspend: () => void
+  /** Resume after `suspend`. Re-acquires the entry and refetches if stale. */
+  resume: () => void
+} {
   const internal = query as unknown as QueryInternal<Args, T>
   const spec = internal.__spec
   const keepPreviousData = spec.keepPreviousData ?? false
@@ -95,8 +103,10 @@ export function createUse<Args extends unknown[], T>(
 
   const sub = new SubscriptionImpl<T>(keepPreviousData)
   let currentEntry: ClientEntry<T> | null = null
+  let suspended = false
 
   const effectDispose = effect(() => {
+    if (suspended) return
     const isEnabled = enabledFn ? enabledFn() : true
     if (!isEnabled) {
       untracked(() => {
@@ -138,7 +148,43 @@ export function createUse<Args extends unknown[], T>(
     sub.detach()
   }
 
-  return { subscription: sub, dispose }
+  const suspend = (): void => {
+    if (suspended) return
+    suspended = true
+    if (currentEntry) {
+      currentEntry.release()
+      currentEntry = null
+    }
+    // Keep subscription detached so reads return the last committed values
+    // via the entry's signals if still alive (the entry may be gc'd after
+    // its gcTime; that's fine — resume re-binds).
+  }
+
+  const resume = (): void => {
+    if (!suspended) return
+    suspended = false
+    // Re-evaluate the keyFn + enabled flag and rebind. The effect's deps
+    // didn't change while suspended, so toggling `suspended` here doesn't
+    // re-fire the effect on its own — force a sync rebind through the same
+    // code path.
+    const isEnabled = enabledFn ? enabledFn() : true
+    if (!isEnabled) return
+    const args = (keyFn ? keyFn() : ([] as unknown as Args)) as Args
+    const entry = client.bindEntry<Args, T>(query, args)
+    entry.acquire()
+    currentEntry = entry
+    sub.attach(entry)
+    // On resume, refetch if stale (matches the spec §4.1 "stale-on-resume"
+    // requirement). Non-stale data stays as-is.
+    const status = entry.entry.status.peek()
+    if (status === 'idle' || entry.entry.isStaleNow() || status === 'error') {
+      entry.entry.startFetch().catch(() => {
+        /* error captured on entry */
+      })
+    }
+  }
+
+  return { subscription: sub, dispose, suspend, resume }
 }
 
 type InfiniteQueryInternal<Args extends unknown[], TPage, TItem> = InfiniteQuery<
@@ -265,6 +311,8 @@ export function createInfiniteUse<Args extends unknown[], TPage, TItem>(
 ): {
   subscription: InfiniteQuerySubscription<TPage, TItem>
   dispose: () => void
+  suspend: () => void
+  resume: () => void
 } {
   const spec = (query as unknown as InfiniteQueryInternal<Args, TPage, TItem>).__spec
   const keepPreviousData = spec.keepPreviousData ?? false
@@ -274,8 +322,10 @@ export function createInfiniteUse<Args extends unknown[], TPage, TItem>(
 
   const sub = new InfiniteSubscriptionImpl<TPage, TItem>(keepPreviousData)
   let currentEntry: InfiniteClientEntry<TPage, TItem, unknown> | null = null
+  let suspended = false
 
   const effectDispose = effect(() => {
+    if (suspended) return
     const isEnabled = enabledFn ? enabledFn() : true
     if (!isEnabled) {
       untracked(() => {
@@ -317,5 +367,32 @@ export function createInfiniteUse<Args extends unknown[], TPage, TItem>(
     sub.detach()
   }
 
-  return { subscription: sub, dispose }
+  const suspend = (): void => {
+    if (suspended) return
+    suspended = true
+    if (currentEntry) {
+      currentEntry.release()
+      currentEntry = null
+    }
+  }
+
+  const resume = (): void => {
+    if (!suspended) return
+    suspended = false
+    const isEnabled = enabledFn ? enabledFn() : true
+    if (!isEnabled) return
+    const args = (keyFn ? keyFn() : ([] as unknown as Args)) as Args
+    const entry = client.bindInfiniteEntry<Args, TPage, TItem>(query, args)
+    entry.acquire()
+    currentEntry = entry
+    sub.attach(entry)
+    const status = entry.entry.status.peek()
+    if (status === 'idle' || entry.entry.isStaleNow() || status === 'error') {
+      entry.entry.startFetch().catch(() => {
+        /* error captured on entry */
+      })
+    }
+  }
+
+  return { subscription: sub, dispose, suspend, resume }
 }

package/src/utils.ts

@@ -11,3 +11,27 @@ export function isAbortError(err: unknown): boolean {
   }
   return false
 }
+
+/**
+ * `setTimeout` wrapped in a promise that rejects with `AbortError` if the
+ * passed signal fires. Internal — used by the retry loops in `Entry`,
+ * `InfiniteEntry`, and `Mutation` so a slow backoff never blocks a supersede.
+ */
+export function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new DOMException('Aborted', 'AbortError'))
+      return
+    }
+    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 })
+  })
+}