effect-machine 0.10.0 → 0.12.0

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

@@ -1,105 +0,0 @@
-import { EventBrand, StateBrand } from "../internal/brands.js";
-import { Machine } from "../machine.js";
-import { Schedule, Schema } from "effect";
-
-//#region src/persistence/persistent-machine.d.ts
-type BrandedState = {
-  readonly _tag: string;
-} & StateBrand;
-type BrandedEvent = {
-  readonly _tag: string;
-} & EventBrand;
-/**
- * Configuration for persistence behavior (after resolution).
- * Schemas are required at runtime - the persist function ensures this.
- *
- * Note: Schema types S and E should match the structural shape of the machine's
- * state and event types (without brands). The schemas don't know about brands.
- */
-interface PersistenceConfig<S, E> {
-  /**
-   * Schedule controlling when snapshots are taken.
-   * Input is the new state after each transition.
-   *
-   * Examples:
-   * - Schedule.forever — snapshot every transition
-   * - Schedule.spaced("5 seconds") — debounced snapshots
-   * - Schedule.recurs(100) — every N transitions
-   */
-  readonly snapshotSchedule: Schedule.Schedule<unknown, S>;
-  /**
-   * Whether to journal events for replay capability.
-   * When true, all events are appended to the event log.
-   */
-  readonly journalEvents: boolean;
-  /**
-   * Schema for serializing/deserializing state.
-   * Always present at runtime (resolved from config or machine).
-   */
-  readonly stateSchema: Schema.Codec<S, unknown, never, never>;
-  /**
-   * Schema for serializing/deserializing events.
-   * Always present at runtime (resolved from config or machine).
-   */
-  readonly eventSchema: Schema.Codec<E, unknown, never, never>;
-  /**
-   * User-provided identifier for the machine type.
-   * Used for filtering actors in restoreAll.
-   * Optional — defaults to "unknown" if not provided.
-   */
-  readonly machineType?: string;
-}
-/**
- * Machine with persistence configuration attached.
- * Spawn auto-detects this and returns PersistentActorRef.
- */
-interface PersistentMachine<S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R = never> {
-  readonly _tag: "PersistentMachine";
-  readonly machine: Machine<S, E, R>;
-  readonly persistence: PersistenceConfig<S, E>;
-}
-/**
- * Type guard to check if a value is a PersistentMachine
- */
-declare const isPersistentMachine: (value: unknown) => value is PersistentMachine<{
-  readonly _tag: string;
-}, {
-  readonly _tag: string;
-}, unknown>;
-/**
- * Attach persistence configuration to a machine.
- *
- * Schemas are read from the machine - must use `Machine.make({ state, event, initial })`.
- *
- * @example
- * ```ts
- * const orderMachine = Machine.make({
- *   state: OrderState,
- *   event: OrderEvent,
- *   initial: OrderState.Idle(),
- * }).pipe(
- *   Machine.on(OrderState.Idle, OrderEvent.Submit, ({ event }) =>
- *     OrderState.Pending({ orderId: event.orderId })
- *   ),
- *   Machine.final(OrderState.Paid),
- *   Machine.persist({
- *     snapshotSchedule: Schedule.forever,
- *     journalEvents: true,
- *   }),
- * );
- * ```
- */
-interface WithPersistenceConfig {
-  readonly snapshotSchedule: Schedule.Schedule<unknown, {
-    readonly _tag: string;
-  }>;
-  readonly journalEvents: boolean;
-  readonly machineType?: string;
-}
-declare const persist: (config: WithPersistenceConfig) => <S extends BrandedState, E extends BrandedEvent, R>(machine: Machine<S, E, R>) => PersistentMachine<S, E, R>;
-//#endregion
-export { PersistenceConfig, PersistentMachine, WithPersistenceConfig, isPersistentMachine, persist };

package/dist/persistence/persistent-machine.js

@@ -1,22 +0,0 @@
-import { MissingSchemaError } from "../errors.js";
-//#region src/persistence/persistent-machine.ts
-/**
-* Type guard to check if a value is a PersistentMachine
-*/
-const isPersistentMachine = (value) => typeof value === "object" && value !== null && "_tag" in value && value._tag === "PersistentMachine";
-const persist = (config) => (machine) => {
-	const stateSchema = machine.stateSchema;
-	const eventSchema = machine.eventSchema;
-	if (stateSchema === void 0 || eventSchema === void 0) throw new MissingSchemaError({ operation: "persist" });
-	return {
-		_tag: "PersistentMachine",
-		machine,
-		persistence: {
-			...config,
-			stateSchema,
-			eventSchema
-		}
-	};
-};
-//#endregion
-export { isPersistentMachine, persist };

package/v3/dist/persistence/adapter.d.ts

@@ -1,138 +0,0 @@
-import { DuplicateActorError } from "../errors.js";
-import { PersistentActorRef } from "./persistent-actor.js";
-import { Context, Effect, Option, Schema } from "effect";
-
-//#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, SI>(id: string, snapshot: Snapshot<S>, schema: Schema.Schema<S, SI, never>) => Effect.Effect<void, PersistenceError | VersionConflictError>;
-  /**
-   * Load the latest snapshot for an actor.
-   * Returns None if no snapshot exists.
-   */
-  readonly loadSnapshot: <S, SI>(id: string, schema: Schema.Schema<S, SI, never>) => Effect.Effect<Option.Option<Snapshot<S>>, PersistenceError>;
-  /**
-   * Append an event to the actor's event journal.
-   */
-  readonly appendEvent: <E, EI>(id: string, event: PersistedEvent<E>, schema: Schema.Schema<E, EI, never>) => Effect.Effect<void, PersistenceError>;
-  /**
-   * Load events from the journal, optionally after a specific version.
-   */
-  readonly loadEvents: <E, EI>(id: string, schema: Schema.Schema<E, EI, 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.TaggedErrorClass<PersistenceError, "PersistenceError", {
-  readonly _tag: Schema.tag<"PersistenceError">;
-} & {
-  operation: typeof Schema.String;
-  actorId: typeof Schema.String;
-  cause: Schema.optional<typeof Schema.Unknown>;
-  message: Schema.optional<typeof Schema.String>;
-}>;
-/**
- * Error type for persistence operations
- */
-declare class PersistenceError extends PersistenceError_base {}
-declare const VersionConflictError_base: Schema.TaggedErrorClass<VersionConflictError, "VersionConflictError", {
-  readonly _tag: Schema.tag<"VersionConflictError">;
-} & {
-  actorId: typeof Schema.String;
-  expectedVersion: typeof Schema.Number;
-  actualVersion: typeof Schema.Number;
-}>;
-/**
- * Version conflict error — snapshot version doesn't match expected
- */
-declare class VersionConflictError extends VersionConflictError_base {}
-declare const PersistenceAdapterTag_base: Context.TagClass<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/v3/dist/persistence/adapter.js

@@ -1,25 +0,0 @@
-import { Context, Schema } from "effect";
-//#region src/persistence/adapter.ts
-/**
-* Error type for persistence operations
-*/
-var PersistenceError = class extends Schema.TaggedError()("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.TaggedError()("VersionConflictError", {
-	actorId: Schema.String,
-	expectedVersion: Schema.Number,
-	actualVersion: Schema.Number
-}) {};
-/**
-* PersistenceAdapter service tag
-*/
-var PersistenceAdapterTag = class extends Context.Tag("effect-machine/src/persistence/adapter/PersistenceAdapterTag")() {};
-//#endregion
-export { PersistenceAdapterTag, PersistenceError, VersionConflictError };

package/v3/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/v3/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.encode(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.decode(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.encode(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.decode(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/v3/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/v3/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/v3/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 };