effect-machine 0.3.1 → 0.4.0

package/README.md

@@ -183,6 +183,29 @@ machine.task(State.Loading, ({ effects, state }) => effects.fetchData({ url: sta
 });
 ```
 
+### Child Actors
+
+Spawn children from `.spawn()` handlers with `self.spawn`. Children are state-scoped — auto-stopped on state exit:
+
+```ts
+machine
+  .spawn(State.Active, ({ self }) =>
+    Effect.gen(function* () {
+      const child = yield* self.spawn("worker-1", workerMachine).pipe(Effect.orDie);
+      yield* child.send(WorkerEvent.Start);
+      // child auto-stopped when parent exits Active state
+    }),
+  )
+  .build();
+
+// Access children externally via actor.system
+const parent = yield * Machine.spawn(parentMachine);
+yield * parent.send(Event.Activate);
+const child = yield * parent.system.get("worker-1"); // Option<ActorRef>
+```
+
+Every actor always has a system — `Machine.spawn` creates an implicit one if no `ActorSystem` is in context.
+
 ### Testing
 
 Test transitions without actors:
@@ -273,6 +296,7 @@ See the [primer](./primer/) for comprehensive documentation:
 | `actor.awaitFinal`               | Wait final state                   |
 | `actor.sendAndWait(ev, State.X)` | Send + wait for state              |
 | `actor.subscribe(fn)`            | Sync callback                      |
+| `actor.system`                   | Access the actor's `ActorSystem`   |
 
 ## License
 

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };

package/dist/actor.d.ts

@@ -0,0 +1,256 @@
+import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { PersistentMachine } from "./persistence/persistent-machine.js";
+import { DuplicateActorError } from "./errors.js";
+import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
+import { PersistentActorRef } from "./persistence/persistent-actor.js";
+import { ActorMetadata, PersistenceAdapterTag, PersistenceError, RestoreResult, VersionConflictError } from "./persistence/adapter.js";
+import { BuiltMachine, Machine, MachineRef } from "./machine.js";
+import { Context, Effect, Layer, Option, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
+import * as effect_Tracer0 from "effect/Tracer";
+
+//#region src/actor.d.ts
+/**
+ * Reference to a running actor.
+ */
+interface ActorRef<State extends {
+  readonly _tag: string;
+}, Event> {
+  /**
+   * Unique identifier for this actor
+   */
+  readonly id: string;
+  /**
+   * Send an event to the actor
+   */
+  readonly send: (event: Event) => Effect.Effect<void>;
+  /**
+   * Observable state of the actor
+   */
+  readonly state: SubscriptionRef.SubscriptionRef<State>;
+  /**
+   * Stop the actor gracefully
+   */
+  readonly stop: Effect.Effect<void>;
+  /**
+   * Stop the actor (fire-and-forget).
+   * Signals graceful shutdown without waiting for completion.
+   * Use when stopping from sync contexts (e.g. framework cleanup hooks).
+   */
+  readonly stopSync: () => void;
+  /**
+   * Get current state snapshot (Effect)
+   */
+  readonly snapshot: Effect.Effect<State>;
+  /**
+   * Get current state snapshot (sync)
+   */
+  readonly snapshotSync: () => State;
+  /**
+   * Check if current state matches tag (Effect)
+   */
+  readonly matches: (tag: State["_tag"]) => Effect.Effect<boolean>;
+  /**
+   * Check if current state matches tag (sync)
+   */
+  readonly matchesSync: (tag: State["_tag"]) => boolean;
+  /**
+   * Check if event can be handled in current state (Effect)
+   */
+  readonly can: (event: Event) => Effect.Effect<boolean>;
+  /**
+   * Check if event can be handled in current state (sync)
+   */
+  readonly canSync: (event: Event) => boolean;
+  /**
+   * Stream of state changes
+   */
+  readonly changes: Stream.Stream<State>;
+  /**
+   * Wait for a state that matches predicate or state variant (includes current snapshot).
+   * Accepts a predicate function or a state constructor/value (e.g. `State.Active`).
+   */
+  readonly waitFor: {
+    (predicate: (state: State) => boolean): Effect.Effect<State>;
+    (state: {
+      readonly _tag: State["_tag"];
+    }): Effect.Effect<State>;
+  };
+  /**
+   * Wait for a final state (includes current snapshot)
+   */
+  readonly awaitFinal: Effect.Effect<State>;
+  /**
+   * Send event and wait for predicate, state variant, or final state.
+   * Accepts a predicate function or a state constructor/value (e.g. `State.Active`).
+   */
+  readonly sendAndWait: {
+    (event: Event, predicate: (state: State) => boolean): Effect.Effect<State>;
+    (event: Event, state: {
+      readonly _tag: State["_tag"];
+    }): Effect.Effect<State>;
+    (event: Event): Effect.Effect<State>;
+  };
+  /**
+   * Send event synchronously (fire-and-forget).
+   * No-op on stopped actors. Use when you need to send from sync contexts
+   * (e.g. framework hooks, event handlers).
+   */
+  readonly sendSync: (event: Event) => void;
+  /**
+   * Subscribe to state changes (sync callback)
+   * Returns unsubscribe function
+   */
+  readonly subscribe: (fn: (state: State) => void) => () => void;
+  /**
+   * The actor system this actor belongs to.
+   * Every actor always has a system — either inherited from context or implicitly created.
+   */
+  readonly system: ActorSystem;
+}
+/** Base type for stored actors (internal) */
+type AnyState = {
+  readonly _tag: string;
+};
+/**
+ * Actor system for managing actor lifecycles
+ */
+interface ActorSystem {
+  /**
+   * Spawn a new actor with the given machine.
+   *
+   * For regular machines, returns ActorRef.
+   * For persistent machines (created with Machine.persist), returns PersistentActorRef.
+   *
+   * All effect slots must be provided via `.build()` before spawning.
+   *
+   * @example
+   * ```ts
+   * // Regular machine (built)
+   * const built = machine.build({ fetchData: ... })
+   * const actor = yield* system.spawn("my-actor", built);
+   *
+   * // Persistent machine (auto-detected)
+   * const persistentActor = yield* system.spawn("my-actor", persistentMachine);
+   * persistentActor.persist; // available
+   * persistentActor.version; // available
+   * ```
+   */
+  readonly spawn: {
+    <S extends {
+      readonly _tag: string;
+    }, E extends {
+      readonly _tag: string;
+    }, R>(id: string, machine: BuiltMachine<S, E, R>): Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
+    <S extends {
+      readonly _tag: string;
+    }, E extends {
+      readonly _tag: string;
+    }, R>(id: string, machine: PersistentMachine<S, E, R>): Effect.Effect<PersistentActorRef<S, E, R>, PersistenceError | VersionConflictError | DuplicateActorError, R | PersistenceAdapterTag>;
+  };
+  /**
+   * Restore an actor from persistence.
+   * Returns None if no persisted state exists for the given ID.
+   *
+   * @example
+   * ```ts
+   * const maybeActor = yield* system.restore("order-1", persistentMachine);
+   * if (Option.isSome(maybeActor)) {
+   *   const actor = maybeActor.value;
+   *   const state = yield* actor.snapshot;
+   *   console.log(`Restored to state: ${state._tag}`);
+   * }
+   * ```
+   */
+  readonly restore: <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(id: string, machine: PersistentMachine<S, E, R>) => Effect.Effect<Option.Option<PersistentActorRef<S, E, R>>, PersistenceError | DuplicateActorError, R | PersistenceAdapterTag>;
+  /**
+   * Get an existing actor by ID
+   */
+  readonly get: (id: string) => Effect.Effect<Option.Option<ActorRef<AnyState, unknown>>>;
+  /**
+   * Stop an actor by ID
+   */
+  readonly stop: (id: string) => Effect.Effect<boolean>;
+  /**
+   * List all persisted actor metadata.
+   * Returns empty array if adapter doesn't support registry.
+   *
+   * @example
+   * ```ts
+   * const actors = yield* system.listPersisted();
+   * for (const meta of actors) {
+   *   console.log(`${meta.id}: ${meta.stateTag} (v${meta.version})`);
+   * }
+   * ```
+   */
+  readonly listPersisted: () => Effect.Effect<ReadonlyArray<ActorMetadata>, PersistenceError, PersistenceAdapterTag>;
+  /**
+   * Restore multiple actors by ID.
+   * Returns both successfully restored actors and failures.
+   *
+   * @example
+   * ```ts
+   * const result = yield* system.restoreMany(["order-1", "order-2"], orderMachine);
+   * console.log(`Restored: ${result.restored.length}, Failed: ${result.failed.length}`);
+   * ```
+   */
+  readonly restoreMany: <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(ids: ReadonlyArray<string>, machine: PersistentMachine<S, E, R>) => Effect.Effect<RestoreResult<S, E, R>, never, R | PersistenceAdapterTag>;
+  /**
+   * Restore all persisted actors for a machine type.
+   * Uses adapter registry if available, otherwise returns empty result.
+   *
+   * @example
+   * ```ts
+   * const result = yield* system.restoreAll(orderMachine, {
+   *   filter: (meta) => meta.stateTag !== "Done"
+   * });
+   * console.log(`Restored ${result.restored.length} active orders`);
+   * ```
+   */
+  readonly restoreAll: <S extends {
+    readonly _tag: string;
+  }, E extends {
+    readonly _tag: string;
+  }, R>(machine: PersistentMachine<S, E, R>, options?: {
+    filter?: (meta: ActorMetadata) => boolean;
+  }) => Effect.Effect<RestoreResult<S, E, R>, PersistenceError, R | PersistenceAdapterTag>;
+}
+/**
+ * ActorSystem service tag
+ */
+declare const ActorSystem: Context.Tag<ActorSystem, ActorSystem>;
+/** Listener set for sync subscriptions */
+type Listeners<S> = Set<(state: S) => void>;
+/**
+ * Notify all listeners of state change.
+ */
+declare const notifyListeners: <S>(listeners: Listeners<S>, state: S) => void;
+/**
+ * Build core ActorRef methods shared between regular and persistent actors.
+ */
+declare const buildActorRefCore: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueue: Queue.Queue<E>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem) => ActorRef<S, E>;
+/**
+ * Create and start an actor for a machine
+ */
+declare const createActor: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>) => Effect.Effect<ActorRef<S, E>, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, effect_Tracer0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_Tracer0.ParentSpan>>;
+/**
+ * Default ActorSystem layer
+ */
+declare const Default: Layer.Layer<ActorSystem, never, never>;
+//#endregion
+export { ActorRef, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects };