@kontsedal/olas-core 0.0.5 → 0.1.0

package/src/controller/root.ts

@@ -10,6 +10,7 @@ const ROOT_METHODS = [
   'resume',
   'dehydrate',
   'waitForIdle',
+  'applyDehydratedEntry',
   '__debug',
 ] as const
 
@@ -38,6 +39,7 @@ export function createRootWithProps<Props, Api, TDeps extends Record<string, unk
     devtools,
     onError: options.onError,
     queryClient,
+    scopesVersion: { value: 0 },
   }
 
   const instance = new ControllerInstance(
@@ -47,6 +49,12 @@ export function createRootWithProps<Props, Api, TDeps extends Record<string, unk
     options.deps as Record<string, unknown>,
   )
 
+  // Pre-seed scopes from RootOptions before the factory runs so
+  // ctx.inject() resolves them from any descendant. SPEC §10.3.
+  if (options.scopes !== undefined && options.scopes.length > 0) {
+    instance.seedScopes(options.scopes)
+  }
+
   // Bootstrap failure throws straight out of createRoot. Spec §12.1.5.
   // Tear down the QueryClient and any plugins it spawned (window/storage
   // listeners, transports) before re-throwing so the failure doesn't leak.
@@ -58,14 +66,39 @@ export function createRootWithProps<Props, Api, TDeps extends Record<string, unk
     throw err
   }
 
+  // Non-object apis get wrapped so root controls have somewhere to live.
+  let target = api
   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)
+    // Wrap in a holder. The declared `Root<Api>` type intersection lies in
+    // this branch — `(holder as Api).dispose` won't be present on the
+    // primitive itself. Dev-warn so the footgun is visible at first run
+    // instead of as a confusing "undefined.value" later.
+    if (__DEV__) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[olas] createRoot: controller returned a non-object api ' +
+          `(${api === null ? 'null' : typeof api}). ` +
+          'Wrapping as { value: api } so root controls (dispose / suspend / ...) ' +
+          "can be attached. Prefer returning an object from a root controller's factory.",
+      )
+    }
+    target = { value: api } as unknown as Api
   }
 
-  return attachRootControls(api, instance, devtools, queryClient)
+  // attachRootControls throws on a root-controls NAME CONFLICT (the api defines
+  // `dispose`/`suspend`/...) — AFTER the tree is fully constructed. Tear down
+  // the live instance + queryClient (effects, focus/online listeners, plugin
+  // transports) before rethrowing so the conflict doesn't leak the whole tree.
+  // The construct-throw path above rolls back via queryClient.dispose(); this
+  // is the symmetric guard for the post-construction failure. (T2.5)
+  try {
+    return attachRootControls(target, instance, devtools, queryClient)
+  } catch (err) {
+    instance.dispose()
+    queryClient.dispose()
+    throw err
+  }
 }
 
 function attachRootControls<Api>(
@@ -116,41 +149,36 @@ function attachRootControls<Api>(
 
   const target = api as Record<string, unknown>
   for (const method of ROOT_METHODS) {
-    if (Object.hasOwn(target, method)) {
+    // Use `in` rather than `Object.hasOwn` so class-based apis with
+    // prototype methods like `dispose()` still trigger the conflict
+    // detection instead of being silently overwritten by defineProperty.
+    if (method in target) {
       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,
-  })
+  // Lock root controls: writable:false + configurable:false so user code
+  // can't `delete api.dispose` (orphaning the root) or shadow them with a
+  // typo. The `in`-check above is the friendly preflight; this is the
+  // hard fence in case a consumer mutates the api after construction.
+  const lock = { enumerable: false, writable: false, configurable: false }
+  Object.defineProperty(target, 'dispose', { value: dispose, ...lock })
+  Object.defineProperty(target, 'suspend', { value: suspend, ...lock })
+  Object.defineProperty(target, 'resume', { value: resume, ...lock })
+  Object.defineProperty(target, '__debug', { value: debug, ...lock })
   Object.defineProperty(target, 'dehydrate', {
     value: () => queryClient.dehydrate(),
-    enumerable: false,
-    configurable: true,
+    ...lock,
   })
   Object.defineProperty(target, 'waitForIdle', {
     value: () => queryClient.waitForIdle(),
-    enumerable: false,
-    configurable: true,
+    ...lock,
+  })
+  Object.defineProperty(target, 'applyDehydratedEntry', {
+    value: (queryId: string, keyArgs: readonly unknown[], data: unknown, lastUpdatedAt: number) =>
+      queryClient.applyDehydratedEntry(queryId, keyArgs, data, lastUpdatedAt),
+    ...lock,
   })
 
   return api as Root<Api>
@@ -160,7 +188,7 @@ function attachRootControls<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>(
+export function createRoot<Api extends object, TDeps extends Record<string, unknown> = AmbientDeps>(
   def: ControllerDef<void, Api>,
   options: RootOptions<TDeps>,
 ): Root<Api> {

package/src/controller/types.ts

@@ -14,7 +14,7 @@ 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'
+import type { Computed, ReadSignal, Signal } from '../signals/types'
 
 /**
  * App-wide deps available on every controller's `ctx.deps`.
@@ -103,6 +103,22 @@ export type Collection<K, Api> = {
   readonly size: ReadSignal<number>
   get(key: K): Api | undefined
   has(key: K): boolean
+  /**
+   * Suspend a specific collection item by key — pauses its effects without
+   * disposing it (mirrors `attach.suspend()`). Useful for virtualized
+   * lists where rows scrolled out of view should stop running their
+   * effects but stay reconstructible without re-fetching their state.
+   *
+   * No-op if the key isn't in the collection. Neither the collection
+   * reconcile nor a whole-tree `suspend()`/`resume()` cascade (e.g.
+   * KeepAlive) will auto-resume a suspended item — call `resumeItem(key)`
+   * to bring it back (spec §4.1).
+   */
+  suspendItem(key: K): void
+  /** Resume a previously-suspended item. No-op if not suspended / not present. */
+  resumeItem(key: K): void
+  /** Whether the item is currently suspended. False when not present. */
+  isItemSuspended(key: K): boolean
 }
 
 /**
@@ -143,12 +159,10 @@ export type CollectionFactoryOptions<Item, K, R, TDeps = AmbientDeps> = {
 }
 
 /** 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
@@ -209,7 +223,27 @@ export type Ctx<TDeps = AmbientDeps> = {
 
   emitter<T = void>(): Emitter<T>
 
-  field<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T>
+  /**
+   * Convenience re-export of the standalone `signal(initial)` function bound
+   * to the controller's surface. Identical semantics — there's no lifecycle
+   * to manage for a plain signal — but having it on `ctx` makes "everything
+   * I need is on ctx" feel honest and lets consumers avoid importing from
+   * `@kontsedal/olas-core` separately.
+   */
+  signal<T>(initial: T): Signal<T>
+
+  /**
+   * Convenience re-export of the standalone `computed(fn)` function bound
+   * to the controller's surface. Re-evaluates on tracked-dep change; same
+   * caveat as `signal` — no lifecycle binding, just discoverability.
+   */
+  computed<T>(fn: () => T): Computed<T>
+
+  field<T>(
+    initial: T,
+    validators?: ReadonlyArray<Validator<T>>,
+    options?: { validateOn?: 'change' | 'blur' | 'submit' },
+  ): Field<T>
 
   form<S extends FormSchema>(schema: S, options?: FormOptions<S>): Form<S>
 
@@ -343,6 +377,17 @@ export type RootOptions<TDeps> = {
    * the root disposes. SPEC §13.2.
    */
   plugins?: QueryClientPlugin[]
+  /**
+   * Pre-seed scopes on the root controller before its factory runs. Useful
+   * for cross-cutting values an adapter wants to provide once (route
+   * params from a router bridge, theme tokens, etc.) without forcing the
+   * user's root controller to call `ctx.provide(...)`.
+   *
+   * Bindings are flat `[scope, value]` tuples; later bindings for the
+   * same scope override earlier ones. `ctx.inject` from any descendant
+   * resolves these via the normal scope chain walk. SPEC §10.3.
+   */
+  scopes?: ReadonlyArray<readonly [Scope<unknown>, unknown]>
 }
 
 /**
@@ -356,5 +401,22 @@ export type Root<Api> = Api & {
   resume(): void
   dehydrate(): DehydratedState
   waitForIdle(): Promise<void>
+  /**
+   * Apply a single dehydrated query entry to this root's cache. Idempotent
+   * across pre-bind / post-bind: if a `ClientEntry` for `queryId + keyArgs`
+   * already exists, the data is written through and supersedes any inflight
+   * fetch; otherwise it's buffered for the next `bindEntry`.
+   *
+   * Designed for streaming SSR — each `<Suspense>` boundary that resolves
+   * on the server can push its entry into the live client root as the
+   * bootstrap script executes. Also useful for `localStorage` warm-starts
+   * and similar "I have fresh data from elsewhere, inject it" patterns.
+   */
+  applyDehydratedEntry(
+    queryId: string,
+    keyArgs: readonly unknown[],
+    data: unknown,
+    lastUpdatedAt: number,
+  ): void
   readonly __debug: DebugBus
 }

package/src/emitter.ts

@@ -1,7 +1,13 @@
 /**
  * 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.
+ *
+ * Emission iterates a SNAPSHOT of the handler set taken at the start of
+ * `emit()`. So within one emission: a handler added during emit does NOT fire
+ * for the current emission, and a handler removed during emit STILL fires for
+ * the current emission (it was captured in the snapshot).
+ *
+ * Handlers are stored in a `Set` keyed by reference — calling `on(h)` twice
+ * with the same `h` registers it ONCE; a single unsubscribe then removes it.
  *
  * `Emitter<void>` exposes `emit()` (no argument); other shapes expose
  * `emit(value: T)`.

package/src/errors.ts

@@ -6,21 +6,52 @@
  *
  * `'plugin'` is used for exceptions raised by `QueryClientPlugin` callbacks
  * (`@kontsedal/olas-cross-tab` and friends); SPEC §13.2.
+ *
+ * The remaining fields are correlation hooks for telemetry adapters
+ * (Sentry / OpenTelemetry breadcrumbs / Datadog RUM): `eventId` is a stable
+ * per-dispatch UUID, `timestamp` is wall-clock ms, `attempt` is the
+ * 0-based retry attempt for cache/mutation paths, `cause` is the
+ * `Error.cause`-style underlying error if the surfaced error wrapped it,
+ * `pluginName` identifies the throwing plugin (set only when `kind ==
+ * 'plugin'`).
  */
 export type ErrorContext = {
   kind: 'effect' | 'cache' | 'mutation' | 'emitter' | 'construction' | 'plugin'
   controllerPath: readonly string[]
   queryKey?: readonly unknown[]
+  eventId: string
+  timestamp: number
+  attempt?: number
+  cause?: unknown
+  pluginName?: string
 }
 
 /** Signature of `RootOptions.onError`. */
 export type ErrorHandler = (err: unknown, context: ErrorContext) => void
 
+/**
+ * Partial context — `dispatchError` fills in `eventId` + `timestamp`. Call
+ * sites pass the diagnostic fields they know about; the dispatcher stamps
+ * the per-dispatch correlation data.
+ */
+export type ErrorContextInput = Omit<ErrorContext, 'eventId' | 'timestamp'>
+
 const defaultHandler: ErrorHandler = (err, context) => {
   // eslint-disable-next-line no-console
   console.error('[olas]', context, err)
 }
 
+let eventCounter = 0
+function nextEventId(): string {
+  // 24 bits of randomness + a monotonic counter. Cheap (no crypto) and
+  // unique-per-process. Adapters that need stronger guarantees can
+  // re-stamp inside their own handler.
+  eventCounter = (eventCounter + 1) >>> 0
+  const r = ((Math.random() * 0x1000000) | 0).toString(16).padStart(6, '0')
+  const c = eventCounter.toString(16).padStart(6, '0')
+  return `e_${r}${c}`
+}
+
 /**
  * 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
@@ -31,17 +62,22 @@ const defaultHandler: ErrorHandler = (err, context) => {
 export function dispatchError(
   handler: ErrorHandler | undefined,
   err: unknown,
-  context: ErrorContext,
+  context: ErrorContextInput,
 ): void {
   const fn = handler ?? defaultHandler
+  const full: ErrorContext = {
+    ...context,
+    eventId: nextEventId(),
+    timestamp: Date.now(),
+  }
   try {
-    fn(err, context)
+    fn(err, full)
   } 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)
+      console.error('[olas] original error:', err, full)
     } catch {
       // Console itself failed — give up silently.
     }