@kontsedal/olas-core 0.0.1-rc.1 → 0.0.2

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).
@@ -155,10 +202,42 @@ class FormImpl<S extends FormSchema> implements Form<S> {
         }
       } else if (isFieldArray(child)) {
         const arr = child
-        // Replace items: clear, then add each
-        arr.clear()
-        for (const itemVal of val as unknown[]) {
-          arr.add(itemVal as ItemInitial<Field<unknown>>)
+        const newValues = val as unknown[]
+        if (asInitial) {
+          // Reset-style application: replace items wholesale and re-anchor
+          // them as the new initial so a later `reset()` returns here.
+          arr.clear()
+          for (const itemVal of newValues) {
+            arr.add(itemVal as ItemInitial<Field<unknown>>)
+          }
+          // Internal: re-anchor the initialItems list. `replaceInitialItems`
+          // is only exposed for this exact use case.
+          ;(
+            arr as unknown as {
+              replaceInitialItems: (items: ReadonlyArray<unknown>) => void
+            }
+          ).replaceInitialItems(newValues)
+        } else {
+          // User-driven patch: preserve item identity where the lengths
+          // overlap so touched / dirty / in-flight validators on existing
+          // items survive. Tail diff handles grow / shrink.
+          const current = arr.items.peek() as ReadonlyArray<Field<unknown> | Form<FormSchema>>
+          const overlap = Math.min(current.length, newValues.length)
+          for (let i = 0; i < overlap; i++) {
+            const item = current[i]
+            const v = newValues[i]
+            if (isForm(item)) {
+              item.set(v as DeepPartial<FormValue<FormSchema>>)
+            } else {
+              ;(item as Field<unknown>).set(v)
+            }
+          }
+          for (let i = current.length; i < newValues.length; i++) {
+            arr.add(newValues[i] as ItemInitial<Field<unknown>>)
+          }
+          for (let i = current.length - 1; i >= newValues.length; i--) {
+            arr.remove(i)
+          }
         }
       } else {
         const f = child as Field<unknown>
@@ -214,6 +293,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 +317,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 +335,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) {
@@ -340,16 +435,27 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
   private readonly topLevelValidating$: Signal<boolean> = signal(false)
 
   private readonly itemFactory: (initial?: ItemInitial<I>) => I
-  private readonly initialItems: Array<ItemInitial<I>> = []
+  private initialItems: Array<ItemInitial<I>> = []
   private readonly validators: ReadonlyArray<FieldArrayValidator<I>>
   private currentValidatorRun = 0
   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
@@ -454,6 +560,16 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
     this.items$.set([])
   }
 
+  /**
+   * Internal — used by `Form.resetWithInitial` to re-anchor the array's
+   * initial items after a parent-driven `applyPartial(..., asInitial: true)`.
+   * Without this, a subsequent `reset()` would revert to the construction-
+   * time initials rather than the most-recently-applied ones.
+   */
+  replaceInitialItems(items: ReadonlyArray<ItemInitial<I>>): void {
+    this.initialItems = [...items]
+  }
+
   reset(): void {
     if (this.disposed) return
     batch(() => {
@@ -480,6 +596,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 +634,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 +683,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 +748,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 +792,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

@@ -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,7 +22,7 @@ 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
@@ -44,6 +50,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,