effect-machine 0.3.1 → 0.4.0

package/src/cluster/entity-machine.ts

@@ -1,201 +0,0 @@
-/**
- * EntityMachine adapter - wires a machine to a cluster Entity layer.
- *
- * @module
- */
-import { Entity } from "@effect/cluster";
-import type { Rpc } from "@effect/rpc";
-import { Effect, type Layer, Queue, Ref, Scope } from "effect";
-
-import type { Machine, MachineRef } from "../machine.js";
-import { runSpawnEffects, processEventCore } from "../actor.js";
-import type { ProcessEventHooks } from "../actor.js";
-import type { GuardsDef, EffectsDef } from "../slot.js";
-
-/**
- * Options for EntityMachine.layer
- */
-export interface EntityMachineOptions<S, E> {
-  /**
-   * Initialize state from entity ID.
-   * Called once when entity is first activated.
-   *
-   * @example
-   * ```ts
-   * EntityMachine.layer(OrderEntity, orderMachine, {
-   *   initializeState: (entityId) => OrderState.Pending({ orderId: entityId }),
-   * })
-   * ```
-   */
-  readonly initializeState?: (entityId: string) => S;
-
-  /**
-   * Optional hooks for inspection/tracing.
-   * Called at specific points during event processing.
-   *
-   * @example
-   * ```ts
-   * EntityMachine.layer(OrderEntity, orderMachine, {
-   *   hooks: {
-   *     onTransition: (from, to, event) =>
-   *       Effect.log(`Transition: ${from._tag} -> ${to._tag}`),
-   *     onSpawnEffect: (state) =>
-   *       Effect.log(`Running spawn effects for ${state._tag}`),
-   *     onError: ({ phase, state }) =>
-   *       Effect.log(`Defect in ${phase} at ${state._tag}`),
-   *   },
-   * })
-   * ```
-   */
-  readonly hooks?: ProcessEventHooks<S, E>;
-}
-
-/**
- * Process a single event through the machine using shared core.
- * Returns the new state after processing.
- */
-const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* <
-  S extends { readonly _tag: string },
-  E extends { readonly _tag: string },
-  R,
-  GD extends GuardsDef = Record<string, never>,
-  EFD extends EffectsDef = Record<string, never>,
->(
-  machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
-  stateRef: Ref.Ref<S>,
-  event: E,
-  self: MachineRef<E>,
-  stateScopeRef: { current: Scope.CloseableScope },
-  hooks?: ProcessEventHooks<S, E>,
-) {
-  const currentState = yield* Ref.get(stateRef);
-
-  // Process event using shared core
-  const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, hooks);
-
-  // Update state ref if transition occurred
-  if (result.transitioned) {
-    yield* Ref.set(stateRef, result.newState);
-  }
-
-  return result.newState;
-});
-
-/**
- * Create an Entity layer that wires a machine to handle RPC calls.
- *
- * The layer:
- * - Maintains state via Ref per entity instance
- * - Resolves transitions using the indexed lookup
- * - Evaluates guards in registration order
- * - Runs lifecycle effects (onEnter/spawn)
- * - Processes internal events from spawn effects
- *
- * @example
- * ```ts
- * const OrderEntity = toEntity(orderMachine, {
- *   type: "Order",
- *   stateSchema: OrderState,
- *   eventSchema: OrderEvent,
- * })
- *
- * const OrderEntityLayer = EntityMachine.layer(OrderEntity, orderMachine, {
- *   initializeState: (entityId) => OrderState.Pending({ orderId: entityId }),
- * })
- *
- * // Use in cluster
- * const program = Effect.gen(function* () {
- *   const client = yield* ShardingClient.client(OrderEntity)
- *   yield* client.Send("order-123", { event: OrderEvent.Ship({ trackingId: "abc" }) })
- * })
- * ```
- */
-export const EntityMachine = {
-  /**
-   * Create a layer that wires a machine to an Entity.
-   *
-   * @param entity - Entity created via toEntity()
-   * @param machine - Machine with all effects provided
-   * @param options - Optional configuration (state initializer, inspection hooks)
-   */
-  layer: <
-    S extends { readonly _tag: string },
-    E extends { readonly _tag: string },
-    R,
-    GD extends GuardsDef,
-    EFD extends EffectsDef,
-    EntityType extends string,
-    Rpcs extends Rpc.Any,
-  >(
-    entity: Entity.Entity<EntityType, Rpcs>,
-    machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
-    options?: EntityMachineOptions<S, E>,
-  ): Layer.Layer<never, never, R> => {
-    const layer = Effect.fn("effect-machine.cluster.layer")(function* () {
-      // Get entity ID from context if available
-      const entityId = yield* Effect.serviceOption(Entity.CurrentAddress).pipe(
-        Effect.map((opt) => (opt._tag === "Some" ? opt.value.entityId : "")),
-      );
-
-      // Initialize state - use provided initializer or machine's initial state
-      const initialState =
-        options?.initializeState !== undefined
-          ? options.initializeState(entityId)
-          : machine.initial;
-
-      // Create self reference for sending events back to machine
-      const internalQueue = yield* Queue.unbounded<E>();
-      const self: MachineRef<E> = {
-        send: Effect.fn("effect-machine.cluster.self.send")(function* (event: E) {
-          yield* Queue.offer(internalQueue, event);
-        }),
-      };
-
-      // Create state ref
-      const stateRef = yield* Ref.make<S>(initialState);
-
-      // Create state scope for spawn effects
-      const stateScopeRef: { current: Scope.CloseableScope } = {
-        current: yield* Scope.make(),
-      };
-
-      // Use $init event for initial lifecycle
-      const initEvent = { _tag: "$init" } as E;
-
-      // Run initial spawn effects
-      yield* runSpawnEffects(
-        machine,
-        initialState,
-        initEvent,
-        self,
-        stateScopeRef.current,
-        options?.hooks?.onError,
-      );
-
-      // Process internal events in background
-      const runInternalEvent = Effect.fn("effect-machine.cluster.internalEvent")(function* () {
-        const event = yield* Queue.take(internalQueue);
-        yield* processEvent(machine, stateRef, event, self, stateScopeRef, options?.hooks);
-      });
-      yield* Effect.forkScoped(Effect.forever(runInternalEvent()));
-
-      // Return handlers matching the Entity's RPC protocol
-      // The actual types are inferred from the entity definition
-      return entity.of({
-        Send: (envelope: { payload: { event: E } }) =>
-          processEvent(
-            machine,
-            stateRef,
-            envelope.payload.event,
-            self,
-            stateScopeRef,
-            options?.hooks,
-          ),
-
-        GetState: () => Ref.get(stateRef),
-        // Entity.of expects handlers matching Rpcs type param - dynamic construction requires cast
-      } as unknown as Parameters<typeof entity.of>[0]);
-    });
-    return entity.toLayer(layer()) as unknown as Layer.Layer<never, never, R>;
-  },
-};

package/src/cluster/index.ts

@@ -1,43 +0,0 @@
-/**
- * Cluster integration for effect-machine.
- *
- * Provides bridges between effect-machine state machines and @effect/cluster:
- * - `toEntity` - Generate Entity definition from machine
- * - `EntityMachine` - Wire machine to cluster Entity layer
- *
- * @example
- * ```ts
- * import { Machine, MachineSchema } from "effect-machine"
- * import { toEntity, EntityMachine } from "effect-machine/cluster"
- *
- * // Schema-first definitions
- * const OrderState = MachineSchema.State({
- *   Pending: { orderId: Schema.String },
- *   Shipped: { trackingId: Schema.String },
- * })
- *
- * const OrderEvent = MachineSchema.Event({
- *   Ship: { trackingId: Schema.String },
- * })
- *
- * // Define machine
- * const orderMachine = Machine.make(OrderState.Pending({ orderId: "" })).pipe(
- *   Machine.on(OrderState.Pending, OrderEvent.Ship, ...)
- * )
- *
- * // Generate Entity
- * const OrderEntity = toEntity(orderMachine, {
- *   type: "Order",
- *   stateSchema: OrderState,
- *   eventSchema: OrderEvent,
- * })
- *
- * // Create layer
- * const OrderEntityLayer = EntityMachine.layer(OrderEntity, orderMachine)
- * ```
- *
- * @module
- */
-
-export { toEntity, type ToEntityOptions } from "./to-entity.js";
-export { EntityMachine, type EntityMachineOptions } from "./entity-machine.js";

package/src/cluster/to-entity.ts

@@ -1,99 +0,0 @@
-/**
- * Generate Entity definition from a machine.
- *
- * @module
- */
-import { Entity } from "@effect/cluster";
-import { Rpc } from "@effect/rpc";
-import type { Schema } from "effect";
-
-import type { Machine } from "../machine.js";
-import { MissingSchemaError } from "../errors.js";
-
-/**
- * Options for toEntity.
- */
-export interface ToEntityOptions {
-  /**
-   * Entity type name (e.g., "Order", "User")
-   */
-  readonly type: string;
-}
-
-/**
- * Default RPC protocol for entity machines.
- *
- * - `Send` - Send event to machine, returns new state
- * - `GetState` - Get current state
- */
-export type EntityRpcs<
-  StateSchema extends Schema.Schema.Any,
-  EventSchema extends Schema.Schema.Any,
-> = readonly [
-  Rpc.Rpc<
-    "Send",
-    Schema.Struct<{ readonly event: EventSchema }>,
-    StateSchema,
-    typeof Schema.Never,
-    never
-  >,
-  Rpc.Rpc<"GetState", typeof Schema.Void, StateSchema, typeof Schema.Never, never>,
-];
-
-/**
- * Generate an Entity definition from a machine.
- *
- * Creates an Entity with a standard RPC protocol:
- * - `Send(event)` - Process event through machine, returns new state
- * - `GetState()` - Returns current state
- *
- * Schemas are read from the machine - must use `Machine.make({ state, event, initial })`.
- *
- * @example
- * ```ts
- * const OrderState = State({
- *   Pending: { orderId: Schema.String },
- *   Shipped: { trackingId: Schema.String },
- * })
- *
- * const OrderEvent = Event({
- *   Ship: { trackingId: Schema.String },
- * })
- *
- * const orderMachine = Machine.make({
- *   state: OrderState,
- *   event: OrderEvent,
- *   initial: OrderState.Pending({ orderId: "" }),
- * }).pipe(
- *   Machine.on(OrderState.Pending, OrderEvent.Ship, ...),
- * )
- *
- * const OrderEntity = toEntity(orderMachine, { type: "Order" })
- * ```
- */
-export const toEntity = <
-  S extends { readonly _tag: string },
-  E extends { readonly _tag: string },
-  R,
->(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-  machine: Machine<S, E, R, any, any, any, any>,
-  options: ToEntityOptions,
-) => {
-  const stateSchema = machine.stateSchema;
-  const eventSchema = machine.eventSchema;
-
-  if (stateSchema === undefined || eventSchema === undefined) {
-    throw new MissingSchemaError({ operation: "toEntity" });
-  }
-
-  return Entity.make(options.type, [
-    Rpc.make("Send", {
-      payload: { event: eventSchema },
-      success: stateSchema,
-    }),
-    Rpc.make("GetState", {
-      success: stateSchema,
-    }),
-  ]);
-};

package/src/errors.ts

@@ -1,64 +0,0 @@
-/**
- * Typed error classes for effect-machine.
- *
- * All errors extend Schema.TaggedError for:
- * - Type-safe catching via Effect.catchTag
- * - Serialization support
- * - Composable error handling
- *
- * @module
- */
-import { Schema } from "effect";
-
-/** Attempted to spawn/restore actor with ID already in use */
-export class DuplicateActorError extends Schema.TaggedError<DuplicateActorError>()(
-  "DuplicateActorError",
-  { actorId: Schema.String },
-) {}
-
-/** Machine has unprovided effect slots */
-export class UnprovidedSlotsError extends Schema.TaggedError<UnprovidedSlotsError>()(
-  "UnprovidedSlotsError",
-  { slots: Schema.Array(Schema.String) },
-) {}
-
-/** Operation requires schemas attached to machine */
-export class MissingSchemaError extends Schema.TaggedError<MissingSchemaError>()(
-  "MissingSchemaError",
-  { operation: Schema.String },
-) {}
-
-/** State/Event schema has no variants */
-export class InvalidSchemaError extends Schema.TaggedError<InvalidSchemaError>()(
-  "InvalidSchemaError",
-  {},
-) {}
-
-/** $match called with missing handler for tag */
-export class MissingMatchHandlerError extends Schema.TaggedError<MissingMatchHandlerError>()(
-  "MissingMatchHandlerError",
-  { tag: Schema.String },
-) {}
-
-/** Slot handler not found at runtime (internal error) */
-export class SlotProvisionError extends Schema.TaggedError<SlotProvisionError>()(
-  "SlotProvisionError",
-  {
-    slotName: Schema.String,
-    slotType: Schema.Literal("guard", "effect"),
-  },
-) {}
-
-/** Machine.build() validation failed - missing or extra handlers */
-export class ProvisionValidationError extends Schema.TaggedError<ProvisionValidationError>()(
-  "ProvisionValidationError",
-  {
-    missing: Schema.Array(Schema.String),
-    extra: Schema.Array(Schema.String),
-  },
-) {}
-
-/** Assertion failed in testing utilities */
-export class AssertionError extends Schema.TaggedError<AssertionError>()("AssertionError", {
-  message: Schema.String,
-}) {}

package/src/index.ts

@@ -1,105 +0,0 @@
-// Machine namespace (Effect-style)
-export * as Machine from "./machine.js";
-
-// Slot module
-export { Slot } from "./slot.js";
-export type {
-  GuardsSchema,
-  EffectsSchema,
-  GuardsDef,
-  EffectsDef,
-  GuardSlots,
-  EffectSlots,
-  GuardSlot,
-  EffectSlot as SlotEffectSlot,
-  GuardHandlers,
-  EffectHandlers as SlotEffectHandlers,
-  MachineContext,
-} from "./slot.js";
-
-// Errors
-export {
-  AssertionError,
-  DuplicateActorError,
-  InvalidSchemaError,
-  MissingMatchHandlerError,
-  MissingSchemaError,
-  ProvisionValidationError,
-  SlotProvisionError,
-  UnprovidedSlotsError,
-} from "./errors.js";
-
-// Schema-first State/Event definitions
-export { State, Event } from "./schema.js";
-export type { MachineStateSchema, MachineEventSchema } from "./schema.js";
-
-// Core machine types (for advanced use)
-export type {
-  Machine as MachineType,
-  BuiltMachine,
-  MachineRef,
-  MakeConfig,
-  Transition,
-  SpawnEffect,
-  BackgroundEffect,
-  PersistOptions,
-  HandlerContext,
-  StateHandlerContext,
-  ProvideHandlers,
-} from "./machine.js";
-
-// Actor types and system
-export type { ActorRef, ActorSystem } from "./actor.js";
-export { ActorSystem as ActorSystemService, Default as ActorSystemDefault } from "./actor.js";
-
-// Testing utilities
-export {
-  assertNeverReaches,
-  assertPath,
-  assertReaches,
-  createTestHarness,
-  simulate,
-} from "./testing.js";
-export type { SimulationResult, TestHarness, TestHarnessOptions } from "./testing.js";
-
-// Inspection
-export type {
-  AnyInspectionEvent,
-  EffectEvent,
-  ErrorEvent,
-  EventReceivedEvent,
-  InspectionEvent,
-  Inspector,
-  SpawnEvent,
-  StopEvent,
-  TransitionEvent,
-} from "./inspection.js";
-export {
-  collectingInspector,
-  consoleInspector,
-  Inspector as InspectorService,
-  makeInspector,
-} from "./inspection.js";
-
-// Persistence
-export type {
-  ActorMetadata,
-  PersistedEvent,
-  PersistenceAdapter,
-  PersistenceConfig,
-  PersistentActorRef,
-  PersistentMachine,
-  RestoreFailure,
-  RestoreResult,
-  Snapshot,
-} from "./persistence/index.js";
-export {
-  createPersistentActor,
-  InMemoryPersistenceAdapter,
-  isPersistentMachine,
-  makeInMemoryPersistenceAdapter,
-  PersistenceAdapterTag,
-  PersistenceError,
-  restorePersistentActor,
-  VersionConflictError,
-} from "./persistence/index.js";

package/src/inspection.ts

@@ -1,178 +0,0 @@
-import { Context, type Schema } from "effect";
-
-// ============================================================================
-// Type-level helpers
-// ============================================================================
-
-/**
- * Resolve a type param: if it's a Schema, extract `.Type`; otherwise use as-is.
- */
-type ResolveType<T> = T extends Schema.Schema<infer A, infer _I, infer _R> ? A : T;
-
-// ============================================================================
-// Inspection Events
-// ============================================================================
-
-/**
- * Event emitted when an actor is spawned
- */
-export interface SpawnEvent<S> {
-  readonly type: "@machine.spawn";
-  readonly actorId: string;
-  readonly initialState: S;
-  readonly timestamp: number;
-}
-
-/**
- * Event emitted when an actor receives an event
- */
-export interface EventReceivedEvent<S, E> {
-  readonly type: "@machine.event";
-  readonly actorId: string;
-  readonly state: S;
-  readonly event: E;
-  readonly timestamp: number;
-}
-
-/**
- * Event emitted when a transition occurs
- */
-export interface TransitionEvent<S, E> {
-  readonly type: "@machine.transition";
-  readonly actorId: string;
-  readonly fromState: S;
-  readonly toState: S;
-  readonly event: E;
-  readonly timestamp: number;
-}
-
-/**
- * Event emitted when a spawn effect runs
- */
-export interface EffectEvent<S> {
-  readonly type: "@machine.effect";
-  readonly actorId: string;
-  readonly effectType: "spawn";
-  readonly state: S;
-  readonly timestamp: number;
-}
-
-/**
- * Event emitted when a transition handler or spawn effect fails with a defect
- */
-export interface ErrorEvent<S, E> {
-  readonly type: "@machine.error";
-  readonly actorId: string;
-  readonly phase: "transition" | "spawn";
-  readonly state: S;
-  readonly event: E;
-  readonly error: string;
-  readonly timestamp: number;
-}
-
-/**
- * Event emitted when an actor stops
- */
-export interface StopEvent<S> {
-  readonly type: "@machine.stop";
-  readonly actorId: string;
-  readonly finalState: S;
-  readonly timestamp: number;
-}
-
-/**
- * Union of all inspection events
- */
-export type InspectionEvent<S, E> =
-  | SpawnEvent<S>
-  | EventReceivedEvent<S, E>
-  | TransitionEvent<S, E>
-  | EffectEvent<S>
-  | ErrorEvent<S, E>
-  | StopEvent<S>;
-
-/**
- * Convenience alias for untyped inspection events.
- * Useful for general-purpose inspectors that don't need specific state/event types.
- * State and event fields are typed as `{ readonly _tag: string }` so discriminated
- * access to `_tag` works without casting.
- */
-export type AnyInspectionEvent = InspectionEvent<
-  { readonly _tag: string },
-  { readonly _tag: string }
->;
-
-// ============================================================================
-// Inspector Service
-// ============================================================================
-
-/**
- * Inspector interface for observing machine behavior
- */
-export interface Inspector<S, E> {
-  readonly onInspect: (event: InspectionEvent<S, E>) => void;
-}
-
-/**
- * Inspector service tag - optional service for machine introspection
- * Uses `any` types to allow variance flexibility when providing the service
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const Inspector = Context.GenericTag<Inspector<any, any>>("@effect/machine/Inspector");
-
-/**
- * Create an inspector from a callback function.
- *
- * Type params accept either raw tagged types or Schema constructors:
- * - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
- * - `makeInspector<MyState, MyEvent>(cb)` — explicit tagged types
- * - `makeInspector<typeof MyState, typeof MyEvent>(cb)` — schema constructors (auto-extracts `.Type`)
- */
-export const makeInspector = <S = { readonly _tag: string }, E = { readonly _tag: string }>(
-  onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => void,
-): Inspector<ResolveType<S>, ResolveType<E>> => ({ onInspect });
-
-// ============================================================================
-// Built-in Inspectors
-// ============================================================================
-
-/**
- * Console inspector that logs events in a readable format
- */
-export const consoleInspector = (): Inspector<
-  { readonly _tag: string },
-  { readonly _tag: string }
-> =>
-  makeInspector((event) => {
-    const prefix = `[${event.actorId}]`;
-    switch (event.type) {
-      case "@machine.spawn":
-        console.log(prefix, "spawned →", event.initialState._tag);
-        break;
-      case "@machine.event":
-        console.log(prefix, "received", event.event._tag, "in", event.state._tag);
-        break;
-      case "@machine.transition":
-        console.log(prefix, event.fromState._tag, "→", event.toState._tag);
-        break;
-      case "@machine.effect":
-        console.log(prefix, event.effectType, "effect in", event.state._tag);
-        break;
-      case "@machine.error":
-        console.log(prefix, "error in", event.phase, event.state._tag, "-", event.error);
-        break;
-      case "@machine.stop":
-        console.log(prefix, "stopped in", event.finalState._tag);
-        break;
-    }
-  });
-
-/**
- * Collecting inspector that stores events in an array for testing
- */
-export const collectingInspector = <
-  S extends { readonly _tag: string },
-  E extends { readonly _tag: string },
->(
-  events: InspectionEvent<S, E>[],
-): Inspector<S, E> => ({ onInspect: (event) => events.push(event) });