@kontsedal/olas-core 0.0.1 → 0.0.3

package/src/forms/validators.ts

@@ -1,5 +1,36 @@
+import { isStandardSchema, type StandardSchemaV1 } from './standard-schema'
 import type { Validator } from './types'
 
+/**
+ * Wrap any Standard-Schema-compatible schema (Zod 4, Valibot 1, ArkType 2,
+ * …) as an Olas validator. The validator returns the first issue's message
+ * on failure (or `'Invalid'` if no issues are produced), `null` on success.
+ *
+ * Standard Schema validators may be sync or async; this wrapper threads
+ * through whichever the schema returns — `Promise<string|null>` only when
+ * the underlying validate call is itself async.
+ *
+ * `signal` is accepted to match the `Validator<T>` shape but isn't forwarded
+ * — Standard Schema v1 has no cancellation surface.
+ */
+export function validator<I, O>(schema: StandardSchemaV1<I, O>): Validator<I> {
+  return (value, signal) => {
+    void signal
+    const result = schema['~standard'].validate(value)
+    if (result instanceof Promise) {
+      return result.then(messageFromResult)
+    }
+    return messageFromResult(result)
+  }
+}
+
+function messageFromResult(result: { issues?: ReadonlyArray<{ message: string }> }): string | null {
+  if (result.issues === undefined || result.issues.length === 0) return null
+  return result.issues[0]?.message ?? 'Invalid'
+}
+
+export { isStandardSchema, type StandardSchemaV1 } from './standard-schema'
+
 const isEmpty = (value: unknown): boolean => {
   if (value === undefined || value === null) return true
   if (typeof value === 'string') return value.length === 0

package/src/index.ts

@@ -3,11 +3,17 @@
 // Controller container
 export type {
   AmbientDeps,
+  Collection,
+  CollectionFactoryApi,
+  CollectionFactoryOptions,
+  CollectionFactoryResult,
+  CollectionHomogeneousOptions,
   ControllerDef,
   CtrlApi,
   CtrlProps,
   Ctx,
   Field,
+  LazyChild,
   Root,
   RootOptions,
 } from './controller'
@@ -16,12 +22,22 @@ export { createRoot, defineController } from './controller'
 export type { DebugBus, DebugCacheEntry, DebugEvent } from './devtools'
 
 // Emitter
-export type { Emitter } from './emitter'
+export type { Emitter, EmitterErrorReporter } from './emitter'
 export { createEmitter } from './emitter'
 export type { ErrorContext } from './errors'
-// Forms — stdlib validators + debouncedValidator
-export type { Validator } from './forms'
-export { email, max, maxLength, min, minLength, pattern, required } from './forms'
+// Forms — stdlib validators + Standard Schema adapter + debouncedValidator
+export type { StandardSchemaV1, Validator } from './forms'
+export {
+  email,
+  isStandardSchema,
+  max,
+  maxLength,
+  min,
+  minLength,
+  pattern,
+  required,
+  validator,
+} from './forms'
 export { debouncedValidator } from './forms/field'
 export type {
   DeepPartial,

package/src/query/entry.ts

@@ -1,5 +1,6 @@
 import { batch, type Signal, signal } from '../signals'
 import { abortableSleep, isAbortError } from '../utils'
+import { structuralShare } from './structural-share'
 import type { AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
 
 export type EntryEvents = {
@@ -180,8 +181,14 @@ export class Entry<T> {
   }
 
   private applySuccess(result: T): T {
+    // Structurally share with the previous value so unchanged sub-trees
+    // keep their `===` identity. Downstream `computed`s and React snapshots
+    // stop thrashing on no-op refetches. Bails on Maps/Sets/class instances
+    // — see `structural-share.ts`.
+    const prev = this.data.peek() as T | undefined
+    const shared = prev === undefined ? result : structuralShare(prev, result)
     batch(() => {
-      this.data.set(result)
+      this.data.set(shared)
       this.error.set(undefined)
       this.status.set('success')
       this.isLoading.set(false)
@@ -195,8 +202,8 @@ export class Entry<T> {
     } catch {
       // devtools handlers must not break the program.
     }
-    this.onSuccessData?.(result)
-    return result
+    this.onSuccessData?.(shared)
+    return shared
   }
 
   private applyFailure(err: unknown): never {

package/src/query/infinite.ts

@@ -1,6 +1,7 @@
 import { batch, computed, type Signal, signal } from '../signals'
 import type { ReadSignal } from '../signals/types'
 import { abortableSleep, isAbortError } from '../utils'
+import { structuralShare } from './structural-share'
 import type { AsyncState, AsyncStatus, RetryDelay, RetryPolicy, Snapshot } from './types'
 
 /**
@@ -205,8 +206,14 @@ export class InfiniteEntry<TPage, TItem, PageParam> {
       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([page])
+          this.pages.set([sharedPage])
           this.pageParams.set([param])
           this.error.set(undefined)
           this.status.set('success')

package/src/query/structural-share.ts

@@ -0,0 +1,114 @@
+/**
+ * Walk `prev` and `next` in parallel. Wherever a sub-tree in `next` is
+ * structurally equal to the corresponding sub-tree in `prev`, return `prev`'s
+ * reference for that sub-tree. Otherwise return `next`'s.
+ *
+ * Result: a value that is `===` to `prev` on every refetch where the payload
+ * didn't actually change, and shares maximum ref-identity on partial changes.
+ * Downstream `computed`s and React `useSyncExternalStore` snapshots stop
+ * thrashing because reference equality holds where content equality holds.
+ *
+ * Bails (returns the `next` ref unchanged, no recursion) on:
+ *   - Mismatched constructors / different `typeof` between `prev` and `next`
+ *   - `Map`, `Set`, `Date`, `RegExp`, class instances (anything where the
+ *     plain-object / array fast path isn't safe)
+ *   - Functions, symbols, promises
+ *
+ * Handles cycles via a `WeakSet` of in-progress objects — a self-referential
+ * payload that compares structurally identical against itself won't loop.
+ */
+export function structuralShare<T>(prev: T, next: T): T {
+  // Identity short-circuit — both branches see the exact same allocation.
+  if (Object.is(prev, next)) return prev
+  return walk(prev, next, new WeakSet<object>()) as T
+}
+
+function walk(prev: unknown, next: unknown, seen: WeakSet<object>): unknown {
+  if (Object.is(prev, next)) return prev
+  if (prev === null || next === null) return next
+  if (typeof prev !== 'object' || typeof next !== 'object') return next
+
+  // Cycle guard. If either side is already on the in-flight stack, we can't
+  // safely recurse — fall back to `next`'s ref. Real cyclic payloads are
+  // exceedingly rare in HTTP responses; defensive bail.
+  if (seen.has(prev as object) || seen.has(next as object)) return next
+
+  // Arrays — only matched against arrays.
+  if (Array.isArray(prev) && Array.isArray(next)) {
+    return walkArray(prev, next, seen)
+  }
+  if (Array.isArray(prev) !== Array.isArray(next)) return next
+
+  // Constructor / prototype check. Plain objects have `Object.prototype`
+  // (and a Map/Set/Date/RegExp/class instance does not). We require an exact
+  // prototype match on both sides AND `Object.prototype` so we never deep-
+  // walk into class instances whose identity might encode hidden state.
+  const prevProto = Object.getPrototypeOf(prev)
+  if (prevProto !== Object.getPrototypeOf(next)) return next
+  if (prevProto !== Object.prototype && prevProto !== null) return next
+
+  return walkPlainObject(prev as Record<string, unknown>, next as Record<string, unknown>, seen)
+}
+
+function walkArray(
+  prev: ReadonlyArray<unknown>,
+  next: ReadonlyArray<unknown>,
+  seen: WeakSet<object>,
+): ReadonlyArray<unknown> {
+  if (prev.length !== next.length) {
+    // Length changed — we can still preserve refs for matching prefixes via
+    // index-aligned walking. That's the right trade-off for tables / lists:
+    // appending an item keeps the head's refs stable, prepending invalidates
+    // everything (which it does anyway — items shifted).
+  }
+  seen.add(prev)
+  seen.add(next)
+  try {
+    const out: unknown[] = new Array(next.length)
+    let changed = next.length !== prev.length
+    for (let i = 0; i < next.length; i++) {
+      const prevItem = i < prev.length ? prev[i] : undefined
+      const shared = walk(prevItem, next[i], seen)
+      out[i] = shared
+      if (shared !== prev[i]) changed = true
+    }
+    if (!changed) return prev
+    return out
+  } finally {
+    seen.delete(prev)
+    seen.delete(next)
+  }
+}
+
+function walkPlainObject(
+  prev: Record<string, unknown>,
+  next: Record<string, unknown>,
+  seen: WeakSet<object>,
+): Record<string, unknown> {
+  const prevKeys = Object.keys(prev)
+  const nextKeys = Object.keys(next)
+  let changed = prevKeys.length !== nextKeys.length
+
+  seen.add(prev)
+  seen.add(next)
+  try {
+    const out: Record<string, unknown> = {}
+    // Iterate `next`'s keys in order so the output preserves payload's
+    // key ordering (matters for downstream `JSON.stringify` callers and
+    // for predictable React reconciliation when an object is rendered).
+    for (const key of nextKeys) {
+      const shared = walk(prev[key], next[key], seen)
+      out[key] = shared
+      if (shared !== prev[key]) changed = true
+      else if (!(key in prev)) changed = true
+    }
+    // Keys present in `prev` but not in `next` are dropped — that's already
+    // expressed by `next.keys`. But the length-mismatch flag above catches
+    // the changed shape.
+    if (!changed) return prev
+    return out
+  } finally {
+    seen.delete(prev)
+    seen.delete(next)
+  }
+}

package/src/query/types.ts

@@ -159,10 +159,23 @@ export type QuerySubscription<T> = AsyncState<T>
 
 /**
  * Options passed to `ctx.use(query, opts)` to control the subscription
- * (reactive key, enabled-gating). The `key` thunk reads signals — re-evaluating
- * when they change re-keys the subscription.
+ * (reactive key, enabled-gating). The `key` thunk reads signals —
+ * re-evaluating when they change re-keys the subscription.
+ *
+ * A `select` projection that maps the underlying data shape to a view
+ * shape is accepted via a dedicated overload on `Ctx.use` rather than this
+ * options bag — the overload threads `T → U` types through cleanly.
  */
 export type UseOptions<Args extends readonly unknown[]> = {
   key?: () => Args
   enabled?: () => boolean
 }
+
+/**
+ * Internal shape — what `createUse` accepts. Includes the optional `select`
+ * field used by the `select` overload on `Ctx.use`. Not exported on the
+ * public surface; consumers use the typed overload.
+ */
+export type UseInternalOptions<Args extends readonly unknown[], T, U> = UseOptions<Args> & {
+  select?: (data: T) => U
+}

package/src/query/use.ts

@@ -2,17 +2,24 @@ 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'
+import type {
+  AsyncStatus,
+  Query,
+  QuerySpec,
+  QuerySubscription,
+  UseInternalOptions,
+  UseOptions,
+} from './types'
 
 type QueryInternal<Args extends unknown[], T> = Query<Args, T> & {
   readonly __spec: QuerySpec<Args, T>
 }
 
-class SubscriptionImpl<T> implements QuerySubscription<T> {
+class SubscriptionImpl<T, U = T> implements QuerySubscription<U> {
   private readonly current$: Signal<ClientEntry<T> | null> = signal(null)
   private readonly previousData$: Signal<T | undefined> = signal(undefined)
 
-  readonly data: ReadSignal<T | undefined>
+  readonly data: ReadSignal<U | undefined>
   readonly error: ReadSignal<unknown | undefined>
   readonly status: ReadSignal<AsyncStatus>
   readonly isLoading: ReadSignal<boolean>
@@ -21,14 +28,30 @@ class SubscriptionImpl<T> implements QuerySubscription<T> {
   readonly lastUpdatedAt: ReadSignal<number | undefined>
   readonly hasPendingMutations: ReadSignal<boolean>
 
-  constructor(private readonly keepPreviousData: boolean) {
-    this.data = computed(() => {
+  constructor(
+    private readonly keepPreviousData: boolean,
+    private readonly select?: (data: T) => U,
+  ) {
+    // The underlying entry stores `T`. The subscription's `data` is `U`
+    // (or `T` when no projection). We compute the raw `T` once, then layer
+    // `select` in a second computed so the projection's `Object.is` dedup
+    // applies BEFORE downstream subscribers run — combined with structural
+    // sharing on the entry, an unchanged payload + a stable `select`
+    // outputs the same `U` reference and doesn't churn the React tree.
+    const rawData = 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.data =
+      select === undefined
+        ? (rawData as unknown as ReadSignal<U | undefined>)
+        : computed<U | undefined>(() => {
+            const raw = rawData.value
+            return raw === undefined ? undefined : select(raw)
+          })
     this.error = computed(() => this.current$.value?.entry.error.value)
     this.status = computed<AsyncStatus>(() => this.current$.value?.entry.status.value ?? 'idle')
     this.isLoading = computed(() => {
@@ -59,33 +82,42 @@ class SubscriptionImpl<T> implements QuerySubscription<T> {
     this.current$.set(null)
   }
 
-  refetch = (): Promise<T> => {
+  refetch = (): Promise<U> => {
     const cur = this.current$.peek()
     if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
-    return cur.entry.refetch()
+    return cur.entry.refetch().then((v) => this.project(v))
   }
 
   reset = (): void => {
     this.current$.peek()?.entry.reset()
   }
 
-  firstValue = (): Promise<T> => {
+  firstValue = (): Promise<U> => {
     const cur = this.current$.peek()
     if (!cur) return Promise.reject(new Error('[olas] no active subscription'))
-    return cur.entry.firstValue()
+    return cur.entry.firstValue().then((v) => this.project(v))
+  }
+
+  private project(v: T): U {
+    return this.select === undefined ? (v as unknown as U) : this.select(v)
   }
 }
 
 /**
  * Build a subscription + the effect that keeps it bound to the right entry.
  * The controller container wires the disposer into the lifecycle.
+ *
+ * `keyOrOptions` may carry an optional `select` projection that maps the
+ * underlying `T` to a view `U`; the returned subscription's data shape
+ * widens accordingly. Without `select`, `U = T` and the projection
+ * computed is skipped.
  */
-export function createUse<Args extends unknown[], T>(
+export function createUse<Args extends unknown[], T, U = T>(
   client: QueryClient,
   query: Query<Args, T>,
-  keyOrOptions?: (() => Args) | UseOptions<Args>,
+  keyOrOptions?: (() => Args) | UseInternalOptions<Args, T, U>,
 ): {
-  subscription: QuerySubscription<T>
+  subscription: QuerySubscription<U>
   dispose: () => void
   /** Suspend the subscription — release the entry (its refetchInterval +
    *  focus/online listeners pause) without disposing it. Spec §4.1. */
@@ -100,8 +132,10 @@ export function createUse<Args extends unknown[], T>(
   const keyFn = typeof keyOrOptions === 'function' ? keyOrOptions : keyOrOptions?.key
   const enabledFn =
     typeof keyOrOptions === 'object' && keyOrOptions !== null ? keyOrOptions.enabled : undefined
+  const select =
+    typeof keyOrOptions === 'object' && keyOrOptions !== null ? keyOrOptions.select : undefined
 
-  const sub = new SubscriptionImpl<T>(keepPreviousData)
+  const sub = new SubscriptionImpl<T, U>(keepPreviousData, select)
   let currentEntry: ClientEntry<T> | null = null
   let suspended = false
 

package/src/signals/readonly.ts

@@ -8,15 +8,15 @@ import type { ReadSignal } from './types'
  * Internal helper — not exported from the package's public surface.
  */
 export function readOnly<T>(source: ReadSignal<T>): ReadSignal<T> {
-  return {
+  return Object.freeze({
     get value() {
       return source.value
     },
     peek() {
       return source.peek()
     },
-    subscribe(handler) {
+    subscribe(handler: (value: T) => void) {
       return source.subscribe(handler)
     },
-  }
+  })
 }

package/src/testing.ts

@@ -47,6 +47,7 @@ export function fakeField<T>(
     reset: () => void
     markTouched: () => void
     revalidate: () => Promise<boolean>
+    setErrors: (errors: ReadonlyArray<string>) => void
     dispose: () => void
   }>,
 ): Field<T> {
@@ -85,6 +86,7 @@ export function fakeField<T>(
     reset: overrides?.reset ?? (() => value$.set(currentInitial)),
     markTouched: overrides?.markTouched ?? (() => touched$.set(true)),
     revalidate: overrides?.revalidate ?? (async () => errors$.peek().length === 0),
+    setErrors: overrides?.setErrors ?? ((errs) => errors$.set([...errs])),
     dispose: overrides?.dispose ?? (() => {}),
   }
   return fake

package/src/timing/debounced.ts

@@ -5,15 +5,22 @@ import type { ReadSignal } from '../signals/types'
  * Lag a signal by `ms`. The returned signal updates only after the source has
  * been unchanged for `ms`. Each new write resets the timer.
  *
- * No lifecycle — the internal effect runs for the lifetime of the program.
- * Use inside a controller closure so it dies with the closure.
+ * Pass `options.signal` (an `AbortSignal`) to tie the internal effect to a
+ * lifecycle — when the signal aborts the effect disposes, the pending timer
+ * clears, and the subscriber chain on `source` drops. Without `signal`, the
+ * effect lives as long as `source` does; pass a signal whenever the source
+ * outlives the consumer.
  */
-export function debounced<T>(source: ReadSignal<T>, ms: number): ReadSignal<T> {
+export function debounced<T>(
+  source: ReadSignal<T>,
+  ms: number,
+  options?: { signal?: AbortSignal },
+): ReadSignal<T> {
   const out = signal<T>(source.peek())
   let timer: ReturnType<typeof setTimeout> | null = null
   let initial = true
 
-  effect(() => {
+  const dispose = effect(() => {
     const value = source.value
     if (initial) {
       // The first effect run reads the source for tracking; we already
@@ -28,5 +35,18 @@ export function debounced<T>(source: ReadSignal<T>, ms: number): ReadSignal<T> {
     }, ms)
   })
 
+  const sig = options?.signal
+  if (sig) {
+    const stop = () => {
+      if (timer != null) {
+        clearTimeout(timer)
+        timer = null
+      }
+      dispose()
+    }
+    if (sig.aborted) stop()
+    else sig.addEventListener('abort', stop, { once: true })
+  }
+
   return out
 }

package/src/timing/throttled.ts

@@ -6,16 +6,22 @@ import type { ReadSignal } from '../signals/types'
  * The first change passes through immediately. Subsequent changes within the
  * window are coalesced; the latest value is emitted when the window expires.
  *
- * No lifecycle — see debounced() note.
+ * Pass `options.signal` to tie the internal effect to a lifecycle — when the
+ * signal aborts the effect disposes and any pending trailing timer clears.
+ * Without `signal`, the effect lives as long as `source` does.
  */
-export function throttled<T>(source: ReadSignal<T>, ms: number): ReadSignal<T> {
+export function throttled<T>(
+  source: ReadSignal<T>,
+  ms: number,
+  options?: { signal?: AbortSignal },
+): ReadSignal<T> {
   const out = signal<T>(source.peek())
   let lastEmit = Number.NEGATIVE_INFINITY
   let trailingTimer: ReturnType<typeof setTimeout> | null = null
   let trailingValue: T = source.peek()
   let initial = true
 
-  effect(() => {
+  const dispose = effect(() => {
     const value = source.value
     if (initial) {
       initial = false
@@ -42,5 +48,18 @@ export function throttled<T>(source: ReadSignal<T>, ms: number): ReadSignal<T> {
     }
   })
 
+  const sig = options?.signal
+  if (sig) {
+    const stop = () => {
+      if (trailingTimer != null) {
+        clearTimeout(trailingTimer)
+        trailingTimer = null
+      }
+      dispose()
+    }
+    if (sig.aborted) stop()
+    else sig.addEventListener('abort', stop, { once: true })
+  }
+
   return out
 }

package/src/utils.ts

@@ -1,14 +1,18 @@
 /**
- * True iff `err` is an AbortError. Used to filter superseded latest-wins
- * mutations and aborted fetches from genuine failures.
+ * True iff `err` looks like an AbortError. Matches the standard `DOMException`
+ * shape thrown by `AbortController` AND any object whose `name === 'AbortError'`
+ * — that covers axios / msw / user-thrown plain Errors that signal abort.
  *
- * Spec: §20.12 — checks `err instanceof DOMException && err.name === 'AbortError'`.
- * Node 17+ exposes a global DOMException, so this works server-side too.
+ * Spec: §20.12. Node 17+ exposes a global DOMException, so the instanceof
+ * branch works server-side; the name-based branch is the portable fallback.
  */
 export function isAbortError(err: unknown): boolean {
   if (typeof DOMException !== 'undefined' && err instanceof DOMException) {
     return err.name === 'AbortError'
   }
+  if (err != null && typeof err === 'object' && 'name' in err) {
+    return (err as { name: unknown }).name === 'AbortError'
+  }
   return false
 }