effect-machine 0.17.1 → 0.18.0

package/v3/dist/machine.d.ts

@@ -1,398 +0,0 @@
-import { DeferReplyResult, ReplyResult, TransitionResult } from "./internal/utils.js";
-import { BrandedEvent, BrandedState, ExtractReply, TaggedOrConstructor } from "./internal/brands.js";
-import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
-import { DuplicateActorError } from "./errors.js";
-import { MachineContext, ProvideSlots, SlotCalls, SlotsDef, SlotsSchema } from "./slot.js";
-import { Supervision } from "./supervision.js";
-import { findTransitions } from "./internal/transition.js";
-import { ActorRef, ActorSystem } from "./actor.js";
-import { Cause, Context, Duration, Effect, Option, Schema, Scope } from "effect";
-
-//#region src/machine.d.ts
-declare namespace machine_d_exports {
-  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, scoped, 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 {
-    readonly _tag: string;
-  }, R2>(id: string, machine: Machine<S2, E2, R2, any, any, any>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
-  /**
-   * Settle a deferred reply from a spawn handler.
-   * Only usable when the transition handler returned `Machine.deferReply(state)`.
-   * Returns true if a pending reply was settled, false if none was pending.
-   */
-  readonly reply: (value: unknown) => Effect.Effect<boolean>;
-}
-/**
- * Handler context passed to transition handlers
- */
-interface HandlerContext<State, Event, SD extends SlotsDef = Record<string, never>> {
-  readonly state: State;
-  readonly event: Event;
-  readonly slots: SlotCalls<SD>;
-}
-/**
- * Handler context passed to state effect handlers (onEnter, spawn, background)
- */
-interface StateHandlerContext<State, Event, SD extends SlotsDef = Record<string, never>> {
-  readonly actorId: string;
-  readonly state: State;
-  readonly event: Event;
-  readonly self: MachineRef<Event>;
-  readonly slots: SlotCalls<SD>;
-  readonly system: ActorSystem;
-}
-/**
- * Transition handler function.
- * When Reply is concrete (event has a reply schema), handler must return Machine.reply().
- * When Reply is never, handler returns plain state.
- */
-type TransitionHandler<S, E, NewState, SD extends SlotsDef, R, Reply = never> = (ctx: HandlerContext<S, E, SD>) => TransitionResult<NewState, R, Reply>;
-/**
- * State effect handler function
- */
-type StateEffectHandler<S, E, SD extends SlotsDef, R> = (ctx: StateHandlerContext<S, E, SD>) => Effect.Effect<void, never, R>;
-/**
- * Transition definition
- */
-interface Transition<State, Event, SD extends SlotsDef, R> {
-  readonly stateTag: string;
-  readonly eventTag: string;
-  readonly handler: TransitionHandler<State, Event, State, SD, R>;
-  readonly reenter?: boolean;
-}
-/**
- * Spawn effect - state-scoped forked effect
- */
-interface SpawnEffect<State, Event, SD extends SlotsDef, R> {
-  readonly stateTag: string;
-  readonly handler: StateEffectHandler<State, Event, SD, R>;
-}
-/**
- * Background effect - runs for entire machine lifetime
- */
-interface BackgroundEffect<State, Event, SD extends SlotsDef, R> {
-  readonly handler: StateEffectHandler<State, Event, SD, R>;
-}
-interface TaskOptions<State, Event, SD extends SlotsDef, A, E1, ES, EF> {
-  readonly onSuccess?: (value: A, ctx: StateHandlerContext<State, Event, SD>) => ES;
-  readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<State, Event, SD>) => EF;
-  readonly name?: string;
-}
-/**
- * Recovery resolves the initial state for a generation. Runs during actor.start.
- *
- * For initial start (generation 0): loads persisted state.
- * For supervision restart (generation 1+): reloads state after crash.
- */
-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;
-}
-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.
- *
- * 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.DurationInput | ((state: State) => Duration.DurationInput);
-  /** Event to send when the timer fires. Static or derived from current state. */
-  readonly event: Event | ((state: State) => Event);
-}
-interface MakeConfig<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, SLD extends SlotsDef = Record<string, never>> {
-  readonly state: MachineStateSchema<SD> & {
-    Type: S;
-  };
-  readonly event: MachineEventSchema<ED> & {
-    Type: E;
-  };
-  readonly slots?: SlotsSchema<SLD>;
-  readonly initial: S;
-  /** Validate slot inputs/outputs at runtime. Default: true. Set to false for hot paths. */
-  readonly slotValidation?: boolean;
-}
-/**
- * Bind slot handlers to a machine, returning a fresh copy with handlers installed.
- * If no handlers provided and machine has no slots, returns the machine as-is.
- * Validates that all required slots are provided and no extra slots are given.
- *
- * @internal — used by spawn, replay, simulate, test harness, entity-machine
- */
-declare const materializeMachine: <S, E, R, SD extends SlotsDef>(machine: Machine<S, E, R, any, any, SD>, handlers?: Record<string, any>) => Machine<S, E, never, any, any, SD>;
-/**
- * Machine definition with fluent builder API.
- *
- * Type parameters:
- * - `State`: The state union type
- * - `Event`: The event union type
- * - `R`: Effect requirements
- * - `_SD`: State schema definition (for compile-time validation)
- * - `_ED`: Event schema definition (for compile-time validation)
- * - `SD`: Slot definitions
- */
-declare class Machine<State, Event, R = never, _SD extends Record<string, Schema.Struct.Fields> = Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields> = Record<string, Schema.Struct.Fields>, SD extends SlotsDef = Record<string, never>> {
-  readonly initial: State;
-  /** @internal */
-  readonly _transitions: Array<Transition<State, Event, SD, R>>;
-  /** @internal */
-  readonly _spawnEffects: Array<SpawnEffect<State, Event, SD, R>>;
-  /** @internal */
-  readonly _backgroundEffects: Array<BackgroundEffect<State, Event, SD, R>>;
-  /** @internal */
-  readonly _finalStates: Set<string>;
-  /** @internal */
-  readonly _postponeRules: Array<{
-    readonly stateTag: string;
-    readonly eventTag: string;
-  }>;
-  /** @internal */
-  readonly _slotsSchema?: SlotsSchema<SD>;
-  /** @internal */
-  readonly _slotHandlers: Map<string, (params: unknown) => unknown | Effect.Effect<unknown, never, R>>;
-  /** @internal */
-  readonly _slots: SlotCalls<SD>;
-  /** @internal */
-  readonly _slotValidation: boolean;
-  readonly stateSchema?: Schema.Schema<State>;
-  readonly eventSchema?: Schema.Schema<Event>;
-  /** @internal */
-  readonly _replySchemas: ReadonlyMap<string, Schema.Schema.Any>;
-  /**
-   * Context tag for accessing machine state/event/self in slot handlers.
-   * Uses shared module-level tag for all machines.
-   */
-  readonly Context: Context.Tag<MachineContext<State, Event, MachineRef<Event>>, MachineContext<State, Event, MachineRef<Event>>>;
-  get transitions(): ReadonlyArray<Transition<State, Event, SD, R>>;
-  get spawnEffects(): ReadonlyArray<SpawnEffect<State, Event, SD, R>>;
-  get backgroundEffects(): ReadonlyArray<BackgroundEffect<State, Event, SD, R>>;
-  get finalStates(): ReadonlySet<string>;
-  get postponeRules(): ReadonlyArray<{
-    readonly stateTag: string;
-    readonly eventTag: string;
-  }>;
-  get slotsSchema(): SlotsSchema<SD> | undefined;
-  get replySchemas(): ReadonlyMap<string, Schema.Schema.Any>;
-  /** @internal */
-  constructor(initial: State, stateSchema?: Schema.Schema<State>, eventSchema?: Schema.Schema<Event>, slotsSchema?: SlotsSchema<SD>, slotValidation?: boolean);
-  from<NS extends VariantsUnion<_SD> & BrandedState, R1>(state: TaggedOrConstructor<NS>, build: (scope: TransitionScope<State, Event, R, _SD, _ED, SD, NS>) => R1): Machine<State, Event, R, _SD, _ED, SD>;
-  from<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, R1>(states: NS, build: (scope: TransitionScope<State, Event, R, _SD, _ED, SD, NS[number] extends TaggedOrConstructor<infer S extends VariantsUnion<_SD> & BrandedState> ? S : never>) => R1): Machine<State, Event, R, _SD, _ED, SD>;
-  /** @internal */
-  scopeTransition<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: ReadonlyArray<TaggedOrConstructor<NS>>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, SD, never, ExtractReply<NE>>, reenter: boolean): Machine<State, Event, R, _SD, _ED, SD>;
-  /** Register transition for a single state */
-  on<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
-  /** Register transition for multiple states (handler receives union of state types) */
-  on<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
-  /**
-   * Like `on()`, but forces onEnter/spawn to run even when transitioning to the same state tag.
-   * Use this to restart timers, re-run spawned effects, or reset state-scoped effects.
-   */
-  /** Single state */
-  reenter<NS extends VariantsUnion<_SD> & BrandedState, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS, NE, RS, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
-  /** Multiple states */
-  reenter<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(states: NS, event: TaggedOrConstructor<NE>, handler: TransitionHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, NE, RS, SD, never, ExtractReply<NE>>): Machine<State, Event, R, _SD, _ED, SD>;
-  /**
-   * Register a wildcard transition that fires from any state when no specific transition matches.
-   * Specific `.on()` transitions always take priority over `.onAny()`.
-   */
-  onAny<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<VariantsUnion<_SD> & BrandedState, NE, RS, SD, never>): Machine<State, Event, R, _SD, _ED, SD>;
-  /** @internal */
-  private addTransition;
-  /**
-   * State-scoped effect that is forked on state entry and automatically cancelled on state exit.
-   *
-   * @example
-   * ```ts
-   * machine.spawn(State.Loading, ({ self, state }) =>
-   *   Effect.gen(function* () {
-   *     yield* Effect.addFinalizer(() => Effect.log("Leaving Loading"));
-   *     const data = yield* Http.get(state.url);
-   *     yield* self.send(Event.Loaded({ data }));
-   *   }),
-   * );
-   * ```
-   */
-  /** Single state */
-  spawn<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, handler: StateEffectHandler<NS, VariantsUnion<_ED> & BrandedEvent, SD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, SD>;
-  /** Multiple states */
-  spawn<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>>(states: NS, handler: StateEffectHandler<NS[number] extends TaggedOrConstructor<infer S> ? S : never, VariantsUnion<_ED> & BrandedEvent, SD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, SD>;
-  /**
-   * State-scoped task that runs on entry and sends success/failure events.
-   * Interrupts do not emit failure events.
-   *
-   * Supports multi-state and shorthand overloads:
-   * - `.task(State.X, run, { onSuccess, onFailure })` — explicit mapping
-   * - `.task(State.X, run, { onFailure })` — shorthand when run returns Event directly
-   * - `.task([State.X, State.Y], run, opts)` — multi-state
-   */
-  /** Single state — onSuccess optional (defaults to identity when task returns Event) */
-  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, SD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, SD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, SD>;
-  /** Multiple states — onSuccess optional */
-  task<NS extends ReadonlyArray<TaggedOrConstructor<VariantsUnion<_SD> & BrandedState>>, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(states: NS, run: (ctx: StateHandlerContext<NS[number] extends TaggedOrConstructor<infer S> ? S : never, VariantsUnion<_ED> & BrandedEvent, SD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS[number] extends TaggedOrConstructor<infer S> ? S : never, VariantsUnion<_ED> & BrandedEvent, SD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, SD>;
-  /**
-   * 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, SD>;
-  /**
-   * Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
-   *
-   * @example
-   * ```ts
-   * machine.background(({ self }) =>
-   *   Effect.forever(
-   *     Effect.sleep("30 seconds").pipe(Effect.andThen(self.send(Event.Ping))),
-   *   ),
-   * );
-   * ```
-   */
-  background(handler: StateEffectHandler<State, Event, SD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, SD>;
-  /**
-   * 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, SD>;
-  final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, SD>;
-  static make<SD extends Record<string, Schema.Struct.Fields>, ED extends Record<string, Schema.Struct.Fields>, S extends BrandedState, E extends BrandedEvent, SLD extends SlotsDef = Record<string, never>>(config: MakeConfig<SD, ED, S, E, SLD>): Machine<S, E, never, SD, ED, SLD>;
-}
-declare class TransitionScope<State, Event, R, _SD extends Record<string, Schema.Struct.Fields>, _ED extends Record<string, Schema.Struct.Fields>, SD extends SlotsDef, SelectedState extends VariantsUnion<_SD> & BrandedState> {
-  private readonly machine;
-  private readonly states;
-  constructor(machine: Machine<State, Event, R, _SD, _ED, SD>, states: ReadonlyArray<TaggedOrConstructor<SelectedState>>);
-  on<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, SD, never, ExtractReply<NE>>): TransitionScope<State, Event, R, _SD, _ED, SD, SelectedState>;
-  reenter<NE extends VariantsUnion<_ED> & BrandedEvent, RS extends VariantsUnion<_SD> & BrandedState>(event: TaggedOrConstructor<NE>, handler: TransitionHandler<SelectedState, NE, RS, SD, never, ExtractReply<NE>>): TransitionScope<State, Event, R, _SD, _ED, SD, SelectedState>;
-}
-declare const make: typeof Machine.make;
-/**
- * Spawn an actor from a machine.
- *
- * For machines with slots, pass implementations via `{ slots: { ... } }`.
- *
- * @example
- * ```ts
- * // No slots
- * const actor = yield* Machine.spawn(machine);
- *
- * // With slots
- * const actor = yield* Machine.spawn(machine, {
- *   slots: { canRetry: ({ max }) => attempts < max },
- * });
- *
- * // With lifecycle (recovery + durability)
- * const actor = yield* Machine.spawn(machine, {
- *   lifecycle: {
- *     recovery: { resolve: ({ machineInitial }) => storage.get("actor-state") },
- *     durability: { save: ({ nextState }) => storage.set("actor-state", nextState) },
- *   },
- * });
- * ```
- */
-declare const spawn: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, SD>, options?: string | {
-  id?: string;
-  hydrate?: S;
-  slots?: ProvideSlots<SD, any>;
-  supervision?: Supervision.Policy;
-  lifecycle?: Lifecycle<S, E>;
-}) => Effect.Effect<ActorRef<S, E>, never, R>;
-/**
- * Wrap an effect to provide an `ActorScope` from the current `Scope`.
- *
- * Actors spawned inside will attach cleanup finalizers to this scope,
- * so they are automatically stopped when the scope closes.
- *
- * @example
- * ```ts
- * yield* Effect.scoped(
- *   Machine.scoped(
- *     Effect.gen(function* () {
- *       const actor = yield* Machine.spawn(machine);
- *       yield* actor.start;
- *       // actor auto-stopped when scope closes
- *     }),
- *   ),
- * );
- * ```
- */
-declare const scoped: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Scope.Scope>;
-declare const replay: {
-  <S extends {
-    readonly _tag: string;
-  }, E extends {
-    readonly _tag: string;
-  }, R, SD extends SlotsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, SD>, events: ReadonlyArray<E>, options?: {
-    from?: S;
-    slots?: ProvideSlots<SD, any>;
-  }): Effect.Effect<S, never, R>;
-};
-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, 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, scoped, spawn };