effect-machine 0.1.0

package/src/persistence/adapter.ts

@@ -0,0 +1,169 @@
+import { Context, Schema } from "effect";
+import type { Effect, Option } from "effect";
+
+import type { PersistentActorRef } from "./persistent-actor.js";
+import type { DuplicateActorError } from "../errors.js";
+
+/**
+ * Metadata for a persisted actor.
+ * Used for discovery and filtering during bulk restore.
+ */
+export 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.
+ */
+export interface RestoreResult<
+  S extends { readonly _tag: string },
+  E extends { readonly _tag: string },
+> {
+  readonly restored: ReadonlyArray<PersistentActorRef<S, E>>;
+  readonly failed: ReadonlyArray<RestoreFailure>;
+}
+
+/**
+ * A single restore failure with actor ID and error details.
+ */
+export interface RestoreFailure {
+  readonly id: string;
+  readonly error: PersistenceError | DuplicateActorError;
+}
+
+/**
+ * Snapshot of actor state at a point in time
+ */
+export interface Snapshot<S> {
+  readonly state: S;
+  readonly version: number;
+  readonly timestamp: number;
+}
+
+/**
+ * Persisted event with metadata
+ */
+export 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>).
+ */
+export 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>;
+
+  // --- 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>;
+}
+
+/**
+ * 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),
+}) {}
+
+/**
+ * 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,
+  },
+) {}
+
+/**
+ * PersistenceAdapter service tag
+ */
+export class PersistenceAdapterTag extends Context.Tag(
+  "effect-machine/persistence/adapter/PersistenceAdapterTag",
+)<PersistenceAdapterTag, PersistenceAdapter>() {}

package/src/persistence/adapters/in-memory.ts

@@ -0,0 +1,275 @@
+import { Effect, Layer, Option, Ref, Schema } from "effect";
+
+import type { ActorMetadata, PersistedEvent, PersistenceAdapter, Snapshot } from "../adapter.js";
+import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "../adapter.js";
+
+/**
+ * In-memory storage for a single actor
+ */
+interface ActorStorage {
+  snapshot: Option.Option<{
+    readonly data: unknown;
+    readonly version: number;
+    readonly timestamp: number;
+  }>;
+  events: Array<{ readonly data: unknown; readonly version: number; readonly timestamp: number }>;
+}
+
+/**
+ * Create an in-memory persistence adapter.
+ * Useful for testing and development.
+ */
+const make = Effect.gen(function* () {
+  const storage = yield* Ref.make(new Map<string, ActorStorage>());
+  const registry = yield* Ref.make(new Map<string, ActorMetadata>());
+
+  const getOrCreateStorage = (id: string): Effect.Effect<ActorStorage> =>
+    Ref.modify(storage, (map) => {
+      const existing = map.get(id);
+      if (existing !== undefined) {
+        return [existing, map];
+      }
+      const newStorage: ActorStorage = {
+        snapshot: Option.none(),
+        events: [],
+      };
+      const newMap = new Map(map);
+      newMap.set(id, newStorage);
+      return [newStorage, newMap];
+    });
+
+  const updateStorage = (
+    id: string,
+    update: (storage: ActorStorage) => ActorStorage,
+  ): Effect.Effect<void> =>
+    Ref.update(storage, (map) => {
+      const existing = map.get(id);
+      if (existing === undefined) {
+        return map;
+      }
+      const newMap = new Map(map);
+      newMap.set(id, update(existing));
+      return newMap;
+    });
+
+  const adapter: PersistenceAdapter = {
+    saveSnapshot: <S, SI>(
+      id: string,
+      snapshot: Snapshot<S>,
+      schema: Schema.Schema<S, SI, never>,
+    ): Effect.Effect<void, PersistenceError | VersionConflictError> =>
+      Effect.gen(function* () {
+        const actorStorage = yield* getOrCreateStorage(id);
+
+        // Optimistic locking: check version
+        // Reject only if trying to save an older version (strict <)
+        // Same-version saves are idempotent (allow retries/multiple callers)
+        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,
+            });
+          }
+        }
+
+        // Encode state using schema
+        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: <S, SI>(
+      id: string,
+      schema: Schema.Schema<S, SI, never>,
+    ): Effect.Effect<Option.Option<Snapshot<S>>, PersistenceError> =>
+      Effect.gen(function* () {
+        const actorStorage = yield* getOrCreateStorage(id);
+
+        if (Option.isNone(actorStorage.snapshot)) {
+          return Option.none();
+        }
+
+        const stored = actorStorage.snapshot.value;
+
+        // Decode state using schema
+        const decoded = yield* Schema.decode(schema)(stored.data as SI).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: <E, EI>(
+      id: string,
+      event: PersistedEvent<E>,
+      schema: Schema.Schema<E, EI, never>,
+    ): Effect.Effect<void, PersistenceError> =>
+      Effect.gen(function* () {
+        yield* getOrCreateStorage(id);
+
+        // Encode event using schema
+        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: <E, EI>(
+      id: string,
+      schema: Schema.Schema<E, EI, never>,
+      afterVersion?: number,
+    ): Effect.Effect<ReadonlyArray<PersistedEvent<E>>, PersistenceError> =>
+      Effect.gen(function* () {
+        const actorStorage = yield* getOrCreateStorage(id);
+
+        // Single pass - skip filtered events inline instead of creating intermediate array
+        const decoded: PersistedEvent<E>[] = [];
+        for (const stored of actorStorage.events) {
+          if (afterVersion !== undefined && stored.version <= afterVersion) continue;
+
+          const event = yield* Schema.decode(schema)(stored.data as EI).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: (id: string): Effect.Effect<void, PersistenceError> =>
+      Effect.gen(function* () {
+        yield* Ref.update(storage, (map) => {
+          const newMap = new Map(map);
+          newMap.delete(id);
+          return newMap;
+        });
+        // Also delete metadata
+        yield* Ref.update(registry, (map) => {
+          const newMap = new Map(map);
+          newMap.delete(id);
+          return newMap;
+        });
+      }),
+
+    // Registry methods for actor discovery
+
+    listActors: (): Effect.Effect<ReadonlyArray<ActorMetadata>, PersistenceError> =>
+      Effect.map(Ref.get(registry), (map) => Array.from(map.values())),
+
+    saveMetadata: (metadata: ActorMetadata): Effect.Effect<void, PersistenceError> =>
+      Ref.update(registry, (map) => {
+        const newMap = new Map(map);
+        newMap.set(metadata.id, metadata);
+        return newMap;
+      }),
+
+    deleteMetadata: (id: string): Effect.Effect<void, PersistenceError> =>
+      Ref.update(registry, (map) => {
+        const newMap = new Map(map);
+        newMap.delete(id);
+        return newMap;
+      }),
+
+    loadMetadata: (id: string): Effect.Effect<Option.Option<ActorMetadata>, PersistenceError> =>
+      Effect.map(Ref.get(registry), (map) => {
+        const meta = map.get(id);
+        return meta !== undefined ? Option.some(meta) : Option.none();
+      }),
+  };
+
+  return adapter;
+});
+
+/**
+ * Create an in-memory persistence adapter effect.
+ * Returns the adapter directly for custom layer composition.
+ */
+export 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),
+ * );
+ * ```
+ */
+export const InMemoryPersistenceAdapter: Layer.Layer<PersistenceAdapterTag> = Layer.effect(
+  PersistenceAdapterTag,
+  make,
+);

package/src/persistence/index.ts

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