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

package/src/controller/root.ts

@@ -48,7 +48,15 @@ export function createRootWithProps<Props, Api, TDeps extends Record<string, unk
   )
 
   // Bootstrap failure throws straight out of createRoot. Spec §12.1.5.
-  const api = instance.construct(getFactory(def), props)
+  // Tear down the QueryClient and any plugins it spawned (window/storage
+  // listeners, transports) before re-throwing so the failure doesn't leak.
+  let api: Api
+  try {
+    api = instance.construct(getFactory(def), props)
+  } catch (err) {
+    queryClient.dispose()
+    throw err
+  }
 
   if (typeof api !== 'object' || api === null) {
     // Allow primitive APIs in principle but root controls must live somewhere.

package/src/controller/types.ts

@@ -127,18 +127,28 @@ export type Ctx<TDeps = AmbientDeps> = {
   ): Api
 
   /**
-   * Like `child(...)` but additionally returns a `dispose()` handle so the
-   * parent can tear down this specific sub-tree early — e.g. when the user
-   * closes a details panel. The child is still disposed automatically when
-   * the parent disposes; `dispose()` is idempotent and only earlies the
-   * teardown. Useful for "openable" sub-controllers whose lifetime is driven
-   * by a user gesture rather than the parent's lifetime alone.
+   * Like `child(...)` but additionally returns a handle that lets the parent
+   * control the attached sub-tree's lifecycle independently — `dispose()`
+   * tears it down early, and `suspend()` / `resume()` freeze and thaw it.
+   * The child is still disposed automatically when the parent disposes;
+   * `dispose()` / `suspend()` / `resume()` are idempotent.
+   *
+   * `<KeepAlive controller={…}>` in `@kontsedal/olas-react` consumes the
+   * returned `{ suspend, resume }` directly — no hand-rolled `isPaused`
+   * signal needed on the child's `Api`. Useful for "openable" sub-
+   * controllers driven by a user gesture (modal, side panel, wizard).
+   *
+   * `suspend()` cascades through the attached controller's lifecycle
+   * entries: cache subscriptions pause `refetchInterval` and release the
+   * entry, effects are torn down, `onSuspend(...)` handlers fire. `resume()`
+   * re-runs effects, re-acquires cache entries (a stale entry refetches),
+   * and fires `onResume(...)`. Spec §4.1, §16.5.
    */
   attach<Props, Api>(
     def: ControllerDef<Props, Api>,
     props: Props,
     options?: { deps?: Partial<TDeps> },
-  ): { api: Api; dispose: () => void }
+  ): { api: Api; dispose: () => void; suspend: () => void; resume: () => void }
 
   effect(fn: () => void | (() => void)): void
 

package/src/forms/field.ts

@@ -23,6 +23,17 @@ export type FieldDevtoolsOwner = {
   emitter: DevtoolsEmitter
 }
 
+/**
+ * Optional reporter for synchronous validator throws — wired in by `ctx.field`
+ * (and `createForm` for leaf fields inside a form) so a thrown validator
+ * doesn't escape the signal effect silently. Without this, a buggy validator
+ * just stops contributing to `errors` and the field reads as "valid" while
+ * silently broken. With it, the throw is routed through `root.onError` as
+ * `kind: 'effect'` AND the throw's message lands in the field's `errors`
+ * array so the UI surfaces the problem.
+ */
+export type ValidatorErrorReporter = (err: unknown) => void
+
 class FieldImpl<T> implements Field<T> {
   private readonly value$: Signal<T>
   private readonly errors$: Signal<string[]>
@@ -41,10 +52,20 @@ class FieldImpl<T> implements Field<T> {
   private runId = 0
   private disposed = false
   private devtoolsOwner: FieldDevtoolsOwner | null = null
+  private onValidatorError: ValidatorErrorReporter | null = null
 
-  constructor(initial: T, validators: ReadonlyArray<Validator<T>> = []) {
+  constructor(
+    initial: T,
+    validators: ReadonlyArray<Validator<T>> = [],
+    options?: { onValidatorError?: ValidatorErrorReporter },
+  ) {
     this.initial = initial
     this.validators = validators
+    // Capture the reporter BEFORE the validator effect kicks off so a sync
+    // throw on the very first pass routes through `onError` instead of
+    // disappearing into the effect (`bindValidatorErrorReporter` is a
+    // 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.touched$ = signal(false)
@@ -60,6 +81,14 @@ class FieldImpl<T> implements Field<T> {
     }
   }
 
+  /**
+   * Internal hook for `ctx.field` / `createForm` to route synchronous
+   * validator throws through `root.onError`. See `ValidatorErrorReporter`.
+   */
+  bindValidatorErrorReporter(reporter: ValidatorErrorReporter | null): void {
+    this.onValidatorError = reporter
+  }
+
   // --- ReadSignal<T> ---
   get value(): T {
     return this.value$.value
@@ -207,11 +236,27 @@ class FieldImpl<T> implements Field<T> {
     const asyncPromises: Promise<string | null>[] = []
 
     for (const validator of this.validators) {
-      const result = validator(value, abort.signal)
-      if (result instanceof Promise) {
-        asyncPromises.push(result)
-      } else if (result != null) {
-        syncErrors.push(result)
+      try {
+        const result = validator(value, abort.signal)
+        if (result instanceof Promise) {
+          // Defend against the validator promise rejecting *synchronously*
+          // with a thrown error (rare but legal) — the catch-handler in
+          // `Promise.allSettled` covers true async rejection.
+          asyncPromises.push(result)
+        } else if (result != null) {
+          syncErrors.push(result)
+        }
+      } catch (err) {
+        // A buggy validator that throws synchronously: surface it twice.
+        // (1) Route through `onError` so the user knows something is wrong.
+        // (2) Convert to a validation error string so the field reads invalid
+        //     until the bug is fixed (don't pretend everything's OK).
+        try {
+          this.onValidatorError?.(err)
+        } catch {
+          // The reporter must not propagate.
+        }
+        syncErrors.push(err instanceof Error ? err.message : String(err))
       }
     }
 
@@ -270,8 +315,28 @@ export function bindFieldDevtoolsOwner<T>(field: Field<T>, owner: FieldDevtoolsO
   }
 }
 
-export function createField<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T> {
-  return new FieldImpl(initial, validators)
+/**
+ * Internal — install a synchronous-validator-throw reporter on a `Field`
+ * (matched structurally to keep the public `Field<T>` surface stable).
+ * Called by `ctx.field` and `bindTreeToDevtools` so leaves inside a form/
+ * field-array tree get the same reporting as a standalone field.
+ */
+export function bindFieldValidatorErrorReporter<T>(
+  field: Field<T>,
+  reporter: ValidatorErrorReporter | null,
+): void {
+  const impl = field as { bindValidatorErrorReporter?: (r: ValidatorErrorReporter | null) => void }
+  if (typeof impl.bindValidatorErrorReporter === 'function') {
+    impl.bindValidatorErrorReporter(reporter)
+  }
+}
+
+export function createField<T>(
+  initial: T,
+  validators?: ReadonlyArray<Validator<T>>,
+  options?: { onValidatorError?: ValidatorErrorReporter },
+): Field<T> {
+  return new FieldImpl(initial, validators, options)
 }
 
 /**

package/src/forms/form-types.ts

@@ -45,8 +45,24 @@ export type FormValidator<S extends FormSchema> = Validator<FormValue<S>>
 export type FieldArrayValidator<I> = Validator<FieldArrayValue<I>>
 
 export type FormOptions<S extends FormSchema> = {
+  /**
+   * Initial values for the form. A function form is **tracked** — if the
+   * function reads reactive signals (e.g. a query's `data`), the form re-seats
+   * itself when those signals change, but only while the form is not dirty
+   * (so a user mid-edit isn't clobbered by a background refetch). See
+   * `resetOnInitialChange` for opt-out. Spec §8.4.
+   */
   initial?: (() => DeepPartial<FormValue<S>> | undefined) | DeepPartial<FormValue<S>>
   validators?: FormValidator<S>[]
+  /**
+   * When `initial` is a function and one of its tracked deps changes:
+   *  - `'when-clean'` (default) — re-seat only if the form is not dirty.
+   *  - `'never'` — never re-seat; `initial()` runs once at construction.
+   *  - `'always'` — re-seat unconditionally (dirty state is discarded).
+   *
+   * Spec §20.7.
+   */
+  resetOnInitialChange?: 'when-clean' | 'never' | 'always'
 }
 
 export type FieldArrayOptions<I> = {

package/src/forms/form.ts

@@ -1,7 +1,12 @@
 import type { Field } from '../controller/types'
 import { batch, computed, effect, type Signal, signal, untracked } from '../signals'
 import type { ReadSignal } from '../signals/types'
-import { bindFieldDevtoolsOwner, createField } from './field'
+import {
+  bindFieldDevtoolsOwner,
+  bindFieldValidatorErrorReporter,
+  createField,
+  type ValidatorErrorReporter,
+} from './field'
 import type {
   DeepPartial,
   FieldArray,
@@ -49,21 +54,59 @@ class FormImpl<S extends FormSchema> implements Form<S> {
   private readonly validators: ReadonlyArray<FormValidator<S>>
   private readonly options: FormOptions<S> | undefined
   private validatorDispose: (() => void) | null = null
+  private initialDispose: (() => void) | null = null
   private currentValidatorRun = 0
   private currentValidatorAbort: AbortController | null = null
   private disposed = false
+  private onValidatorError: ((err: unknown) => void) | null = null
 
-  constructor(schema: S, options?: FormOptions<S>) {
+  /** Internal — wire a sync-throw reporter for the top-level validators. */
+  bindValidatorErrorReporter(reporter: ((err: unknown) => void) | null): void {
+    this.onValidatorError = reporter
+  }
+
+  constructor(
+    schema: S,
+    options?: FormOptions<S>,
+    internalOptions?: { onValidatorError?: (err: unknown) => void },
+  ) {
     this.fields = schema
     this.options = options
     this.validators = options?.validators ?? []
-
-    // Apply initial values (one-shot or initial snapshot from a function).
-    // `asInitial: true` flag tells leaf fields to set their value AND re-anchor
-    // their `reset()` target without marking themselves dirty.
+    // Capture reporter BEFORE the top-level validator effect kicks off in
+    // this constructor — mirrors the FieldImpl fix.
+    this.onValidatorError = internalOptions?.onValidatorError ?? null
+
+    // Initial values — supports both the static shape and the tracked-function
+    // shape from spec §8.4. For the function form, wrap in an effect so a
+    // change to any tracked signal re-seats the form (subject to the dirty
+    // guard from `resetOnInitialChange`).
     if (options?.initial !== undefined) {
-      const ini = typeof options.initial === 'function' ? options.initial() : options.initial
-      if (ini !== undefined) this.applyPartial(ini as DeepPartial<FormValue<S>>, true)
+      if (typeof options.initial === 'function') {
+        const initialFn = options.initial
+        const mode = options.resetOnInitialChange ?? 'when-clean'
+        let firstRun = true
+        this.initialDispose = effect(() => {
+          // Track signals read by `initialFn`. The dirty-guard MUST run
+          // untracked — otherwise `isDirty` would become a dep and re-seating
+          // on user input would cascade.
+          const ini = initialFn()
+          if (ini === undefined) return
+          untracked(() => {
+            if (this.disposed) return
+            if (firstRun) {
+              firstRun = false
+              this.applyPartial(ini as DeepPartial<FormValue<S>>, true)
+              return
+            }
+            if (mode === 'never') return
+            if (mode === 'when-clean' && this.isDirty.peek()) return
+            this.applyPartial(ini as DeepPartial<FormValue<S>>, true)
+          })
+        })
+      } else {
+        this.applyPartial(options.initial as DeepPartial<FormValue<S>>, true)
+      }
     }
 
     this.value = computed(() => this.computeValue())
@@ -145,6 +188,10 @@ class FormImpl<S extends FormSchema> implements Form<S> {
     for (const [k, val] of Object.entries(partial)) {
       const child = (this.fields as Record<string, unknown>)[k]
       if (!child) continue
+      // `partial.someNestedForm === undefined` means "leave this subtree
+      // alone", not "reset it with undefined" — which would crash on
+      // `Object.entries(undefined)`.
+      if (val === undefined) continue
       if (isForm(child)) {
         // Nested form: recurse via its own `set` (user) or rebuild via reset
         // through the same `applyPartial`-with-`asInitial` flag (initial).
@@ -214,6 +261,12 @@ class FormImpl<S extends FormSchema> implements Form<S> {
       }
     }
     await Promise.all(tasks)
+    // Kick a fresh top-level run so the surface matches "re-run every
+    // validator" — without this, `validate()` would skip top-level if it
+    // settled before the call and the value hasn't tracked-changed since.
+    if (this.validators.length > 0) {
+      this.runTopLevelValidators()
+    }
     // Wait for top-level validators to finish.
     if (this.topLevelValidating$.peek()) {
       await new Promise<void>((resolve) => {
@@ -232,6 +285,7 @@ class FormImpl<S extends FormSchema> implements Form<S> {
     if (this.disposed) return
     this.disposed = true
     this.validatorDispose?.()
+    this.initialDispose?.()
     this.currentValidatorAbort?.abort()
     for (const child of Object.values(this.fields)) {
       ;(child as { dispose?: () => void }).dispose?.()
@@ -249,9 +303,18 @@ class FormImpl<S extends FormSchema> implements Form<S> {
     const syncErrors: string[] = []
     const asyncPromises: Promise<string | null>[] = []
     for (const v of this.validators) {
-      const r = v(value, abort.signal)
-      if (r instanceof Promise) asyncPromises.push(r)
-      else if (r != null) syncErrors.push(r)
+      try {
+        const r = v(value, abort.signal)
+        if (r instanceof Promise) asyncPromises.push(r)
+        else if (r != null) syncErrors.push(r)
+      } catch (err) {
+        try {
+          this.onValidatorError?.(err)
+        } catch {
+          // The reporter must not propagate.
+        }
+        syncErrors.push(err instanceof Error ? err.message : String(err))
+      }
     }
 
     if (syncErrors.length > 0) {
@@ -346,10 +409,21 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
   private currentValidatorAbort: AbortController | null = null
   private validatorDispose: (() => void) | null = null
   private disposed = false
+  private onValidatorError: ((err: unknown) => void) | null = null
 
-  constructor(itemFactory: (initial?: ItemInitial<I>) => I, options?: FieldArrayOptions<I>) {
+  /** Internal — see `FormImpl.bindValidatorErrorReporter`. */
+  bindValidatorErrorReporter(reporter: ((err: unknown) => void) | null): void {
+    this.onValidatorError = reporter
+  }
+
+  constructor(
+    itemFactory: (initial?: ItemInitial<I>) => I,
+    options?: FieldArrayOptions<I>,
+    internalOptions?: { onValidatorError?: (err: unknown) => void },
+  ) {
     this.itemFactory = itemFactory
     this.validators = options?.validators ?? []
+    this.onValidatorError = internalOptions?.onValidatorError ?? null
     this.items$ = signal<I[]>([])
     if (options?.initial) {
       this.initialItems = options.initial
@@ -480,6 +554,10 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
       else tasks.push((item as Field<unknown>).revalidate())
     }
     await Promise.all(tasks)
+    // Fresh top-level run — see `FormImpl.validate` for the rationale.
+    if (this.validators.length > 0) {
+      this.runTopLevelValidators()
+    }
     if (this.topLevelValidating$.peek()) {
       await new Promise<void>((resolve) => {
         const unsub = this.topLevelValidating$.subscribe((v) => {
@@ -514,9 +592,18 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
     const syncErrors: string[] = []
     const asyncPromises: Promise<string | null>[] = []
     for (const v of this.validators) {
-      const r = v(value, abort.signal)
-      if (r instanceof Promise) asyncPromises.push(r)
-      else if (r != null) syncErrors.push(r)
+      try {
+        const r = v(value, abort.signal)
+        if (r instanceof Promise) asyncPromises.push(r)
+        else if (r != null) syncErrors.push(r)
+      } catch (err) {
+        try {
+          this.onValidatorError?.(err)
+        } catch {
+          // The reporter must not propagate.
+        }
+        syncErrors.push(err instanceof Error ? err.message : String(err))
+      }
     }
 
     if (syncErrors.length > 0) {
@@ -554,15 +641,20 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
   }
 }
 
-export function createForm<S extends FormSchema>(schema: S, options?: FormOptions<S>): Form<S> {
-  return new FormImpl(schema, options)
+export function createForm<S extends FormSchema>(
+  schema: S,
+  options?: FormOptions<S>,
+  internalOptions?: { onValidatorError?: (err: unknown) => void },
+): Form<S> {
+  return new FormImpl(schema, options, internalOptions)
 }
 
 export function createFieldArray<I extends Field<any> | Form<any>>(
   itemFactory: (initial?: ItemInitial<I>) => I,
   options?: FieldArrayOptions<I>,
+  internalOptions?: { onValidatorError?: (err: unknown) => void },
 ): FieldArray<I> {
-  return new FieldArrayImpl<I>(itemFactory, options)
+  return new FieldArrayImpl<I>(itemFactory, options, internalOptions)
 }
 
 /**
@@ -614,16 +706,40 @@ function bindTreeToDevtoolsInto(
   }
   if (isFieldArray(node)) {
     // Re-bind on every items change so dynamically-added entries get tracked.
-    // `effect()` returns its own disposer; capture it so the controller can
-    // tear it down on dispose (otherwise dynamic forms leak reactive work).
+    // Each re-bind has its own disposer set scoped to that pass; on the next
+    // items change we flush the previous pass's disposers BEFORE creating the
+    // new effects, so a churning array doesn't accumulate reactive work.
+    // (Pre-fix, every items mutation appended fresh effects to the outer
+    // `disposers` array and never released the old ones.)
     const arr = node as FieldArray<Field<unknown> | Form<FormSchema>>
+    let perPass: Array<() => void> = []
     const stop = effect(() => {
       const items = arr.items.value
+      // Flush previous pass before rebinding the new item set.
+      for (const d of perPass) {
+        try {
+          d()
+        } catch {
+          // Disposer failures must not break sibling cleanup.
+        }
+      }
+      perPass = []
       items.forEach((item, idx) => {
-        bindTreeToDevtoolsInto(item, `${prefix}[${idx}]`, controllerPath, emitter, disposers)
+        bindTreeToDevtoolsInto(item, `${prefix}[${idx}]`, controllerPath, emitter, perPass)
       })
     })
     disposers.push(stop)
+    // On final dispose, drain the per-pass disposers too.
+    disposers.push(() => {
+      for (const d of perPass) {
+        try {
+          d()
+        } catch {
+          // Ignore.
+        }
+      }
+      perPass = []
+    })
     return
   }
   // Leaf Field.
@@ -634,6 +750,40 @@ function bindTreeToDevtoolsInto(
   })
 }
 
+/**
+ * Walk a Form/FieldArray subtree and install `reporter` on every level —
+ * leaf fields, nested forms' top-level validators, and field-arrays' top-level
+ * validators. Called by `ctx.form` / `ctx.fieldArray` so synchronous validator
+ * throws anywhere in the tree route through `root.onError`. See
+ * `ValidatorErrorReporter` in `./field.ts`.
+ */
+export function bindTreeValidatorErrorReporter(
+  node: Field<unknown> | Form<FormSchema> | FieldArray<Field<unknown> | Form<FormSchema>>,
+  reporter: ValidatorErrorReporter | null,
+): void {
+  if (isForm(node)) {
+    const impl = node as { bindValidatorErrorReporter?: (r: ValidatorErrorReporter | null) => void }
+    impl.bindValidatorErrorReporter?.(reporter)
+    for (const child of Object.values(node.fields)) {
+      bindTreeValidatorErrorReporter(child, reporter)
+    }
+    return
+  }
+  if (isFieldArray(node)) {
+    const impl = node as { bindValidatorErrorReporter?: (r: ValidatorErrorReporter | null) => void }
+    impl.bindValidatorErrorReporter?.(reporter)
+    // Items currently in the array. (Items added later won't get the reporter
+    // unless `ctx.fieldArray` is wrapped to rebind — but the leaf items in the
+    // typical pattern come from a user factory that constructs through
+    // `createField` and is bound here by the parent traversal.)
+    for (const item of node.items.value) {
+      bindTreeValidatorErrorReporter(item, reporter)
+    }
+    return
+  }
+  bindFieldValidatorErrorReporter(node as Field<unknown>, reporter)
+}
+
 // Quiet unused-import linter without exporting these symbols publicly.
 void createField
 void untracked

package/src/index.ts

@@ -44,6 +44,11 @@ export type {
   InfiniteQuerySpec,
   InfiniteQuerySubscription,
 } from './query/infinite'
+// Key hashing — exported so plugins (entities, etc.) that need a stable
+// per-`keyArgs` index key reuse the canonical implementation instead of
+// rolling their own ad-hoc JSON.stringify (which mishandles Date, key
+// ordering, and `undefined`).
+export { stableHash } from './query/keys'
 export type {
   Mutation,
   MutationConcurrency,