@kontsedal/olas-core 0.0.1-rc.0

package/src/query/use.ts

@@ -0,0 +1,321 @@
+import { computed, effect, type Signal, signal, untracked } from '../signals'
+import type { ReadSignal } from '../signals/types'
+import type { ClientEntry, InfiniteClientEntry, QueryClient } from './client'
+import type { InfiniteQuery, InfiniteQuerySpec, InfiniteQuerySubscription } from './infinite'
+import type { AsyncStatus, Query, QuerySpec, QuerySubscription, UseOptions } from './types'
+
+type QueryInternal<Args extends unknown[], T> = Query<Args, T> & {
+  readonly __spec: QuerySpec<Args, T>
+}
+
+class SubscriptionImpl<T> implements QuerySubscription<T> {
+  private readonly current$: Signal<ClientEntry<T> | null> = signal(null)
+  private readonly previousData$: Signal<T | undefined> = signal(undefined)
+
+  readonly data: ReadSignal<T | undefined>
+  readonly error: ReadSignal<unknown | undefined>
+  readonly status: ReadSignal<AsyncStatus>
+  readonly isLoading: ReadSignal<boolean>
+  readonly isFetching: ReadSignal<boolean>
+  readonly isStale: ReadSignal<boolean>
+  readonly lastUpdatedAt: ReadSignal<number | undefined>
+  readonly hasPendingMutations: ReadSignal<boolean>
+
+  constructor(private readonly keepPreviousData: boolean) {
+    this.data = computed(() => {
+      const cur = this.current$.value
+      const curData = cur?.entry.data.value
+      if (curData !== undefined) return curData
+      if (keepPreviousData) return this.previousData$.value
+      return undefined
+    })
+    this.error = computed(() => this.current$.value?.entry.error.value)
+    this.status = computed<AsyncStatus>(() => this.current$.value?.entry.status.value ?? 'idle')
+    this.isLoading = computed(() => {
+      const cur = this.current$.value
+      if (!cur) return false
+      if (keepPreviousData && this.previousData$.value !== undefined) return false
+      return cur.entry.isLoading.value
+    })
+    this.isFetching = computed(() => this.current$.value?.entry.isFetching.value ?? false)
+    this.isStale = computed(() => this.current$.value?.entry.isStale.value ?? true)
+    this.lastUpdatedAt = computed(() => this.current$.value?.entry.lastUpdatedAt.value)
+    this.hasPendingMutations = computed(
+      () => this.current$.value?.entry.hasPendingMutations.value ?? false,
+    )
+  }
+
+  attach(entry: ClientEntry<T>): void {
+    const prev = this.current$.peek()
+    if (prev === entry) return
+    if (prev && this.keepPreviousData) {
+      const prevData = prev.entry.data.peek()
+      if (prevData !== undefined) this.previousData$.set(prevData)
+    }
+    this.current$.set(entry)
+  }
+
+  detach(): void {
+    this.current$.set(null)
+  }
+
+  refetch = (): Promise<T> => {
+    const cur = this.current$.peek()
+    if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
+    return cur.entry.refetch()
+  }
+
+  reset = (): void => {
+    this.current$.peek()?.entry.reset()
+  }
+
+  firstValue = (): Promise<T> => {
+    const cur = this.current$.peek()
+    if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
+    return cur.entry.firstValue()
+  }
+}
+
+/**
+ * Build a subscription + the effect that keeps it bound to the right entry.
+ * The controller container wires the disposer into the lifecycle.
+ */
+export function createUse<Args extends unknown[], T>(
+  client: QueryClient,
+  query: Query<Args, T>,
+  keyOrOptions?: (() => Args) | UseOptions<Args>,
+): { subscription: QuerySubscription<T>; dispose: () => void } {
+  const internal = query as unknown as QueryInternal<Args, T>
+  const spec = internal.__spec
+  const keepPreviousData = spec.keepPreviousData ?? false
+
+  const keyFn = typeof keyOrOptions === 'function' ? keyOrOptions : keyOrOptions?.key
+  const enabledFn =
+    typeof keyOrOptions === 'object' && keyOrOptions !== null ? keyOrOptions.enabled : undefined
+
+  const sub = new SubscriptionImpl<T>(keepPreviousData)
+  let currentEntry: ClientEntry<T> | null = null
+
+  const effectDispose = effect(() => {
+    const isEnabled = enabledFn ? enabledFn() : true
+    if (!isEnabled) {
+      untracked(() => {
+        if (currentEntry) {
+          currentEntry.release()
+          currentEntry = null
+        }
+        sub.detach()
+      })
+      return
+    }
+
+    const args = (keyFn ? keyFn() : ([] as unknown as Args)) as Args
+
+    untracked(() => {
+      const entry = client.bindEntry<Args, T>(query, args)
+      if (currentEntry === entry) return
+      if (currentEntry) currentEntry.release()
+      entry.acquire()
+      currentEntry = entry
+      sub.attach(entry)
+
+      const status = entry.entry.status.peek()
+      const fetching = entry.entry.isFetching.peek()
+      if (!fetching && (status === 'idle' || entry.entry.isStaleNow() || status === 'error')) {
+        entry.entry.startFetch().catch(() => {
+          /* error captured on entry */
+        })
+      }
+    })
+  })
+
+  const dispose = () => {
+    effectDispose()
+    if (currentEntry) {
+      currentEntry.release()
+      currentEntry = null
+    }
+    sub.detach()
+  }
+
+  return { subscription: sub, dispose }
+}
+
+type InfiniteQueryInternal<Args extends unknown[], TPage, TItem> = InfiniteQuery<
+  Args,
+  TPage,
+  TItem
+> & {
+  readonly __spec: InfiniteQuerySpec<Args, any, TPage, TItem>
+}
+
+class InfiniteSubscriptionImpl<TPage, TItem> implements InfiniteQuerySubscription<TPage, TItem> {
+  private readonly current$: Signal<InfiniteClientEntry<TPage, TItem, unknown> | null> =
+    signal(null)
+  private readonly previousPages$: Signal<TPage[] | undefined> = signal(undefined)
+
+  readonly data: ReadSignal<TPage[] | undefined>
+  readonly pages: ReadSignal<TPage[]>
+  readonly flat: ReadSignal<TItem[]>
+  readonly error: ReadSignal<unknown | undefined>
+  readonly status: ReadSignal<AsyncStatus>
+  readonly isLoading: ReadSignal<boolean>
+  readonly isFetching: ReadSignal<boolean>
+  readonly isStale: ReadSignal<boolean>
+  readonly lastUpdatedAt: ReadSignal<number | undefined>
+  readonly hasPendingMutations: ReadSignal<boolean>
+  readonly hasNextPage: ReadSignal<boolean>
+  readonly hasPreviousPage: ReadSignal<boolean>
+  readonly isFetchingNextPage: ReadSignal<boolean>
+  readonly isFetchingPreviousPage: ReadSignal<boolean>
+
+  constructor(private readonly keepPreviousData: boolean) {
+    this.pages = computed(() => {
+      const cur = this.current$.value
+      const ps = cur?.entry.pages.value
+      if (ps && ps.length > 0) return ps
+      if (keepPreviousData) return this.previousPages$.value ?? []
+      return ps ?? []
+    })
+    this.data = computed(() => {
+      const cur = this.current$.value
+      const ps = cur?.entry.pages.value
+      if (ps && ps.length > 0) return ps
+      if (keepPreviousData) {
+        const prev = this.previousPages$.value
+        if (prev && prev.length > 0) return prev
+      }
+      return undefined
+    })
+    this.flat = computed(() => this.current$.value?.entry.flat.value ?? [])
+    this.error = computed(() => this.current$.value?.entry.error.value)
+    this.status = computed<AsyncStatus>(() => this.current$.value?.entry.status.value ?? 'idle')
+    this.isLoading = computed(() => {
+      const cur = this.current$.value
+      if (!cur) return false
+      if (keepPreviousData) {
+        const prev = this.previousPages$.value
+        if (prev && prev.length > 0) return false
+      }
+      return cur.entry.isLoading.value
+    })
+    this.isFetching = computed(() => this.current$.value?.entry.isFetching.value ?? false)
+    this.isStale = computed(() => this.current$.value?.entry.isStale.value ?? true)
+    this.lastUpdatedAt = computed(() => this.current$.value?.entry.lastUpdatedAt.value)
+    this.hasPendingMutations = computed(
+      () => this.current$.value?.entry.hasPendingMutations.value ?? false,
+    )
+    this.hasNextPage = computed(() => this.current$.value?.entry.hasNextPage.value ?? false)
+    this.hasPreviousPage = computed(() => this.current$.value?.entry.hasPreviousPage.value ?? false)
+    this.isFetchingNextPage = computed(
+      () => this.current$.value?.entry.isFetchingNextPage.value ?? false,
+    )
+    this.isFetchingPreviousPage = computed(
+      () => this.current$.value?.entry.isFetchingPreviousPage.value ?? false,
+    )
+  }
+
+  attach(entry: InfiniteClientEntry<TPage, TItem, unknown>): void {
+    const prev = this.current$.peek()
+    if (prev === entry) return
+    if (prev && this.keepPreviousData) {
+      const prevPages = prev.entry.pages.peek()
+      if (prevPages.length > 0) this.previousPages$.set(prevPages)
+    }
+    this.current$.set(entry)
+  }
+
+  detach(): void {
+    this.current$.set(null)
+  }
+
+  refetch = (): Promise<TPage[]> => {
+    const cur = this.current$.peek()
+    if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
+    return cur.entry.refetch().then(() => cur.entry.pages.peek())
+  }
+
+  reset = (): void => {
+    this.current$.peek()?.entry.reset()
+  }
+
+  firstValue = (): Promise<TPage[]> => {
+    const cur = this.current$.peek()
+    if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
+    return cur.entry.firstValue()
+  }
+
+  fetchNextPage = (): Promise<void> => {
+    const cur = this.current$.peek()
+    if (!cur) return Promise.resolve()
+    return cur.entry.fetchNextPage()
+  }
+
+  fetchPreviousPage = (): Promise<void> => {
+    const cur = this.current$.peek()
+    if (!cur) return Promise.resolve()
+    return cur.entry.fetchPreviousPage()
+  }
+}
+
+export function createInfiniteUse<Args extends unknown[], TPage, TItem>(
+  client: QueryClient,
+  query: InfiniteQuery<Args, TPage, TItem>,
+  keyOrOptions?: (() => Args) | UseOptions<Args>,
+): {
+  subscription: InfiniteQuerySubscription<TPage, TItem>
+  dispose: () => void
+} {
+  const spec = (query as unknown as InfiniteQueryInternal<Args, TPage, TItem>).__spec
+  const keepPreviousData = spec.keepPreviousData ?? false
+  const keyFn = typeof keyOrOptions === 'function' ? keyOrOptions : keyOrOptions?.key
+  const enabledFn =
+    typeof keyOrOptions === 'object' && keyOrOptions !== null ? keyOrOptions.enabled : undefined
+
+  const sub = new InfiniteSubscriptionImpl<TPage, TItem>(keepPreviousData)
+  let currentEntry: InfiniteClientEntry<TPage, TItem, unknown> | null = null
+
+  const effectDispose = effect(() => {
+    const isEnabled = enabledFn ? enabledFn() : true
+    if (!isEnabled) {
+      untracked(() => {
+        if (currentEntry) {
+          currentEntry.release()
+          currentEntry = null
+        }
+        sub.detach()
+      })
+      return
+    }
+
+    const args = (keyFn ? keyFn() : ([] as unknown as Args)) as Args
+
+    untracked(() => {
+      const entry = client.bindInfiniteEntry<Args, TPage, TItem>(query, args)
+      if (currentEntry === entry) return
+      if (currentEntry) currentEntry.release()
+      entry.acquire()
+      currentEntry = entry
+      sub.attach(entry)
+
+      const status = entry.entry.status.peek()
+      const fetching = entry.entry.isFetching.peek()
+      if (!fetching && (status === 'idle' || entry.entry.isStaleNow() || status === 'error')) {
+        entry.entry.startFetch().catch(() => {
+          /* error captured on entry */
+        })
+      }
+    })
+  })
+
+  const dispose = () => {
+    effectDispose()
+    if (currentEntry) {
+      currentEntry.release()
+      currentEntry = null
+    }
+    sub.detach()
+  }
+
+  return { subscription: sub, dispose }
+}

package/src/scope.ts

@@ -0,0 +1,42 @@
+/**
+ * Typed cross-tree data slot. Provided by an ancestor via `ctx.provide(scope, value)`
+ * and consumed anywhere in its subtree via `ctx.inject(scope)`. Defined at module
+ * scope so the identity is stable across calls. See spec §10.3.
+ */
+export type Scope<T> = {
+  readonly __olas: 'scope'
+  /** Per-scope identity; matches across `provide` / `inject`. */
+  readonly __id: symbol
+  /** Optional human-readable name (used in error messages). */
+  readonly name?: string
+  /** Default value used when no provider exists; `undefined` if none was set. */
+  readonly default?: T
+  /** True iff `defineScope` was called with a `default` (even `default: undefined`). */
+  readonly hasDefault: boolean
+  // Phantom for inference — typed `T` is preserved through the scope's lifetime.
+  readonly __t?: T
+}
+
+export type ScopeOptions<T> = {
+  default?: T
+  name?: string
+}
+
+/**
+ * Create a scope. The returned value is the typed handle passed to
+ * `ctx.provide(scope, value)` and `ctx.inject(scope)`. Identity is keyed by
+ * an internal symbol so two `defineScope()` calls — even with identical
+ * options — yield distinct scopes.
+ */
+export function defineScope<T>(options?: ScopeOptions<T>): Scope<T> {
+  const hasDefault = options !== undefined && 'default' in options
+  const name = options?.name
+  const scope: Scope<T> = {
+    __olas: 'scope',
+    __id: Symbol(name ?? 'scope'),
+    hasDefault,
+    ...(name !== undefined ? { name } : {}),
+    ...(hasDefault ? { default: options?.default as T } : {}),
+  }
+  return scope
+}

package/src/selection.ts

@@ -0,0 +1,146 @@
+import { computed, signal } from './signals'
+import { readOnly } from './signals/readonly'
+import type { ReadSignal } from './signals/types'
+
+/**
+ * Multi-select state for tables / lists with bulk actions (spec §17.5).
+ *
+ * Plain function — not bound to `ctx`. Place it in a controller's closure so
+ * it dies with the closure. The phantom `T` parameter brands the selection by
+ * item type; IDs are always strings.
+ */
+// biome-ignore lint/correctness/noUnusedVariables: phantom branding param (spec §17.5)
+export type Selection<T = unknown> = {
+  selectedIds: ReadSignal<ReadonlySet<string>>
+  size: ReadSignal<number>
+  isSelected(id: string): ReadSignal<boolean>
+
+  select(id: string): void
+  deselect(id: string): void
+  toggle(id: string): void
+  clear(): void
+  selectAll(ids: readonly string[]): void
+
+  handleClick(
+    id: string,
+    mods: { shift?: boolean; meta?: boolean },
+    ordered: readonly string[],
+  ): void
+}
+
+/**
+ * Create a `Selection<T>`. Optional `initial` seeds the selected set.
+ *
+ * `handleClick` encapsulates the standard click semantics:
+ * - plain click → select only `id` (anchor moves to `id`)
+ * - meta-click  → toggle `id` (anchor moves to `id` on add)
+ * - shift-click → range from anchor to `id` along `ordered` (anchor sticks,
+ *   so subsequent shift-clicks extend from the same origin)
+ *
+ * Spec §16.5 / §17.5.
+ */
+export function selection<T = unknown>(options?: { initial?: readonly string[] }): Selection<T> {
+  const ids = signal<ReadonlySet<string>>(new Set(options?.initial))
+  let anchor: string | null = options?.initial?.length
+    ? (options.initial[options.initial.length - 1] ?? null)
+    : null
+  // Snapshot of the selection just before the first shift-click of a run.
+  // Subsequent shift-clicks re-compute the range against this snapshot so the
+  // user can shrink or grow the range. Reset on any non-shift click.
+  let preShiftSelection: ReadonlySet<string> | null = null
+
+  const size = computed(() => ids.value.size)
+
+  const isSelected = (id: string): ReadSignal<boolean> => computed(() => ids.value.has(id))
+
+  const select = (id: string): void => {
+    const prev = ids.peek()
+    if (!prev.has(id)) {
+      const next = new Set(prev)
+      next.add(id)
+      ids.set(next)
+    }
+    anchor = id
+  }
+
+  const deselect = (id: string): void => {
+    const prev = ids.peek()
+    if (!prev.has(id)) return
+    const next = new Set(prev)
+    next.delete(id)
+    ids.set(next)
+  }
+
+  const toggle = (id: string): void => {
+    const prev = ids.peek()
+    const next = new Set(prev)
+    if (prev.has(id)) {
+      next.delete(id)
+    } else {
+      next.add(id)
+      anchor = id
+    }
+    ids.set(next)
+  }
+
+  const clear = (): void => {
+    if (ids.peek().size === 0) {
+      anchor = null
+      return
+    }
+    ids.set(new Set())
+    anchor = null
+  }
+
+  const selectAll = (incoming: readonly string[]): void => {
+    ids.set(new Set(incoming))
+    anchor = incoming.length > 0 ? (incoming[incoming.length - 1] ?? null) : null
+  }
+
+  const handleClick = (
+    id: string,
+    mods: { shift?: boolean; meta?: boolean },
+    ordered: readonly string[],
+  ): void => {
+    if (mods.shift && anchor !== null) {
+      const anchorIdx = ordered.indexOf(anchor)
+      const targetIdx = ordered.indexOf(id)
+      if (anchorIdx === -1 || targetIdx === -1) {
+        // anchor or target not visible — fall back to plain select
+        ids.set(new Set([id]))
+        anchor = id
+        preShiftSelection = null
+        return
+      }
+      if (preShiftSelection === null) {
+        preShiftSelection = ids.peek()
+      }
+      const [lo, hi] = anchorIdx < targetIdx ? [anchorIdx, targetIdx] : [targetIdx, anchorIdx]
+      const next = new Set(preShiftSelection)
+      for (const k of ordered.slice(lo, hi + 1)) next.add(k)
+      ids.set(next)
+      // Anchor stays — subsequent shift-clicks extend from the same origin.
+      return
+    }
+    // Any non-shift click ends the shift run.
+    preShiftSelection = null
+    if (mods.meta) {
+      toggle(id)
+      return
+    }
+    ids.set(new Set([id]))
+    anchor = id
+  }
+
+  return {
+    selectedIds: readOnly(ids),
+    size,
+    isSelected,
+    select,
+    deselect,
+    toggle,
+    clear,
+    selectAll,
+    handleClick,
+  }
+}

package/src/signals/index.ts

@@ -0,0 +1,3 @@
+export { readOnly } from './readonly'
+export { batch, computed, effect, signal, untracked } from './runtime'
+export type { Computed, ReadSignal, Signal } from './types'

package/src/signals/readonly.ts

@@ -0,0 +1,22 @@
+import type { ReadSignal } from './types'
+
+/**
+ * Project a Signal (or any object with a reactive `value` + `peek` + `subscribe`)
+ * as a `ReadSignal`. The returned object does not expose `set` / `update` /
+ * settable `value`, so it can be returned from APIs without callers mutating it.
+ *
+ * Internal helper — not exported from the package's public surface.
+ */
+export function readOnly<T>(source: ReadSignal<T>): ReadSignal<T> {
+  return {
+    get value() {
+      return source.value
+    },
+    peek() {
+      return source.peek()
+    },
+    subscribe(handler) {
+      return source.subscribe(handler)
+    },
+  }
+}

package/src/signals/runtime.ts

@@ -0,0 +1,115 @@
+import {
+  batch as _batch,
+  computed as _computed,
+  effect as _effect,
+  signal as _signal,
+  untracked as _untracked,
+  type ReadonlySignal as PreactReadonlySignal,
+  type Signal as PreactSignal,
+} from '@preact/signals-core'
+
+import type { Computed, Signal } from './types'
+
+class SignalImpl<T> implements Signal<T> {
+  private readonly inner: PreactSignal<T>
+
+  constructor(initial: T) {
+    this.inner = _signal<T>(initial)
+  }
+
+  get value(): T {
+    return this.inner.value
+  }
+
+  set value(next: T) {
+    this.inner.value = next
+  }
+
+  peek(): T {
+    return this.inner.peek()
+  }
+
+  subscribe(handler: (value: T) => void): () => void {
+    return this.inner.subscribe(handler)
+  }
+
+  set(value: T): void {
+    this.inner.value = value
+  }
+
+  update(fn: (prev: T) => T): void {
+    this.inner.value = fn(this.inner.peek())
+  }
+}
+
+class ComputedImpl<T> implements Computed<T> {
+  private readonly inner: PreactReadonlySignal<T>
+
+  constructor(fn: () => T) {
+    this.inner = _computed<T>(fn)
+  }
+
+  get value(): T {
+    return this.inner.value
+  }
+
+  peek(): T {
+    return this.inner.peek()
+  }
+
+  subscribe(handler: (value: T) => void): () => void {
+    return this.inner.subscribe(handler)
+  }
+}
+
+/**
+ * Create a writable `Signal<T>`. Reads track the current auto-tracking scope
+ * (effect / computed); writes notify all subscribers (deduped via `Object.is`).
+ *
+ * Spec §20.1. For a single-pass non-tracked read use `signal.peek()`.
+ */
+export function signal<T>(initial: T): Signal<T> {
+  return new SignalImpl(initial)
+}
+
+/**
+ * Create a `Computed<T>` — a read-only derived signal. The provided `fn` is
+ * re-evaluated whenever a signal it read during its last run changes; the
+ * resulting value is cached until then.
+ *
+ * Spec §20.1. The graph is glitch-free: a `computed` re-runs at most once per
+ * batched-write cycle.
+ */
+export function computed<T>(fn: () => T): Computed<T> {
+  return new ComputedImpl(fn)
+}
+
+/**
+ * Run `fn` immediately and again whenever any signal it reads changes. If
+ * `fn` returns a function, that function is called as a cleanup before the
+ * next re-run and on dispose.
+ *
+ * Returns a `dispose` function. Inside a controller use `ctx.effect(...)`
+ * instead — that variant is auto-disposed with the controller.
+ */
+export function effect(fn: () => void | (() => void)): () => void {
+  return _effect(fn)
+}
+
+/**
+ * Batch synchronous signal writes so subscribers see one notification at the
+ * end of the batch rather than one per write. Returns whatever `fn` returns.
+ */
+export function batch<T>(fn: () => T): T {
+  return _batch(fn)
+}
+
+/**
+ * Run `fn` with auto-tracking suppressed — signals read inside don't become
+ * dependencies of the surrounding `computed` / `effect`. Useful for "read
+ * these signals once to log them" or for snapshotting state inside an effect
+ * without subscribing to it. For a single-signal peek, prefer `signal.peek()`.
+ */
+export function untracked<T>(fn: () => T): T {
+  return _untracked(fn)
+}

package/src/signals/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Read-only reactive value. Reading `.value` inside a tracking scope
+ * (`computed` / `effect`) registers a dependency; `peek()` reads without
+ * tracking; `subscribe(handler)` fires `handler` immediately with the current
+ * value and on every change until the returned unsubscribe is called.
+ */
+export type ReadSignal<T> = {
+  readonly value: T
+  /** Read the current value without registering a dependency. */
+  peek(): T
+  /**
+   * Subscribe to value changes. The handler is called synchronously with the
+   * current value on subscribe and on every change thereafter. Returns the
+   * unsubscribe function.
+   */
+  subscribe(handler: (value: T) => void): () => void
+}
+
+/**
+ * Writable reactive value. `value` is assignable; `set(value)` is the
+ * functional equivalent; `update(fn)` reads (peek) and writes the result of
+ * `fn(previous)`.
+ */
+export type Signal<T> = ReadSignal<T> & {
+  value: T
+  set(value: T): void
+  update(fn: (prev: T) => T): void
+}
+
+/** A read-only derived signal — alias of `ReadSignal<T>`. */
+export type Computed<T> = ReadSignal<T>