@kontsedal/olas-core 0.0.1 → 0.0.2

package/src/controller/instance.ts

@@ -24,9 +24,19 @@ import { createMutation, type Mutation, type MutationSpec } from '../query/mutat
 import type { LocalCache, Query } from '../query/types'
 import { createInfiniteUse, createUse } from '../query/use'
 import type { Scope } from '../scope'
-import { effect as standaloneEffect } from '../signals'
+import { computed, signal, effect as standaloneEffect } from '../signals'
 import { getFactory, getName } from './define'
-import type { ControllerDef, Ctx, Field } from './types'
+import type {
+  Collection,
+  CollectionFactoryApi,
+  CollectionFactoryOptions,
+  CollectionFactoryResult,
+  CollectionHomogeneousOptions,
+  ControllerDef,
+  Ctx,
+  Field,
+  LazyChild,
+} from './types'
 
 export type RootShared = {
   readonly devtools: DevtoolsEmitter
@@ -342,7 +352,17 @@ export class ControllerInstance {
       },
 
       emitter<T>(): Emitter<T> {
-        const e = createEmitter<T>()
+        const e = createEmitter<T>({
+          // Spec §20.6: emit-time handler throws must not block sibling
+          // handlers. Route to the root's onError with kind: 'emitter' and
+          // this controller's path.
+          onError: (err) => {
+            dispatchError(self.rootShared.onError, err, {
+              kind: 'emitter',
+              controllerPath: self.path,
+            })
+          },
+        })
         self.entries.push({ kind: 'cleanup', dispose: () => e.dispose() })
         return e
       },
@@ -535,6 +555,300 @@ export class ControllerInstance {
         }
       },
 
+      session<Props, Api>(
+        def: ControllerDef<Props, Api>,
+        props: Props,
+        options?: { deps?: Partial<Record<string, unknown>> },
+      ): readonly [Api, () => void] {
+        const segment = self.makeChildSegment(getFactory(def), getName(def))
+        const override = options?.deps
+        const childDeps = override !== undefined ? { ...self.deps, ...override } : self.deps
+        const childInstance = new ControllerInstance(self, self.rootShared, segment, childDeps)
+        const api = childInstance.construct(getFactory(def), props)
+        const entry: LifecycleEntry = { kind: 'child', instance: childInstance }
+        self.entries.push(entry)
+        let disposed = false
+        const dispose = (): void => {
+          if (disposed) return
+          disposed = true
+          const idx = self.entries.indexOf(entry)
+          if (idx >= 0) self.entries.splice(idx, 1)
+          try {
+            childInstance.dispose()
+          } catch (err) {
+            dispatchError(self.rootShared.onError, err, {
+              kind: 'effect',
+              controllerPath: self.path,
+            })
+          }
+        }
+        return [api, dispose] as const
+      },
+
+      collection<Item, K, Props, Api, R extends CollectionFactoryResult>(
+        options:
+          | CollectionHomogeneousOptions<Item, K, Props, Api>
+          | CollectionFactoryOptions<Item, K, R>,
+      ): Collection<K, Api> | Collection<K, CollectionFactoryApi<R>> {
+        type ChildInfo = {
+          instance: ControllerInstance
+          api: Api
+          entry: LifecycleEntry
+          // For factory form: the controller def used to construct this child.
+          // A different def on a future render means "rebuild with new type".
+          def: ControllerDef<unknown, unknown>
+        }
+        const childMap = new Map<K, ChildInfo>()
+        const items$ = signal<ReadonlyArray<{ key: K; api: Api }>>([])
+        const size$ = computed(() => items$.value.length)
+
+        const isFactoryForm =
+          (options as CollectionFactoryOptions<Item, K, R>).factory !== undefined
+
+        const buildChild = (
+          item: Item,
+        ): {
+          instance: ControllerInstance
+          api: Api
+          def: ControllerDef<unknown, unknown>
+        } | null => {
+          let def: ControllerDef<unknown, unknown>
+          let childProps: unknown
+          if (isFactoryForm) {
+            const factoryOpts = options as CollectionFactoryOptions<Item, K, R>
+            const result = factoryOpts.factory(item) as CollectionFactoryResult
+            def = result.controller as ControllerDef<unknown, unknown>
+            childProps = result.props
+          } else {
+            const homoOpts = options as CollectionHomogeneousOptions<Item, K, Props, Api>
+            def = homoOpts.controller as unknown as ControllerDef<unknown, unknown>
+            childProps = homoOpts.propsOf(item)
+          }
+          const segment = self.makeChildSegment(getFactory(def), getName(def))
+          const childDeps =
+            options.deps !== undefined ? { ...self.deps, ...options.deps } : self.deps
+          const instance = new ControllerInstance(self, self.rootShared, segment, childDeps)
+          try {
+            const api = instance.construct(
+              getFactory(def) as (ctx: Ctx, props: unknown) => Api,
+              childProps,
+            )
+            return { instance, api, def }
+          } catch (err) {
+            // SPEC §12.1.6: runtime construction errors in collection items
+            // route to onError; the bad item is skipped.
+            dispatchError(self.rootShared.onError, err, {
+              kind: 'construction',
+              controllerPath: self.path,
+            })
+            return null
+          }
+        }
+
+        const removeKey = (key: K): void => {
+          const info = childMap.get(key)
+          if (info === undefined) return
+          childMap.delete(key)
+          const idx = self.entries.indexOf(info.entry)
+          if (idx >= 0) self.entries.splice(idx, 1)
+          try {
+            info.instance.dispose()
+          } catch (err) {
+            dispatchError(self.rootShared.onError, err, {
+              kind: 'effect',
+              controllerPath: self.path,
+            })
+          }
+        }
+
+        const reconcile = (): void => {
+          const source = options.source.value
+          const itemByKey = new Map<K, Item>()
+          for (const item of source) {
+            const key = options.keyOf(item)
+            if (!itemByKey.has(key)) itemByKey.set(key, item)
+          }
+
+          // Drop removed keys.
+          for (const key of [...childMap.keys()]) {
+            if (!itemByKey.has(key)) removeKey(key)
+          }
+
+          // Add new keys + rebuild factory-form type changes.
+          for (const [key, item] of itemByKey) {
+            const existing = childMap.get(key)
+            if (existing !== undefined) {
+              if (isFactoryForm) {
+                const result = (options as CollectionFactoryOptions<Item, K, R>).factory(
+                  item,
+                ) as CollectionFactoryResult
+                if ((result.controller as unknown) !== existing.def) {
+                  removeKey(key)
+                  const built = buildChild(item)
+                  if (built !== null) {
+                    const entry: LifecycleEntry = { kind: 'child', instance: built.instance }
+                    self.entries.push(entry)
+                    childMap.set(key, { ...built, entry })
+                  }
+                }
+              }
+              continue
+            }
+            const built = buildChild(item)
+            if (built !== null) {
+              const entry: LifecycleEntry = { kind: 'child', instance: built.instance }
+              self.entries.push(entry)
+              childMap.set(key, { ...built, entry })
+            }
+          }
+
+          // Project to items signal in source order, deduped, skipping failures.
+          const next: Array<{ key: K; api: Api }> = []
+          const seen = new Set<K>()
+          for (const item of source) {
+            const key = options.keyOf(item)
+            if (seen.has(key)) continue
+            seen.add(key)
+            const info = childMap.get(key)
+            if (info !== undefined) next.push({ key, api: info.api })
+          }
+          items$.set(next)
+        }
+
+        // Register the diff loop as an 'effect' entry so it pauses on suspend
+        // and re-runs on resume — mirrors how `ctx.effect` is wired.
+        const wrapped = (): void => {
+          try {
+            reconcile()
+          } catch (err) {
+            dispatchError(self.rootShared.onError, err, {
+              kind: 'effect',
+              controllerPath: self.path,
+            })
+          }
+        }
+        const effectEntry: LifecycleEntry = {
+          kind: 'effect',
+          factory: wrapped,
+          dispose: null,
+        }
+        if (self.state !== 'suspended') {
+          effectEntry.dispose = standaloneEffect(wrapped)
+        }
+        self.entries.push(effectEntry)
+
+        return {
+          items: items$,
+          size: size$,
+          get: (key: K) => childMap.get(key)?.api,
+          has: (key: K) => childMap.has(key),
+        }
+      },
+
+      lazyChild<Props, Api>(
+        loader: () => Promise<ControllerDef<Props, Api>>,
+        props: Props,
+        options?: { deps?: Partial<Record<string, unknown>> },
+      ): LazyChild<Api> {
+        const status$ = signal<'idle' | 'loading' | 'ready' | 'error'>('idle')
+        const api$ = signal<Api | undefined>(undefined)
+        const error$ = signal<unknown | undefined>(undefined)
+
+        let childInstance: ControllerInstance | null = null
+        let childEntry: LifecycleEntry | null = null
+        let pendingLoad: Promise<Api> | null = null
+        let disposed = false
+
+        // Parent dispose flag; the child entry (when present) is disposed
+        // via the parent's normal cascade, so we don't double-tear-down.
+        const flagEntry: LifecycleEntry = {
+          kind: 'onDispose',
+          fn: () => {
+            disposed = true
+          },
+        }
+        self.entries.push(flagEntry)
+
+        const handleFailure = (err: unknown): void => {
+          status$.set('error')
+          error$.set(err)
+          dispatchError(self.rootShared.onError, err, {
+            kind: 'construction',
+            controllerPath: self.path,
+          })
+        }
+
+        const load = (): Promise<Api> => {
+          if (disposed) {
+            return Promise.reject(new Error('[olas] ctx.lazyChild: cannot load after dispose'))
+          }
+          if (pendingLoad !== null) return pendingLoad
+          status$.set('loading')
+          pendingLoad = loader().then(
+            (def) => {
+              if (disposed) {
+                throw new Error('[olas] ctx.lazyChild: disposed during load')
+              }
+              const segment = self.makeChildSegment(getFactory(def), getName(def))
+              const childDeps =
+                options?.deps !== undefined ? { ...self.deps, ...options.deps } : self.deps
+              const instance = new ControllerInstance(self, self.rootShared, segment, childDeps)
+              try {
+                const api = instance.construct(getFactory(def), props)
+                childInstance = instance
+                childEntry = { kind: 'child', instance }
+                self.entries.push(childEntry)
+                api$.set(api)
+                status$.set('ready')
+                return api
+              } catch (err) {
+                handleFailure(err)
+                throw err
+              }
+            },
+            (err) => {
+              if (disposed) throw err
+              handleFailure(err)
+              throw err
+            },
+          )
+          return pendingLoad
+        }
+
+        const dispose = (): void => {
+          if (disposed) return
+          disposed = true
+          if (childEntry !== null && childInstance !== null) {
+            const idx = self.entries.indexOf(childEntry)
+            if (idx >= 0) self.entries.splice(idx, 1)
+            try {
+              childInstance.dispose()
+            } catch (err) {
+              dispatchError(self.rootShared.onError, err, {
+                kind: 'effect',
+                controllerPath: self.path,
+              })
+            }
+            childInstance = null
+            childEntry = null
+          }
+          // Splice the parent-dispose flag entry too — its only job was to
+          // signal disposal to an in-flight loader, and `disposed` is now
+          // already true. Leaving it behind leaks one closure per ever-
+          // disposed lazyChild for the parent's remaining lifetime.
+          const flagIdx = self.entries.indexOf(flagEntry)
+          if (flagIdx >= 0) self.entries.splice(flagIdx, 1)
+        }
+
+        return {
+          status: status$,
+          api: api$,
+          error: error$,
+          load,
+          dispose,
+        }
+      },
+
       onDispose(fn) {
         self.entries.push({
           kind: 'onDispose',

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
@@ -150,6 +224,63 @@ export type Ctx<TDeps = AmbientDeps> = {
     options?: { deps?: Partial<TDeps> },
   ): { 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
 
   on<T>(emitter: Emitter<T>, handler: (value: T) => 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/form.ts

@@ -202,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>
@@ -403,7 +435,7 @@ 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
@@ -528,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(() => {

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

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)
     },
-  }
+  })
 }