@demlik/tea 0.14.0 → 0.16.0

package/dist/testing/index.d.ts

@@ -1,7 +1,6 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-CTzMJ82M.js';
-import { R as Runtime } from '../runtime-types-LWDoi943.js';
-import 'zod';
-import 'better-result';
+import { C as Cmd, S as Sub, M as Machine, a as BuiltinSub, p as Interpret } from '../core-BbgtiXdg.js';
+import { C as CtxArg, R as Runtime } from '../runtime-types-CiVpC0HN.js';
+import '@standard-schema/spec';
 
 /**
  * The composed Model shape every `withX` wrapper produces: the base machine's
@@ -31,10 +30,10 @@ interface AssertWrapperFaithfulOpts<S, WM, BaseM, BaseCtx, WrapperCtx> {
      */
     readonly baseLoaded?: S | null;
     /**
-     * Opt-in relaxation for an INTERCEPTING wrapper (e.g. `withResilience`).
+     * Opt-in relaxation for an INTERCEPTING wrapper (e.g. a retry wrapper).
      *
-     * DEFAULT (`undefined` / `false`) — the OBSERVE-ONLY contract that
-     * `withTelemetry` and `withDeadline` satisfy: every bare base Cmd must appear
+     * DEFAULT (`undefined` / `false`) — the OBSERVE-ONLY contract that a
+     * deadline wrapper satisfies: every bare base Cmd must appear
      * UNCHANGED, in order, as a subsequence of the wrapped Cmd stream (properties
      * 1 and 3b). The wrapper may APPEND its own Cmds but may NOT alter, drop, or
      * retime a base Cmd. This is the strict default and it is NOT weakened.
@@ -58,7 +57,7 @@ interface AssertWrapperFaithfulOpts<S, WM, BaseM, BaseCtx, WrapperCtx> {
      * Cmd in its window is a SWALLOW betrayal and still fails the gate.
      *
      * Provide the field names the carrier uses so the gate can unwrap it
-     * structurally without hard-coding `withResilience`'s vocabulary.
+     * structurally without hard-coding any one wrapper's vocabulary.
      */
     readonly intercepting?: InterceptingOpt;
 }
@@ -94,10 +93,11 @@ interface InterceptingOpt {
  *
  * @param base       the bare base `Machine`.
  * @param makeWrapped a thunk that wraps `base` and returns the composed machine
- *   (e.g. `() => withTelemetry(base, cfg)`). A thunk — not the wrapped value —
- *   so a wrapper that registers process-scoped ports (`definePort`) is
- *   constructed inside the assertion's control, and so the same betrayal-
- *   detector reads as `assertWrapperFaithful(base, () => withX(base, cfg), ...)`
+ *   (e.g. `() => withTimeout(wired, cfg).machine`, where `wired.machine` is
+ *   `base`). A thunk — not the wrapped value — so a wrapper that registers
+ *   process-scoped ports (`definePort`) is constructed inside the assertion's
+ *   control, and so the same betrayal-detector reads as
+ *   `assertWrapperFaithful(wired.machine, () => withX(wired, cfg).machine, ...)`
  *   at every wrapper's test site.
  * @param opts       the conformance replay options.
  */
@@ -239,7 +239,7 @@ interface BoundMachine<S, M extends {
      * Assert the exact set of subs desired at the final state. Mirrors the
      * free `expectActiveSubs(machine, opts, expected)`.
      */
-    expectActiveSubs(opts: BoundOpts<S, M>, expected: readonly NoInfer<U>[]): void;
+    expectActiveSubs(opts: BoundOpts<S, M>, expected: readonly NoInfer<U | BuiltinSub<M>>[]): void;
     /**
      * Bound `replay` — returns `{ state, cmds, subs }` for the given opts.
      * Use for the "narrow-then-assert" pattern where the test inspects a
@@ -248,7 +248,7 @@ interface BoundMachine<S, M extends {
     replay(opts: BoundOpts<S, M>): {
         state: S;
         cmds: readonly C[];
-        subs: readonly U[];
+        subs: readonly (U | BuiltinSub<M>)[];
     };
 }
 /**
@@ -265,6 +265,156 @@ declare function bindMachine<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: Ctx): BoundMachine<S, M, C, U, Ctx>;
 
+/**
+ * The default round bound when `opts.maxRounds` is omitted: **100**.
+ *
+ * A round is one drain of the pending Msgs plus one drain of the Cmds those
+ * folds emitted, so a settling machine costs a handful; 100 is loose enough
+ * that a legitimate retry ladder finishes inside it and tight enough that a
+ * genuine cycle stops rather than hangs.
+ */
+declare const DEFAULT_MAX_ROUNDS = 100;
+/**
+ * One entry of a driven run's history, in dispatch order.
+ *
+ * - `msg` — a Msg folded through the machine's reducer. The seed Msg is the
+ *   first entry of every trace; every later one is a settle Msg a handler
+ *   returned (or fired through its injected `dispatch`).
+ * - `cmd` — a Cmd handed to an interpret handler. It is recorded BEFORE the
+ *   handler is awaited, so a trace recovered from a rejected handler names the
+ *   Cmd that rejected as its last entry.
+ */
+type DriveTraceEntry<M, C> = {
+    readonly kind: "msg";
+    readonly msg: M;
+} | {
+    readonly kind: "cmd";
+    readonly cmd: C;
+};
+/** What a settled {@link drive} hands back. */
+interface DriveResult<S, M, C> {
+    /** The state after the machine went quiet — no Msg pending, no Cmd unperformed. */
+    readonly state: S;
+    /**
+     * Every Msg folded and every Cmd dispatched, in order. Filtering it to its
+     * `msg` entries and replaying those through `replay` from the same initial
+     * state reproduces {@link DriveResult.state}.
+     */
+    readonly trace: readonly DriveTraceEntry<M, C>[];
+}
+/**
+ * {@link drive}'s `ctx` field. `CtxArg` widened by exactly one case: a machine
+ * declaring `ctx: undefined` in its `types` block — the pure shape every
+ * how-to on this package writes — may omit it too. `CtxArg` alone keeps `ctx`
+ * REQUIRED there, because `{}` is not assignable to `undefined`, which would
+ * make the common pure call site spell `{ ctx: undefined }` to say nothing.
+ * A machine whose `Ctx` carries a field a handler reads still requires it.
+ */
+type DriveCtxArg<Ctx> = [undefined] extends [Ctx] ? {
+    readonly ctx?: Ctx;
+} : CtxArg<Ctx>;
+/**
+ * {@link drive}'s options. `ctx` is conditionally optional (see
+ * {@link DriveCtxArg}).
+ */
+type DriveOptions<Ctx> = DriveCtxArg<Ctx> & {
+    /**
+     * The round bound. Exceeding it throws {@link DriveRoundsExceededError};
+     * `drive` never returns a half-driven state. Defaults to
+     * {@link DEFAULT_MAX_ROUNDS} (100).
+     */
+    readonly maxRounds?: number;
+    /**
+     * The clock that stamps `at` on a `Cmd.define`d Cmd's minted `_ok` / `_err`
+     * Msg — the one `run` takes. Defaults to `Date.now`; pin it for a test that
+     * asserts on `at`.
+     */
+    readonly clock?: () => number;
+};
+/**
+ * Raised when a driven machine is still emitting work after `maxRounds` rounds.
+ * Follows the tea error dialect (`override readonly name`) and carries a `_tag`
+ * discriminant, so a test branches on it by `instanceof` or on the tag.
+ *
+ * It carries the round count it stopped at and the PARTIAL trace up to that
+ * point, which is what a test needs to see the cycle — the bound alone says
+ * only that one exists.
+ */
+declare class DriveRoundsExceededError<M, C> extends Error {
+    /** The bound that was exceeded. */
+    readonly maxRounds: number;
+    /** The round the driver stopped at — always `maxRounds + 1`. */
+    readonly rounds: number;
+    /** Every Msg folded and Cmd dispatched before the driver gave up. */
+    readonly trace: readonly DriveTraceEntry<M, C>[];
+    readonly name = "DriveRoundsExceededError";
+    readonly _tag: "DriveRoundsExceededError";
+    constructor(
+    /** The bound that was exceeded. */
+    maxRounds: number, 
+    /** The round the driver stopped at — always `maxRounds + 1`. */
+    rounds: number, 
+    /** Every Msg folded and Cmd dispatched before the driver gave up. */
+    trace: readonly DriveTraceEntry<M, C>[]);
+}
+/**
+ * Raised when a Cmd reaches {@link drive} with no handler for its `type` in the
+ * `handlers` record. `Interpret`'s mapped type makes that a compile error at a
+ * well-typed call site; this is the runtime arm for a handler record assembled
+ * dynamically or cast.
+ */
+declare class DriveNoHandlerError<M, C> extends Error {
+    /** The Cmd `type` nothing in the handler record answered. */
+    readonly cmdType: string;
+    /** Every Msg folded and Cmd dispatched before the miss. */
+    readonly trace: readonly DriveTraceEntry<M, C>[];
+    readonly name = "DriveNoHandlerError";
+    readonly _tag: "DriveNoHandlerError";
+    constructor(
+    /** The Cmd `type` nothing in the handler record answered. */
+    cmdType: string, 
+    /** Every Msg folded and Cmd dispatched before the miss. */
+    trace: readonly DriveTraceEntry<M, C>[]);
+}
+/**
+ * Read back the partial trace `drive` attached to an error a handler rejected
+ * with. Returns `undefined` for anything `drive` did not annotate.
+ *
+ * A rejecting handler's error propagates out of `drive` UNSWALLOWED — same
+ * value, same `instanceof`, same `_tag` — so a test that already branches on
+ * the handler's own error type keeps doing so. The trace rides along on a
+ * non-enumerable property so it is recoverable without changing how the error
+ * prints or serializes.
+ */
+declare function driveTraceOf<M, C>(err: unknown): readonly DriveTraceEntry<M, C>[] | undefined;
+/**
+ * Drive `machine` from `initial` through `msg` against the REAL interpret
+ * `handlers`, feeding every settle Msg back until the machine goes quiet, and
+ * hand back the settled state together with the whole history.
+ *
+ * `handlers` is the same table a host hands `run` as its `interpret` (e.g.
+ * a jev knob's `resilient_run` handler), so the test drives the real interpreter and
+ * mocks only the port beneath it.
+ *
+ * One round is: fold every pending Msg, then await a handler for every Cmd
+ * those folds emitted. A Msg a handler returns — or fires through its injected
+ * `dispatch` — is pending for the next round. A machine that emits no Cmd for
+ * its seed Msg therefore settles in ONE round and never awaits a handler at
+ * all.
+ *
+ * The `ctx` handed to each handler is `opts.ctx` augmented with a NO-OP `emit`,
+ * so a handler that emits to a `Port` runs without a live runtime; nothing here
+ * observes ports. Supply your own `emit` on `ctx` to capture them.
+ *
+ * @throws {DriveRoundsExceededError} when the machine is still emitting work
+ *   after `opts.maxRounds` rounds. It never returns a half-driven state.
+ * @throws whatever a handler rejects with, unchanged — annotated with the
+ *   partial trace, readable via {@link driveTraceOf}.
+ */
+declare function drive<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, initial: S, msg: M, handlers: Interpret<M, C, Ctx>, ...[opts]: Record<never, never> extends DriveOptions<Ctx> ? [opts?: DriveOptions<Ctx>] : [opts: DriveOptions<Ctx>]): Promise<DriveResult<S, M, C>>;
+
 /**
  * Construct an inert `Runtime<S, M>` value. Use at ctx sites that require
  * a Runtime reference but where the test never invokes `interpret` (so
@@ -324,4 +474,4 @@ declare function stateFactory<S extends {
     type: string;
 }>(defaults: StateFactoryDefaults<S>): StateFactoryAPI<S>;
 
-export { type AssertWrapperFaithfulOpts, type BoundMachine, type InterceptingOpt, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, type WrapperModel, assertWrapperFaithful, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+export { type AssertWrapperFaithfulOpts, type BoundMachine, DEFAULT_MAX_ROUNDS, type DriveCtxArg, DriveNoHandlerError, type DriveOptions, type DriveResult, DriveRoundsExceededError, type DriveTraceEntry, type InterceptingOpt, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, type WrapperModel, assertWrapperFaithful, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };

package/dist/testing/index.js

@@ -1,4 +1,5 @@
-import { replay } from '../chunk-RQULHGYH.js';
+import '../chunk-GOX2CYIM.js';
+import { replay, cmdEdgeOver, Outcome, cmdEdge } from '../chunk-CH5KTOEZ.js';
 import { expect, vi } from 'vitest';
 
 function assertWrapperFaithful(base, makeWrapped, opts) {
@@ -116,7 +117,7 @@ function wrapperSliceKey(model) {
   const dollarKeys = Object.keys(model).filter((k) => k.startsWith("$"));
   if (dollarKeys.length !== 1) {
     throw new Error(
-      `assertWrapperFaithful: expected exactly one "$"-prefixed wrapper slice on the composed Model, found ${dollarKeys.length} (${dollarKeys.join(", ") || "none"}). Every withX wrapper owns exactly one named slice (e.g. "$telemetry").`
+      `assertWrapperFaithful: expected exactly one "$"-prefixed wrapper slice on the composed Model, found ${dollarKeys.length} (${dollarKeys.join(", ") || "none"}). Every withX wrapper owns exactly one named slice (e.g. "$deadline").`
     );
   }
   return dollarKeys[0];
@@ -223,6 +224,106 @@ function bindMachine(machine, ctx) {
   };
 }
 
+// src/testing/drive.ts
+var DEFAULT_MAX_ROUNDS = 100;
+var DriveRoundsExceededError = class extends Error {
+  constructor(maxRounds, rounds, trace) {
+    super(
+      `@demlik/tea: drive did not settle within ${maxRounds} round(s) \u2014 the machine was still emitting work at round ${rounds}. The partial trace (${trace.length} entr${trace.length === 1 ? "y" : "ies"}) is on the error's \`trace\` field.`
+    );
+    this.maxRounds = maxRounds;
+    this.rounds = rounds;
+    this.trace = trace;
+  }
+  maxRounds;
+  rounds;
+  trace;
+  name = "DriveRoundsExceededError";
+  _tag = "DriveRoundsExceededError";
+};
+var DriveNoHandlerError = class extends Error {
+  constructor(cmdType, trace) {
+    super(
+      `@demlik/tea: drive found no interpret handler for Cmd type "${cmdType}" \u2014 the handlers record must answer every Cmd the machine emits.`
+    );
+    this.cmdType = cmdType;
+    this.trace = trace;
+  }
+  cmdType;
+  trace;
+  name = "DriveNoHandlerError";
+  _tag = "DriveNoHandlerError";
+};
+var TRACE_KEY = "driveTrace";
+function driveTraceOf(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const carried = err[TRACE_KEY];
+  return Array.isArray(carried) ? carried : void 0;
+}
+async function drive(machine, initial, msg, handlers, ...[opts]) {
+  const options = opts ?? {};
+  const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
+  const bound = bindMachine(machine, options.ctx);
+  const settle = cmdEdgeOver(machine.cmds ?? [], options.clock ?? Date.now);
+  const noopEmit = { emit: () => {
+  } };
+  const handlerCtx = {
+    ...noopEmit,
+    ok: Outcome.ok,
+    err: Outcome.err,
+    [cmdEdge]: settle,
+    ...options.ctx
+  };
+  const cells = handlers;
+  const trace = [];
+  let state = initial;
+  let pending = [msg];
+  let round = 0;
+  while (pending.length > 0) {
+    round += 1;
+    if (round > maxRounds) {
+      throw new DriveRoundsExceededError(maxRounds, round, trace);
+    }
+    const folding = pending;
+    pending = [];
+    const emitted = [];
+    for (const next of folding) {
+      trace.push({ kind: "msg", msg: next });
+      const [advanced, cmds] = bound.step(state, next);
+      state = advanced;
+      emitted.push(...cmds);
+    }
+    for (const cmd of emitted) {
+      trace.push({ kind: "cmd", cmd });
+      const cell = cells[cmd.type];
+      if (cell === void 0) {
+        throw new DriveNoHandlerError(cmd.type, trace);
+      }
+      let settled;
+      try {
+        settled = settle(
+          cmd,
+          await cell(cmd, handlerCtx, (fired) => {
+            pending.push(fired);
+          })
+        );
+      } catch (err) {
+        if (typeof err === "object" && err !== null) {
+          Object.defineProperty(err, TRACE_KEY, {
+            value: [...trace],
+            enumerable: false,
+            configurable: true,
+            writable: true
+          });
+        }
+        throw err;
+      }
+      if (settled !== void 0) pending.push(settled);
+    }
+  }
+  return { state, trace };
+}
+
 // src/testing/noop-runtime.ts
 function noopRuntime(opts) {
   const initialState = opts?.initialState;
@@ -297,6 +398,6 @@ function stateFactory(defaults) {
   return api;
 }
 
-export { assertWrapperFaithful, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+export { DEFAULT_MAX_ROUNDS, DriveNoHandlerError, DriveRoundsExceededError, assertWrapperFaithful, bindMachine, drive, driveTraceOf, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map