effect-machine 0.14.0 → 0.15.1

package/v3/dist/machine.d.ts

@@ -10,7 +10,7 @@ import { Cause, Context, Duration, Effect, Option, Schema, Scope } from "effect"
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, PersistConfig, ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, materializeMachine, replay, reply, spawn };
+  export { BackgroundEffect, DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, make, materializeMachine, replay, reply, spawn };
 }
 /**
  * Self reference for sending events back to the machine
@@ -88,32 +88,39 @@ interface TaskOptions<State, Event, SD extends SlotsDef, A, E1, ES, EF> {
   readonly name?: string;
 }
 /**
- * Local persistence configuration for Machine.spawn.
+ * Recovery resolves the initial state for a generation. Runs during actor.start.
  *
- * Fully-resolved callbacks — no service dependency.
- * Separate from cluster EntityPersistence which uses a service-based adapter.
+ * For initial start (generation 0): loads persisted state.
+ * For supervision restart (generation 1+): reloads state after crash.
  */
-interface PersistConfig<S> {
-  /** Load saved state on actor start (and restart). Returns None for cold start. */
-  readonly load: () => Effect.Effect<Option.Option<S>>;
-  /** Save state after each transition. Runs inline (blocks next event). */
-  readonly save: (state: S) => Effect.Effect<void>;
-  /** Optional filter — return false to skip saving for this transition. */
+interface Recovery<S> {
+  readonly resolve: (ctx: RecoveryContext<S>) => Effect.Effect<Option.Option<S>>;
+}
+interface RecoveryContext<S> {
+  readonly actorId: string;
+  readonly generation: number;
+  readonly machineInitial: S;
+}
+/**
+ * Durability saves state after committed transitions. Runs during runtime.
+ */
+interface Durability<S, E> {
+  readonly save: (commit: DurabilityCommit<S, E>) => Effect.Effect<void>;
   readonly shouldSave?: (state: S, previousState: S) => boolean;
-  /**
-   * Called after load() returns Some(state). Inspect the restored state
-   * and decide how to proceed before the machine starts.
-   *
-   * Return Some(state) to use that state, or None to discard and start fresh.
-   * Called on both initial spawn and supervision restart.
-   * Receives `initial` (machine.initial) for comparison.
-   *
-   * Use cases: validate persisted state against external systems,
-   * migrate schema changes, downgrade to a safe state on partial corruption.
-   */
-  readonly onRestore?: (state: S, context: {
-    readonly initial: S;
-  }) => Effect.Effect<Option.Option<S>>;
+}
+interface DurabilityCommit<S, E> {
+  readonly actorId: string;
+  readonly generation: number;
+  readonly previousState: S;
+  readonly nextState: S;
+  readonly event: E;
+}
+/**
+ * Actor lifecycle configuration.
+ */
+interface Lifecycle<S, E> {
+  readonly recovery?: Recovery<S>;
+  readonly durability?: Durability<S, E>;
 }
 /**
  * Configuration for `.timeout()` — gen_statem-style state timeouts.
@@ -335,11 +342,11 @@ declare const make: typeof Machine.make;
  *   slots: { canRetry: ({ max }) => attempts < max },
  * });
  *
- * // With persistence
+ * // With lifecycle (recovery + durability)
  * const actor = yield* Machine.spawn(machine, {
- *   persist: {
- *     load: () => storage.get("actor-state"),
- *     save: (state) => storage.set("actor-state", state),
+ *   lifecycle: {
+ *     recovery: { resolve: ({ machineInitial }) => storage.get("actor-state") },
+ *     durability: { save: ({ nextState }) => storage.set("actor-state", nextState) },
  *   },
  * });
  * ```
@@ -353,7 +360,7 @@ declare const spawn: <S extends {
   hydrate?: S;
   slots?: ProvideSlots<SD, any>;
   supervision?: Supervision.Policy;
-  persist?: PersistConfig<S>;
+  lifecycle?: Lifecycle<S, E>;
 }) => Effect.Effect<ActorRef<S, E>, never, R>;
 declare const replay: {
   <S extends {
@@ -368,4 +375,4 @@ declare const replay: {
 declare const reply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
 declare const deferReply: <State>(state: State) => DeferReplyResult<State>;
 //#endregion
-export { BackgroundEffect, type DeferReplyResult, HandlerContext, Machine, MachineRef, MakeConfig, PersistConfig, type ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };
+export { BackgroundEffect, type DeferReplyResult, Durability, DurabilityCommit, HandlerContext, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, type ReplyResult, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, deferReply, findTransitions, machine_d_exports, make, materializeMachine, replay, reply, spawn };

package/v3/dist/machine.js

@@ -395,11 +395,11 @@ const make = Machine.make;
 *   slots: { canRetry: ({ max }) => attempts < max },
 * });
 *
-* // With persistence
+* // With lifecycle (recovery + durability)
 * const actor = yield* Machine.spawn(machine, {
-*   persist: {
-*     load: () => storage.get("actor-state"),
-*     save: (state) => storage.set("actor-state", state),
+*   lifecycle: {
+*     recovery: { resolve: ({ machineInitial }) => storage.get("actor-state") },
+*     durability: { save: ({ nextState }) => storage.set("actor-state", nextState) },
 *   },
 * });
 * ```
@@ -409,7 +409,7 @@ const spawn = Effect.fn("effect-machine.spawn")(function* (machine, idOrOptions)
 	const actor = yield* createActor(opts?.id ?? `actor-${(yield* Random.next).toString(36).slice(2)}`, materializeMachine(machine, opts?.slots), {
 		initialState: opts?.hydrate,
 		supervision: opts?.supervision,
-		persist: opts?.persist
+		lifecycle: opts?.lifecycle
 	});
 	const maybeScope = yield* Effect.serviceOption(Scope.Scope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);