effect-machine 0.1.0

package/src/slot.ts

@@ -0,0 +1,281 @@
+/**
+ * Slot module - schema-based, parameterized guards and effects.
+ *
+ * Guards and Effects are defined with schemas for their parameters,
+ * and provided implementations receive typed parameters plus machine context.
+ *
+ * @example
+ * ```ts
+ * import { Slot } from "effect-machine"
+ * import { Schema } from "effect"
+ *
+ * const MyGuards = Slot.Guards({
+ *   canRetry: { max: Schema.Number },
+ *   isValid: {},  // no params
+ * })
+ *
+ * const MyEffects = Slot.Effects({
+ *   fetchData: { url: Schema.String },
+ *   notify: { message: Schema.String },
+ * })
+ *
+ * // Used in handlers:
+ * .on(State.X, Event.Y, ({ guards, effects }) =>
+ *   Effect.gen(function* () {
+ *     if (yield* guards.canRetry({ max: 3 })) {
+ *       yield* effects.fetchData({ url: "/api" })
+ *       return State.Next
+ *     }
+ *     return state
+ *   })
+ * )
+ * ```
+ *
+ * @module
+ */
+import { Context } from "effect";
+import type { Effect, Schema } from "effect";
+
+// ============================================================================
+// Type-level utilities
+// ============================================================================
+
+/** Schema fields definition (like Schema.Struct.Fields) */
+type Fields = Record<string, Schema.Schema.All>;
+
+/** Extract the encoded type from schema fields (used for parameters) */
+type FieldsToParams<F extends Fields> = keyof F extends never
+  ? void
+  : Schema.Schema.Type<Schema.Struct<F>>;
+
+// ============================================================================
+// Slot Types
+// ============================================================================
+
+/**
+ * A guard slot - callable function that returns Effect<boolean>.
+ */
+export interface GuardSlot<Name extends string, Params> {
+  readonly _tag: "GuardSlot";
+  readonly name: Name;
+  (params: Params): Effect.Effect<boolean>;
+}
+
+/**
+ * An effect slot - callable function that returns Effect<void>.
+ */
+export interface EffectSlot<Name extends string, Params> {
+  readonly _tag: "EffectSlot";
+  readonly name: Name;
+  (params: Params): Effect.Effect<void>;
+}
+
+/**
+ * Guard definition - name to schema fields mapping
+ */
+export type GuardsDef = Record<string, Fields>;
+
+/**
+ * Effect definition - name to schema fields mapping
+ */
+export type EffectsDef = Record<string, Fields>;
+
+/**
+ * Convert guard definitions to callable guard slots
+ */
+export type GuardSlots<D extends GuardsDef> = {
+  readonly [K in keyof D & string]: GuardSlot<K, FieldsToParams<D[K]>>;
+};
+
+/**
+ * Convert effect definitions to callable effect slots
+ */
+export type EffectSlots<D extends EffectsDef> = {
+  readonly [K in keyof D & string]: EffectSlot<K, FieldsToParams<D[K]>>;
+};
+
+// ============================================================================
+// Machine Context Tag
+// ============================================================================
+
+/**
+ * Type for machine context - state, event, and self reference.
+ * Shared across all machines via MachineContextTag.
+ */
+export interface MachineContext<State, Event, Self> {
+  readonly state: State;
+  readonly event: Event;
+  readonly self: Self;
+}
+
+/**
+ * Shared Context tag for all machines.
+ * Single module-level tag instead of per-machine allocation.
+ * @internal
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- generic context tag */
+export const MachineContextTag =
+  Context.GenericTag<MachineContext<any, any, any>>("@effect-machine/Context");
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+// ============================================================================
+// Handler Types (for provide)
+// ============================================================================
+
+/**
+ * Guard handler implementation.
+ * Receives params and context, returns Effect<boolean>.
+ */
+export type GuardHandler<Params, Ctx, R = never> = (
+  params: Params,
+  ctx: Ctx,
+) => boolean | Effect.Effect<boolean, never, R>;
+
+/**
+ * Effect handler implementation.
+ * Receives params and context, returns Effect<void>.
+ */
+export type EffectHandler<Params, Ctx, R = never> = (
+  params: Params,
+  ctx: Ctx,
+) => Effect.Effect<void, never, R>;
+
+/**
+ * Handler types for all guards in a definition
+ */
+export type GuardHandlers<D extends GuardsDef, MachineCtx, R = never> = {
+  readonly [K in keyof D & string]: GuardHandler<FieldsToParams<D[K]>, MachineCtx, R>;
+};
+
+/**
+ * Handler types for all effects in a definition
+ */
+export type EffectHandlers<D extends EffectsDef, MachineCtx, R = never> = {
+  readonly [K in keyof D & string]: EffectHandler<FieldsToParams<D[K]>, MachineCtx, R>;
+};
+
+// ============================================================================
+// Schema Types (for Machine.make)
+// ============================================================================
+
+/**
+ * Guards schema - returned by Slot.Guards()
+ */
+export interface GuardsSchema<D extends GuardsDef> {
+  readonly _tag: "GuardsSchema";
+  readonly definitions: D;
+  /** Create callable guard slots (used by Machine internally) */
+  readonly _createSlots: (
+    resolve: <N extends keyof D & string>(
+      name: N,
+      params: FieldsToParams<D[N]>,
+    ) => Effect.Effect<boolean>,
+  ) => GuardSlots<D>;
+}
+
+/**
+ * Effects schema - returned by Slot.Effects()
+ */
+export interface EffectsSchema<D extends EffectsDef> {
+  readonly _tag: "EffectsSchema";
+  readonly definitions: D;
+  /** Create callable effect slots (used by Machine internally) */
+  readonly _createSlots: (
+    resolve: <N extends keyof D & string>(
+      name: N,
+      params: FieldsToParams<D[N]>,
+    ) => Effect.Effect<void>,
+  ) => EffectSlots<D>;
+}
+
+// ============================================================================
+// Slot Factories
+// ============================================================================
+
+/**
+ * Generic slot schema factory. Used internally by Guards() and Effects().
+ * @internal
+ */
+const createSlotSchema = <
+  Tag extends "GuardsSchema" | "EffectsSchema",
+  D extends Record<string, Fields>,
+>(
+  tag: Tag,
+  slotTag: "GuardSlot" | "EffectSlot",
+  definitions: D,
+): {
+  readonly _tag: Tag;
+  readonly definitions: D;
+  readonly _createSlots: (
+    resolve: <N extends keyof D & string>(
+      name: N,
+      params: FieldsToParams<D[N]>,
+    ) => Effect.Effect<unknown>,
+  ) => Record<string, unknown>;
+} => ({
+  _tag: tag,
+  definitions,
+  _createSlots: (resolve) => {
+    const slots: Record<string, unknown> = {};
+    for (const name of Object.keys(definitions)) {
+      const slot = (params: unknown) => resolve(name, params as FieldsToParams<D[typeof name]>);
+      Object.defineProperty(slot, "_tag", { value: slotTag, enumerable: true });
+      Object.defineProperty(slot, "name", { value: name, enumerable: true });
+      slots[name] = slot;
+    }
+    return slots;
+  },
+});
+
+/**
+ * Create a guards schema with parameterized guard definitions.
+ *
+ * @example
+ * ```ts
+ * const MyGuards = Slot.Guards({
+ *   canRetry: { max: Schema.Number },
+ *   isValid: {},
+ * })
+ * ```
+ */
+export const Guards = <D extends GuardsDef>(definitions: D): GuardsSchema<D> =>
+  createSlotSchema("GuardsSchema", "GuardSlot", definitions) as GuardsSchema<D>;
+
+/**
+ * Create an effects schema with parameterized effect definitions.
+ *
+ * @example
+ * ```ts
+ * const MyEffects = Slot.Effects({
+ *   fetchData: { url: Schema.String },
+ *   notify: { message: Schema.String },
+ * })
+ * ```
+ */
+export const Effects = <D extends EffectsDef>(definitions: D): EffectsSchema<D> =>
+  createSlotSchema("EffectsSchema", "EffectSlot", definitions) as EffectsSchema<D>;
+
+// ============================================================================
+// Type extraction helpers
+// ============================================================================
+
+/** Extract guard definition type from GuardsSchema */
+export type GuardsDefOf<G> = G extends GuardsSchema<infer D> ? D : never;
+
+/** Extract effect definition type from EffectsSchema */
+export type EffectsDefOf<E> = E extends EffectsSchema<infer D> ? D : never;
+
+/** Extract guard slots type from GuardsSchema */
+export type GuardSlotsOf<G> = G extends GuardsSchema<infer D> ? GuardSlots<D> : never;
+
+/** Extract effect slots type from EffectsSchema */
+export type EffectSlotsOf<E> = E extends EffectsSchema<infer D> ? EffectSlots<D> : never;
+
+// ============================================================================
+// Slot namespace export
+// ============================================================================
+
+export const Slot = {
+  Guards,
+  Effects,
+} as const;

package/src/testing.ts

@@ -0,0 +1,282 @@
+import { Effect, SubscriptionRef } from "effect";
+
+import type { Machine, MachineRef } from "./machine.js";
+import { AssertionError } from "./errors.js";
+import type { GuardsDef, EffectsDef } from "./slot.js";
+import { executeTransition } from "./internal/transition.js";
+
+/**
+ * Result of simulating events through a machine
+ */
+export 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
+ * ```
+ */
+export 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>,
+>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
+  machine: Machine<S, E, R, any, any, GD, EFD>,
+  events: ReadonlyArray<E>,
+): Effect.Effect<SimulationResult<S>, never, R> =>
+  Effect.gen(function* () {
+    // Create a dummy self for slot accessors
+    const dummySelf: MachineRef<E> = {
+      send: () => Effect.void,
+    };
+
+    let currentState = machine.initial;
+    const states: S[] = [currentState];
+
+    for (const event of events) {
+      const result = yield* executeTransition(machine, currentState, event, dummySelf);
+
+      if (!result.transitioned) {
+        continue;
+      }
+
+      currentState = result.newState;
+      states.push(currentState);
+
+      // Stop if final state
+      if (machine.finalStates.has(currentState._tag)) {
+        break;
+      }
+    }
+
+    return { states, finalState: currentState };
+  });
+
+// AssertionError is exported from errors.ts
+export { AssertionError } from "./errors.js";
+
+/**
+ * Assert that a machine can reach a specific state given a sequence of events
+ */
+export 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>,
+>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
+  machine: Machine<S, E, R, any, any, GD, EFD>,
+  events: ReadonlyArray<E>,
+  expectedTag: string,
+): Effect.Effect<S, AssertionError, R> =>
+  Effect.gen(function* () {
+    const result = yield* simulate(machine, 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"]
+ * )
+ * ```
+ */
+export 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>,
+>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
+  machine: Machine<S, E, R, any, any, GD, EFD>,
+  events: ReadonlyArray<E>,
+  expectedPath: ReadonlyArray<string>,
+): Effect.Effect<SimulationResult<S>, AssertionError, R> =>
+  Effect.gen(function* () {
+    const result = yield* simulate(machine, 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}.\n` +
+          `Expected: ${expectedPath.join(" -> ")}\n` +
+          `Actual:   ${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]}".\n` +
+            `Expected: ${expectedPath.join(" -> ")}\n` +
+            `Actual:   ${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"
+ * )
+ * ```
+ */
+export 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>,
+>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
+  machine: Machine<S, E, R, any, any, GD, EFD>,
+  events: ReadonlyArray<E>,
+  forbiddenTag: string,
+): Effect.Effect<SimulationResult<S>, AssertionError, R> =>
+  Effect.gen(function* () {
+    const result = yield* simulate(machine, 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}.\n` +
+          `States visited: ${result.states.map((s) => s._tag).join(" -> ")}`,
+      });
+    }
+
+    return result;
+  });
+
+/**
+ * Create a controllable test harness for a machine
+ */
+export 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
+ */
+export 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 })
+ * })
+ * ```
+ */
+export 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>,
+>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
+  machine: Machine<S, E, R, any, any, GD, EFD>,
+  options?: TestHarnessOptions<S, E>,
+): Effect.Effect<TestHarness<S, E, R>, never, R> =>
+  Effect.gen(function* () {
+    // Create a dummy self for slot accessors
+    const dummySelf: MachineRef<E> = {
+      send: () => Effect.void,
+    };
+
+    const stateRef = yield* SubscriptionRef.make(machine.initial);
+
+    const send = (event: E): Effect.Effect<S, never, R> =>
+      Effect.gen(function* () {
+        const currentState = yield* SubscriptionRef.get(stateRef);
+
+        const result = yield* executeTransition(machine, currentState, event, dummySelf);
+
+        if (!result.transitioned) {
+          return currentState;
+        }
+
+        const newState = result.newState;
+        yield* SubscriptionRef.set(stateRef, newState);
+
+        // Call transition observer
+        if (options?.onTransition !== undefined) {
+          options.onTransition(currentState, event, newState);
+        }
+
+        return newState;
+      });
+
+    return {
+      state: stateRef,
+      send,
+      getState: SubscriptionRef.get(stateRef),
+    };
+  });

package/tsconfig.json

@@ -0,0 +1,68 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnostics": true,
+        "diagnosticsName": true,
+        "diagnosticSeverity": {
+          // Enable rules that are off by default
+          "anyUnknownInErrorContext": "error",
+          "deterministicKeys": "warning",
+          "importFromBarrel": "warning",
+          "instanceOfSchema": "warning",
+          "missedPipeableOpportunity": "warning",
+          "missingEffectServiceDependency": "warning",
+          "schemaUnionOfLiterals": "warning",
+          "strictBooleanExpressions": "warning",
+          "strictEffectProvide": "warning",
+
+          // Upgrade suggestions to warnings for stricter enforcement
+          "catchAllToMapError": "warning",
+          "catchUnfailableEffect": "warning",
+          "effectFnOpportunity": "warning",
+          "effectMapVoid": "warning",
+          "effectSucceedWithVoid": "warning",
+          "leakingRequirements": "warning",
+          "preferSchemaOverJson": "warning",
+          "redundantSchemaTagIdentifier": "warning",
+          "returnEffectInGen": "warning",
+          "runEffectInsideEffect": "error",
+          "schemaStructWithTag": "warning",
+          "schemaSyncInEffect": "warning",
+          "tryCatchInEffectGen": "warning",
+          "unnecessaryEffectGen": "warning",
+          "unnecessaryFailYieldableError": "warning",
+          "unnecessaryPipe": "warning",
+          "unnecessaryPipeChain": "warning"
+        },
+        "keyPatterns": [
+          {
+            "target": "service",
+            "pattern": "default",
+            "skipLeadingPath": ["src/"]
+          },
+          {
+            "target": "error",
+            "pattern": "default",
+            "skipLeadingPath": ["src/"]
+          }
+        ]
+      }
+    ]
+  },
+  "include": ["src", "test"],
+  "exclude": ["node_modules"]
+}