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

package/src/controller/types.ts

@@ -79,6 +79,80 @@ export type CtrlProps<C> = C extends ControllerDef<infer P, unknown> ? P : never
 /** Extract a controller's Api type. */
 export type CtrlApi<C> = C extends ControllerDef<unknown, infer A> ? A : never
 
+/**
+ * The reactive surface returned by `ctx.collection(...)`. `items` is the
+ * canonical ordered view (source-order, with any construction-failed items
+ * filtered out); `size` mirrors `items.length`; `get` / `has` are
+ * imperative key lookups. SPEC §11.1.
+ */
+export type Collection<K, Api> = {
+  readonly items: ReadSignal<ReadonlyArray<{ readonly key: K; readonly api: Api }>>
+  readonly size: ReadSignal<number>
+  get(key: K): Api | undefined
+  has(key: K): boolean
+}
+
+/**
+ * Homogeneous form of `ctx.collection`: one controller def for every item,
+ * with `propsOf` projecting each item to the controller's `Props`. Construct
+ * happens once per new key — `propsOf` is **not** re-applied for unchanged
+ * keys.
+ */
+export type CollectionHomogeneousOptions<Item, K, Props, Api, TDeps = AmbientDeps> = {
+  readonly source: ReadSignal<readonly Item[]>
+  readonly keyOf: (item: Item) => K
+  readonly controller: ControllerDef<Props, Api>
+  readonly propsOf: (item: Item) => Props
+  readonly factory?: never
+  readonly propsFor?: never
+  readonly deps?: Partial<TDeps>
+}
+
+/**
+ * Heterogeneous form of `ctx.collection`: a single `factory` decides per-item
+ * which controller + props to construct. When a key's factory result picks a
+ * *different* controller than last time, the existing child is disposed and
+ * the new one constructed (type-discriminant rebuild).
+ *
+ * `R` is the factory's *return type* (typically inferred as the union of the
+ * branches' `{ controller, props }` shapes). `Api` is then projected out as
+ * the union of every branch's controller Api via `CollectionFactoryApi<R>` —
+ * unlike a single `Api` generic, the union doesn't collapse to the first
+ * branch.
+ */
+export type CollectionFactoryOptions<Item, K, R, TDeps = AmbientDeps> = {
+  readonly source: ReadSignal<readonly Item[]>
+  readonly keyOf: (item: Item) => K
+  readonly controller?: never
+  readonly propsOf?: never
+  readonly factory: (item: Item) => R
+  readonly deps?: Partial<TDeps>
+}
+
+/** Constraint for the factory form's return shape. */
+// biome-ignore lint/suspicious/noExplicitAny: per-branch types vary
+export type CollectionFactoryResult = { controller: ControllerDef<any, any>; props: any }
+
+/** Extract the union of every branch's controller Api. Distributes over R. */
+export type CollectionFactoryApi<R> = R extends {
+  // biome-ignore lint/suspicious/noExplicitAny: distributive infer across the union
+  controller: ControllerDef<any, infer A>
+}
+  ? A
+  : never
+
+/**
+ * Handle returned by `ctx.lazyChild(...)`. `status` walks `idle → loading →
+ * (ready | error)`; `api` becomes defined once `status === 'ready'`. SPEC §16.5.
+ */
+export type LazyChild<Api> = {
+  readonly status: ReadSignal<'idle' | 'loading' | 'ready' | 'error'>
+  readonly api: ReadSignal<Api | undefined>
+  readonly error: ReadSignal<unknown | undefined>
+  load(): Promise<Api>
+  dispose(): void
+}
+
 /**
  * `ctx` is the lifecycle-bound surface every controller factory receives.
  * Every primitive constructed through `ctx` is owned by the controller and
@@ -127,18 +201,85 @@ 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 }
+
+  /**
+   * Ephemeral child controller bound to either (a) the explicit `dispose()`
+   * call returned in the tuple, or (b) the parent's disposal — whichever
+   * comes first. Same lifecycle semantics as `ctx.attach` minus suspend /
+   * resume (sessions are short-lived, not pause-able). Returns a `[api,
+   * dispose]` tuple so the api shape is exactly the controller's return
+   * type, with no wrapper to unpack.
+   *
+   * Use cases: modal forms, inline edit sessions, wizards, command palette.
+   * SPEC §11.1.
+   */
+  session<Props, Api>(
+    def: ControllerDef<Props, Api>,
+    props: Props,
+    options?: { deps?: Partial<TDeps> },
+  ): readonly [api: Api, dispose: () => void]
+
+  /**
+   * Diff-by-key set of child controllers driven by a reactive `source`.
+   * On every change to `source`, the collection:
+   *   - **new keys** → construct a child via `controller` + `propsOf(item)`
+   *     (or `factory(item)` for the heterogeneous form);
+   *   - **removed keys** → dispose that child;
+   *   - **unchanged keys** → leave it alone (`propsOf` is NOT re-applied).
+   *
+   * For per-item type-discriminated children, use the `factory` form —
+   * type changes for an existing key dispose and reconstruct.
+   *
+   * Construction errors (factory or controller throw) are routed to
+   * `onError` with `kind: 'construction'` and the item is **skipped** —
+   * the collection's surface shows one fewer entry. The diff loop does
+   * not re-throw. SPEC §11.1, §12.1.6.
+   */
+  collection<Item, K, Props, Api>(
+    options: CollectionHomogeneousOptions<Item, K, Props, Api, TDeps>,
+  ): Collection<K, Api>
+  collection<Item, K, R extends CollectionFactoryResult>(
+    options: CollectionFactoryOptions<Item, K, R, TDeps>,
+  ): Collection<K, CollectionFactoryApi<R>>
+
+  /**
+   * Code-split child controller. The loader is invoked on `load()`
+   * (idempotent), then the controller is constructed with the supplied
+   * `props`. `status` / `api` / `error` are reactive signals; subscribe
+   * via `use(child.api)` in your view layer.
+   *
+   * Parent disposal disposes the loaded child (if any) and flags any
+   * in-flight load so its eventual settle is dropped on the floor.
+   * Construction or import failures route through `onError` with
+   * `kind: 'construction'`. SPEC §16.5.
+   */
+  lazyChild<Props, Api>(
+    loader: () => Promise<ControllerDef<Props, Api>>,
+    props: Props,
+    options?: { deps?: Partial<TDeps> },
+  ): LazyChild<Api>
 
   effect(fn: () => void | (() => void)): void
 

package/src/emitter.ts

@@ -20,17 +20,43 @@ export type Emitter<T> = {
 
 type AnyHandler = (value: unknown) => void
 
+/**
+ * Optional escape hatch for emit-time handler throws. If supplied, a thrown
+ * handler is reported here and emission continues with the remaining handlers
+ * (spec §20.6 — one throwing handler must not block the rest). If absent,
+ * the throw is logged via `console.error`.
+ */
+export type EmitterErrorReporter = (err: unknown) => void
+
 class EmitterImpl<T> {
   private handlers = new Set<AnyHandler>()
   private disposed = false
 
+  constructor(private onError?: EmitterErrorReporter) {}
+
   emit(value: T): void {
     if (this.disposed) return
     // Snapshot so a handler that unsubscribes itself (or another) doesn't
     // mutate the set mid-iteration.
     const snapshot = Array.from(this.handlers)
     for (const handler of snapshot) {
-      handler(value as unknown)
+      try {
+        handler(value as unknown)
+      } catch (err) {
+        // Spec §20.6: isolate handler throws so siblings still fire.
+        if (this.onError) {
+          try {
+            this.onError(err)
+          } catch {
+            // Reporter itself threw — last resort.
+            // eslint-disable-next-line no-console
+            console.error('[olas] emitter handler threw and reporter threw:', err)
+          }
+        } else {
+          // eslint-disable-next-line no-console
+          console.error('[olas] emitter handler threw:', err)
+        }
+      }
     }
   }
 
@@ -67,9 +93,14 @@ class EmitterImpl<T> {
  * (or the emitter is disposed). Use this for emitters that live outside any
  * single controller — typically in deps. Use `ctx.emitter()` for emitters that
  * should auto-clean with a controller.
+ *
+ * Pass `onError` to receive emit-time handler throws (spec §20.6 — one
+ * throwing handler must not block the rest of the fan-out). `ctx.emitter()`
+ * wires this to the root's `onError` so deps-level emitters get isolation
+ * by default when constructed via `ctx`.
  */
-export function createEmitter<T = void>(): Emitter<T> {
-  const impl = new EmitterImpl<T>()
+export function createEmitter<T = void>(options?: { onError?: EmitterErrorReporter }): Emitter<T> {
+  const impl = new EmitterImpl<T>(options?.onError)
   return {
     emit: ((value?: T) => impl.emit(value as T)) as Emitter<T>['emit'],
     on: (handler) => impl.on(handler),

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> = {