@kontsedal/olas-core 0.0.1-rc.0

package/src/query/define.ts

@@ -0,0 +1,154 @@
+import type { QueryClient } from './client'
+import type { InfiniteQuery, InfiniteQuerySpec } from './infinite'
+import { type RegisteredQuery, registerQueryById } from './plugin'
+import type { Query, QuerySpec, Snapshot } from './types'
+
+type QueryInternal<Args extends unknown[], T> = Query<Args, T> & {
+  readonly __spec: QuerySpec<Args, T>
+  __clients: Set<QueryClient>
+}
+
+const warnedMissingId = new WeakSet<object>()
+
+function registerQueryId(spec: { queryId?: string; crossTab?: boolean }, query: object): void {
+  if (spec.queryId != null) {
+    registerQueryById(spec.queryId, query as RegisteredQuery)
+  } else if (spec.crossTab === true) {
+    // Plugins can't route a message without a `queryId`. Warn once per
+    // offending spec — repeated warnings on every render would be noisy.
+    if (__DEV__ && !warnedMissingId.has(spec as object)) {
+      warnedMissingId.add(spec as object)
+      console.warn(
+        '[olas] defineQuery({ crossTab: true }) requires a stable `queryId`. ' +
+          'Add `queryId: "<unique-string>"` to the spec. Cross-tab sync is disabled for this query.',
+      )
+    }
+  }
+}
+
+/**
+ * Define a keyed, shared query. The returned Query value lives at module
+ * scope; per-root QueryClients bind their own entry registries to it.
+ */
+export function defineQuery<Args extends unknown[], T>(spec: QuerySpec<Args, T>): Query<Args, T> {
+  const clients = new Set<QueryClient>()
+  const query = {
+    __olas: 'query' as const,
+    __spec: spec,
+    __clients: clients,
+
+    invalidate(...args: Args): void {
+      for (const client of clients) {
+        client.invalidate(query as Query<Args, T>, args)
+      }
+    },
+
+    invalidateAll(): void {
+      for (const client of clients) {
+        client.invalidateAll(query as Query<Args, T>)
+      }
+    },
+
+    setData(...rest: [...Args, updater: (prev: T | undefined) => T]): Snapshot {
+      const updater = rest[rest.length - 1] as (prev: T | undefined) => T
+      const keyArgs = rest.slice(0, -1) as unknown as Args
+      const childSnapshots: Snapshot[] = []
+      for (const client of clients) {
+        childSnapshots.push(client.setData(query as Query<Args, T>, keyArgs, updater))
+      }
+      return {
+        rollback: () => {
+          for (const s of childSnapshots) s.rollback()
+        },
+        finalize: () => {
+          for (const s of childSnapshots) s.finalize()
+        },
+      }
+    },
+
+    prefetch(...args: Args): Promise<T> {
+      // Single-client common case; if none, throw.
+      const [first] = clients
+      if (!first) {
+        return Promise.reject(new Error('[olas] prefetch called before any root has subscribed'))
+      }
+      return first.prefetch(query as Query<Args, T>, args)
+    },
+  } satisfies QueryInternal<Args, T>
+
+  registerQueryId(spec, query)
+  return query as Query<Args, T>
+}
+
+type InfiniteQueryInternal<Args extends unknown[], TPage, TItem> = InfiniteQuery<
+  Args,
+  TPage,
+  TItem
+> & {
+  readonly __spec: InfiniteQuerySpec<Args, any, TPage, TItem>
+  __clients: Set<QueryClient>
+}
+
+/**
+ * Define a paginated query (chat-style "load more", infinite scrolling). Pages
+ * are kept in order and concatenated via `getNextPageParam` /
+ * `getPreviousPageParam`. The returned handle is module-scoped — bind
+ * subscribers via `ctx.use(infiniteQuery, () => [...args])`. Spec §5.7,
+ * §20.4.
+ */
+export function defineInfiniteQuery<Args extends unknown[], PageParam, TPage, TItem = TPage>(
+  spec: InfiniteQuerySpec<Args, PageParam, TPage, TItem>,
+): InfiniteQuery<Args, TPage, TItem> {
+  const clients = new Set<QueryClient>()
+  const query = {
+    __olas: 'infiniteQuery' as const,
+    __spec: spec,
+    __clients: clients,
+
+    invalidate(...args: Args): void {
+      for (const client of clients) {
+        client.invalidateInfinite(query as InfiniteQuery<Args, TPage, TItem>, args)
+      }
+    },
+
+    invalidateAll(): void {
+      for (const client of clients) {
+        client.invalidateAllInfinite(query as InfiniteQuery<Args, TPage, TItem>)
+      }
+    },
+
+    setData(...rest: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): Snapshot {
+      const updater = rest[rest.length - 1] as (prev: TPage[] | undefined) => TPage[]
+      const keyArgs = rest.slice(0, -1) as unknown as Args
+      const childSnapshots: Snapshot[] = []
+      for (const client of clients) {
+        childSnapshots.push(
+          client.setInfiniteData<Args, TPage>(
+            query as InfiniteQuery<Args, TPage, TItem>,
+            keyArgs,
+            updater,
+          ),
+        )
+      }
+      return {
+        rollback: () => {
+          for (const s of childSnapshots) s.rollback()
+        },
+        finalize: () => {
+          for (const s of childSnapshots) s.finalize()
+        },
+      }
+    },
+
+    prefetch(...args: Args): Promise<TPage> {
+      const [first] = clients
+      if (!first) {
+        return Promise.reject(new Error('[olas] prefetch called before any root has subscribed'))
+      }
+      return first.prefetchInfinite(query as InfiniteQuery<Args, TPage, TItem>, args)
+    },
+  } satisfies InfiniteQueryInternal<Args, TPage, TItem>
+
+  registerQueryId(spec, query)
+  return query as InfiniteQuery<Args, TPage, TItem>
+}

package/src/query/entry.ts

@@ -0,0 +1,322 @@
+import { batch, type Signal, signal } from '../signals'
+import { isAbortError } from '../utils'
+import type { AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
+
+export type EntryEvents = {
+  onFetchStart?: () => void
+  onFetchSuccess?: (durationMs: number) => void
+  onFetchError?: (durationMs: number, error: unknown) => void
+}
+
+export type EntryOptions<T> = {
+  fetcher: () => (signal: AbortSignal) => Promise<T>
+  staleTime?: number
+  initialData?: T | undefined
+  initialUpdatedAt?: number | undefined
+  retry?: RetryPolicy
+  retryDelay?: RetryDelay
+  events?: EntryEvents
+}
+
+type SnapshotRecord<T> = {
+  id: number
+  prev: T | undefined
+  live: boolean
+}
+
+/**
+ * One cache entry's state machine. Owns the AsyncState signals, race
+ * protection, retry loop, optimistic-update snapshot stack.
+ *
+ * Internal — not exported from the public surface.
+ */
+export class Entry<T> {
+  readonly data: Signal<T | undefined>
+  readonly error: Signal<unknown | undefined> = signal(undefined)
+  readonly status: Signal<AsyncStatus>
+  readonly isLoading: Signal<boolean> = signal(false)
+  readonly isFetching: Signal<boolean> = signal(false)
+  readonly lastUpdatedAt: Signal<number | undefined>
+  readonly hasPendingMutations: Signal<boolean> = signal(false)
+  readonly isStale: Signal<boolean> = signal(true)
+
+  fetcherProvider: () => (signal: AbortSignal) => Promise<T>
+  private staleTime: number
+  private retry: RetryPolicy
+  private retryDelay: RetryDelay
+  private currentFetchId = 0
+  private currentAbort: AbortController | null = null
+  private staleTimer: ReturnType<typeof setTimeout> | null = null
+  private snapshots: Array<SnapshotRecord<T>> = []
+  private nextSnapshotId = 0
+  private disposed = false
+  private readonly events: EntryEvents
+  private fetchStartTime = 0
+
+  constructor(options: EntryOptions<T>) {
+    this.fetcherProvider = options.fetcher
+    this.staleTime = options.staleTime ?? 0
+    this.retry = options.retry ?? 0
+    this.retryDelay = options.retryDelay ?? 1000
+    this.events = options.events ?? {}
+    this.data = signal<T | undefined>(options.initialData)
+    if (options.initialData !== undefined) {
+      this.status = signal<AsyncStatus>('success')
+      this.scheduleStaleness()
+      this.isStale.set(this.staleTime === 0)
+    } else {
+      this.status = signal<AsyncStatus>('idle')
+    }
+    this.lastUpdatedAt = signal<number | undefined>(options.initialUpdatedAt)
+  }
+
+  startFetch(): Promise<T> {
+    if (this.disposed) {
+      return Promise.reject(new Error('Entry disposed'))
+    }
+    const myId = ++this.currentFetchId
+    this.currentAbort?.abort()
+    const abort = new AbortController()
+    this.currentAbort = abort
+
+    const previouslyHadData = this.data.peek() !== undefined
+    batch(() => {
+      this.status.set('pending')
+      this.isFetching.set(true)
+      this.isLoading.set(!previouslyHadData)
+    })
+
+    this.fetchStartTime = Date.now()
+    try {
+      this.events.onFetchStart?.()
+    } catch {
+      // devtools handlers must not break the program.
+    }
+
+    return this.runWithRetry(myId, abort)
+  }
+
+  private async runWithRetry(myId: number, abort: AbortController): Promise<T> {
+    let attempt = 0
+    while (true) {
+      if (myId !== this.currentFetchId || this.disposed) {
+        throw new DOMException('Superseded', 'AbortError')
+      }
+      try {
+        const fetcher = this.fetcherProvider()
+        const result = await fetcher(abort.signal)
+        if (myId !== this.currentFetchId || this.disposed) {
+          throw new DOMException('Superseded', 'AbortError')
+        }
+        return this.applySuccess(result)
+      } catch (err) {
+        if (myId !== this.currentFetchId || this.disposed || isAbortError(err)) {
+          throw err
+        }
+        if (!this.shouldRetry(attempt, err)) {
+          return this.applyFailure(err)
+        }
+        const delay = this.computeDelay(attempt)
+        await abortableSleep(delay, abort.signal)
+        attempt += 1
+      }
+    }
+  }
+
+  private shouldRetry(attempt: number, err: unknown): boolean {
+    const retry = this.retry
+    if (retry === 0) return false
+    if (typeof retry === 'number') return attempt < retry
+    return retry(attempt, err)
+  }
+
+  private computeDelay(attempt: number): number {
+    const d = this.retryDelay
+    return typeof d === 'function' ? d(attempt) : d
+  }
+
+  private applySuccess(result: T): T {
+    batch(() => {
+      this.data.set(result)
+      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()
+    try {
+      this.events.onFetchSuccess?.(Date.now() - this.fetchStartTime)
+    } catch {
+      // devtools handlers must not break the program.
+    }
+    return result
+  }
+
+  private applyFailure(err: unknown): never {
+    batch(() => {
+      this.error.set(err)
+      this.status.set('error')
+      this.isLoading.set(false)
+      this.isFetching.set(false)
+    })
+    try {
+      this.events.onFetchError?.(Date.now() - this.fetchStartTime, err)
+    } catch {
+      // devtools handlers must not break the program.
+    }
+    throw err
+  }
+
+  private scheduleStaleness(): void {
+    if (this.staleTimer != null) clearTimeout(this.staleTimer)
+    if (this.staleTime > 0) {
+      this.staleTimer = setTimeout(() => {
+        this.staleTimer = null
+        if (!this.disposed) this.isStale.set(true)
+      }, this.staleTime)
+    }
+  }
+
+  refetch(): Promise<T> {
+    return this.startFetch()
+  }
+
+  invalidate(): Promise<T> {
+    if (this.staleTimer != null) {
+      clearTimeout(this.staleTimer)
+      this.staleTimer = null
+    }
+    this.isStale.set(true)
+    return this.startFetch()
+  }
+
+  reset(): void {
+    if (this.disposed) return
+    batch(() => {
+      this.error.set(undefined)
+      this.status.set(this.data.peek() !== undefined ? 'success' : 'idle')
+    })
+  }
+
+  setData(updater: (prev: T | undefined) => T): 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)
+
+    batch(() => {
+      this.data.set(next)
+      if (this.status.peek() === 'idle' || this.status.peek() === 'pending') {
+        this.status.set('success')
+      }
+      this.lastUpdatedAt.set(Date.now())
+      this.hasPendingMutations.set(true)
+    })
+
+    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)
+        })
+      },
+      finalize: () => {
+        if (!record.live || this.disposed) return
+        record.live = false
+        this.snapshots = this.snapshots.filter((s) => s.id !== id)
+        if (!this.snapshots.some((s) => s.live)) {
+          this.hasPendingMutations.set(false)
+        }
+      },
+    }
+  }
+
+  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.status.peek() === 'success') {
+      return Promise.resolve(this.data.peek() as T)
+    }
+    if (this.status.peek() === 'error') {
+      return Promise.reject(this.error.peek())
+    }
+    return new Promise<T>((resolve, reject) => {
+      const unsub = this.status.subscribe((s) => {
+        if (s === 'success') {
+          unsub()
+          resolve(this.data.peek() as T)
+        } else if (s === 'error') {
+          unsub()
+          reject(this.error.peek())
+        }
+      })
+    })
+  }
+
+  /**
+   * True iff data is older than `staleTime` (or no data has been fetched yet).
+   * Used by the query client to decide whether to refetch on subscribe.
+   */
+  isStaleNow(): boolean {
+    const last = this.lastUpdatedAt.peek()
+    if (last === undefined) return true
+    return Date.now() - last >= this.staleTime
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    if (this.staleTimer != null) {
+      clearTimeout(this.staleTimer)
+      this.staleTimer = null
+    }
+    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
+    }
+    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/focus-online.ts

@@ -0,0 +1,73 @@
+/**
+ * Lazy pub/sub for window-focus and reconnect events.
+ *
+ * Each `ClientEntry` with `refetchOnWindowFocus` or `refetchOnReconnect` set
+ * subscribes here on its first subscriber and unsubscribes when it has none.
+ * We install a single window/document listener for each event the first time
+ * anyone subscribes; after that, we fan out to all subscribers ourselves.
+ *
+ * SSR-safe: no-ops when `window` is undefined. Spec §5.9.
+ */
+
+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 {
+      fn()
+    } catch {
+      // Subscriber failures must not break the fan-out.
+    }
+  }
+}
+
+function fireOnline(): void {
+  for (const fn of onlineSubs) {
+    try {
+      fn()
+    } catch {
+      // ditto
+    }
+  }
+}
+
+function ensureFocusInstalled(): void {
+  if (focusInstalled) return
+  if (typeof window === 'undefined') return
+  window.addEventListener('focus', fireFocus)
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'visible') fireFocus()
+    })
+  }
+  focusInstalled = true
+}
+
+function ensureOnlineInstalled(): void {
+  if (onlineInstalled) return
+  if (typeof window === 'undefined') return
+  window.addEventListener('online', fireOnline)
+  onlineInstalled = true
+}
+
+export function subscribeWindowFocus(fn: Sub): () => void {
+  ensureFocusInstalled()
+  focusSubs.add(fn)
+  return () => {
+    focusSubs.delete(fn)
+  }
+}
+
+export function subscribeReconnect(fn: Sub): () => void {
+  ensureOnlineInstalled()
+  onlineSubs.add(fn)
+  return () => {
+    onlineSubs.delete(fn)
+  }
+}

package/src/query/index.ts

@@ -0,0 +1,3 @@
+export type { LocalCacheOptions } from './local'
+export { createLocalCache } from './local'
+export type { AsyncState, AsyncStatus, LocalCache, Snapshot } from './types'