@orkestrel/test 0.0.10 → 0.0.12

package/dist/src/core/index.d.cts

@@ -1,3 +1,17 @@
+/**
+ * Builds the error {@link retryUntil} raises when its elapsed-time budget runs out.
+ *
+ * @param description - The operation the retry was named for.
+ * @param budget - The elapsed-time limit in milliseconds.
+ * @param elapsed - The milliseconds the retry actually spent.
+ * @param last - The rendered last unsatisfying value, or `undefined` when the retry produced none.
+ * @param cause - The last producer error, which becomes the returned error's `cause`.
+ * @returns The exhaustion error, unthrown.
+ * @remarks Both of `retryUntil`'s elapsed checks raise this one message, so an edit to it lands in
+ * one place. The rendered value is appended only when the retry produced one.
+ */
+export declare function buildRetryExhausted(description: string, budget: number, elapsed: number, last: string | undefined, cause: unknown): Error;
+
 /**
  * Captures the value thrown by a thunk.
  *
@@ -6,6 +20,19 @@
  */
 export declare function captureError(thunk: () => unknown): unknown;
 
+/**
+ * Checks the resolved bounds one bounded wait runs under.
+ *
+ * @param subject - The bound's owner, which opens each refusal message.
+ * @param budget - The resolved elapsed-time limit in milliseconds.
+ * @param interval - The resolved delay between readings in milliseconds.
+ * @throws An `Error` reading `<subject> budget must be finite and non-negative` or
+ * `<subject> interval must be finite and non-negative`.
+ * @remarks Every member of the wait family resolves its own defaults first and passes the resolved
+ * numbers here, so each keeps its own defaults while one contract states what a bound must be.
+ */
+export declare function checkBounds(subject: string, budget: number, interval: number): void;
+
 /**
  * Collects every value from an async iterable.
  *
@@ -133,6 +160,18 @@ export declare function createTeardown(): TeardownInterface;
  */
 export declare function decodeJSONLines(text: string): readonly unknown[];
 
+/**
+ * Drops the registration an instrumented signal installed for one listener.
+ *
+ * @param registrations - The live registration list, spliced in place.
+ * @param installed - The installed listener naming the registration to drop.
+ * @returns The dropped registration, or `undefined` when the list holds none for that listener.
+ * @remarks The dropped registration's cleanup controller is aborted as it leaves, so the scope
+ * subscription installed beside it leaves with it. Removing the installed listener from the signal
+ * stays with the caller, because only the scope-abort path has one to remove.
+ */
+export declare function dropRegistration(registrations: SignalRegistration[], installed: EventListener | EventListenerObject): SignalRegistration | undefined;
+
 /**
  * Subscribes handlers to a typed event source.
  *
@@ -157,6 +196,73 @@ export declare interface EventSourceInterface<TMap extends Record<string, readon
  */
 export declare type EventSubscriber<TArgs extends readonly unknown[]> = (listener: (...args: TArgs) => void) => (() => void) | void;
 
+/**
+ * Drives one statechart scenario through its arrange, act, and assert phases.
+ *
+ * @typeParam TState - The states the entity moves between.
+ * @typeParam TEvent - The events the entity accepts.
+ * @typeParam TContext - The fixture the phases drive.
+ * @param scenario - The scenario to drive.
+ * @param context - The fixture handed to each phase.
+ * @returns A promise that resolves after the assert phase completes.
+ * @throws An `Error` whose message opens with the transition's `name` and whose `cause` is the value
+ * the failing phase threw.
+ * @remarks Each phase is awaited before the next begins, so an asynchronous arrange settles before
+ * the event is applied. The phases receive the transition's own parts: `arrange` receives `from`,
+ * `act` receives `event`, and `assert` receives `to`.
+ *
+ * The row's name is prepended because a table's rows run under one test name, so a bare assertion
+ * message says what failed and never which row. A thrown `Error` keeps its own message after the
+ * name and arrives as the `cause`; anything else thrown is named by its type and arrives as the
+ * `cause` unchanged.
+ *
+ * @example
+ * ```ts
+ * await executeScenario(scenarios[0], { disclosure: new Disclosure() })
+ * ```
+ */
+export declare function executeScenario<TState extends string, TEvent extends string, TContext>(scenario: StateScenario<TState, TEvent, TContext>, context: TContext): Promise<void>;
+
+/**
+ * Drives a statechart table row by row, each row against a context of its own.
+ *
+ * @typeParam TState - The states the entity moves between.
+ * @typeParam TEvent - The events the entity accepts.
+ * @typeParam TContext - The fixture the phases drive.
+ * @param scenarios - The table to drive, in the order it is written.
+ * @param build - The fixture builder, called once per row and awaited when it returns a promise.
+ * @returns A promise that resolves after the last row completes.
+ * @throws An `Error` reading `<name>: build refused` when the row's builder throws or rejects, whose
+ * `cause` is the value the builder refused with, or whatever {@link executeScenario} throws for the
+ * first row whose phases fail. Either way the run stops at that row and the rows after it never
+ * start.
+ * @remarks The rows run one after another rather than together: a statechart's rows drive one
+ * entity on one page, so a parallel run would have them arranging over each other. `build` receives
+ * the row it is building for, which is what lets one table mix fixtures.
+ *
+ * A refusing builder is named for its row the way a failing phase is, because a table's rows build
+ * under one test name too. The refusal itself arrives as the `cause`, by identity, so its own
+ * message and stack survive the naming.
+ *
+ * @example
+ * ```ts
+ * await executeScenarios(SCENARIOS, () => ({ disclosure: new Disclosure() }))
+ * ```
+ */
+export declare function executeScenarios<TState extends string, TEvent extends string, TContext>(scenarios: ReadonlyArray<StateScenario<TState, TEvent, TContext>>, build: (scenario: StateScenario<TState, TEvent, TContext>) => TContext | Promise<TContext>): Promise<void>;
+
+/**
+ * Represents one operation that raised a failure instead of producing a value.
+ *
+ * @typeParam E - The failure type.
+ */
+export declare interface Failure<E> {
+    /** Holds the discriminant that names the failed arm. */
+    readonly success: false;
+    /** Holds the failure the operation raised. */
+    readonly error: E;
+}
+
 /**
  * Normalizes headers into a frozen plain record.
  *
@@ -168,7 +274,7 @@ export declare type EventSubscriber<TArgs extends readonly unknown[]> = (listene
 export declare function flattenHeaders(init: HeadersSource): Readonly<Record<string, string>>;
 
 /**
- * Any value the host `Headers` constructor accepts.
+ * Covers any value the host `Headers` constructor accepts.
  *
  * @remarks Derived from the host constructor rather than named from a single library, so the type
  * resolves in every project against that project's own `Headers` declaration. The record,
@@ -206,8 +312,8 @@ export declare function invokeUnchecked<T>(target: unknown, method: unknown, arg
 export declare function isRecorderMapComplete<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]): value is RecorderMap<TMap, TName>;
 
 /**
- * The JSON-safe projection of a type: every member JSON preserves, mapped to itself, and every
- * member it does not, mapped to `never`.
+ * Represents the JSON-safe projection of a type: every member JSON preserves, mapped to itself, and
+ * every member it does not, mapped to `never`.
  *
  * @typeParam T - The type to project.
  * @remarks Intersect a parameter with this rather than constraining it to `JSONValue`. A `JSONValue`
@@ -238,7 +344,7 @@ export declare type JSONSafe<T> = unknown extends T ? T : T extends string | num
     readonly [K in keyof T]: K extends symbol ? never : JSONSafe<T[K]>;
 } : never;
 
-/** Any value JSON can represent, so a round trip through JSON preserves the type. */
+/** Covers any value JSON can represent, so a round trip through JSON preserves the type. */
 export declare type JSONValue = string | number | boolean | null | readonly JSONValue[] | {
     readonly [key: string]: JSONValue;
 };
@@ -262,11 +368,11 @@ export declare function readProperty<T>(target: unknown, key: PropertyKey): T;
  * @typeParam TArgs - The argument tuple the recorded handler accepts.
  */
 export declare interface RecorderInterface<TArgs extends readonly unknown[]> {
-    /** Every recorded call, oldest first, each entry the arguments of one call. */
+    /** Lists every recorded call, oldest first, each entry the arguments of one call. */
     readonly calls: readonly TArgs[];
-    /** How many calls have been recorded. */
+    /** Reports how many calls have been recorded. */
     readonly count: number;
-    /** The callback to hand to the code under test. */
+    /** Holds the callback to hand to the code under test. */
     readonly handler: (...args: TArgs) => void;
     /** Discards the recorded calls and keeps the recorder usable. */
     clear(): void;
@@ -301,11 +407,11 @@ export declare function requireValue<T>(value: T | null | undefined, message?: s
  */
 export declare function resolveRoot(meta: ImportMeta): URL;
 
-/** A numbered resource factory with records of every creation and destruction. */
+/** Represents a numbered resource factory with records of every creation and destruction. */
 export declare interface ResourceFactoryInterface {
-    /** The ids returned by `create`, in order. */
+    /** Records the ids returned by `create`, in order. */
     readonly created: RecorderInterface<readonly [id: number]>;
-    /** The ids passed to `destroy`, in order. */
+    /** Records the ids passed to `destroy`, in order. */
     readonly destroyed: RecorderInterface<readonly [id: number]>;
     /**
      * Creates a numbered resource.
@@ -321,9 +427,20 @@ export declare interface ResourceFactoryInterface {
     destroy(id: number): void;
 }
 
+/**
+ * Represents the outcome of one operation: the value it produced, or the failure it raised.
+ *
+ * @typeParam T - The produced value type.
+ * @typeParam E - The failure type. Defaults to `Error`.
+ * @remarks `success` is the discriminant, so a caller narrows on it before reading `value` or
+ * `error`. This package declares no runtime dependency, so this is the one outcome contract its own
+ * members read rather than an anonymous union written at each call site.
+ */
+export declare type Result<T, E = Error> = Success<T> | Failure<E>;
+
 /** Configures a bounded retry. */
 export declare interface RetryOptions extends WaitOptions {
-    /** The maximum number of producer calls. When omitted, only the time budget bounds the retry. */
+    /** Caps the number of producer calls. When omitted, only the time budget bounds the retry. */
     readonly attempts?: number;
 }
 
@@ -356,22 +473,154 @@ export declare function retryUntil<T>(description: string, produce: () => T | Pr
  */
 export declare function roundTripJSON<T>(value: T & JSONSafe<T>): T;
 
-/** A real abort signal and controller instrumented with its live abort-listener tally. */
+/** Holds a real abort signal and controller instrumented with its live abort-listener tally. */
 export declare interface SignalInterface {
-    /** The controller that owns the signal. */
+    /** Holds the controller that owns the signal. */
     readonly controller: AbortController;
-    /** The instrumented signal. */
+    /** Holds the signal to hand to the code under test. */
     readonly signal: AbortSignal;
-    /** The live abort-listener tally. */
+    /** Reports the live abort-listener tally. */
     readonly count: number;
 }
 
-/** The work one teardown entry performs when the list is destroyed. */
+/**
+ * Represents one abort listener an instrumented signal installed, as its tally holds it.
+ *
+ * @remarks The members are the listener the caller supplied, the listener installed in its place,
+ * the capture flag the pair was registered under, and the controller that removes the scope
+ * subscription installed beside it, which is `undefined` where no other signal scopes the
+ * registration.
+ */
+export declare type SignalRegistration = readonly [
+listener: EventListener | EventListenerObject,
+installed: EventListener | EventListenerObject,
+capture: boolean,
+cleanup: AbortController | undefined
+];
+
+/**
+ * Names the attributes a statechart harness publishes, keyed by the fact each one carries.
+ *
+ * @remarks
+ * A harness renders its own table and a gate outside the page polls the rendered markup, so these
+ * names are the whole contract between the two. `status`, `passed`, `failed`, and `total` belong on
+ * the harness root, because a gate finds the harness by `status` and reads the tally from the same
+ * element. `scenario` and `result` belong on each row, so a failing row is found by `result` and
+ * named by `scenario`. `state` belongs on the element rendering the entity's current state.
+ *
+ * The values are the attribute names themselves, so a harness writes `setAttribute` against this map
+ * and a gate writes `querySelector` against it, and neither spells a `data-statechart-*` string of
+ * its own.
+ *
+ * @example
+ * ```ts
+ * harness.getAttribute(STATECHART_ATTRIBUTES.status) // 'passed'
+ * ```
+ */
+export declare const STATECHART_ATTRIBUTES: Readonly<{
+    status: "data-statechart-status";
+    passed: "data-statechart-passed";
+    failed: "data-statechart-failed";
+    total: "data-statechart-total";
+    scenario: "data-statechart-scenario";
+    result: "data-statechart-result";
+    state: "data-statechart-state";
+}>;
+
+/**
+ * Lists every value a statechart harness reports through its `status` attribute.
+ *
+ * @remarks
+ * `pending` is what a harness carries before a run has produced a result for every row, `idle` is a
+ * harness standing ready with nothing running, and `running` is a run in flight. `passed` and
+ * `failed` are the two terminal readings, so a gate waits for membership in that pair rather than
+ * for a fixed duration.
+ *
+ * The tuple's order is the order a run passes through, and its element type is the literal union, so
+ * `(typeof STATECHART_STATUSES)[number]` is the status type a harness and its gate share.
+ *
+ * @example
+ * ```ts
+ * const terminal = new Set<string>([STATECHART_STATUSES[3], STATECHART_STATUSES[4]])
+ * ```
+ */
+export declare const STATECHART_STATUSES: readonly ["pending", "idle", "running", "passed", "failed"];
+
+/**
+ * Drives one {@link StateTransition} through the three phases that prove it.
+ *
+ * @typeParam TState - The states the entity moves between, as a string-literal union.
+ * @typeParam TEvent - The events the entity accepts, as a string-literal union.
+ * @typeParam TContext - The fixture the three phases drive.
+ * @remarks Each phase receives the context and the part of the transition it is responsible for, so
+ * a phase reads its subject from its own parameters rather than from the row it belongs to. A phase
+ * may be synchronous or asynchronous, and `executeScenario` awaits each one before starting the
+ * next.
+ */
+export declare interface StateScenario<TState extends string, TEvent extends string, TContext> {
+    /** Holds the row this scenario drives. */
+    readonly transition: StateTransition<TState, TEvent>;
+    /**
+     * Puts the entity into the transition's `from` state.
+     *
+     * @param context - The fixture this row drives.
+     * @param state - The transition's `from` state.
+     */
+    arrange(context: TContext, state: TState): Promise<void> | void;
+    /**
+     * Applies the transition's event to the arranged entity.
+     *
+     * @param context - The fixture this row drives.
+     * @param event - The transition's event.
+     */
+    act(context: TContext, event: TEvent): Promise<void> | void;
+    /**
+     * Checks that the entity reached the transition's `to` state.
+     *
+     * @param context - The fixture this row drives.
+     * @param state - The transition's `to` state.
+     */
+    assert(context: TContext, state: TState): Promise<void> | void;
+}
+
+/**
+ * Represents one row of a statechart table: the entity's state before an event, the event, and the
+ * state that event must leave it in.
+ *
+ * @typeParam TState - The states the entity moves between, as a string-literal union.
+ * @typeParam TEvent - The events the entity accepts, as a string-literal union.
+ * @remarks The two unions are the entity's own vocabulary, so a table naming a state or an event the
+ * entity does not have fails to typecheck rather than failing at runtime.
+ */
+export declare interface StateTransition<TState extends string, TEvent extends string> {
+    /** Holds the row's name, which is prepended to the message of whatever the row throws. */
+    readonly name: string;
+    /** Holds the state the row arranges before it acts. */
+    readonly from: TState;
+    /** Holds the event the row applies to the arranged entity. */
+    readonly event: TEvent;
+    /** Holds the state the row asserts the entity reached. */
+    readonly to: TState;
+}
+
+/**
+ * Represents one operation that produced a value.
+ *
+ * @typeParam T - The produced value type.
+ */
+export declare interface Success<T> {
+    /** Holds the discriminant that names the produced arm. */
+    readonly success: true;
+    /** Holds the value the operation produced. */
+    readonly value: T;
+}
+
+/** Represents the work one teardown entry performs when the list is destroyed. */
 export declare type TeardownHandler = () => void | Promise<void>;
 
-/** The cleanup a test adds as it goes and runs once, newest first, when it is done. */
+/** Represents the cleanup a test adds as it goes and runs once, newest first, when it is done. */
 export declare interface TeardownInterface {
-    /** How many handlers are registered. */
+    /** Reports how many handlers are registered. */
     readonly count: number;
     /**
      * Registers a handler to run when the list is destroyed.
@@ -447,11 +696,11 @@ export declare function waitForEvent<TArgs extends readonly unknown[]>(subscribe
  * consumers do not agree on one. Each states its own numbers in its `@remarks`.
  */
 export declare interface WaitOptions {
-    /** The elapsed-time limit in milliseconds. */
+    /** Holds the elapsed-time limit in milliseconds. */
     readonly budget?: number;
-    /** The delay between readings in milliseconds. */
+    /** Holds the delay between readings in milliseconds. */
     readonly interval?: number;
-    /** The signal that aborts the wait. */
+    /** Holds the signal that aborts the wait. */
     readonly signal?: AbortSignal;
 }