effect-machine 0.1.0

package/src/cluster/entity-machine.ts

@@ -0,0 +1,202 @@
+/**
+ * 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}`),
+   *   },
+   * })
+   * ```
+   */
+  readonly hooks?: ProcessEventHooks<S, E>;
+}
+
+/**
+ * Process a single event through the machine using shared core.
+ * Returns the new state after processing.
+ */
+const processEvent = <
+  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>,
+): Effect.Effect<S, never, R> =>
+  Effect.gen(function* () {
+    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> => {
+    return entity.toLayer(
+      Effect.gen(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: (event) => 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);
+
+        // Process internal events in background
+        yield* Effect.forkScoped(
+          Effect.forever(
+            Effect.gen(function* () {
+              const event = yield* Queue.take(internalQueue);
+              yield* processEvent(machine, stateRef, event, self, stateScopeRef, options?.hooks);
+            }),
+          ),
+        );
+
+        // 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]);
+      }),
+    ) as unknown as Layer.Layer<never, never, R>;
+  },
+};

package/src/cluster/index.ts

@@ -0,0 +1,43 @@
+/**
+ * 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

@@ -0,0 +1,99 @@
+/**
+ * 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

@@ -0,0 +1,64 @@
+/**
+ * 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.provide() 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

@@ -0,0 +1,102 @@
+// 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,
+  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 {
+  EffectEvent,
+  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

@@ -0,0 +1,132 @@
+import { Context } from "effect";
+
+// ============================================================================
+// 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 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>
+  | StopEvent<S>;
+
+// ============================================================================
+// 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
+ */
+export const makeInspector = <S, E>(
+  onInspect: (event: InspectionEvent<S, E>) => void,
+): Inspector<S, E> => ({ onInspect });
+
+// ============================================================================
+// Built-in Inspectors
+// ============================================================================
+
+/**
+ * Console inspector that logs events in a readable format
+ */
+export const consoleInspector = <
+  S extends { readonly _tag: string },
+  E extends { readonly _tag: string },
+>(): Inspector<S, E> =>
+  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.stop":
+        console.log(prefix, "stopped in", event.finalState._tag);
+        break;
+    }
+  });
+
+/**
+ * Collecting inspector that stores events in an array for testing
+ */
+export const collectingInspector = <S, E>(events: InspectionEvent<S, E>[]): Inspector<S, E> =>
+  makeInspector((event) => events.push(event));

package/src/internal/brands.ts

@@ -0,0 +1,51 @@
+// eslint-disable-next-line eslint-plugin-import/namespace -- false positive: Brand is a type namespace in effect
+import type { Brand } from "effect";
+
+// Unique symbols for type-level branding
+declare const StateTypeId: unique symbol;
+declare const EventTypeId: unique symbol;
+
+export type StateTypeId = typeof StateTypeId;
+export type EventTypeId = typeof EventTypeId;
+
+// Brand interfaces - eslint-disable-next-line comments for false positive namespace warnings
+// eslint-disable-next-line import/namespace
+export interface StateBrand extends Brand.Brand<StateTypeId> {}
+// eslint-disable-next-line import/namespace
+export interface EventBrand extends Brand.Brand<EventTypeId> {}
+
+// Shared branded type constraints used across all combinators
+export type BrandedState = { readonly _tag: string } & StateBrand;
+export type BrandedEvent = { readonly _tag: string } & EventBrand;
+
+// Unique symbols for schema-level branding (ties brand to specific schema definition)
+declare const SchemaIdTypeId: unique symbol;
+type SchemaIdTypeId = typeof SchemaIdTypeId;
+
+/**
+ * Brand that captures the schema definition type D.
+ * Two schemas with identical definition shapes will have compatible brands.
+ * Different definitions = incompatible brands.
+ */
+export interface SchemaIdBrand<
+  _D extends Record<string, unknown>,
+  // eslint-disable-next-line import/namespace
+> extends Brand.Brand<SchemaIdTypeId> {}
+
+/**
+ * Full state brand: combines base state brand with schema-specific brand
+ */
+export type FullStateBrand<D extends Record<string, unknown>> = StateBrand & SchemaIdBrand<D>;
+
+/**
+ * Full event brand: combines base event brand with schema-specific brand
+ */
+export type FullEventBrand<D extends Record<string, unknown>> = EventBrand & SchemaIdBrand<D>;
+
+/**
+ * Value or constructor for a tagged type.
+ * Accepts both plain values (empty structs) and constructor functions (non-empty structs).
+ */
+export type TaggedOrConstructor<T extends { readonly _tag: string }> =
+  | T
+  | ((...args: never[]) => T);