effect-machine 0.9.0 → 0.11.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "effect-machine",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
   },
   "files": [
     "dist",
-    "dist-v3"
+    "v3/dist"
   ],
   "type": "module",
   "exports": {
@@ -25,14 +25,14 @@
     },
     "./v3": {
       "import": {
-        "types": "./dist-v3/index.d.ts",
-        "default": "./dist-v3/index.js"
+        "types": "./v3/dist/index.d.ts",
+        "default": "./v3/dist/index.js"
       }
     },
     "./v3/cluster": {
       "import": {
-        "types": "./dist-v3/cluster/index.d.ts",
-        "default": "./dist-v3/cluster/index.js"
+        "types": "./v3/dist/cluster/index.d.ts",
+        "default": "./v3/dist/cluster/index.js"
       }
     }
   },
@@ -41,17 +41,18 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "typecheck:v3": "tsc --noEmit -p tsconfig.v3.json",
+    "typecheck:v3": "tsc --noEmit -p v3/tsconfig.json",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "test": "bun test",
+    "test:v3": "bun test --tsconfig-override=v3/tsconfig.json v3/test/",
     "test:watch": "bun test --watch",
     "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",
-    "build": "tsdown && tsdown --config tsdown.v3.config.ts",
+    "build": "tsdown && tsdown --config v3/tsdown.config.ts",
     "release": "bun run build && changeset publish"
   },
   "dependencies": {
@@ -63,7 +64,7 @@
     "@effect/language-service": "^0.82.0",
     "@types/bun": "1.3.11",
     "concurrently": "^9.2.1",
-    "effect-bun-test": "0.2.1",
+    "effect-bun-test": "0.3.0",
     "effect-v3": "npm:effect@^3.21.0",
     "lefthook": "^2.1.4",
     "oxfmt": "^0.41.0",

package/v3/dist/actor.d.ts

@@ -0,0 +1,210 @@
+import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
+import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
+import { BuiltMachine, Machine, MachineRef } from "./machine.js";
+import { Context, Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
+import * as effect_dist_dts_Tracer_js0 from "effect/dist/dts/Tracer.js";
+
+//#region src/actor.d.ts
+/** Discriminated mailbox request */
+type QueuedEvent<E> = {
+  readonly _tag: "send";
+  readonly event: E;
+} | {
+  readonly _tag: "call";
+  readonly event: E;
+  readonly reply: Deferred.Deferred<ProcessEventResult<{
+    readonly _tag: string;
+  }>, ActorStoppedError>;
+} | {
+  readonly _tag: "ask";
+  readonly event: E;
+  readonly reply: Deferred.Deferred<unknown, NoReplyError | ActorStoppedError>;
+};
+/**
+ * Reference to a running actor.
+ */
+/**
+ * Sync projection of ActorRef for non-Effect boundaries (React hooks, framework callbacks).
+ */
+interface ActorRefSync<State extends {
+  readonly _tag: string;
+}, Event> {
+  readonly send: (event: Event) => void;
+  readonly stop: () => void;
+  readonly snapshot: () => State;
+  readonly matches: (tag: State["_tag"]) => boolean;
+  readonly can: (event: Event) => boolean;
+}
+/**
+ * Information about a successful transition.
+ * Emitted on the `transitions` stream after each accepted event.
+ */
+interface TransitionInfo<State, Event> {
+  readonly fromState: State;
+  readonly toState: State;
+  readonly event: Event;
+}
+interface ActorRef<State extends {
+  readonly _tag: string;
+}, Event> {
+  readonly id: string;
+  /** Send an event (fire-and-forget). */
+  readonly send: (event: Event) => Effect.Effect<void>;
+  /** Fire-and-forget alias for send (OTP gen_server:cast). */
+  readonly cast: (event: Event) => Effect.Effect<void>;
+  /**
+   * Serialized request-reply (OTP gen_server:call).
+   * Event is processed through the queue; caller gets ProcessEventResult back.
+   */
+  readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State>>;
+  /**
+   * Typed request-reply. Event is processed through the queue; caller gets
+   * the domain value returned by the handler's `reply` field.
+   * Fails with NoReplyError if the handler doesn't provide a reply.
+   */
+  readonly ask: <R>(event: Event) => Effect.Effect<R, NoReplyError | ActorStoppedError>;
+  /** Observable state. */
+  readonly state: SubscriptionRef.SubscriptionRef<State>;
+  /** Stop the actor gracefully. */
+  readonly stop: Effect.Effect<void>;
+  /** Get current state snapshot. */
+  readonly snapshot: Effect.Effect<State>;
+  /** Check if current state matches tag. */
+  readonly matches: (tag: State["_tag"]) => Effect.Effect<boolean>;
+  /** Check if event can be handled in current state. */
+  readonly can: (event: Event) => Effect.Effect<boolean>;
+  /** Stream of state changes. */
+  readonly changes: Stream.Stream<State>;
+  /**
+   * Stream of accepted transitions (edge stream).
+   *
+   * Emits `{ fromState, toState, event }` on every successful transition,
+   * including same-state reenters. PubSub-backed — late subscribers miss
+   * past edges. This is observational, not a durability guarantee.
+   */
+  readonly transitions: Stream.Stream<TransitionInfo<State, Event>>;
+  /** Wait for a state matching predicate or variant (includes current snapshot). */
+  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. */
+  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>;
+  };
+  /** Subscribe to state changes (sync callback). Returns unsubscribe function. */
+  readonly subscribe: (fn: (state: State) => void) => () => void;
+  /** Sync helpers for non-Effect boundaries. */
+  readonly sync: ActorRefSync<State, Event>;
+  /** The actor system this actor belongs to. */
+  readonly system: ActorSystem;
+  /** Child actors spawned via `self.spawn` in this actor's handlers. */
+  readonly children: ReadonlyMap<string, ActorRef<AnyState, unknown>>;
+}
+/** Base type for stored actors (internal) */
+type AnyState = {
+  readonly _tag: string;
+};
+/**
+ * Events emitted by the ActorSystem when actors are spawned or stopped.
+ */
+type SystemEvent = {
+  readonly _tag: "ActorSpawned";
+  readonly id: string;
+  readonly actor: ActorRef<AnyState, unknown>;
+} | {
+  readonly _tag: "ActorStopped";
+  readonly id: string;
+  readonly actor: ActorRef<AnyState, unknown>;
+};
+/**
+ * Listener callback for system events.
+ */
+type SystemEventListener = (event: SystemEvent) => void;
+/**
+ * Actor system for managing actor lifecycles
+ */
+interface ActorSystem {
+  /**
+   * Spawn a new actor with the given machine.
+   *
+   * @example
+   * ```ts
+   * const built = machine.build({ fetchData: ... })
+   * const actor = yield* system.spawn("my-actor", built);
+   * ```
+   */
+  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>;
+  /**
+   * 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>;
+  /**
+   * Async stream of system events (actor spawned/stopped).
+   * Each subscriber gets their own queue — late subscribers miss prior events.
+   */
+  readonly events: Stream.Stream<SystemEvent>;
+  /**
+   * Sync snapshot of all currently registered actors.
+   * Returns a new Map on each access (not live).
+   */
+  readonly actors: ReadonlyMap<string, ActorRef<AnyState, unknown>>;
+  /**
+   * Subscribe to system events synchronously.
+   * Returns an unsubscribe function.
+   */
+  readonly subscribe: (fn: SystemEventListener) => () => void;
+}
+/**
+ * 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<QueuedEvent<E>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub?: PubSub.PubSub<TransitionInfo<S, E>>) => 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>, options?: {
+  initialState?: S;
+} | undefined) => Effect.Effect<ActorRef<S, E>, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, effect_dist_dts_Tracer_js0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_dist_dts_Tracer_js0.ParentSpan>>;
+/** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
+declare const settlePendingReplies: (pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, actorId: string) => Effect.Effect<void, never, never>;
+/**
+ * Default ActorSystem layer
+ */
+declare const Default: Layer.Layer<ActorSystem, never, never>;
+//#endregion
+export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };