@kontsedal/olas-core 0.0.1-rc.0

package/src/controller/root.ts

@@ -0,0 +1,160 @@
+import { DevtoolsEmitter } from '../devtools'
+import { QueryClient } from '../query/client'
+import { getFactory } from './define'
+import { ControllerInstance, type RootShared } from './instance'
+import type { AmbientDeps, ControllerDef, Root, RootOptions } from './types'
+
+const ROOT_METHODS = [
+  'dispose',
+  'suspend',
+  'resume',
+  'dehydrate',
+  'waitForIdle',
+  '__debug',
+] as const
+
+/**
+ * Construct a root controller.
+ *
+ * Internal: this is the shared engine. The public `createRoot` (props-less)
+ * and `createTestController` (props-allowing) both call through here.
+ */
+export function createRootWithProps<Props, Api, TDeps extends Record<string, unknown>>(
+  def: ControllerDef<Props, Api>,
+  props: Props,
+  options: RootOptions<TDeps>,
+): Root<Api> {
+  const devtools = new DevtoolsEmitter()
+  const queryClient = new QueryClient({
+    onError: options.onError,
+    hydrate: options.hydrate,
+    devtools,
+    deps: options.deps as Record<string, unknown>,
+    refetchOnWindowFocus: options.refetchOnWindowFocus,
+    refetchOnReconnect: options.refetchOnReconnect,
+    plugins: options.plugins,
+  })
+  const rootShared: RootShared = {
+    devtools,
+    onError: options.onError,
+    queryClient,
+  }
+
+  const instance = new ControllerInstance(
+    null,
+    rootShared,
+    'root',
+    options.deps as Record<string, unknown>,
+  )
+
+  // Bootstrap failure throws straight out of createRoot. Spec §12.1.5.
+  const api = instance.construct(getFactory(def), props)
+
+  if (typeof api !== 'object' || api === null) {
+    // Allow primitive APIs in principle but root controls must live somewhere.
+    // Wrap in a holder.
+    const holder = { value: api } as unknown as Api
+    return attachRootControls(holder, instance, devtools, queryClient)
+  }
+
+  return attachRootControls(api, instance, devtools, queryClient)
+}
+
+function attachRootControls<Api>(
+  api: Api,
+  instance: ControllerInstance,
+  devtools: DevtoolsEmitter,
+  queryClient: QueryClient,
+): Root<Api> {
+  let suspendTimer: ReturnType<typeof setTimeout> | null = null
+
+  const dispose = () => {
+    if (suspendTimer != null) {
+      clearTimeout(suspendTimer)
+      suspendTimer = null
+    }
+    instance.dispose()
+    queryClient.dispose()
+  }
+
+  const suspend = (opts?: { maxIdle?: number }) => {
+    instance.suspend()
+    if (suspendTimer != null) {
+      clearTimeout(suspendTimer)
+      suspendTimer = null
+    }
+    const maxIdle = opts?.maxIdle
+    if (maxIdle != null && maxIdle !== Number.POSITIVE_INFINITY) {
+      suspendTimer = setTimeout(() => {
+        suspendTimer = null
+        dispose()
+      }, maxIdle)
+    }
+  }
+
+  const resume = () => {
+    if (suspendTimer != null) {
+      clearTimeout(suspendTimer)
+      suspendTimer = null
+    }
+    instance.resume()
+  }
+
+  const debug = {
+    subscribe: (handler: Parameters<DevtoolsEmitter['subscribe']>[0]) =>
+      devtools.subscribe(handler),
+    queryEntries: () => queryClient.queryEntriesSnapshot(),
+  }
+
+  const target = api as Record<string, unknown>
+  for (const method of ROOT_METHODS) {
+    if (Object.hasOwn(target, method)) {
+      throw new Error(
+        `[olas] Root controller api defines '${method}' which conflicts with the root controls.`,
+      )
+    }
+  }
+  Object.defineProperty(target, 'dispose', {
+    value: dispose,
+    enumerable: false,
+    configurable: true,
+  })
+  Object.defineProperty(target, 'suspend', {
+    value: suspend,
+    enumerable: false,
+    configurable: true,
+  })
+  Object.defineProperty(target, 'resume', {
+    value: resume,
+    enumerable: false,
+    configurable: true,
+  })
+  Object.defineProperty(target, '__debug', {
+    value: debug,
+    enumerable: false,
+    configurable: true,
+  })
+  Object.defineProperty(target, 'dehydrate', {
+    value: () => queryClient.dehydrate(),
+    enumerable: false,
+    configurable: true,
+  })
+  Object.defineProperty(target, 'waitForIdle', {
+    value: () => queryClient.waitForIdle(),
+    enumerable: false,
+    configurable: true,
+  })
+
+  return api as Root<Api>
+}
+
+/**
+ * Construct a root controller. Root factories take no props — startup config
+ * goes in `deps`.
+ */
+export function createRoot<Api, TDeps extends Record<string, unknown> = AmbientDeps>(
+  def: ControllerDef<void, Api>,
+  options: RootOptions<TDeps>,
+): Root<Api> {
+  return createRootWithProps<void, Api, TDeps>(def, undefined as void, options)
+}

package/src/controller/types.ts

@@ -0,0 +1,195 @@
+import type { Emitter } from '../emitter'
+import type { ErrorContext } from '../errors'
+import type {
+  FieldArray,
+  FieldArrayOptions,
+  Form,
+  FormOptions,
+  FormSchema,
+  ItemInitial,
+} from '../forms/form-types'
+import type { Validator } from '../forms/types'
+import type { InfiniteQuery, InfiniteQuerySubscription } from '../query/infinite'
+import type { Mutation, MutationSpec } from '../query/mutation'
+import type { QueryClientPlugin } from '../query/plugin'
+import type { LocalCache, Query, QuerySubscription, UseOptions } from '../query/types'
+import type { Scope } from '../scope'
+import type { ReadSignal } from '../signals/types'
+
+/**
+ * App-wide deps available on every controller's `ctx.deps`.
+ *
+ * Default shape carries an index signature so untyped reads compile (as
+ * `unknown`). Users augment this interface in their app to add typed services:
+ *
+ * ```ts
+ * declare module '@kontsedal/olas-core' {
+ *   interface AmbientDeps {
+ *     api: ApiClient
+ *     session: SessionStore
+ *   }
+ * }
+ * ```
+ */
+export interface AmbientDeps {
+  [key: string]: unknown
+}
+
+/**
+ * A reactive form field. Extends `ReadSignal<T>` for the current value, plus
+ * five signals for state (errors / isValid / isDirty / touched / isValidating)
+ * and four methods (`set`, `reset`, `markTouched`, `revalidate`). Created via
+ * `ctx.field(initial, validators?)`. Spec §8, §20.7.
+ */
+export type Field<T> = ReadSignal<T> & {
+  errors: ReadSignal<string[]>
+  isValid: ReadSignal<boolean>
+  isDirty: ReadSignal<boolean>
+  touched: ReadSignal<boolean>
+  isValidating: ReadSignal<boolean>
+  set(value: T): void
+  /**
+   * Reseat the field as if this value had been its constructor `initial`:
+   * writes the value, re-anchors `reset()`'s target, leaves `isDirty` false.
+   * `Form` uses this when applying its own `initial` (constructor + reset),
+   * so a form populated from server data isn't born dirty. Useful for any
+   * "load this value as the new baseline" pattern.
+   */
+  setAsInitial(value: T): void
+  reset(): void
+  markTouched(): void
+  revalidate(): Promise<boolean>
+  /** Idempotent. Called by the owning controller's dispose. */
+  dispose(): void
+}
+
+/**
+ * The handle returned by `defineController(...)`. Pass it to `createRoot(...)`
+ * or `ctx.child(...)` to instantiate. Phantom types preserve `Props` / `Api`
+ * for inference via `CtrlProps<C>` / `CtrlApi<C>`.
+ */
+export type ControllerDef<Props, Api> = {
+  readonly __olas: 'controller'
+  readonly __types?: { props: Props; api: Api }
+}
+
+/** Extract a controller's Props type. */
+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
+
+/**
+ * `ctx` is the lifecycle-bound surface every controller factory receives.
+ * Every primitive constructed through `ctx` is owned by the controller and
+ * disposed when the controller disposes.
+ *
+ * Phase 3 surface — caches, mutations, forms, collections, scopes, etc.
+ * land in later phases.
+ */
+export type Ctx<TDeps = AmbientDeps> = {
+  cache<T>(
+    fetcher: (signal: AbortSignal) => Promise<T>,
+    options?: {
+      key?: () => readonly unknown[]
+      staleTime?: number
+      keepPreviousData?: boolean
+      initialData?: T | undefined
+    },
+  ): LocalCache<T>
+
+  use<Args extends unknown[], T>(
+    source: Query<Args, T>,
+    keyOrOptions?: (() => Args) | UseOptions<Args>,
+  ): QuerySubscription<T>
+  use<Args extends unknown[], TPage, TItem>(
+    source: InfiniteQuery<Args, TPage, TItem>,
+    keyOrOptions?: (() => Args) | UseOptions<Args>,
+  ): InfiniteQuerySubscription<TPage, TItem>
+
+  mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R>
+
+  emitter<T = void>(): Emitter<T>
+
+  field<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T>
+
+  form<S extends FormSchema>(schema: S, options?: FormOptions<S>): Form<S>
+
+  fieldArray<I extends Field<any> | Form<any>>(
+    itemFactory: (initial?: ItemInitial<I>) => I,
+    options?: FieldArrayOptions<I>,
+  ): FieldArray<I>
+
+  child<Props, Api>(
+    def: ControllerDef<Props, Api>,
+    props: Props,
+    options?: { deps?: Partial<TDeps> },
+  ): 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.
+   */
+  attach<Props, Api>(
+    def: ControllerDef<Props, Api>,
+    props: Props,
+    options?: { deps?: Partial<TDeps> },
+  ): { api: Api; dispose: () => void }
+
+  effect(fn: () => void | (() => void)): void
+
+  on<T>(emitter: Emitter<T>, handler: (value: T) => void): void
+
+  // scopes — typed cross-tree data (§10.3)
+  provide<T>(scope: Scope<T>, value: T): void
+  inject<T>(scope: Scope<T>): T
+
+  onDispose(fn: () => void): void
+  onSuspend(fn: () => void): void
+  onResume(fn: () => void): void
+
+  readonly deps: TDeps
+}
+
+import type { DebugBus } from '../devtools'
+import type { DehydratedState } from '../query/types'
+
+/**
+ * Configuration passed to `createRoot(def, options)`. `deps` is required and
+ * available everywhere as `ctx.deps`. `onError` receives errors from effects,
+ * mutations, caches, emitter handlers, and construction. `hydrate` replays a
+ * `DehydratedState` produced on the server. Spec §20.8.
+ */
+export type RootOptions<TDeps> = {
+  deps: TDeps
+  onError?: (err: unknown, context: ErrorContext) => void
+  hydrate?: DehydratedState
+  /** Default for queries that don't set `refetchOnWindowFocus` on their spec (§5.9). */
+  refetchOnWindowFocus?: boolean
+  /** Default for queries that don't set `refetchOnReconnect` on their spec (§5.9). */
+  refetchOnReconnect?: boolean
+  /**
+   * `QueryClientPlugin`s — cross-tab sync, server-push patches, etc.
+   * Installed when the root's `QueryClient` is constructed; disposed when
+   * the root disposes. SPEC §13.2.
+   */
+  plugins?: QueryClientPlugin[]
+}
+
+/**
+ * The root's public surface: the controller's `Api` plus lifecycle controls
+ * (`dispose`, `suspend`, `resume`), SSR (`dehydrate`, `waitForIdle`), and
+ * devtools (`__debug`). Spec §20.8.
+ */
+export type Root<Api> = Api & {
+  dispose(): void
+  suspend(options?: { maxIdle?: number }): void
+  resume(): void
+  dehydrate(): DehydratedState
+  waitForIdle(): Promise<void>
+  readonly __debug: DebugBus
+}

package/src/emitter.ts

@@ -0,0 +1,79 @@
+/**
+ * Synchronous fan-out event bus. Handlers run in the order they subscribed.
+ * Handlers added during emit don't fire for the current emission; handlers
+ * removed during emit are skipped from that point in the iteration.
+ *
+ * `Emitter<void>` exposes `emit()` (no argument); other shapes expose
+ * `emit(value: T)`.
+ *
+ * Spec §7, §20.6.
+ */
+export type Emitter<T> = {
+  emit: [T] extends [void] ? () => void : (value: T) => void
+  /** Subscribe to every emission. Returns the unsubscribe function. */
+  on(handler: (value: T) => void): () => void
+  /** Subscribe to the next emission only. Auto-unsubscribes after firing. */
+  once(handler: (value: T) => void): () => void
+  /** Tear down the emitter. Subsequent `emit` / `on` / `once` are no-ops. */
+  dispose(): void
+}
+
+type AnyHandler = (value: unknown) => void
+
+class EmitterImpl<T> {
+  private handlers = new Set<AnyHandler>()
+  private disposed = false
+
+  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)
+    }
+  }
+
+  on(handler: (value: T) => void): () => void {
+    if (this.disposed) return () => {}
+    const wrapped = handler as AnyHandler
+    this.handlers.add(wrapped)
+    return () => {
+      this.handlers.delete(wrapped)
+    }
+  }
+
+  once(handler: (value: T) => void): () => void {
+    if (this.disposed) return () => {}
+    const wrapped: AnyHandler = (value) => {
+      this.handlers.delete(wrapped)
+      handler(value as T)
+    }
+    this.handlers.add(wrapped)
+    return () => {
+      this.handlers.delete(wrapped)
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.handlers.clear()
+  }
+}
+
+/**
+ * Create a standalone emitter. Handlers persist until explicitly unsubscribed
+ * (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.
+ */
+export function createEmitter<T = void>(): Emitter<T> {
+  const impl = new EmitterImpl<T>()
+  return {
+    emit: ((value?: T) => impl.emit(value as T)) as Emitter<T>['emit'],
+    on: (handler) => impl.on(handler),
+    once: (handler) => impl.once(handler),
+    dispose: () => impl.dispose(),
+  }
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+/**
+ * Context passed to a root's `onError` handler. `kind` identifies where in
+ * the controller's surface the throw originated; `controllerPath` is the
+ * path from root to the controller that owned the failing code; `queryKey`
+ * is set for `cache` kinds. Spec §12, §20.9.
+ *
+ * `'plugin'` is used for exceptions raised by `QueryClientPlugin` callbacks
+ * (`@kontsedal/olas-cross-tab` and friends); SPEC §13.2.
+ */
+export type ErrorContext = {
+  kind: 'effect' | 'cache' | 'mutation' | 'emitter' | 'construction' | 'plugin'
+  controllerPath: readonly string[]
+  queryKey?: readonly unknown[]
+}
+
+/** Signature of `RootOptions.onError`. */
+export type ErrorHandler = (err: unknown, context: ErrorContext) => void
+
+const defaultHandler: ErrorHandler = (err, context) => {
+  // eslint-disable-next-line no-console
+  console.error('[olas]', context, err)
+}
+
+/**
+ * Dispatch an error to a user-provided handler, falling back to console.error.
+ * The handler itself is wrapped — if it throws, the throw is swallowed and
+ * logged so an `onError` bug never tears down the tree.
+ *
+ * Internal — used by the controller container and query client.
+ */
+export function dispatchError(
+  handler: ErrorHandler | undefined,
+  err: unknown,
+  context: ErrorContext,
+): void {
+  const fn = handler ?? defaultHandler
+  try {
+    fn(err, context)
+  } catch (handlerErr) {
+    try {
+      // eslint-disable-next-line no-console
+      console.error('[olas] onError handler threw:', handlerErr)
+      // eslint-disable-next-line no-console
+      console.error('[olas] original error:', err, context)
+    } catch {
+      // Console itself failed — give up silently.
+    }
+  }
+}