effect-machine 0.3.1 → 0.4.0

package/dist/testing.d.ts

@@ -0,0 +1,142 @@
+import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { AssertionError } from "./errors.js";
+import { BuiltMachine, Machine, MachineRef } from "./machine.js";
+import { Effect, SubscriptionRef } from "effect";
+
+//#region src/testing.d.ts
+/** Accept either Machine or BuiltMachine for testing utilities. */
+type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> = Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>;
+/**
+ * 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 guard/effect 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, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[]) => 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, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string) => 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, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[]) => 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, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string) => 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> {
+  /**
+   * 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;
+}
+/**
+ * Create a test harness for step-by-step testing.
+ * Does not run onEnter/spawn/background effects, but does run guard/effect 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, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, options?: TestHarnessOptions<S, E> | 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/dist/testing.js

@@ -0,0 +1,138 @@
+import { stubSystem } from "./internal/utils.js";
+import { AssertionError } from "./errors.js";
+import { BuiltMachine } from "./machine.js";
+import { executeTransition } from "./internal/transition.js";
+import { Effect, SubscriptionRef } from "effect";
+
+//#region src/testing.ts
+/**
+* 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 guard/effect 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) {
+	const machine = input instanceof BuiltMachine ? input._inner : input;
+	const dummySelf = {
+		send: Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void),
+		spawn: () => Effect.die("spawn not supported in simulation")
+	};
+	let currentState = machine.initial;
+	const states = [currentState];
+	for (const event of events) {
+		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
+		if (!result.transitioned) continue;
+		currentState = result.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) {
+	const result = yield* simulate(input, events);
+	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) {
+	const result = yield* simulate(input, events);
+	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) {
+	const result = yield* simulate(input, events);
+	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 guard/effect 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 = input instanceof BuiltMachine ? input._inner : input;
+	const dummySelf = {
+		send: Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void),
+		spawn: () => Effect.die("spawn not supported in test harness")
+	};
+	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	return {
+		state: stateRef,
+		send: Effect.fn("effect-machine.testHarness.send")(function* (event) {
+			const currentState = yield* SubscriptionRef.get(stateRef);
+			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
+			if (!result.transitioned) return currentState;
+			const newState = result.newState;
+			yield* SubscriptionRef.set(stateRef, newState);
+			if (options?.onTransition !== void 0) options.onTransition(currentState, event, newState);
+			return newState;
+		}),
+		getState: SubscriptionRef.get(stateRef)
+	};
+});
+
+//#endregion
+export { AssertionError, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate };

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "effect-machine",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
   },
   "files": [
-    "src",
-    "tsconfig.json"
+    "dist"
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts",
-    "./cluster": "./src/cluster/index.ts"
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./cluster": {
+      "import": {
+        "types": "./dist/cluster/index.d.ts",
+        "default": "./dist/cluster/index.js"
+      }
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -25,27 +34,29 @@
     "fmt:check": "oxfmt --check",
     "test": "bun test",
     "test:watch": "bun test --watch",
-    "gate": "concurrently -n type,lint,fmt,test -c blue,yellow,magenta,green \"bun run typecheck\" \"bun run lint:fix\" \"bun run fmt\" \"bun run test\"",
+    "gate": "concurrently -n type,lint,fmt,test,build -c blue,yellow,magenta,green,cyan \"bun run typecheck\" \"bun run lint:fix\" \"bun run fmt\" \"bun run test\" \"bun run build\"",
     "prepare": "lefthook install || true && effect-language-service patch",
     "version": "changeset version",
-    "release": "changeset publish"
+    "build": "tsdown",
+    "release": "bun run build && changeset publish"
   },
   "dependencies": {
-    "effect": "^3.19.15"
+    "effect": "^3.19.16"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
-    "@effect/cluster": "^0.56.1",
+    "@effect/cluster": "^0.56.2",
     "@effect/experimental": "^0.58.0",
-    "@effect/language-service": "^0.72.0",
+    "@effect/language-service": "^0.73.0",
     "@effect/rpc": "^0.73.0",
-    "@types/bun": "latest",
+    "@types/bun": "1.3.8",
     "concurrently": "^9.2.1",
     "effect-bun-test": "^0.1.0",
-    "lefthook": "^2.0.15",
-    "oxfmt": "^0.26.0",
-    "oxlint": "^1.41.0",
+    "lefthook": "^2.1.0",
+    "oxfmt": "^0.28.0",
+    "oxlint": "^1.43.0",
+    "tsdown": "^0.20.3",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
@@ -59,5 +70,8 @@
     "@effect/rpc": {
       "optional": true
     }
+  },
+  "overrides": {
+    "effect": "^3.19.16"
   }
 }