@kontsedal/olas-core 0.0.2 → 0.0.4

package/src/controller/types.ts

@@ -42,6 +42,10 @@ export interface AmbientDeps {
  * `ctx.field(initial, validators?)`. Spec §8, §20.7.
  */
 export type Field<T> = ReadSignal<T> & {
+  /**
+   * All errors currently surfaced on this field — validator errors first,
+   * server errors after. See `setErrors` for the server-error channel.
+   */
   errors: ReadSignal<string[]>
   isValid: ReadSignal<boolean>
   isDirty: ReadSignal<boolean>
@@ -59,6 +63,15 @@ export type Field<T> = ReadSignal<T> & {
   reset(): void
   markTouched(): void
   revalidate(): Promise<boolean>
+  /**
+   * Pin externally-sourced errors on the field — typically server-side
+   * validation results returned from a failed submit. These errors live in
+   * a separate channel from validator output, so a re-run of local
+   * validators (triggered by a new value or `revalidate()`) does NOT clear
+   * them. They're cleared automatically the next time the user writes to
+   * the field (via `set`), or explicitly via `setErrors([])` / `reset()`.
+   */
+  setErrors(errors: ReadonlyArray<string>): void
   /** Idempotent. Called by the owning controller's dispose. */
   dispose(): void
 }
@@ -172,13 +185,24 @@ export type Ctx<TDeps = AmbientDeps> = {
     },
   ): LocalCache<T>
 
+  // Select-projecting overload — picked when the options object has a
+  // required `select` field. `key`'s return is `readonly [...Args]` so
+  // callers writing `() => [id] as const` flow through cleanly.
+  use<Args extends unknown[], T, U>(
+    source: Query<Args, T>,
+    options: {
+      key?: () => readonly [...Args]
+      enabled?: () => boolean
+      select: (data: T) => U
+    },
+  ): QuerySubscription<U>
   use<Args extends unknown[], T>(
     source: Query<Args, T>,
-    keyOrOptions?: (() => Args) | UseOptions<Args>,
+    keyOrOptions?: (() => readonly [...Args]) | UseOptions<Args>,
   ): QuerySubscription<T>
   use<Args extends unknown[], TPage, TItem>(
     source: InfiniteQuery<Args, TPage, TItem>,
-    keyOrOptions?: (() => Args) | UseOptions<Args>,
+    keyOrOptions?: (() => readonly [...Args]) | UseOptions<Args>,
   ): InfiniteQuerySubscription<TPage, TItem>
 
   mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R>

package/src/forms/field.ts

@@ -36,7 +36,18 @@ export type ValidatorErrorReporter = (err: unknown) => void
 
 class FieldImpl<T> implements Field<T> {
   private readonly value$: Signal<T>
-  private readonly errors$: Signal<string[]>
+  /**
+   * Validator-produced errors. The public `errors` getter merges this with
+   * `serverErrors$` so consumers see a single flat array. Kept separate so a
+   * re-run of validators (after a new value) doesn't clobber server errors.
+   */
+  private readonly validatorErrors$: Signal<string[]>
+  /**
+   * Externally-injected errors — see `setErrors`. Cleared on the next user
+   * `set()`, on `reset()`, or via an explicit `setErrors([])`.
+   */
+  private readonly serverErrors$: Signal<string[]>
+  private readonly errors$: Computed<string[]>
   private readonly touched$: Signal<boolean>
   private readonly dirty$: Signal<boolean>
   private readonly validating$: Signal<boolean>
@@ -67,11 +78,19 @@ class FieldImpl<T> implements Field<T> {
     // post-construct hook so it can't catch the first run).
     this.onValidatorError = options?.onValidatorError ?? null
     this.value$ = signal(initial)
-    this.errors$ = signal<string[]>([])
+    this.validatorErrors$ = signal<string[]>([])
+    this.serverErrors$ = signal<string[]>([])
     this.touched$ = signal(false)
     this.dirty$ = signal(false)
     this.validating$ = signal(false)
     this.revalidateTrigger$ = signal(0)
+    this.errors$ = computed(() => {
+      const v = this.validatorErrors$.value
+      const s = this.serverErrors$.value
+      if (s.length === 0) return v
+      if (v.length === 0) return s
+      return [...v, ...s]
+    })
     this.isValid$ = computed(() => this.errors$.value.length === 0 && !this.validating$.value)
 
     if (validators.length > 0) {
@@ -126,8 +145,21 @@ class FieldImpl<T> implements Field<T> {
   // --- mutating methods ---
   set(value: T): void {
     if (this.disposed) return
-    this.value$.set(value)
-    this.dirty$.set(true)
+    batch(() => {
+      this.value$.set(value)
+      this.dirty$.set(true)
+      // Server errors are pinned externally and survive validator re-runs,
+      // but they MUST clear when the user edits the field — otherwise a
+      // server error like "username taken" would persist after the user
+      // typed a different username.
+      if (this.serverErrors$.peek().length > 0) this.serverErrors$.set([])
+    })
+  }
+
+  setErrors(errors: ReadonlyArray<string>): void {
+    if (this.disposed) return
+    const next = errors.length === 0 ? [] : [...errors]
+    this.serverErrors$.set(next)
   }
 
   /**
@@ -154,7 +186,8 @@ class FieldImpl<T> implements Field<T> {
       this.value$.set(this.initial)
       this.dirty$.set(false)
       this.touched$.set(false)
-      this.errors$.set([])
+      this.validatorErrors$.set([])
+      this.serverErrors$.set([])
       this.validating$.set(false)
     })
   }
@@ -262,7 +295,7 @@ class FieldImpl<T> implements Field<T> {
 
     if (syncErrors.length > 0) {
       batch(() => {
-        this.errors$.set(syncErrors)
+        this.validatorErrors$.set(syncErrors)
         this.validating$.set(false)
       })
       this.emitValidated(false, syncErrors)
@@ -271,7 +304,7 @@ class FieldImpl<T> implements Field<T> {
 
     if (asyncPromises.length === 0) {
       batch(() => {
-        this.errors$.set([])
+        this.validatorErrors$.set([])
         this.validating$.set(false)
       })
       this.emitValidated(true, [])
@@ -279,7 +312,7 @@ class FieldImpl<T> implements Field<T> {
     }
 
     batch(() => {
-      this.errors$.set([])
+      this.validatorErrors$.set([])
       this.validating$.set(true)
     })
 
@@ -295,7 +328,7 @@ class FieldImpl<T> implements Field<T> {
         }
       }
       batch(() => {
-        this.errors$.set(asyncErrors)
+        this.validatorErrors$.set(asyncErrors)
         this.validating$.set(false)
       })
       this.emitValidated(asyncErrors.length === 0, asyncErrors)

package/src/forms/form-types.ts

@@ -90,6 +90,22 @@ export type Form<S extends FormSchema> = {
   readonly touched: ReadSignal<boolean>
   readonly isValidating: ReadSignal<boolean>
 
+  /**
+   * `true` while a `submit(...)` is in flight. Clears when the handler
+   * resolves, throws, or pre-submit validation fails.
+   */
+  readonly isSubmitting: ReadSignal<boolean>
+  /** Number of times `submit(...)` has been called. Bumps before the handler runs. */
+  readonly submitCount: ReadSignal<number>
+  /**
+   * The thrown value from the most recent failed submission, if any.
+   * Cleared at the start of each new `submit(...)` call and on `reset()`.
+   * Note that a validation failure ("submit blocked because the form is
+   * invalid") is NOT a thrown error — `submitError` stays whatever it
+   * was, and the returned promise resolves with `{ ok: false }`.
+   */
+  readonly submitError: ReadSignal<unknown>
+
   /** Deep-merge a partial value into the form, batched. */
   set(partial: DeepPartial<FormValue<S>>): void
   /**
@@ -105,6 +121,27 @@ export type Form<S extends FormSchema> = {
   markAllTouched(): void
   /** Re-run every leaf's validators. Resolves with true if all leaves are valid. */
   validate(): Promise<boolean>
+  /**
+   * Run a submission. Pre-validates the form (unless `validateBeforeSubmit: false`),
+   * then calls `handler(value)`. Maintains `isSubmitting` / `submitCount` /
+   * `submitError`. Returns `{ ok, data?, error? }` — see `FormImpl.submit`
+   * for the full contract.
+   */
+  submit(
+    handler: (value: FormValue<S>) => unknown | Promise<unknown>,
+    options?: {
+      validateBeforeSubmit?: boolean
+      resetOnSuccess?: boolean
+      onError?: 'rethrow' | 'capture'
+    },
+  ): Promise<{ ok: boolean; data?: unknown; error?: unknown }>
+  /**
+   * Pin externally-sourced errors on specific fields. Keys are dot-separated
+   * paths through nested forms / field arrays (numeric segments are array
+   * indices). Errors land in each field's `serverErrors` channel — kept
+   * separate from validator output and auto-cleared on the next user write.
+   */
+  setErrors(errors: Record<string, ReadonlyArray<string>>): void
   /** Idempotent. Called by the owning controller's dispose. */
   dispose(): void
 }

package/src/forms/form.ts

@@ -51,6 +51,14 @@ class FormImpl<S extends FormSchema> implements Form<S> {
   readonly topLevelErrors: ReadSignal<string[]> = this.topLevelErrors$
   private readonly topLevelValidating$: Signal<boolean> = signal(false)
 
+  // Submission lifecycle.
+  private readonly isSubmitting$: Signal<boolean> = signal(false)
+  private readonly submitCount$: Signal<number> = signal(0)
+  private readonly submitError$: Signal<unknown> = signal(undefined)
+  readonly isSubmitting: ReadSignal<boolean> = this.isSubmitting$
+  readonly submitCount: ReadSignal<number> = this.submitCount$
+  readonly submitError: ReadSignal<unknown> = this.submitError$
+
   private readonly validators: ReadonlyArray<FormValidator<S>>
   private readonly options: FormOptions<S> | undefined
   private validatorDispose: (() => void) | null = null
@@ -313,6 +321,116 @@ class FormImpl<S extends FormSchema> implements Form<S> {
     return this.isValid.peek()
   }
 
+  /**
+   * Run a submission against this form. Wraps `handler(value)` with:
+   * - `isSubmitting` set true while the handler is in flight.
+   * - `submitCount` incremented before the handler runs.
+   * - `submitError` set to the throw, if any.
+   * - Optional pre-submit `validate()` (default true). When invalid every
+   *   field is marked touched and the handler is skipped — the returned
+   *   promise resolves with `{ ok: false }` and `submitError` is left
+   *   untouched (validation failure is not a thrown error).
+   *
+   * The handler may return a value (synchronously or via Promise); it's
+   * captured in the resolved object's `data` field. Throws are captured
+   * unless `onError: 'rethrow'`. A `resetOnSuccess: true` option calls
+   * `reset()` after the handler resolves successfully.
+   */
+  async submit(
+    handler: (value: FormValue<S>) => unknown | Promise<unknown>,
+    options?: {
+      validateBeforeSubmit?: boolean
+      resetOnSuccess?: boolean
+      onError?: 'rethrow' | 'capture'
+    },
+  ): Promise<{ ok: boolean; data?: unknown; error?: unknown }> {
+    if (this.disposed) return { ok: false, error: new Error('form is disposed') }
+
+    // Double-submit guard — refusing to start a second submission while one
+    // is in flight matches RHF / TanStack-Form. Consumers wanting parallel
+    // submits should run them off the form directly.
+    if (this.isSubmitting$.peek()) {
+      return { ok: false, error: new Error('submit already in progress') }
+    }
+
+    const validateFirst = options?.validateBeforeSubmit ?? true
+    const onErrorMode = options?.onError ?? 'capture'
+
+    batch(() => {
+      this.submitCount$.update((n) => n + 1)
+      this.submitError$.set(undefined)
+      this.isSubmitting$.set(true)
+    })
+
+    try {
+      if (validateFirst) {
+        const ok = await this.validate()
+        if (!ok) {
+          this.markAllTouched()
+          this.isSubmitting$.set(false)
+          return { ok: false }
+        }
+      }
+      const result = await handler(this.value.peek())
+      if (options?.resetOnSuccess) this.reset()
+      this.isSubmitting$.set(false)
+      return { ok: true, data: result }
+    } catch (err) {
+      batch(() => {
+        this.submitError$.set(err)
+        this.isSubmitting$.set(false)
+      })
+      if (onErrorMode === 'rethrow') throw err
+      return { ok: false, error: err }
+    }
+  }
+
+  /**
+   * Pin externally-sourced errors on specific fields — typically server-side
+   * validation results from a failed submit. Paths are dot-separated and
+   * traverse nested `Form` / `FieldArray` children (numeric segments are
+   * array indices). Errors land in the field's `serverErrors` channel and
+   * clear automatically on the next user write to that field. Passing an
+   * empty array for a path clears that field's server errors immediately.
+   */
+  setErrors(errors: Record<string, ReadonlyArray<string>>): void {
+    if (this.disposed) return
+    batch(() => {
+      for (const [path, msgs] of Object.entries(errors)) {
+        const target = this.resolvePath(path)
+        if (target === undefined) continue
+        if ((target as { setErrors?: unknown }).setErrors === undefined) continue
+        ;(target as { setErrors: (e: ReadonlyArray<string>) => void }).setErrors(msgs)
+      }
+    })
+  }
+
+  private resolvePath(path: string): unknown {
+    if (path === '') return undefined
+    const segments = path.split('.')
+    let cursor: unknown = this
+    for (const seg of segments) {
+      if (cursor === undefined || cursor === null) return undefined
+      if (isForm(cursor)) {
+        cursor = (cursor.fields as Record<string, unknown>)[seg]
+        continue
+      }
+      if (isFieldArray(cursor)) {
+        const idx = Number(seg)
+        if (!Number.isInteger(idx) || idx < 0) return undefined
+        cursor = (cursor as { at(i: number): unknown }).at(idx)
+        continue
+      }
+      // Top-level dispatch — `this` is the FormImpl; walk via `fields`.
+      if (cursor === this) {
+        cursor = (this.fields as Record<string, unknown>)[seg]
+        continue
+      }
+      return undefined
+    }
+    return cursor
+  }
+
   dispose(): void {
     if (this.disposed) return
     this.disposed = true

package/src/forms/index.ts

@@ -1,2 +1,13 @@
+export type { StandardSchemaV1 } from './standard-schema'
+export { isStandardSchema } from './standard-schema'
 export type { Validator } from './types'
-export { email, max, maxLength, min, minLength, pattern, required } from './validators'
+export {
+  email,
+  max,
+  maxLength,
+  min,
+  minLength,
+  pattern,
+  required,
+  validator,
+} from './validators'

package/src/forms/standard-schema.ts

@@ -0,0 +1,37 @@
+/**
+ * Standard Schema v1 — the cross-library validation contract adopted by
+ * Zod 4, Valibot 1, ArkType 2, and others. See https://standardschema.dev.
+ *
+ * We type-only-import the shape so consumers don't take a new runtime dep:
+ * any object with a `~standard.validate(value)` method conforming to this
+ * structure works.
+ */
+export type StandardSchemaV1Issue = {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+}
+
+export type StandardSchemaV1Result<O> =
+  | { readonly value: O; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<StandardSchemaV1Issue> }
+
+export type StandardSchemaV1<I = unknown, O = I> = {
+  readonly '~standard': {
+    readonly version: 1
+    readonly vendor: string
+    validate(value: unknown): StandardSchemaV1Result<O> | Promise<StandardSchemaV1Result<O>>
+    readonly types?: { readonly input: I; readonly output: O } | undefined
+  }
+}
+
+/**
+ * Heuristic: does `x` look like a Standard Schema?
+ */
+export function isStandardSchema(x: unknown): x is StandardSchemaV1<unknown, unknown> {
+  return (
+    x !== null &&
+    typeof x === 'object' &&
+    '~standard' in x &&
+    typeof (x as { '~standard': { validate?: unknown } })['~standard']?.validate === 'function'
+  )
+}

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

@@ -25,9 +25,19 @@ export type { DebugBus, DebugCacheEntry, DebugEvent } from './devtools'
 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/local.ts

@@ -83,6 +83,7 @@ class LocalCacheImpl<T> implements LocalCache<T> {
   refetch = (): Promise<T> => this.entry.refetch()
   reset = (): void => this.entry.reset()
   firstValue = (): Promise<T> => this.entry.firstValue()
+  promise = (): Promise<T> => this.entry.firstValue()
   invalidate = (): void => {
     this.entry.invalidate().catch(() => {})
   }

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

@@ -32,6 +32,13 @@ export type AsyncState<T> = {
   refetch: () => Promise<T>
   reset: () => void
   firstValue: () => Promise<T>
+  /**
+   * Alias of `firstValue()` — clearer name for Suspense / `React.use(...)`
+   * use cases. Resolves with `data` on first success (short-circuits if
+   * already settled), rejects with `error` on the first failure. Use this
+   * to suspend a React tree until the query lands its first value.
+   */
+  promise: () => Promise<T>
 }
 
 /**
@@ -159,10 +166,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
+}