@kyneta/machine 1.3.0

package/src/observable.ts

@@ -0,0 +1,270 @@
+// observable — data-effect runtime with state observation.
+//
+// createObservableProgram() is the data-effect counterpart to runtime().
+// Where runtime() executes closure effects (Effect<Msg>), this function
+// accepts a custom executor for data effects (Fx). It also provides
+// state observation: subscribeToTransitions, waitForState, waitForStatus.
+//
+// This subsumes ClientStateMachine's observation API and the peer program's
+// hand-rolled dispatch loop. Transition delivery is synchronous — the
+// listener fires after each update. The microtask-batched delivery from
+// ClientStateMachine is unnecessary complexity that no consumer depends on.
+
+import type { Dispatch, Program } from "./machine.js"
+
+// ---------------------------------------------------------------------------
+// Ambient declarations for timer APIs (not in lib: ["ESNext"])
+// ---------------------------------------------------------------------------
+
+declare function setTimeout(callback: () => void, ms: number): unknown
+declare function clearTimeout(id: unknown): void
+
+// ---------------------------------------------------------------------------
+// Observation types
+// ---------------------------------------------------------------------------
+
+/**
+ * A state transition event — from one model to another.
+ *
+ * Generic over the model type. This is the machine-level primitive;
+ * transport packages re-export or alias it for their specific state types.
+ */
+export type StateTransition<S> = {
+  from: S
+  to: S
+  timestamp: number
+}
+
+/**
+ * Listener for state transitions.
+ */
+export type TransitionListener<S> = (transition: StateTransition<S>) => void
+
+// ---------------------------------------------------------------------------
+// ObservableHandle
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle for a running observable program.
+ *
+ * Provides dispatch, state access, transition observation, and disposal.
+ * The observation API (`subscribeToTransitions`, `waitForState`, `waitForStatus`)
+ * matches the surface of the former `ClientStateMachine<S>`.
+ */
+export interface ObservableHandle<Msg, Model> {
+  /** Dispatch a message into the program. */
+  dispatch: Dispatch<Msg>
+
+  /** Get the current model synchronously. */
+  getState(): Model
+
+  /**
+   * Subscribe to state transitions.
+   *
+   * Transitions are delivered synchronously after each update.
+   * Returns an unsubscribe function.
+   */
+  subscribeToTransitions(listener: TransitionListener<Model>): () => void
+
+  /**
+   * Wait for a specific state.
+   *
+   * Resolves immediately if the current state matches the predicate.
+   * Otherwise waits for a transition that matches.
+   */
+  waitForState(
+    predicate: (state: Model) => boolean,
+    options?: { timeoutMs?: number },
+  ): Promise<Model>
+
+  /**
+   * Wait for a specific status string on a model with a `status` discriminant.
+   *
+   * Convenience wrapper around `waitForState()`.
+   */
+  waitForStatus<S extends { status: string }>(
+    this: ObservableHandle<Msg, S>,
+    status: S["status"],
+    options?: { timeoutMs?: number },
+  ): Promise<S>
+
+  /**
+   * Dispose the program — stops dispatch and calls `program.done`.
+   */
+  dispose(): void
+}
+
+// ---------------------------------------------------------------------------
+// createObservableProgram
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a program with data effects and state observation.
+ *
+ * Like `runtime()`, but instead of executing closure effects directly,
+ * it delegates to a custom `executor` for each data effect. This enables
+ * programs whose effects are inspectable data types (not opaque closures).
+ *
+ * The runtime:
+ * 1. Extracts `[model, ...effects]` from `program.init`.
+ * 2. Executes each initial effect via `executor(effect, dispatch)`.
+ * 3. On `dispatch(msg)`: calls `update(msg, state)`, updates state,
+ *    notifies transition listeners, executes effects.
+ * 4. Re-entrant dispatch (effect calls dispatch) is queued and processed
+ *    after the current dispatch cycle completes.
+ * 5. `dispose()` stops dispatch and calls `program.done`.
+ *
+ * @param program - The program algebra: init, update, done.
+ * @param executor - Interprets data effects as I/O.
+ * @returns An observable handle for the running program.
+ */
+export function createObservableProgram<Msg, Model, Fx>(
+  program: Program<Msg, Model, Fx>,
+  executor: (effect: Fx, dispatch: Dispatch<Msg>) => void,
+): ObservableHandle<Msg, Model> {
+  let state: Model
+  let isRunning = true
+  const pending: Msg[] = []
+  let isDispatching = false
+  const listeners = new Set<TransitionListener<Model>>()
+
+  // --------------------------------------------------------------------------
+  // Transition notification
+  // --------------------------------------------------------------------------
+
+  function notifyTransition(from: Model, to: Model): void {
+    if (from === to) return
+
+    const transition: StateTransition<Model> = {
+      from,
+      to,
+      timestamp: Date.now(),
+    }
+
+    for (const listener of listeners) {
+      try {
+        listener(transition)
+      } catch {
+        // Swallow listener errors — observers must not break dispatch.
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Dispatch
+  // --------------------------------------------------------------------------
+
+  function dispatch(msg: Msg): void {
+    if (!isRunning) return
+
+    pending.push(msg)
+    if (isDispatching) return
+
+    isDispatching = true
+    try {
+      while (pending.length > 0) {
+        const next = pending.shift()!
+        const prev = state
+        const [newModel, ...effects] = program.update(next, state)
+        state = newModel
+        notifyTransition(prev, state)
+        for (const effect of effects) {
+          executor(effect, dispatch)
+        }
+      }
+    } finally {
+      isDispatching = false
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Observation
+  // --------------------------------------------------------------------------
+
+  function getState(): Model {
+    return state
+  }
+
+  function subscribeToTransitions(
+    listener: TransitionListener<Model>,
+  ): () => void {
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+    }
+  }
+
+  function waitForState(
+    predicate: (state: Model) => boolean,
+    options?: { timeoutMs?: number },
+  ): Promise<Model> {
+    // Resolve immediately if already matching
+    if (predicate(state)) {
+      return Promise.resolve(state)
+    }
+
+    return new Promise((resolve, reject) => {
+      let timeoutId: unknown
+
+      const unsubscribe = subscribeToTransitions(transition => {
+        if (predicate(transition.to)) {
+          cleanup()
+          resolve(transition.to)
+        }
+      })
+
+      const cleanup = () => {
+        unsubscribe()
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId)
+        }
+      }
+
+      if (options?.timeoutMs !== undefined) {
+        timeoutId = setTimeout(() => {
+          cleanup()
+          reject(
+            new Error(`Timeout waiting for state after ${options.timeoutMs}ms`),
+          )
+        }, options.timeoutMs)
+      }
+    })
+  }
+
+  function waitForStatus<S extends { status: string }>(
+    this: ObservableHandle<Msg, S>,
+    status: S["status"],
+    options?: { timeoutMs?: number },
+  ): Promise<S> {
+    return this.waitForState((s: S) => s.status === status, options)
+  }
+
+  function dispose(): void {
+    if (!isRunning) return
+    isRunning = false
+    program.done?.(state)
+  }
+
+  // --------------------------------------------------------------------------
+  // Initialize
+  // --------------------------------------------------------------------------
+
+  const [initialModel, ...initialEffects] = program.init
+  state = initialModel
+  for (const effect of initialEffects) {
+    executor(effect, dispatch)
+  }
+
+  // --------------------------------------------------------------------------
+  // Return handle
+  // --------------------------------------------------------------------------
+
+  return {
+    dispatch,
+    getState,
+    subscribeToTransitions,
+    waitForState,
+    waitForStatus,
+    dispose,
+  }
+}