effect-machine 0.11.0 → 0.12.0

package/dist/actor.d.ts

@@ -1,4 +1,5 @@
 import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { ExtractReply, ReplyTypeBrand } from "./internal/brands.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";
@@ -59,11 +60,11 @@ interface ActorRef<State extends {
    */
   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.
+   * Typed request-reply. Accepts only events with a reply schema
+   * (defined via `Event.reply()`). Return type is inferred from the schema.
    * Fails with NoReplyError if the handler doesn't provide a reply.
    */
-  readonly ask: <R>(event: Event) => Effect.Effect<R, NoReplyError | ActorStoppedError>;
+  readonly ask: <E extends Event & ReplyTypeBrand<unknown>>(event: E) => Effect.Effect<ExtractReply<E>, NoReplyError | ActorStoppedError>;
   /** Observable state. */
   readonly state: SubscriptionRef.SubscriptionRef<State>;
   /** Stop the actor gracefully. */
@@ -202,9 +203,14 @@ declare const createActor: <S extends {
 } | undefined) => 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>>;
 /** 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>;
+/**
+ * Create an ActorSystem instance. Must be run in a Scope.
+ * @internal — use Default layer for normal usage
+ */
+declare const makeSystem: () => Effect.Effect<ActorSystem, never, Scope.Scope>;
 /**
  * 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 };
+export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/dist/actor.js

@@ -3,7 +3,7 @@ import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { processEventCore, resolveTransition, runSpawnEffects, shouldPostpone } from "./internal/transition.js";
-import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
+import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Schema, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
@@ -163,6 +163,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const eventQueue = yield* Queue.unbounded();
 	const stoppedRef = yield* Ref.make(false);
 	const childrenMap = /* @__PURE__ */ new Map();
+	const deferredReplyRef = { current: void 0 };
 	const selfSend = Effect.fn("effect-machine.actor.self.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		yield* Queue.offer(eventQueue, {
@@ -181,6 +182,15 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 				childrenMap.delete(childId);
 			}));
 			return child;
+		}),
+		reply: (value) => Effect.sync(() => {
+			const deferred = deferredReplyRef.current;
+			if (deferred !== void 0) {
+				deferredReplyRef.current = void 0;
+				Effect.runFork(Deferred.succeed(deferred, value));
+				return true;
+			}
+			return false;
 		})
 	};
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
@@ -230,7 +240,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	}
 	const pendingReplies = /* @__PURE__ */ new Set();
 	const transitionsPubSub = yield* PubSub.unbounded();
-	const loopFiber = yield* Effect.forkDetach(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies, transitionsPubSub));
+	const loopFiber = yield* Effect.forkDetach(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies, transitionsPubSub, deferredReplyRef));
 	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -258,7 +268,7 @@ const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
 * Includes postpone buffer — events matching postpone rules are buffered
 * and drained after state tag changes (gen_statem semantics).
 */
-const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies, transitionsPubSub) {
+const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies, transitionsPubSub, deferredReplyRef) {
 	const postponed = [];
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const processQueued = Effect.fn("effect-machine.actor.processQueued")(function* (queued) {
@@ -274,6 +284,7 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 					lifecycleRan: false,
 					isFinal: false,
 					hasReply: false,
+					deferReply: false,
 					reply: void 0,
 					postponed: true
 				};
@@ -294,7 +305,19 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 				yield* Deferred.succeed(queued.reply, result);
 				break;
 			case "ask":
-				if (result.hasReply) yield* Deferred.succeed(queued.reply, result.reply);
+				if (result.hasReply) {
+					const replySchema = machine._replySchemas?.get(event._tag);
+					if (replySchema !== void 0) {
+						let decoded;
+						try {
+							decoded = Schema.decodeUnknownSync(replySchema)(result.reply);
+						} catch (decodeError) {
+							yield* Deferred.die(queued.reply, decodeError);
+							return yield* Effect.die(decodeError);
+						}
+						yield* Deferred.succeed(queued.reply, decoded);
+					} else yield* Deferred.succeed(queued.reply, result.reply);
+				} else if (result.deferReply) deferredReplyRef.current = queued.reply;
 				else yield* Deferred.fail(queued.reply, new NoReplyError({
 					actorId,
 					eventTag: event._tag
@@ -529,8 +552,13 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	});
 });
 /**
+* Create an ActorSystem instance. Must be run in a Scope.
+* @internal — use Default layer for normal usage
+*/
+const makeSystem = make;
+/**
 * Default ActorSystem layer
 */
 const Default = Layer.effect(ActorSystem, make());
 //#endregion
-export { ActorSystem, Default, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };
+export { ActorSystem, Default, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/dist/cluster/adapters/in-memory.d.ts

@@ -0,0 +1,28 @@
+import { PersistedEvent, PersistenceAdapter, Snapshot } from "../persistence.js";
+import { Effect, Layer, Ref } from "effect";
+
+//#region src/cluster/adapters/in-memory.d.ts
+interface EntityStore {
+  snapshot: Snapshot<unknown> | undefined;
+  events: Array<PersistedEvent<unknown>>;
+}
+/**
+ * Create an in-memory persistence adapter.
+ *
+ * Returns a Layer providing `PersistenceAdapter` and a ref
+ * to the backing store for test assertions.
+ *
+ * @example
+ * ```ts
+ * const { layer, storeRef } = yield* makeInMemoryPersistenceAdapter
+ * // Use layer to provide PersistenceAdapter
+ * // Inspect storeRef for test assertions
+ * ```
+ */
+declare const makeInMemoryPersistenceAdapter: Effect.Effect<{
+  adapter: PersistenceAdapter;
+  storeRef: Ref.Ref<Map<string, EntityStore>>;
+  layer: Layer.Layer<PersistenceAdapter, never, never>;
+}, never, never>;
+//#endregion
+export { makeInMemoryPersistenceAdapter };

package/dist/cluster/adapters/in-memory.js

@@ -0,0 +1,79 @@
+import { VersionConflictError } from "../../errors.js";
+import { PersistenceAdapter } from "../persistence.js";
+import { Effect, Layer, Option, Ref } from "effect";
+//#region src/cluster/adapters/in-memory.ts
+/**
+* In-memory persistence adapter for testing and development.
+*
+* Backed by a simple Map — state is lost on process exit.
+* Supports both snapshot and journal strategies with proper
+* version checking (CAS on appends, monotonic on snapshots).
+*
+* @module
+*/
+const makeKey = (key) => `${key.entityType}/${key.entityId}`;
+const getOrCreate = (store, key) => {
+	let entry = store.get(key);
+	if (entry === void 0) {
+		entry = {
+			snapshot: void 0,
+			events: []
+		};
+		store.set(key, entry);
+	}
+	return entry;
+};
+/**
+* Create an in-memory persistence adapter.
+*
+* Returns a Layer providing `PersistenceAdapter` and a ref
+* to the backing store for test assertions.
+*
+* @example
+* ```ts
+* const { layer, storeRef } = yield* makeInMemoryPersistenceAdapter
+* // Use layer to provide PersistenceAdapter
+* // Inspect storeRef for test assertions
+* ```
+*/
+const makeInMemoryPersistenceAdapter = Effect.gen(function* () {
+	const store = /* @__PURE__ */ new Map();
+	const storeRef = yield* Ref.make(store);
+	const adapter = {
+		saveSnapshot: (key, snapshot) => Effect.gen(function* () {
+			const entry = getOrCreate(yield* Ref.get(storeRef), makeKey(key));
+			if (entry.snapshot !== void 0 && snapshot.version < entry.snapshot.version) return yield* new VersionConflictError({
+				expected: snapshot.version,
+				actual: entry.snapshot.version
+			});
+			entry.snapshot = snapshot;
+		}),
+		loadSnapshot: (key) => Effect.gen(function* () {
+			const entry = (yield* Ref.get(storeRef)).get(makeKey(key));
+			return Option.fromNullishOr(entry?.snapshot);
+		}),
+		appendEvents: (key, events, expectedVersion) => Effect.gen(function* () {
+			const entry = getOrCreate(yield* Ref.get(storeRef), makeKey(key));
+			const lastEvent = entry.events[entry.events.length - 1];
+			const currentVersion = lastEvent !== void 0 ? lastEvent.version : 0;
+			if (currentVersion !== expectedVersion) return yield* new VersionConflictError({
+				expected: expectedVersion,
+				actual: currentVersion
+			});
+			for (const event of events) entry.events.push(event);
+		}),
+		loadEvents: (key, afterVersion) => Effect.gen(function* () {
+			const entry = (yield* Ref.get(storeRef)).get(makeKey(key));
+			if (entry === void 0) return [];
+			if (afterVersion === void 0) return entry.events;
+			return entry.events.filter((e) => e.version > afterVersion);
+		})
+	};
+	return {
+		adapter,
+		storeRef,
+		layer: Layer.succeed(PersistenceAdapter, adapter)
+	};
+});
+//#endregion
+export { makeInMemoryPersistenceAdapter };

package/dist/cluster/entity-actor-ref.d.ts

@@ -0,0 +1,56 @@
+import { ExtractReply, ReplyTypeBrand } from "../internal/brands.js";
+import { ActorStoppedError, NoReplyError } from "../errors.js";
+import { EntityRpcs } from "./to-entity.js";
+import { Effect, Stream } from "effect";
+import { RpcClient } from "effect/unstable/rpc";
+
+//#region src/cluster/entity-actor-ref.d.ts
+/**
+ * Typed client wrapper for remote entity machines.
+ *
+ * Unlike local `ActorRef`, this communicates over cluster RPCs.
+ * Only operations that make sense over the network are exposed.
+ *
+ * @example
+ * ```ts
+ * const ref = makeEntityActorRef(client, "order-123")
+ * yield* ref.send(OrderEvent.Ship({ trackingId: "abc" }))
+ * const state = yield* ref.snapshot
+ * yield* ref.waitFor((s) => s._tag === "Shipped")
+ * ```
+ */
+interface EntityActorRef<State extends {
+  readonly _tag: string;
+}, Event extends {
+  readonly _tag: string;
+}> {
+  readonly entityId: string;
+  /** Send event. Returns new state after processing. */
+  readonly send: (event: Event) => Effect.Effect<State>;
+  /** Send event and get typed domain reply (via Event.reply() schema). */
+  readonly ask: <E extends Event & ReplyTypeBrand<unknown>>(event: E) => Effect.Effect<ExtractReply<E>, NoReplyError>;
+  /** Get current state. */
+  readonly snapshot: Effect.Effect<State>;
+  /** Stream of state changes (via WatchState streaming RPC). */
+  readonly watch: Stream.Stream<State>;
+  /** Wait for a state matching the predicate. Snapshots first, then watches stream. */
+  readonly waitFor: (predicate: (state: State) => boolean) => Effect.Effect<State, ActorStoppedError>;
+}
+/**
+ * Create an EntityActorRef from a RPC client.
+ *
+ * @example
+ * ```ts
+ * const makeClient = yield* Entity.makeTestClient(entity, entityLayer)
+ * const client = yield* makeClient("order-123")
+ * const ref = makeEntityActorRef(client, "order-123")
+ * yield* ref.send(OrderEvent.Process)
+ * ```
+ */
+declare const makeEntityActorRef: <State extends {
+  readonly _tag: string;
+}, Event extends {
+  readonly _tag: string;
+}, Rpcs extends EntityRpcs<any, any>[number]>(client: RpcClient.RpcClient<Rpcs>, entityId: string) => EntityActorRef<State, Event>;
+//#endregion
+export { EntityActorRef, makeEntityActorRef };

package/dist/cluster/entity-actor-ref.js

@@ -0,0 +1,33 @@
+import { ActorStoppedError } from "../errors.js";
+import { Effect, Option, Stream } from "effect";
+//#region src/cluster/entity-actor-ref.ts
+/**
+* Create an EntityActorRef from a RPC client.
+*
+* @example
+* ```ts
+* const makeClient = yield* Entity.makeTestClient(entity, entityLayer)
+* const client = yield* makeClient("order-123")
+* const ref = makeEntityActorRef(client, "order-123")
+* yield* ref.send(OrderEvent.Process)
+* ```
+*/
+const makeEntityActorRef = (client, entityId) => {
+	const c = client;
+	return {
+		entityId,
+		send: (event) => c.Send({ event }),
+		ask: ((event) => c.Ask({ event })),
+		snapshot: c.GetState(),
+		watch: c.WatchState(),
+		waitFor: (predicate) => Effect.gen(function* () {
+			const current = yield* c.GetState();
+			if (predicate(current)) return current;
+			const result = yield* c.WatchState().pipe(Stream.filter(predicate), Stream.take(1), Stream.runHead);
+			if (Option.isSome(result)) return result.value;
+			return yield* new ActorStoppedError({ actorId: entityId });
+		})
+	};
+};
+//#endregion
+export { makeEntityActorRef };

package/dist/cluster/entity-machine.d.ts

@@ -1,7 +1,7 @@
-import { EffectsDef, GuardsDef } from "../slot.js";
 import { ProcessEventHooks } from "../internal/transition.js";
 import { Machine } from "../machine.js";
-import { Layer } from "effect";
+import { EntityPersistenceConfig } from "./persistence.js";
+import { Duration, Layer, Schedule } from "effect";
 import { Entity } from "effect/unstable/cluster";
 import { Rpc } from "effect/unstable/rpc";
 
@@ -13,77 +13,59 @@ 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>;
+  /**
+   * Maximum idle time before entity deactivation.
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly maxIdleTime?: Duration.Input;
+  /**
+   * Mailbox capacity. Default: "unbounded".
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly mailboxCapacity?: number | "unbounded";
+  /**
+   * Disable fatal defects (defects won't crash the entity activation).
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly disableFatalDefects?: boolean;
+  /**
+   * Retry policy for defects (schedule for restarting after defect).
+   * Forwarded to Entity.toLayerQueue.
+   */
+  readonly defectRetryPolicy?: Schedule.Schedule<any, unknown>;
+  /**
+   * Persistence configuration. When set, requires PersistenceAdapter in R.
+   */
+  readonly persistence?: EntityPersistenceConfig;
 }
 /**
  * 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
+ * Uses `Entity.toLayerQueue` for a single serialized mailbox per entity.
+ * The runtime kernel handles event processing, postpone, background effects,
+ * spawn effects, and final state detection.
  *
  * @example
  * ```ts
- * const OrderEntity = toEntity(orderMachine, {
- *   type: "Order",
- *   stateSchema: OrderState,
- *   eventSchema: OrderEvent,
- * })
+ * const OrderEntity = toEntity(orderMachine, { type: "Order" })
  *
  * 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" }) })
- * })
  * ```
  */
 declare 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>;
+  }, R, EntityType extends string, Rpcs extends Rpc.Any>(entity: Entity.Entity<EntityType, Rpcs>, machine: Machine<S, E, R, any, any, any, any>, options?: EntityMachineOptions<S, E>) => Layer.Layer<never, never, R>;
 };
 //#endregion
 export { EntityMachine, EntityMachineOptions };