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

package/src/controller/instance.ts

@@ -2,7 +2,12 @@ import type { DevtoolsEmitter } from '../devtools'
 import { createEmitter, type Emitter } from '../emitter'
 import { dispatchError, type ErrorHandler } from '../errors'
 import { bindFieldDevtoolsOwner, createField } from '../forms/field'
-import { bindTreeToDevtools, createFieldArray, createForm } from '../forms/form'
+import {
+  bindTreeToDevtools,
+  bindTreeValidatorErrorReporter,
+  createFieldArray,
+  createForm,
+} from '../forms/form'
 import type {
   FieldArray,
   FieldArrayOptions,
@@ -19,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
@@ -36,6 +51,17 @@ type LifecycleEntry =
       dispose: (() => void) | null
     }
   | { kind: 'cleanup'; dispose: () => void }
+  | {
+      /**
+       * Cache subscription via `ctx.use`. Suspend/resume call the
+       * `suspend`/`resume` hooks so the underlying entry's `refetchInterval`
+       * and event listeners pause for the duration. Spec §4.1.
+       */
+      kind: 'subscription-cache'
+      dispose: () => void
+      suspend: () => void
+      resume: () => void
+    }
   | { kind: 'child'; instance: ControllerInstance }
   | { kind: 'onDispose'; fn: () => void }
   | { kind: 'onSuspend'; fn: () => void }
@@ -109,7 +135,6 @@ export class ControllerInstance {
 
   dispose(): void {
     if (this.state === 'disposed') return
-    const wasSuspended = this.state === 'suspended'
     this.state = 'disposed'
 
     for (let i = this.entries.length - 1; i >= 0; i--) {
@@ -130,8 +155,6 @@ export class ControllerInstance {
     if (__DEV__) {
       this.rootShared.devtools.emit({ type: 'controller:disposed', path: this.path })
     }
-    // Silence "unused" — `wasSuspended` may inform future logic; intentionally a no-op for now.
-    void wasSuspended
   }
 
   private disposeEntry(entry: LifecycleEntry): void {
@@ -143,6 +166,9 @@ export class ControllerInstance {
       case 'cleanup':
         entry.dispose()
         break
+      case 'subscription-cache':
+        entry.dispose()
+        break
       case 'child':
         entry.instance.dispose()
         break
@@ -172,6 +198,11 @@ export class ControllerInstance {
             entry.dispose?.()
             entry.dispose = null
             break
+          case 'subscription-cache':
+            // Pause `refetchInterval` + focus/online listeners + release the
+            // entry from this subscriber. Spec §4.1.
+            entry.suspend()
+            break
           case 'child':
             entry.instance.suspend()
             break
@@ -204,6 +235,11 @@ export class ControllerInstance {
           case 'effect':
             entry.dispose = standaloneEffect(entry.factory)
             break
+          case 'subscription-cache':
+            // Re-acquire the entry, restart `refetchInterval`, and re-check
+            // staleness (a stale entry refetches on resume — spec §4.1).
+            entry.resume()
+            break
           case 'child':
             entry.instance.resume()
             break
@@ -255,7 +291,12 @@ export class ControllerInstance {
           }
         }
         entry.factory = wrapped
-        entry.dispose = standaloneEffect(wrapped)
+        // If we're suspended, register the entry but defer activation to
+        // `resume()` — otherwise the resume loop would overwrite a live
+        // `dispose` ref (the just-activated effect), leaking it.
+        if (self.state !== 'suspended') {
+          entry.dispose = standaloneEffect(wrapped)
+        }
         self.entries.push(entry)
       },
 
@@ -271,21 +312,31 @@ export class ControllerInstance {
       use(query: any, keyOrOptions?: any): any {
         const brand = (query as { __olas?: string }).__olas
         if (brand === 'infiniteQuery') {
-          const { subscription, dispose: d } = createInfiniteUse(
+          const handle = createInfiniteUse(
             self.rootShared.queryClient,
             query as InfiniteQuery<unknown[], unknown, unknown>,
             keyOrOptions,
           )
-          self.entries.push({ kind: 'cleanup', dispose: d })
-          return subscription
+          self.entries.push({
+            kind: 'subscription-cache',
+            dispose: handle.dispose,
+            suspend: handle.suspend,
+            resume: handle.resume,
+          })
+          return handle.subscription
         }
-        const { subscription, dispose: d } = createUse(
+        const handle = createUse(
           self.rootShared.queryClient,
           query as Query<unknown[], unknown>,
           keyOrOptions,
         )
-        self.entries.push({ kind: 'cleanup', dispose: d })
-        return subscription
+        self.entries.push({
+          kind: 'subscription-cache',
+          dispose: handle.dispose,
+          suspend: handle.suspend,
+          resume: handle.resume,
+        })
+        return handle.subscription
       },
 
       mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R> {
@@ -301,13 +352,33 @@ 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
       },
 
       field<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T> {
-        const f = createField(initial, validators)
+        // Pass the reporter at construct time so the FIRST validator pass
+        // (which runs synchronously in the FieldImpl constructor's
+        // validator-effect) is covered.
+        const f = createField(initial, validators, {
+          onValidatorError: (err) => {
+            dispatchError(self.rootShared.onError, err, {
+              kind: 'effect',
+              controllerPath: self.path,
+            })
+          },
+        })
         self.entries.push({ kind: 'cleanup', dispose: () => f.dispose() })
         // Standalone fields (not inside a form) still publish field:validated
         // events. Use the controller path with field name "(field)" — the
@@ -321,7 +392,13 @@ export class ControllerInstance {
       },
 
       form<S extends FormSchema>(schema: S, options?: FormOptions<S>): Form<S> {
-        const f = createForm(schema, options)
+        const reporter = (err: unknown): void => {
+          dispatchError(self.rootShared.onError, err, {
+            kind: 'effect',
+            controllerPath: self.path,
+          })
+        }
+        const f = createForm(schema, options, { onValidatorError: reporter })
         self.entries.push({ kind: 'cleanup', dispose: () => f.dispose() })
         // Make every leaf field publish `field:validated` to the devtools bus
         // with its key path inside the form. See spec §20.9.
@@ -332,6 +409,12 @@ export class ControllerInstance {
           self.rootShared.devtools,
         )
         self.entries.push({ kind: 'cleanup', dispose: stop })
+        // Bind the reporter onto every leaf in the tree too (the form itself
+        // got it via the constructor option; nested forms/arrays inside the
+        // schema didn't, since they were constructed by the caller before
+        // ctx.form ran). Idempotent — leaves that already got the reporter
+        // via ctx.field get the same one set again.
+        bindTreeValidatorErrorReporter(f as unknown as Form<FormSchema>, reporter)
         return f
       },
 
@@ -339,7 +422,13 @@ export class ControllerInstance {
         itemFactory: (initial?: ItemInitial<I>) => I,
         options?: FieldArrayOptions<I>,
       ): FieldArray<I> {
-        const fa = createFieldArray<I>(itemFactory, options)
+        const reporter = (err: unknown): void => {
+          dispatchError(self.rootShared.onError, err, {
+            kind: 'effect',
+            controllerPath: self.path,
+          })
+        }
+        const fa = createFieldArray<I>(itemFactory, options, { onValidatorError: reporter })
         self.entries.push({ kind: 'cleanup', dispose: () => fa.dispose() })
         const stop = bindTreeToDevtools(
           fa as unknown as FieldArray<Field<unknown> | Form<FormSchema>>,
@@ -348,6 +437,10 @@ export class ControllerInstance {
           self.rootShared.devtools,
         )
         self.entries.push({ kind: 'cleanup', dispose: stop })
+        bindTreeValidatorErrorReporter(
+          fa as unknown as FieldArray<Field<unknown> | Form<FormSchema>>,
+          reporter,
+        )
         return fa
       },
 
@@ -407,7 +500,7 @@ export class ControllerInstance {
         def: ControllerDef<Props, Api>,
         props: Props,
         options?: { deps?: Partial<Record<string, unknown>> },
-      ): { api: Api; dispose: () => void } {
+      ): { api: Api; dispose: () => void; suspend: () => void; resume: () => void } {
         const segment = self.makeChildSegment(getFactory(def), getName(def))
         const override = options?.deps
         const childDeps = override !== undefined ? { ...self.deps, ...override } : self.deps
@@ -432,6 +525,327 @@ export class ControllerInstance {
               })
             }
           },
+          // Suspend / resume cascade through the child instance's lifecycle
+          // entries (same code path as `root.suspend()`); the child's state
+          // machine handles the no-op cases (suspending a disposed child,
+          // resuming an active child) on its own — no need to track an
+          // extra flag here.
+          suspend: () => {
+            if (disposed) return
+            try {
+              childInstance.suspend()
+            } catch (err) {
+              dispatchError(self.rootShared.onError, err, {
+                kind: 'effect',
+                controllerPath: self.path,
+              })
+            }
+          },
+          resume: () => {
+            if (disposed) return
+            try {
+              childInstance.resume()
+            } catch (err) {
+              dispatchError(self.rootShared.onError, err, {
+                kind: 'effect',
+                controllerPath: self.path,
+              })
+            }
+          },
+        }
+      },
+
+      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,
         }
       },
 

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.