xstate 6.0.0-alpha.21 → 6.0.0-alpha.23

package/dist/declarations/src/types.d.ts

@@ -5,7 +5,7 @@ import { AsyncActorLogic } from "./actors/promise.js";
 import type { Actor } from "./createActor.js";
 import { InspectionEvent } from "./inspection.js";
 import { Spawner } from "./spawn.js";
-import { AnyActorSystem, Clock } from "./system.js";
+import type { ActorSystemRuntime, AnyActorSystem, Clock } from "./system.js";
 import { Implementations, Next_StateNodeConfig } from "./types.v6.js";
 import { StandardSchemaV1 } from "./schema.types.js";
 import { builtInActions } from "./actions.js";
@@ -486,50 +486,27 @@ export interface StateConfig<TContext extends MachineContext, TEvent extends Eve
     context: TContext;
     historyValue?: HistoryValue;
     children: Record<string, AnyActorRef | undefined>;
+    timers?: Record<string, LogicalTimer>;
     status: SnapshotStatus;
     output?: any;
     error?: unknown;
     machine?: StateMachine<TContext, TEvent, any, any, any, any, any, any, any, any, any, any, any, any>;
 }
-/**
- * A pending effect (delayed event/transition that has not fired yet) captured
- * in a persisted snapshot — a serialized built-in action descriptor plus its
- * runtime progress, with enough information to restore it under any strategy.
- */
-export interface PendingEffect {
-    /** The serialized built-in action type for this effect. */
-    type: '@xstate.raise';
-    event: EventObject;
+/** A deterministic delayed-delivery declaration owned by a logic snapshot. */
+export interface LogicalTimer {
     id: string;
-    /** The original delay (in ms) the effect was scheduled with. */
     delay: number;
-    /** Wall-clock timestamp (ms) when the effect was scheduled. */
-    startedAt: number;
-    /** Wall-clock time (ms) that had elapsed when the snapshot was persisted. */
-    elapsed: number;
+    type: '@xstate.raise' | '@xstate.sendTo';
+    event: EventObject;
+    /** `self` or the logical actor that will receive `event`. */
+    target: 'self' | AnyActor;
+}
+/** The logical input delivered to a timer's source when its runtime delay ends. */
+export interface TimerEvent extends EventObject {
+    type: 'xstate.timer';
+    id: string;
 }
-/**
- * How pending effects (timers) from a persisted snapshot are restored on
- * `actor.start()`:
- *
- * - `'resume'` (default) — the clock was "frozen" while persisted: a 5-minute
- *   timer persisted with 1 minute elapsed fires after 4 more minutes.
- * - `'restart'` — timers start over with their full delay.
- * - `'absolute'` — timers honor the original wall-clock expiry (`startedAt +
- *   delay`); already-expired timers fire immediately.
- * - A custom function receiving the pending effect and returning the remaining
- *   delay in ms.
- */
-export type TimersRestoreStrategy = 'resume' | 'restart' | 'absolute' | ((pendingEffect: PendingEffect) => number);
 export interface ActorOptions<TLogic extends AnyActorLogic> {
-    /**
-     * How pending timers (delayed events/transitions) from a persisted `snapshot`
-     * are restored when the actor starts. Applies to this actor and (when this is
-     * the root) all rehydrated child actors.
-     *
-     * @default 'resume'
-     */
-    timers?: TimersRestoreStrategy;
     /**
      * The clock that is responsible for setting and clearing timeouts, such as
      * delayed events and transitions.
@@ -795,7 +772,7 @@ export interface ActorScope<TSnapshot extends Snapshot<unknown>, TEvent extends
     sessionId: string;
     logger: (...args: any[]) => void;
     defer: (fn: () => void) => void;
-    emit: (event: TEmitted) => void;
+    emit: (event: TEmitted) => void | PromiseLike<void>;
     system: TSystem;
     stopChild: (child: AnyActor) => void;
     actionExecutor: ActionExecutor;
@@ -822,7 +799,7 @@ export type Snapshot<TOutput> = {
     output: undefined;
     error: undefined;
 };
-export type ActorLogicTransitionResult<TSnapshot extends Snapshot<unknown>, TEffect = unknown> = [nextSnapshot: TSnapshot, effects: TEffect[]];
+export type ActorLogicTransitionResult<TSnapshot extends Snapshot<unknown>, TEffect = ExecutableActionObject> = [nextSnapshot: TSnapshot, effects: TEffect[]];
 /**
  * Represents logic which can be used by an actor.
  *
@@ -877,8 +854,12 @@ in TInput = NonReducibleUnknown, TSystem extends AnyActorSystem = AnyActorSystem
      *
      * @param snapshot - The starting state.
      * @param actorScope - The actor scope.
+     * @param options - Start metadata, including whether the snapshot was
+     *   restored.
      */
-    start?: (snapshot: TSnapshot, actorScope: ActorScope<TSnapshot, TEvent, AnyActorSystem, TEmitted>) => void;
+    start?: (snapshot: TSnapshot, actorScope: ActorScope<TSnapshot, TEvent, AnyActorSystem, TEmitted>, options?: {
+        restored: boolean;
+    }) => void;
     /**
      * Obtains the internal state of the actor in a representation which can be be
      * persisted. The persisted state can be restored by `restoreSnapshot`.
@@ -887,12 +868,6 @@ in TInput = NonReducibleUnknown, TSystem extends AnyActorSystem = AnyActorSystem
      * @returns The a representation of the internal state to be persisted.
      */
     getPersistedSnapshot: (snapshot: TSnapshot, options?: unknown) => Snapshot<unknown>;
-    /**
-     * Executes the non-action effects returned from `transition` (e.g. the
-     * effects produced by `createLogic`-based actors). Actor logic that never
-     * returns such effects can omit this.
-     */
-    executeEffects?: (effects: readonly unknown[], actorScope: ActorScope<TSnapshot, TEvent, TSystem, TEmitted>) => void;
     /**
      * Returns an event that the actor should transition with to recover from an
      * execution error, or `undefined` if the given snapshot cannot handle it.
@@ -906,9 +881,10 @@ export interface AnyActorLogic {
     initialTransition(input: any, actorScope: any): ActorLogicTransitionResult<any>;
     getInitialSnapshot(actorScope: any, input: any): any;
     restoreSnapshot?(persistedState: Snapshot<unknown>, actorScope: any): any;
-    start?(snapshot: any, actorScope: any): void;
+    start?(snapshot: any, actorScope: any, options?: {
+        restored: boolean;
+    }): void;
     getPersistedSnapshot(snapshot: any, options?: unknown): Snapshot<unknown>;
-    executeEffects?(effects: readonly unknown[], actorScope: any): void;
     getExecutionErrorEvent?(snapshot: any, error: unknown): any;
 }
 export type UnknownActorLogic = ActorLogic<any, // snapshot
@@ -1047,13 +1023,35 @@ export type ToStateValue<T extends StateSchema> = T extends {
 export interface BaseExecutableActionObject {
     params: NonReducibleUnknown;
     args: unknown[];
-    exec: (() => void) | undefined;
+    exec(runtime?: Partial<ActorSystemRuntime>): void | PromiseLike<void> | undefined;
 }
+/** The terminal result published when an actor completes or errors. */
+export type ActorTermination = {
+    status: 'done';
+    output: unknown;
+    error: undefined;
+} | {
+    status: 'error';
+    output: undefined;
+    error: unknown;
+};
 export interface CustomExecutableActionObject<TType extends string = string & {}> extends BaseExecutableActionObject {
+    kind: 'action';
     type: TType;
+    action: ((...args: any[]) => void | PromiseLike<void>) | undefined;
+}
+export interface EmitExecutableActionObject<TType extends string = string & {}> extends BaseExecutableActionObject {
+    kind: 'emit';
+    type: TType;
+    source: AnyActor;
+    event: EventObject & {
+        type: TType;
+    };
 }
 export interface SpawnExecutableActionObject extends BaseExecutableActionObject {
+    kind: 'builtin';
     type: '@xstate.spawn';
+    source: AnyActor | undefined;
     actor: AnyActor;
     id: string;
     logic: AnyActorLogic;
@@ -1062,20 +1060,26 @@ export interface SpawnExecutableActionObject extends BaseExecutableActionObject
     args: Parameters<(typeof builtInActions)['@xstate.spawn']>;
 }
 export interface StartExecutableActionObject extends BaseExecutableActionObject {
+    kind: 'builtin';
     type: '@xstate.start';
+    source: AnyActor | undefined;
     actor: AnyActor;
     id: string;
     args: Parameters<(typeof builtInActions)['@xstate.start']>;
 }
 export interface RaiseExecutableActionObject extends BaseExecutableActionObject {
+    kind: 'builtin';
     type: '@xstate.raise';
+    source: AnyActor;
     event: EventObject;
     id: string | undefined;
     delay: number | undefined;
     args: Parameters<(typeof builtInActions)['@xstate.raise']>;
 }
 export interface SendToExecutableActionObject extends BaseExecutableActionObject {
+    kind: 'builtin';
     type: '@xstate.sendTo';
+    source: AnyActor;
     target: AnyActor;
     event: EventObject;
     id: string | undefined;
@@ -1083,15 +1087,29 @@ export interface SendToExecutableActionObject extends BaseExecutableActionObject
     args: Parameters<(typeof builtInActions)['@xstate.sendTo']>;
 }
 export interface CancelExecutableActionObject extends BaseExecutableActionObject {
+    kind: 'builtin';
     type: '@xstate.cancel';
+    source: AnyActor;
     id: string;
     args: Parameters<(typeof builtInActions)['@xstate.cancel']>;
 }
 export interface StopExecutableActionObject extends BaseExecutableActionObject {
+    kind: 'builtin';
     type: '@xstate.stop';
+    source: AnyActor;
     actor: AnyActor;
+    id: string;
     args: Parameters<(typeof builtInActions)['@xstate.stop']>;
 }
+/** An executable effect that publishes an actor's terminal result. */
+export type TerminateExecutableActionObject = BaseExecutableActionObject & {
+    kind: 'builtin';
+    type: '@xstate.terminate';
+    source: AnyActor;
+    actor: AnyActor;
+    id: string;
+    args: Parameters<(typeof builtInActions)['@xstate.terminate']>;
+} & ActorTermination;
 export type BuiltInExecutableActionObject = Values<{
     '@xstate.spawn': SpawnExecutableActionObject;
     '@xstate.start': StartExecutableActionObject;
@@ -1099,16 +1117,17 @@ export type BuiltInExecutableActionObject = Values<{
     '@xstate.sendTo': SendToExecutableActionObject;
     '@xstate.cancel': CancelExecutableActionObject;
     '@xstate.stop': StopExecutableActionObject;
+    '@xstate.terminate': TerminateExecutableActionObject;
 }>;
 export type SpecialExecutableAction = BuiltInExecutableActionObject;
-type TransitionExecutableActionObject<TType extends string = never> = BuiltInExecutableActionObject | CustomExecutableActionObject<TType | (string & {})>;
+type TransitionExecutableActionObject<TType extends string = never> = BuiltInExecutableActionObject | EmitExecutableActionObject | CustomExecutableActionObject<TType | (string & {})>;
 type KnownImplementationKeys<TImplementationMap> = string extends keyof TImplementationMap ? never : Extract<keyof TImplementationMap, string>;
 export type ExecutableActionObjectFromLogic<T extends AnyActorLogic> = T extends StateMachine<any, any, any, any, any, any, any, any, any, any, infer TActionMap, any, any, any> ? TransitionExecutableActionObject<KnownImplementationKeys<TActionMap>> : ExecutableActionObject;
-export type ExecutableActionObject<TType extends string = string & {}> = BuiltInExecutableActionObject | CustomExecutableActionObject<TType>;
+export type ExecutableActionObject<TType extends string = string & {}> = BuiltInExecutableActionObject | EmitExecutableActionObject | CustomExecutableActionObject<TType>;
 export interface ToExecutableAction<T extends ParameterizedObject> extends CustomExecutableActionObject<T['type']> {
     type: T['type'];
     params: T['params'];
-    exec: undefined;
+    action: undefined;
 }
 export type ActionExecutor = (actionToExecute: ExecutableActionObject) => void;
 /** Mappers for subscribeTo - maps lifecycle events to machine events */