effect-machine 0.17.1 → 0.18.0

package/v3/dist/testing.d.ts

@@ -1,151 +0,0 @@
-import { AssertionError } from "./errors.js";
-import { MachineContext, ProvideSlots, SlotsDef } from "./slot.js";
-import { Machine, MachineRef } from "./machine.js";
-import { Effect, SubscriptionRef } from "effect";
-
-//#region src/testing.d.ts
-type MachineInput<S, E, R, SD extends SlotsDef = Record<string, never>> = Machine<S, E, R, any, any, SD>;
-/**
- * Result of simulating events through a machine
- */
-interface SimulationResult<S> {
-  readonly states: ReadonlyArray<S>;
-  readonly finalState: S;
-}
-/**
- * Simulate a sequence of events through a machine without running an actor.
- * Useful for testing state transitions in isolation.
- * Does not run onEnter/spawn/background effects, but does run slots
- * within transition handlers.
- *
- * @example
- * ```ts
- * const result = yield* simulate(
- *   fetcherMachine,
- *   [
- *     Event.Fetch({ url: "https://example.com" }),
- *     Event._Done({ data: { foo: "bar" } })
- *   ]
- * )
- *
- * expect(result.finalState._tag).toBe("Success")
- * expect(result.states).toHaveLength(3) // Idle -> Loading -> Success
- * ```
- */
-declare const simulate: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], options?: {
-  slots?: ProvideSlots<SD, any>;
-} | undefined) => Effect.Effect<{
-  states: S[];
-  finalState: S;
-}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
-/**
- * Assert that a machine can reach a specific state given a sequence of events
- */
-declare const assertReaches: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], expectedTag: string, options?: {
-  slots?: ProvideSlots<SD, any>;
-} | undefined) => Effect.Effect<S, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
-/**
- * Assert that a machine follows a specific path of state tags
- *
- * @example
- * ```ts
- * yield* assertPath(
- *   machine,
- *   [Event.Start(), Event.Increment(), Event.Stop()],
- *   ["Idle", "Counting", "Counting", "Done"]
- * )
- * ```
- */
-declare const assertPath: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], expectedPath: readonly string[], options?: {
-  slots?: ProvideSlots<SD, any>;
-} | undefined) => Effect.Effect<{
-  states: S[];
-  finalState: S;
-}, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
-/**
- * Assert that a machine never reaches a specific state given a sequence of events
- *
- * @example
- * ```ts
- * // Verify error handling doesn't reach crash state
- * yield* assertNeverReaches(
- *   machine,
- *   [Event.Error(), Event.Retry(), Event.Success()],
- *   "Crashed"
- * )
- * ```
- */
-declare const assertNeverReaches: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, events: readonly E[], forbiddenTag: string, options?: {
-  slots?: ProvideSlots<SD, any>;
-} | undefined) => Effect.Effect<{
-  states: S[];
-  finalState: S;
-}, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
-/**
- * Create a controllable test harness for a machine
- */
-interface TestHarness<S, E, R> {
-  readonly state: SubscriptionRef.SubscriptionRef<S>;
-  readonly send: (event: E) => Effect.Effect<S, never, R>;
-  readonly getState: Effect.Effect<S>;
-}
-/**
- * Options for creating a test harness
- */
-interface TestHarnessOptions<S, E, SD extends SlotsDef = Record<string, never>> {
-  /**
-   * Called after each transition with the previous state, event, and new state.
-   * Useful for logging or spying on transitions.
-   */
-  readonly onTransition?: (from: S, event: E, to: S) => void;
-  /** Slot handler implementations. */
-  readonly slots?: ProvideSlots<SD, any>;
-}
-/**
- * Create a test harness for step-by-step testing.
- * Does not run onEnter/spawn/background effects, but does run slots
- * within transition handlers.
- *
- * @example Basic usage
- * ```ts
- * const harness = yield* createTestHarness(machine)
- * yield* harness.send(Event.Start())
- * const state = yield* harness.getState
- * ```
- *
- * @example With transition observer
- * ```ts
- * const transitions: Array<{ from: string; event: string; to: string }> = []
- * const harness = yield* createTestHarness(machine, {
- *   onTransition: (from, event, to) =>
- *     transitions.push({ from: from._tag, event: event._tag, to: to._tag })
- * })
- * ```
- */
-declare const createTestHarness: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef = Record<string, never>>(input: MachineInput<S, E, R, SD>, options?: TestHarnessOptions<S, E, SD> | undefined) => Effect.Effect<{
-  state: SubscriptionRef.SubscriptionRef<S>;
-  send: (event: E) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
-  getState: Effect.Effect<S, never, never>;
-}, never, never>;
-//#endregion
-export { AssertionError, SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate };

package/v3/dist/testing.js

@@ -1,189 +0,0 @@
-import { stubSystem } from "./internal/utils.js";
-import { AssertionError } from "./errors.js";
-import { executeTransition, shouldPostpone } from "./internal/transition.js";
-import { materializeMachine } from "./machine.js";
-import { Effect, SubscriptionRef } from "effect";
-//#region src/testing.ts
-const makeDummySelf = (label) => {
-	const dummySend = Effect.fn(label)((_event) => Effect.void);
-	return {
-		send: dummySend,
-		cast: dummySend,
-		spawn: () => Effect.die(`spawn not supported in ${label}`),
-		reply: () => Effect.succeed(false)
-	};
-};
-/**
-* Simulate a sequence of events through a machine without running an actor.
-* Useful for testing state transitions in isolation.
-* Does not run onEnter/spawn/background effects, but does run slots
-* within transition handlers.
-*
-* @example
-* ```ts
-* const result = yield* simulate(
-*   fetcherMachine,
-*   [
-*     Event.Fetch({ url: "https://example.com" }),
-*     Event._Done({ data: { foo: "bar" } })
-*   ]
-* )
-*
-* expect(result.finalState._tag).toBe("Success")
-* expect(result.states).toHaveLength(3) // Idle -> Loading -> Success
-* ```
-*/
-const simulate = Effect.fn("effect-machine.simulate")(function* (input, events, options) {
-	const machine = materializeMachine(input, options?.slots);
-	const dummySelf = makeDummySelf("effect-machine.testing.simulate");
-	let currentState = machine.initial;
-	const states = [currentState];
-	const hasPostponeRules = machine.postponeRules.length > 0;
-	const postponed = [];
-	for (const event of events) {
-		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
-			postponed.push(event);
-			continue;
-		}
-		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "simulation");
-		if (!result.transitioned) continue;
-		const prevTag = currentState._tag;
-		currentState = result.newState;
-		states.push(currentState);
-		if (machine.finalStates.has(currentState._tag)) break;
-		let drainTag = prevTag;
-		while (currentState._tag !== drainTag && postponed.length > 0) {
-			drainTag = currentState._tag;
-			const drained = postponed.splice(0);
-			for (const postponedEvent of drained) {
-				if (shouldPostpone(machine, currentState._tag, postponedEvent._tag)) {
-					postponed.push(postponedEvent);
-					continue;
-				}
-				const drainResult = yield* executeTransition(machine, currentState, postponedEvent, dummySelf, stubSystem, "simulation");
-				if (drainResult.transitioned) {
-					currentState = drainResult.newState;
-					states.push(currentState);
-					if (machine.finalStates.has(currentState._tag)) break;
-				}
-			}
-		}
-	}
-	return {
-		states,
-		finalState: currentState
-	};
-});
-/**
-* Assert that a machine can reach a specific state given a sequence of events
-*/
-const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input, events, expectedTag, options) {
-	const result = yield* simulate(input, events, options);
-	if (result.finalState._tag !== expectedTag) return yield* new AssertionError({ message: `Expected final state "${expectedTag}" but got "${result.finalState._tag}". States visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
-	return result.finalState;
-});
-/**
-* Assert that a machine follows a specific path of state tags
-*
-* @example
-* ```ts
-* yield* assertPath(
-*   machine,
-*   [Event.Start(), Event.Increment(), Event.Stop()],
-*   ["Idle", "Counting", "Counting", "Done"]
-* )
-* ```
-*/
-const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, events, expectedPath, options) {
-	const result = yield* simulate(input, events, options);
-	const actualPath = result.states.map((s) => s._tag);
-	if (actualPath.length !== expectedPath.length) return yield* new AssertionError({ message: `Path length mismatch. Expected ${expectedPath.length} states but got ${actualPath.length}.\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
-	for (let i = 0; i < expectedPath.length; i++) if (actualPath[i] !== expectedPath[i]) return yield* new AssertionError({ message: `Path mismatch at position ${i}. Expected "${expectedPath[i]}" but got "${actualPath[i]}".\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
-	return result;
-});
-/**
-* Assert that a machine never reaches a specific state given a sequence of events
-*
-* @example
-* ```ts
-* // Verify error handling doesn't reach crash state
-* yield* assertNeverReaches(
-*   machine,
-*   [Event.Error(), Event.Retry(), Event.Success()],
-*   "Crashed"
-* )
-* ```
-*/
-const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(function* (input, events, forbiddenTag, options) {
-	const result = yield* simulate(input, events, options);
-	const visitedIndex = result.states.findIndex((s) => s._tag === forbiddenTag);
-	if (visitedIndex !== -1) return yield* new AssertionError({ message: `Machine reached forbidden state "${forbiddenTag}" at position ${visitedIndex}.\nStates visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
-	return result;
-});
-/**
-* Create a test harness for step-by-step testing.
-* Does not run onEnter/spawn/background effects, but does run slots
-* within transition handlers.
-*
-* @example Basic usage
-* ```ts
-* const harness = yield* createTestHarness(machine)
-* yield* harness.send(Event.Start())
-* const state = yield* harness.getState
-* ```
-*
-* @example With transition observer
-* ```ts
-* const transitions: Array<{ from: string; event: string; to: string }> = []
-* const harness = yield* createTestHarness(machine, {
-*   onTransition: (from, event, to) =>
-*     transitions.push({ from: from._tag, event: event._tag, to: to._tag })
-* })
-* ```
-*/
-const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
-	const machine = materializeMachine(input, options?.slots);
-	const dummySelf = makeDummySelf("effect-machine.testing.harness");
-	const stateRef = yield* SubscriptionRef.make(machine.initial);
-	const hasPostponeRules = machine.postponeRules.length > 0;
-	const postponed = [];
-	return {
-		state: stateRef,
-		send: Effect.fn("effect-machine.testHarness.send")(function* (event) {
-			const currentState = yield* SubscriptionRef.get(stateRef);
-			if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
-				postponed.push(event);
-				return currentState;
-			}
-			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "test-harness");
-			if (!result.transitioned) return currentState;
-			const prevTag = currentState._tag;
-			const newState = result.newState;
-			yield* SubscriptionRef.set(stateRef, newState);
-			if (options?.onTransition !== void 0) options.onTransition(currentState, event, newState);
-			let drainTag = prevTag;
-			let currentTag = newState._tag;
-			while (currentTag !== drainTag && postponed.length > 0) {
-				drainTag = currentTag;
-				const drained = postponed.splice(0);
-				for (const postponedEvent of drained) {
-					const state = yield* SubscriptionRef.get(stateRef);
-					if (shouldPostpone(machine, state._tag, postponedEvent._tag)) {
-						postponed.push(postponedEvent);
-						continue;
-					}
-					const drainResult = yield* executeTransition(machine, state, postponedEvent, dummySelf, stubSystem, "test-harness");
-					if (drainResult.transitioned) {
-						yield* SubscriptionRef.set(stateRef, drainResult.newState);
-						currentTag = drainResult.newState._tag;
-						if (options?.onTransition !== void 0) options.onTransition(state, postponedEvent, drainResult.newState);
-					}
-				}
-			}
-			return newState;
-		}),
-		getState: SubscriptionRef.get(stateRef)
-	};
-});
-//#endregion
-export { AssertionError, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate };