effect-machine 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { EffectHandlers, EffectSlot, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlot, GuardSlots, GuardsDef, GuardsSchema, MachineContext, Slot } from "./slot.js";
 import { Event, MachineEventSchema, MachineStateSchema, State } from "./schema.js";
 import { PersistenceConfig, PersistentMachine, isPersistentMachine } from "./persistence/persistent-machine.js";
-import { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
 import { ProcessEventResult } from "./internal/transition.js";
 import { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
 import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./persistence/adapter.js";
 import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
 import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
-import { ActorRef, ActorSystem, Default, SystemEvent, SystemEventListener } from "./actor.js";
+import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener } from "./actor.js";
 import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
 import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { type ActorMetadata, type ActorRef, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };
+export { type ActorMetadata, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-import { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
 import { isPersistentMachine } from "./persistence/persistent-machine.js";
 import { Slot } from "./slot.js";
 import { machine_exports } from "./machine.js";
@@ -10,4 +10,4 @@ import { Event, State } from "./schema.js";
 import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
 import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
 import "./persistence/index.js";
-export { Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };
+export { ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };

package/dist/internal/transition.d.ts

@@ -29,7 +29,11 @@ declare const runTransitionHandler: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<{
+  newState: S;
+  hasReply: boolean;
+  reply: unknown;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Execute a transition for a given state and event.
  * Handles transition resolution, handler invocation, and guard/effect slot creation.
@@ -49,6 +53,8 @@ declare const executeTransition: <S extends {
   newState: S;
   transitioned: boolean;
   reenter: boolean;
+  hasReply: boolean;
+  reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Optional hooks for event processing inspection/tracing.
@@ -84,7 +90,22 @@ interface ProcessEventResult<S> {
   readonly lifecycleRan: boolean;
   /** Whether new state is final */
   readonly isFinal: boolean;
+  /** Whether the handler provided a reply (structural, not value-based) */
+  readonly hasReply: boolean;
+  /** Domain reply value from handler (used by ask). Only meaningful when hasReply is true. */
+  readonly reply?: unknown;
+  /** Whether the event was postponed (buffered for retry after next state change) */
+  readonly postponed: boolean;
 }
+/**
+ * Check if an event should be postponed in the current state.
+ * @internal
+ */
+declare const shouldPostpone: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, stateTag: string, eventTag: string) => boolean;
 /**
  * Process a single event through the machine.
  *
@@ -109,6 +130,9 @@ declare const processEventCore: <S extends {
   transitioned: boolean;
   lifecycleRan: boolean;
   isFinal: boolean;
+  hasReply: boolean;
+  reply: unknown;
+  postponed: boolean;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Run spawn effects for a state (forked into state scope, auto-cancelled on state exit).
@@ -157,4 +181,4 @@ declare const findSpawnEffects: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, GD, EFD>, stateTag: string) => ReadonlyArray<SpawnEffect<S, E, EFD, R>>;
 //#endregion
-export { ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionExecutionResult, executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };
+export { ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionExecutionResult, executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/dist/internal/transition.js

@@ -37,8 +37,18 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 		guards,
 		effects
 	};
-	const result = transition.handler(handlerCtx);
-	return isEffect(result) ? yield* result.pipe(Effect.provideService(machine.Context, ctx)) : result;
+	const raw = transition.handler(handlerCtx);
+	const resolved = isEffect(raw) ? yield* raw.pipe(Effect.provideService(machine.Context, ctx)) : raw;
+	if (resolved !== null && typeof resolved === "object" && "state" in resolved && "reply" in resolved && !("_tag" in resolved)) return {
+		newState: resolved.state,
+		hasReply: true,
+		reply: resolved.reply
+	};
+	return {
+		newState: resolved,
+		hasReply: false,
+		reply: void 0
+	};
 });
 /**
 * Execute a transition for a given state and event.
@@ -56,15 +66,28 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 	if (transition === void 0) return {
 		newState: currentState,
 		transitioned: false,
-		reenter: false
+		reenter: false,
+		hasReply: false,
+		reply: void 0
 	};
+	const { newState, hasReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
 	return {
-		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId),
+		newState,
 		transitioned: true,
-		reenter: transition.reenter === true
+		reenter: transition.reenter === true,
+		hasReply,
+		reply
 	};
 });
 /**
+* Check if an event should be postponed in the current state.
+* @internal
+*/
+const shouldPostpone = (machine, stateTag, eventTag) => {
+	for (const rule of machine.postponeRules) if (rule.stateTag === stateTag && rule.eventTag === eventTag) return true;
+	return false;
+};
+/**
 * Process a single event through the machine.
 *
 * Handles:
@@ -93,7 +116,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		previousState: currentState,
 		transitioned: false,
 		lifecycleRan: false,
-		isFinal: false
+		isFinal: false,
+		hasReply: false,
+		reply: void 0,
+		postponed: false
 	};
 	const newState = result.newState;
 	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
@@ -109,7 +135,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		previousState: currentState,
 		transitioned: true,
 		lifecycleRan: runLifecycle,
-		isFinal: machine.finalStates.has(newState._tag)
+		isFinal: machine.finalStates.has(newState._tag),
+		hasReply: result.hasReply,
+		reply: result.reply,
+		postponed: false
 	};
 });
 /**
@@ -236,4 +265,4 @@ const findSpawnEffects = (machine, stateTag) => {
 	return getIndex(machine).spawn.get(stateTag) ?? [];
 };
 //#endregion
-export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };
+export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/dist/internal/utils.d.ts

@@ -26,7 +26,12 @@ type TaggedConstructor<T extends {
 /**
  * Transition handler result - either a new state or Effect producing one
  */
-type TransitionResult<State, R> = State | Effect.Effect<State, never, R>;
+/** Reply tuple returned from transition handlers for ask support */
+interface TransitionReply<State> {
+  readonly state: State;
+  readonly reply: unknown;
+}
+type TransitionResult<State, R> = State | TransitionReply<State> | Effect.Effect<State | TransitionReply<State>, never, R>;
 /**
  * Internal event tags used for lifecycle effect contexts.
  * Prefixed with $ to distinguish from user events.
@@ -57,4 +62,4 @@ declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unkn
  */
 declare const stubSystem: ActorSystem;
 //#endregion
-export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect, stubSystem };
+export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionReply, TransitionResult, getTag, isEffect, stubSystem };

package/dist/machine.d.ts

@@ -6,17 +6,19 @@ import { PersistenceConfig, PersistentMachine } from "./persistence/persistent-m
 import { DuplicateActorError } from "./errors.js";
 import { findTransitions } from "./internal/transition.js";
 import { ActorRef, ActorSystem } from "./actor.js";
-import { Cause, Effect, Schedule, Schema, Scope, ServiceMap } from "effect";
+import { Cause, Duration, Effect, Schedule, Schema, Scope, ServiceMap } from "effect";
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, make, spawn };
+  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, spawn };
 }
 /**
  * Self reference for sending events back to the machine
  */
 interface MachineRef<Event> {
   readonly send: (event: Event) => Effect.Effect<void>;
+  /** Fire-and-forget alias for send (OTP gen_server:cast). */
+  readonly cast: (event: Event) => Effect.Effect<void>;
   readonly spawn: <S2 extends {
     readonly _tag: string;
   }, E2 extends {
@@ -86,6 +88,18 @@ interface TaskOptions<State, Event, ED extends EffectsDef, A, E1, ES, EF> {
   readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<State, Event, ED>) => EF;
   readonly name?: string;
 }
+/**
+ * Configuration for `.timeout()` — gen_statem-style state timeouts.
+ *
+ * Entering the state starts a timer. Leaving cancels it.
+ * `.reenter()` restarts the timer with fresh state values.
+ */
+interface TimeoutConfig<State, Event> {
+  /** Duration before firing. Static or derived from current state. */
+  readonly duration: Duration.Input | ((state: State) => Duration.Input);
+  /** Event to send when the timer fires. Static or derived from current state. */
+  readonly event: Event | ((state: State) => Event);
+}
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
 type NormalizeR<T> = IsAny<T> extends true ? T : IsUnknown<T> extends true ? never : T;
@@ -152,6 +166,11 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   /** @internal */
   readonly _finalStates: Set<string>;
   /** @internal */
+  readonly _postponeRules: Array<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
+  /** @internal */
   readonly _guardsSchema?: GuardsSchema<GD>;
   /** @internal */
   readonly _effectsSchema?: EffectsSchema<EFD>;
@@ -175,6 +194,10 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   get spawnEffects(): ReadonlyArray<SpawnEffect<State, Event, EFD, R>>;
   get backgroundEffects(): ReadonlyArray<BackgroundEffect<State, Event, EFD, R>>;
   get finalStates(): ReadonlySet<string>;
+  get postponeRules(): ReadonlyArray<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
   get guardsSchema(): GuardsSchema<GD> | undefined;
   get effectsSchema(): EffectsSchema<EFD> | undefined;
   /** @internal */
@@ -230,6 +253,28 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * Interrupts do not emit failure events.
    */
   task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, EFD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * State timeout — gen_statem's `state_timeout`.
+   *
+   * Entering the state starts a timer. Leaving cancels it (via state scope).
+   * `.reenter()` restarts the timer with fresh state values.
+   * Compiles to `.task()` internally — preserves `@machine.task` inspection events.
+   *
+   * @example
+   * ```ts
+   * machine
+   *   .timeout(State.Loading, {
+   *     duration: Duration.seconds(30),
+   *     event: Event.Timeout,
+   *   })
+   *   // Dynamic duration from state
+   *   .timeout(State.Retrying, {
+   *     duration: (state) => Duration.seconds(state.backoff),
+   *     event: Event.GiveUp,
+   *   })
+   * ```
+   */
+  timeout<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, config: TimeoutConfig<NS, VariantsUnion<_ED> & BrandedEvent>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
    * Use effect slots defined via `Slot.Effects` for the actual work.
@@ -251,6 +296,24 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * ```
    */
   background(handler: StateEffectHandler<State, Event, EFD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * Postpone events — gen_statem's event postpone.
+   *
+   * When a matching event arrives in the given state, it is buffered instead of
+   * processed. After the next state transition (tag change), all buffered events
+   * are drained through the loop in FIFO order.
+   *
+   * Reply-bearing events (from `call`/`ask`) in the postpone buffer are settled
+   * with `ActorStoppedError` on stop/interrupt/final-state.
+   *
+   * @example
+   * ```ts
+   * machine
+   *   .postpone(State.Connecting, Event.Data)           // single event
+   *   .postpone(State.Connecting, [Event.Data, Event.Cmd]) // multiple events
+   * ```
+   */
+  postpone<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, events: TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent> | ReadonlyArray<TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
@@ -288,4 +351,4 @@ declare const spawn: {
   }, R>(machine: BuiltMachine<S, E, R>, id: string): Effect.Effect<ActorRef<S, E>, never, R>;
 };
 //#endregion
-export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };
+export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };

package/dist/machine.js

@@ -64,6 +64,7 @@ var Machine = class Machine {
 	/** @internal */ _spawnEffects;
 	/** @internal */ _backgroundEffects;
 	/** @internal */ _finalStates;
+	/** @internal */ _postponeRules;
 	/** @internal */ _guardsSchema;
 	/** @internal */ _effectsSchema;
 	/** @internal */ _guardHandlers;
@@ -88,6 +89,9 @@ var Machine = class Machine {
 	get finalStates() {
 		return this._finalStates;
 	}
+	get postponeRules() {
+		return this._postponeRules;
+	}
 	get guardsSchema() {
 		return this._guardsSchema;
 	}
@@ -101,6 +105,7 @@ var Machine = class Machine {
 		this._spawnEffects = [];
 		this._backgroundEffects = [];
 		this._finalStates = /* @__PURE__ */ new Set();
+		this._postponeRules = [];
 		this._guardsSchema = guardsSchema;
 		this._effectsSchema = effectsSchema;
 		this._guardHandlers = /* @__PURE__ */ new Map();
@@ -259,6 +264,36 @@ var Machine = class Machine {
 		return this.spawn(state, handler);
 	}
 	/**
+	* State timeout — gen_statem's `state_timeout`.
+	*
+	* Entering the state starts a timer. Leaving cancels it (via state scope).
+	* `.reenter()` restarts the timer with fresh state values.
+	* Compiles to `.task()` internally — preserves `@machine.task` inspection events.
+	*
+	* @example
+	* ```ts
+	* machine
+	*   .timeout(State.Loading, {
+	*     duration: Duration.seconds(30),
+	*     event: Event.Timeout,
+	*   })
+	*   // Dynamic duration from state
+	*   .timeout(State.Retrying, {
+	*     duration: (state) => Duration.seconds(state.backoff),
+	*     event: Event.GiveUp,
+	*   })
+	* ```
+	*/
+	timeout(state, config) {
+		const stateTag = getTag(state);
+		const resolveDuration = typeof config.duration === "function" ? config.duration : () => config.duration;
+		const resolveEvent = typeof config.event === "function" ? config.event : () => config.event;
+		return this.task(state, (ctx) => Effect.sleep(resolveDuration(ctx.state)), {
+			onSuccess: (_, ctx) => resolveEvent(ctx.state),
+			name: `$timeout:${stateTag}`
+		});
+	}
+	/**
 	* Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
 	* Use effect slots defined via `Slot.Effects` for the actual work.
 	*
@@ -282,6 +317,35 @@ var Machine = class Machine {
 		this._backgroundEffects.push({ handler });
 		return this;
 	}
+	/**
+	* Postpone events — gen_statem's event postpone.
+	*
+	* When a matching event arrives in the given state, it is buffered instead of
+	* processed. After the next state transition (tag change), all buffered events
+	* are drained through the loop in FIFO order.
+	*
+	* Reply-bearing events (from `call`/`ask`) in the postpone buffer are settled
+	* with `ActorStoppedError` on stop/interrupt/final-state.
+	*
+	* @example
+	* ```ts
+	* machine
+	*   .postpone(State.Connecting, Event.Data)           // single event
+	*   .postpone(State.Connecting, [Event.Data, Event.Cmd]) // multiple events
+	* ```
+	*/
+	postpone(state, events) {
+		const stateTag = getTag(state);
+		const eventList = Array.isArray(events) ? events : [events];
+		for (const ev of eventList) {
+			const eventTag = getTag(ev);
+			this._postponeRules.push({
+				stateTag,
+				eventTag
+			});
+		}
+		return this;
+	}
 	final(state) {
 		const stateTag = getTag(state);
 		this._finalStates.add(stateTag);
@@ -313,6 +377,7 @@ var Machine = class Machine {
 			result._finalStates = new Set(this._finalStates);
 			result._spawnEffects = [...this._spawnEffects];
 			result._backgroundEffects = [...this._backgroundEffects];
+			result._postponeRules = [...this._postponeRules];
 			const anyHandlers = handlers;
 			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) result._guardHandlers.set(name, anyHandlers[name]);
 			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) result._effectHandlers.set(name, anyHandlers[name]);

package/dist/persistence/persistent-actor.js

@@ -1,9 +1,10 @@
 import { Inspector } from "../inspection.js";
 import { INTERNAL_INIT_EVENT, stubSystem } from "../internal/utils.js";
+import { NoReplyError } from "../errors.js";
 import { emitWithTimestamp } from "../internal/inspection.js";
-import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler } from "../internal/transition.js";
+import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone } from "../internal/transition.js";
 import { PersistenceAdapterTag } from "./adapter.js";
-import { ActorSystem, buildActorRefCore, notifyListeners } from "../actor.js";
+import { ActorSystem, buildActorRefCore, notifyListeners, settlePendingReplies } from "../actor.js";
 import { Cause, Clock, Deferred, Effect, Exit, Fiber, Option, Queue, Ref, Schedule, Scope, SubscriptionRef } from "effect";
 //#region src/persistence/persistent-actor.ts
 /** Get current time in milliseconds using Effect Clock */
@@ -19,7 +20,7 @@ const replayEvents = Effect.fn("effect-machine.persistentActor.replayEvents")(fu
 	for (const persistedEvent of events) {
 		if (stopVersion !== void 0 && persistedEvent.version > stopVersion) break;
 		const transition = resolveTransition(machine, state, persistedEvent.event);
-		if (transition !== void 0) state = yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem, "restore");
+		if (transition !== void 0) state = (yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem, "restore")).newState;
 		version = persistedEvent.version;
 	}
 	return {
@@ -30,7 +31,7 @@ const replayEvents = Effect.fn("effect-machine.persistentActor.replayEvents")(fu
 /**
 * Build PersistentActorRef with all methods
 */
-const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter, system, childrenMap) => {
+const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter, system, childrenMap, pendingReplies) => {
 	const { machine, persistence } = persistentMachine;
 	const typedMachine = machine;
 	const persist = Effect.gen(function* () {
@@ -44,8 +45,10 @@ const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, ev
 	const version = Ref.get(versionRef).pipe(Effect.withSpan("effect-machine.persistentActor.version"));
 	const replayTo = Effect.fn("effect-machine.persistentActor.replayTo")(function* (targetVersion) {
 		if (targetVersion <= (yield* Ref.get(versionRef))) {
+			const dummySend = Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void);
 			const dummySelf = {
-				send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void),
+				send: dummySend,
+				cast: dummySend,
 				spawn: () => Effect.die("spawn not supported in replay")
 			};
 			const maybeSnapshot = yield* adapter.loadSnapshot(id, persistence.stateSchema);
@@ -70,7 +73,7 @@ const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, ev
 		}
 	});
 	return {
-		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap),
+		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies),
 		persist,
 		version,
 		replayTo
@@ -92,11 +95,16 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const eventQueue = yield* Queue.unbounded();
 	const stoppedRef = yield* Ref.make(false);
 	const childrenMap = /* @__PURE__ */ new Map();
+	const selfSend = Effect.fn("effect-machine.persistentActor.self.send")(function* (event) {
+		if (yield* Ref.get(stoppedRef)) return;
+		yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	});
 	const self = {
-		send: Effect.fn("effect-machine.persistentActor.self.send")(function* (event) {
-			if (yield* Ref.get(stoppedRef)) return;
-			yield* Queue.offer(eventQueue, { event });
-		}),
+		send: selfSend,
+		cast: selfSend,
 		spawn: (childId, childMachine) => Effect.gen(function* () {
 			const child = yield* system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system));
 			childrenMap.set(childId, child);
@@ -177,9 +185,10 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 			finalState: resolvedInitial,
 			timestamp
 		}));
-		return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap);
+		return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap, /* @__PURE__ */ new Set());
 	}
-	const loopFiber = yield* Effect.forkDetach(persistentEventLoop(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system));
+	const pendingReplies = /* @__PURE__ */ new Set();
+	const loopFiber = yield* Effect.forkDetach(persistentEventLoop(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system, pendingReplies));
 	return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspector, (timestamp) => ({
@@ -190,16 +199,17 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 		}));
 		yield* Ref.set(stoppedRef, true);
 		yield* Fiber.interrupt(loopFiber);
+		yield* settlePendingReplies(pendingReplies, id);
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 		yield* Fiber.interrupt(snapshotFiber);
 		yield* Fiber.interrupt(persistenceFiber);
-	}).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap);
+	}).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap, pendingReplies);
 });
 /**
 * Main event loop for persistent actor
 */
-const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop")(function* (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system) {
+const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop")(function* (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system, pendingReplies) {
 	const { machine, persistence } = persistentMachine;
 	const typedMachine = machine;
 	const hooks = inspector === void 0 ? void 0 : {
@@ -228,10 +238,28 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 			timestamp
 		}))
 	};
+	const postponed = [];
+	const pendingDrain = [];
+	const hasPostponeRules = machine.postponeRules.length > 0;
 	while (true) {
-		const { event, reply } = yield* Queue.take(eventQueue);
+		const queued = pendingDrain.length > 0 ? pendingDrain.shift() : yield* Queue.take(eventQueue);
+		const event = queued.event;
 		const currentState = yield* SubscriptionRef.get(stateRef);
 		const currentVersion = yield* Ref.get(versionRef);
+		if (hasPostponeRules && shouldPostpone(typedMachine, currentState._tag, event._tag)) {
+			postponed.push(queued);
+			if (queued._tag === "call") yield* Deferred.succeed(queued.reply, {
+				newState: currentState,
+				previousState: currentState,
+				transitioned: false,
+				lifecycleRan: false,
+				isFinal: false,
+				hasReply: false,
+				reply: void 0,
+				postponed: true
+			});
+			continue;
+		}
 		yield* emitWithTimestamp(inspector, (timestamp) => ({
 			type: "@machine.event",
 			actorId: id,
@@ -240,7 +268,12 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 			timestamp
 		}));
 		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, id, hooks);
-		if (reply !== void 0) yield* Deferred.succeed(reply, result);
+		if (queued._tag === "call") yield* Deferred.succeed(queued.reply, result);
+		else if (queued._tag === "ask") if (result.hasReply) yield* Deferred.succeed(queued.reply, result.reply);
+		else yield* Deferred.fail(queued.reply, new NoReplyError({
+			actorId: id,
+			eventTag: event._tag
+		}));
 		if (!result.transitioned) continue;
 		const newVersion = currentVersion + 1;
 		yield* Ref.set(versionRef, newVersion);
@@ -268,12 +301,15 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 				timestamp
 			}));
 			yield* Ref.set(stoppedRef, true);
+			postponed.length = 0;
+			yield* settlePendingReplies(pendingReplies, id);
 			yield* Scope.close(stateScopeRef.current, Exit.void);
 			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 			yield* Fiber.interrupt(snapshotFiber);
 			yield* Fiber.interrupt(persistenceFiber);
 			return;
 		}
+		if (result.lifecycleRan && postponed.length > 0) pendingDrain.push(...postponed.splice(0));
 	}
 });
 /**