effect-machine 0.3.1 → 0.3.2

package/{src/persistence/adapter.ts → dist/persistence/adapter.d.ts}

@@ -1,14 +1,13 @@
-import { Context, Schema } from "effect";
-import type { Effect, Option } from "effect";
-
-import type { PersistentActorRef } from "./persistent-actor.js";
-import type { DuplicateActorError } from "../errors.js";
+import { PersistentActorRef } from "./persistent-actor.js";
+import { DuplicateActorError } from "../errors.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.
  */
-export interface ActorMetadata {
+interface ActorMetadata {
   readonly id: string;
   /** User-provided identifier for the machine type */
   readonly machineType: string;
@@ -18,46 +17,41 @@ export interface ActorMetadata {
   /** Current state _tag value */
   readonly stateTag: string;
 }
-
 /**
  * Result of a bulk restore operation.
  * Contains both successfully restored actors and failures.
  */
-export interface RestoreResult<
-  S extends { readonly _tag: string },
-  E extends { readonly _tag: string },
-  R = never,
-> {
+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.
  */
-export interface RestoreFailure {
+interface RestoreFailure {
   readonly id: string;
   readonly error: PersistenceError | DuplicateActorError;
 }
-
 /**
  * Snapshot of actor state at a point in time
  */
-export interface Snapshot<S> {
+interface Snapshot<S> {
   readonly state: S;
   readonly version: number;
   readonly timestamp: number;
 }
-
 /**
  * Persisted event with metadata
  */
-export interface PersistedEvent<E> {
+interface PersistedEvent<E> {
   readonly event: E;
   readonly version: number;
   readonly timestamp: number;
 }
-
 /**
  * Adapter for persisting actor state and events.
  *
@@ -65,106 +59,80 @@ export interface PersistedEvent<E> {
  * Schema parameters ensure type-safe serialization/deserialization.
  * Schemas must have no context requirements (use Schema<S, SI, never>).
  */
-export interface PersistenceAdapter {
+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>;
-
+  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>;
-
+  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>;
-
+  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>;
-
+  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>;
-
-  // --- Optional registry methods for actor discovery ---
-
   /**
    * 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>;
+  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
  */
-export class PersistenceError extends Schema.TaggedError<PersistenceError>()("PersistenceError", {
-  operation: Schema.String,
-  actorId: Schema.String,
-  cause: Schema.optional(Schema.Unknown),
-  message: Schema.optional(Schema.String),
-}) {}
-
+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
  */
-export class VersionConflictError extends Schema.TaggedError<VersionConflictError>()(
-  "VersionConflictError",
-  {
-    actorId: Schema.String,
-    expectedVersion: Schema.Number,
-    actualVersion: Schema.Number,
-  },
-) {}
-
+declare class VersionConflictError extends VersionConflictError_base {}
+declare const PersistenceAdapterTag_base: Context.TagClass<PersistenceAdapterTag, "effect-machine/src/persistence/adapter/PersistenceAdapterTag", PersistenceAdapter>;
 /**
  * PersistenceAdapter service tag
  */
-export class PersistenceAdapterTag extends Context.Tag(
-  "effect-machine/src/persistence/adapter/PersistenceAdapterTag",
-)<PersistenceAdapterTag, PersistenceAdapter>() {}
+declare class PersistenceAdapterTag extends PersistenceAdapterTag_base {}
+//#endregion
+export { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError };

package/dist/persistence/adapter.js

@@ -0,0 +1,27 @@
+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/dist/persistence/adapters/in-memory.d.ts

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,176 @@
+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/dist/persistence/index.d.ts

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,50 @@
+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 };