effect-machine 0.9.0 → 0.11.0

package/{dist-v3 → v3/dist}/testing.js

@@ -1,9 +1,9 @@
 import { stubSystem } from "./internal/utils.js";
 import { AssertionError } from "./errors.js";
 import { BuiltMachine } from "./machine.js";
-import { executeTransition } from "./internal/transition.js";
+import { executeTransition, shouldPostpone } from "./internal/transition.js";
 import { Effect, SubscriptionRef } from "effect";
-//#region src-v3/testing.ts
+//#region src/testing.ts
 /**
 * Simulate a sequence of events through a machine without running an actor.
 * Useful for testing state transitions in isolation.
@@ -26,18 +26,44 @@ import { Effect, SubscriptionRef } from "effect";
 */
 const simulate = Effect.fn("effect-machine.simulate")(function* (input, events) {
 	const machine = input instanceof BuiltMachine ? input._inner : input;
+	const dummySend = Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void);
 	const dummySelf = {
-		send: Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void),
+		send: dummySend,
+		cast: dummySend,
 		spawn: () => Effect.die("spawn not supported in simulation")
 	};
 	let currentState = machine.initial;
 	const states = [currentState];
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const postponed = [];
 	for (const event of events) {
-		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
+		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+			postponed.push(event);
+			continue;
+		}
+		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "simulation");
 		if (!result.transitioned) continue;
+		const prevTag = currentState._tag;
 		currentState = result.newState;
 		states.push(currentState);
 		if (machine.finalStates.has(currentState._tag)) break;
+		let drainTag = prevTag;
+		while (currentState._tag !== drainTag && postponed.length > 0) {
+			drainTag = currentState._tag;
+			const drained = postponed.splice(0);
+			for (const postponedEvent of drained) {
+				if (shouldPostpone(machine, currentState._tag, postponedEvent._tag)) {
+					postponed.push(postponedEvent);
+					continue;
+				}
+				const drainResult = yield* executeTransition(machine, currentState, postponedEvent, dummySelf, stubSystem, "simulation");
+				if (drainResult.transitioned) {
+					currentState = drainResult.newState;
+					states.push(currentState);
+					if (machine.finalStates.has(currentState._tag)) break;
+				}
+			}
+		}
 	}
 	return {
 		states,
@@ -113,20 +139,48 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 */
 const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
 	const machine = input instanceof BuiltMachine ? input._inner : input;
+	const dummySend = Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void);
 	const dummySelf = {
-		send: Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void),
+		send: dummySend,
+		cast: dummySend,
 		spawn: () => Effect.die("spawn not supported in test harness")
 	};
 	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const postponed = [];
 	return {
 		state: stateRef,
 		send: Effect.fn("effect-machine.testHarness.send")(function* (event) {
 			const currentState = yield* SubscriptionRef.get(stateRef);
-			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
+			if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+				postponed.push(event);
+				return currentState;
+			}
+			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem, "test-harness");
 			if (!result.transitioned) return currentState;
+			const prevTag = currentState._tag;
 			const newState = result.newState;
 			yield* SubscriptionRef.set(stateRef, newState);
 			if (options?.onTransition !== void 0) options.onTransition(currentState, event, newState);
+			let drainTag = prevTag;
+			let currentTag = newState._tag;
+			while (currentTag !== drainTag && postponed.length > 0) {
+				drainTag = currentTag;
+				const drained = postponed.splice(0);
+				for (const postponedEvent of drained) {
+					const state = yield* SubscriptionRef.get(stateRef);
+					if (shouldPostpone(machine, state._tag, postponedEvent._tag)) {
+						postponed.push(postponedEvent);
+						continue;
+					}
+					const drainResult = yield* executeTransition(machine, state, postponedEvent, dummySelf, stubSystem, "test-harness");
+					if (drainResult.transitioned) {
+						yield* SubscriptionRef.set(stateRef, drainResult.newState);
+						currentTag = drainResult.newState._tag;
+						if (options?.onTransition !== void 0) options.onTransition(state, postponedEvent, drainResult.newState);
+					}
+				}
+			}
 			return newState;
 		}),
 		getState: SubscriptionRef.get(stateRef)

package/dist/persistence/adapter.d.ts

@@ -1,135 +0,0 @@
-import { DuplicateActorError } from "../errors.js";
-import { PersistentActorRef } from "./persistent-actor.js";
-import { Effect, Option, Schema, ServiceMap } from "effect";
-import * as effect_Cause0 from "effect/Cause";
-
-//#region src/persistence/adapter.d.ts
-/**
- * Metadata for a persisted actor.
- * Used for discovery and filtering during bulk restore.
- */
-interface ActorMetadata {
-  readonly id: string;
-  /** User-provided identifier for the machine type */
-  readonly machineType: string;
-  readonly createdAt: number;
-  readonly lastActivityAt: number;
-  readonly version: number;
-  /** Current state _tag value */
-  readonly stateTag: string;
-}
-/**
- * Result of a bulk restore operation.
- * Contains both successfully restored actors and failures.
- */
-interface RestoreResult<S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R = never> {
-  readonly restored: ReadonlyArray<PersistentActorRef<S, E, R>>;
-  readonly failed: ReadonlyArray<RestoreFailure>;
-}
-/**
- * A single restore failure with actor ID and error details.
- */
-interface RestoreFailure {
-  readonly id: string;
-  readonly error: PersistenceError | DuplicateActorError;
-}
-/**
- * Snapshot of actor state at a point in time
- */
-interface Snapshot<S> {
-  readonly state: S;
-  readonly version: number;
-  readonly timestamp: number;
-}
-/**
- * Persisted event with metadata
- */
-interface PersistedEvent<E> {
-  readonly event: E;
-  readonly version: number;
-  readonly timestamp: number;
-}
-/**
- * Adapter for persisting actor state and events.
- *
- * Implementations handle serialization and storage of snapshots and event journals.
- * Schema parameters ensure type-safe serialization/deserialization.
- * Schemas must have no context requirements (use Schema<S, SI, never>).
- */
-interface PersistenceAdapter {
-  /**
-   * Save a snapshot of actor state.
-   * Implementations should use optimistic locking — fail if version mismatch.
-   */
-  readonly saveSnapshot: <S>(id: string, snapshot: Snapshot<S>, schema: Schema.Codec<S, unknown, never, never>) => Effect.Effect<void, PersistenceError | VersionConflictError>;
-  /**
-   * Load the latest snapshot for an actor.
-   * Returns None if no snapshot exists.
-   */
-  readonly loadSnapshot: <S>(id: string, schema: Schema.Codec<S, unknown, never, never>) => Effect.Effect<Option.Option<Snapshot<S>>, PersistenceError>;
-  /**
-   * Append an event to the actor's event journal.
-   */
-  readonly appendEvent: <E>(id: string, event: PersistedEvent<E>, schema: Schema.Codec<E, unknown, never, never>) => Effect.Effect<void, PersistenceError>;
-  /**
-   * Load events from the journal, optionally after a specific version.
-   */
-  readonly loadEvents: <E>(id: string, schema: Schema.Codec<E, unknown, never, never>, afterVersion?: number) => Effect.Effect<ReadonlyArray<PersistedEvent<E>>, PersistenceError>;
-  /**
-   * Delete all persisted data for an actor (snapshot + events).
-   */
-  readonly deleteActor: (id: string) => Effect.Effect<void, PersistenceError>;
-  /**
-   * List all persisted actor metadata.
-   * Optional — adapters without registry support can omit this.
-   */
-  readonly listActors?: () => Effect.Effect<ReadonlyArray<ActorMetadata>, PersistenceError>;
-  /**
-   * Save or update actor metadata.
-   * Called on spawn and state transitions.
-   * Optional — adapters without registry support can omit this.
-   */
-  readonly saveMetadata?: (metadata: ActorMetadata) => Effect.Effect<void, PersistenceError>;
-  /**
-   * Delete actor metadata.
-   * Called when actor is deleted.
-   * Optional — adapters without registry support can omit this.
-   */
-  readonly deleteMetadata?: (id: string) => Effect.Effect<void, PersistenceError>;
-  /**
-   * Load metadata for a specific actor by ID.
-   * Returns None if no metadata exists.
-   * Optional — adapters without registry support can omit this.
-   */
-  readonly loadMetadata?: (id: string) => Effect.Effect<Option.Option<ActorMetadata>, PersistenceError>;
-}
-declare const PersistenceError_base: Schema.ErrorClass<PersistenceError, Schema.TaggedStruct<"PersistenceError", {
-  readonly operation: Schema.String;
-  readonly actorId: Schema.String;
-  readonly cause: Schema.optional<Schema.Unknown>;
-  readonly message: Schema.optional<Schema.String>;
-}>, effect_Cause0.YieldableError>;
-/**
- * Error type for persistence operations
- */
-declare class PersistenceError extends PersistenceError_base {}
-declare const VersionConflictError_base: Schema.ErrorClass<VersionConflictError, Schema.TaggedStruct<"VersionConflictError", {
-  readonly actorId: Schema.String;
-  readonly expectedVersion: Schema.Number;
-  readonly actualVersion: Schema.Number;
-}>, effect_Cause0.YieldableError>;
-/**
- * Version conflict error — snapshot version doesn't match expected
- */
-declare class VersionConflictError extends VersionConflictError_base {}
-declare const PersistenceAdapterTag_base: ServiceMap.ServiceClass<PersistenceAdapterTag, "effect-machine/src/persistence/adapter/PersistenceAdapterTag", PersistenceAdapter>;
-/**
- * PersistenceAdapter service tag
- */
-declare class PersistenceAdapterTag extends PersistenceAdapterTag_base {}
-//#endregion
-export { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError };

package/dist/persistence/adapter.js

@@ -1,25 +0,0 @@
-import { Schema, ServiceMap } from "effect";
-//#region src/persistence/adapter.ts
-/**
-* Error type for persistence operations
-*/
-var PersistenceError = class extends Schema.TaggedErrorClass()("PersistenceError", {
-	operation: Schema.String,
-	actorId: Schema.String,
-	cause: Schema.optional(Schema.Unknown),
-	message: Schema.optional(Schema.String)
-}) {};
-/**
-* Version conflict error — snapshot version doesn't match expected
-*/
-var VersionConflictError = class extends Schema.TaggedErrorClass()("VersionConflictError", {
-	actorId: Schema.String,
-	expectedVersion: Schema.Number,
-	actualVersion: Schema.Number
-}) {};
-/**
-* PersistenceAdapter service tag
-*/
-var PersistenceAdapterTag = class extends ServiceMap.Service()("effect-machine/src/persistence/adapter/PersistenceAdapterTag") {};
-//#endregion
-export { PersistenceAdapterTag, PersistenceError, VersionConflictError };

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

@@ -1,32 +0,0 @@
-import { PersistenceAdapter, PersistenceAdapterTag } from "../adapter.js";
-import { Effect, Layer } from "effect";
-
-//#region src/persistence/adapters/in-memory.d.ts
-/**
- * Create an in-memory persistence adapter effect.
- * Returns the adapter directly for custom layer composition.
- */
-declare const makeInMemoryPersistenceAdapter: Effect.Effect<PersistenceAdapter, never, never>;
-/**
- * In-memory persistence adapter layer.
- * Data is not persisted across process restarts.
- *
- * NOTE: Each `Effect.provide(InMemoryPersistenceAdapter)` creates a NEW adapter
- * with empty storage. For tests that need persistent storage across multiple
- * runPromise calls, use `makeInMemoryPersistenceAdapter` with a shared scope.
- *
- * @example
- * ```ts
- * const program = Effect.gen(function* () {
- *   const system = yield* ActorSystemService;
- *   const actor = yield* system.spawn("my-actor", persistentMachine);
- *   // ...
- * }).pipe(
- *   Effect.provide(InMemoryPersistenceAdapter),
- *   Effect.provide(ActorSystemDefault),
- * );
- * ```
- */
-declare const InMemoryPersistenceAdapter: Layer.Layer<PersistenceAdapterTag>;
-//#endregion
-export { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter };

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

@@ -1,174 +0,0 @@
-import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "../adapter.js";
-import { Effect, Layer, Option, Ref, Schema } from "effect";
-//#region src/persistence/adapters/in-memory.ts
-/**
-* Create an in-memory persistence adapter.
-* Useful for testing and development.
-*/
-const make = Effect.gen(function* () {
-	const storage = yield* Ref.make(/* @__PURE__ */ new Map());
-	const registry = yield* Ref.make(/* @__PURE__ */ new Map());
-	const getOrCreateStorage = Effect.fn("effect-machine.persistence.inMemory.getOrCreateStorage")(function* (id) {
-		return yield* Ref.modify(storage, (map) => {
-			const existing = map.get(id);
-			if (existing !== void 0) return [existing, map];
-			const newStorage = {
-				snapshot: Option.none(),
-				events: []
-			};
-			const newMap = new Map(map);
-			newMap.set(id, newStorage);
-			return [newStorage, newMap];
-		});
-	});
-	const updateStorage = Effect.fn("effect-machine.persistence.inMemory.updateStorage")(function* (id, update) {
-		yield* Ref.update(storage, (map) => {
-			const existing = map.get(id);
-			if (existing === void 0) return map;
-			const newMap = new Map(map);
-			newMap.set(id, update(existing));
-			return newMap;
-		});
-	});
-	return {
-		saveSnapshot: Effect.fn("effect-machine.persistence.inMemory.saveSnapshot")(function* (id, snapshot, schema) {
-			const actorStorage = yield* getOrCreateStorage(id);
-			if (Option.isSome(actorStorage.snapshot)) {
-				const existingVersion = actorStorage.snapshot.value.version;
-				if (snapshot.version < existingVersion) return yield* new VersionConflictError({
-					actorId: id,
-					expectedVersion: existingVersion,
-					actualVersion: snapshot.version
-				});
-			}
-			const encoded = yield* Schema.encodeEffect(schema)(snapshot.state).pipe(Effect.mapError((cause) => new PersistenceError({
-				operation: "saveSnapshot",
-				actorId: id,
-				cause,
-				message: "Failed to encode state"
-			})));
-			yield* updateStorage(id, (s) => ({
-				...s,
-				snapshot: Option.some({
-					data: encoded,
-					version: snapshot.version,
-					timestamp: snapshot.timestamp
-				})
-			}));
-		}),
-		loadSnapshot: Effect.fn("effect-machine.persistence.inMemory.loadSnapshot")(function* (id, schema) {
-			const actorStorage = yield* getOrCreateStorage(id);
-			if (Option.isNone(actorStorage.snapshot)) return Option.none();
-			const stored = actorStorage.snapshot.value;
-			const decoded = yield* Schema.decodeEffect(schema)(stored.data).pipe(Effect.mapError((cause) => new PersistenceError({
-				operation: "loadSnapshot",
-				actorId: id,
-				cause,
-				message: "Failed to decode state"
-			})));
-			return Option.some({
-				state: decoded,
-				version: stored.version,
-				timestamp: stored.timestamp
-			});
-		}),
-		appendEvent: Effect.fn("effect-machine.persistence.inMemory.appendEvent")(function* (id, event, schema) {
-			yield* getOrCreateStorage(id);
-			const encoded = yield* Schema.encodeEffect(schema)(event.event).pipe(Effect.mapError((cause) => new PersistenceError({
-				operation: "appendEvent",
-				actorId: id,
-				cause,
-				message: "Failed to encode event"
-			})));
-			yield* updateStorage(id, (s) => ({
-				...s,
-				events: [...s.events, {
-					data: encoded,
-					version: event.version,
-					timestamp: event.timestamp
-				}]
-			}));
-		}),
-		loadEvents: Effect.fn("effect-machine.persistence.inMemory.loadEvents")(function* (id, schema, afterVersion) {
-			const actorStorage = yield* getOrCreateStorage(id);
-			const decoded = [];
-			for (const stored of actorStorage.events) {
-				if (afterVersion !== void 0 && stored.version <= afterVersion) continue;
-				const event = yield* Schema.decodeEffect(schema)(stored.data).pipe(Effect.mapError((cause) => new PersistenceError({
-					operation: "loadEvents",
-					actorId: id,
-					cause,
-					message: "Failed to decode event"
-				})));
-				decoded.push({
-					event,
-					version: stored.version,
-					timestamp: stored.timestamp
-				});
-			}
-			return decoded;
-		}),
-		deleteActor: Effect.fn("effect-machine.persistence.inMemory.deleteActor")(function* (id) {
-			yield* Ref.update(storage, (map) => {
-				const newMap = new Map(map);
-				newMap.delete(id);
-				return newMap;
-			});
-			yield* Ref.update(registry, (map) => {
-				const newMap = new Map(map);
-				newMap.delete(id);
-				return newMap;
-			});
-		}),
-		listActors: Effect.fn("effect-machine.persistence.inMemory.listActors")(function* () {
-			const map = yield* Ref.get(registry);
-			return Array.from(map.values());
-		}),
-		saveMetadata: Effect.fn("effect-machine.persistence.inMemory.saveMetadata")(function* (metadata) {
-			yield* Ref.update(registry, (map) => {
-				const newMap = new Map(map);
-				newMap.set(metadata.id, metadata);
-				return newMap;
-			});
-		}),
-		deleteMetadata: Effect.fn("effect-machine.persistence.inMemory.deleteMetadata")(function* (id) {
-			yield* Ref.update(registry, (map) => {
-				const newMap = new Map(map);
-				newMap.delete(id);
-				return newMap;
-			});
-		}),
-		loadMetadata: Effect.fn("effect-machine.persistence.inMemory.loadMetadata")(function* (id) {
-			const meta = (yield* Ref.get(registry)).get(id);
-			return meta !== void 0 ? Option.some(meta) : Option.none();
-		})
-	};
-}).pipe(Effect.withSpan("effect-machine.persistence.inMemory.make"));
-/**
-* Create an in-memory persistence adapter effect.
-* Returns the adapter directly for custom layer composition.
-*/
-const makeInMemoryPersistenceAdapter = make;
-/**
-* In-memory persistence adapter layer.
-* Data is not persisted across process restarts.
-*
-* NOTE: Each `Effect.provide(InMemoryPersistenceAdapter)` creates a NEW adapter
-* with empty storage. For tests that need persistent storage across multiple
-* runPromise calls, use `makeInMemoryPersistenceAdapter` with a shared scope.
-*
-* @example
-* ```ts
-* const program = Effect.gen(function* () {
-*   const system = yield* ActorSystemService;
-*   const actor = yield* system.spawn("my-actor", persistentMachine);
-*   // ...
-* }).pipe(
-*   Effect.provide(InMemoryPersistenceAdapter),
-*   Effect.provide(ActorSystemDefault),
-* );
-* ```
-*/
-const InMemoryPersistenceAdapter = Layer.effect(PersistenceAdapterTag, make);
-//#endregion
-export { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter };

package/dist/persistence/index.d.ts

@@ -1,5 +0,0 @@
-import { PersistenceConfig, PersistentMachine, isPersistentMachine, persist } from "./persistent-machine.js";
-import { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistent-actor.js";
-import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./adapter.js";
-import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./adapters/in-memory.js";
-export { type ActorMetadata, InMemoryPersistenceAdapter, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type RestoreFailure, type RestoreResult, type Snapshot, VersionConflictError, createPersistentActor, isPersistentMachine, makeInMemoryPersistenceAdapter, persist, restorePersistentActor };

package/dist/persistence/index.js

@@ -1,5 +0,0 @@
-import { isPersistentMachine, persist } from "./persistent-machine.js";
-import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "./adapter.js";
-import { createPersistentActor, restorePersistentActor } from "./persistent-actor.js";
-import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./adapters/in-memory.js";
-export { InMemoryPersistenceAdapter, PersistenceAdapterTag, PersistenceError, VersionConflictError, createPersistentActor, isPersistentMachine, makeInMemoryPersistenceAdapter, persist, restorePersistentActor };

package/dist/persistence/persistent-actor.d.ts

@@ -1,50 +0,0 @@
-import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
-import { PersistentMachine } from "./persistent-machine.js";
-import { PersistedEvent, PersistenceAdapterTag, PersistenceError, Snapshot, VersionConflictError } from "./adapter.js";
-import { MachineRef } from "../machine.js";
-import { ActorRef } from "../actor.js";
-import { Effect, Option, Scope } from "effect";
-
-//#region src/persistence/persistent-actor.d.ts
-/**
- * Extended ActorRef with persistence capabilities
- */
-interface PersistentActorRef<S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R = never> extends ActorRef<S, E> {
-  /**
-   * Force an immediate snapshot save
-   */
-  readonly persist: Effect.Effect<void, PersistenceError | VersionConflictError>;
-  /**
-   * Get the current persistence version
-   */
-  readonly version: Effect.Effect<number>;
-  /**
-   * Replay events to restore actor to a specific version.
-   * Note: This only computes state; does not re-run transition effects.
-   */
-  readonly replayTo: (version: number) => Effect.Effect<void, PersistenceError, R>;
-}
-/**
- * Create a persistent actor from a PersistentMachine.
- * Restores from existing snapshot if available, otherwise starts fresh.
- */
-declare const createPersistentActor: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(id: string, persistentMachine: PersistentMachine<S, E, R>, initialSnapshot: Option.Option<Snapshot<S>>, initialEvents: readonly PersistedEvent<E>[]) => Effect.Effect<PersistentActorRef<S, E, R>, PersistenceError, PersistenceAdapterTag | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
-/**
- * Restore an actor from persistence.
- * Returns None if no persisted state exists.
- */
-declare const restorePersistentActor: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R>(id: string, persistentMachine: PersistentMachine<S, E, R>) => Effect.Effect<Option.None<PersistentActorRef<S, E, R>> | Option.Some<PersistentActorRef<S, E, R>>, PersistenceError, PersistenceAdapterTag | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
-//#endregion
-export { PersistentActorRef, createPersistentActor, restorePersistentActor };