type InspectionEvent = InspectedSnapshotEvent | InspectedEventEvent | InspectedActorEvent | InspectedMicrostepEvent | InspectedActionEvent; interface BaseInspectionEventProperties { rootId: string; /** * The relevant actorRef for the inspection event. * * - For snapshot events, this is the `actorRef` of the snapshot. * - For event events, this is the target `actorRef` (recipient of event). * - For actor events, this is the `actorRef` of the registered actor. */ actorRef: ActorRefLike; } interface InspectedSnapshotEvent extends BaseInspectionEventProperties { type: '@xstate.snapshot'; event: AnyEventObject; snapshot: Snapshot; } interface InspectedMicrostepEvent extends BaseInspectionEventProperties { type: '@xstate.microstep'; event: AnyEventObject; snapshot: Snapshot; _transitions: AnyTransitionDefinition[]; } interface InspectedActionEvent extends BaseInspectionEventProperties { type: '@xstate.action'; action: { type: string; params: unknown; }; } interface InspectedEventEvent extends BaseInspectionEventProperties { type: '@xstate.event'; sourceRef: ActorRefLike | undefined; event: AnyEventObject; } interface InspectedActorEvent extends BaseInspectionEventProperties { type: '@xstate.actor'; } interface ScheduledEvent { id: string; event: EventObject; startedAt: number; delay: number; source: AnyActorRef; target: AnyActorRef; } interface Clock { setTimeout(fn: (...args: any[]) => void, timeout: number): any; clearTimeout(id: any): void; } interface Scheduler { schedule(source: AnyActorRef, target: AnyActorRef, event: EventObject, delay: number, id: string | undefined): void; cancel(source: AnyActorRef, id: string): void; cancelAll(actorRef: AnyActorRef): void; } interface ActorSystem { get: (key: K) => T['actors'][K] | undefined; inspect: (observer: Observer | ((inspectionEvent: InspectionEvent) => void)) => Subscription; scheduler: Scheduler; getSnapshot: () => { _scheduledEvents: Record; }; start: () => void; _clock: Clock; _logger: (...args: any[]) => void; } type AnyActorSystem = ActorSystem; declare class StateMachine, TActor extends ProvidedActor, TAction extends ParameterizedObject, TGuard extends ParameterizedObject, TDelay extends string, TStateValue extends StateValue, TTag extends string, TInput, TOutput, TEmitted extends EventObject, TMeta extends MetaObject, TConfig extends StateSchema> implements ActorLogic, TEvent, TInput, AnyActorSystem, TEmitted> { /** The raw config used to create the machine. */ config: MachineConfig & { schemas?: unknown; }; /** The machine's own version. */ version?: string; schemas: unknown; implementations: MachineImplementationsSimplified; root: StateNode; id: string; states: StateNode['states']; events: Array>; constructor( /** The raw config used to create the machine. */ config: MachineConfig & { schemas?: unknown; }, implementations?: MachineImplementationsSimplified); /** * Clones this state machine with the provided implementations and merges the * `context` (if provided). * * @param implementations Options (`actions`, `guards`, `actors`, `delays`, * `context`) to recursively merge with the existing options. * @returns A new `StateMachine` instance with the provided implementations. */ provide(implementations: InternalMachineImplementations, TActor, TAction, TGuard, TDelay, TTag, TEmitted>>): StateMachine; resolveState(config: { value: StateValue; context?: TContext; historyValue?: HistoryValue; status?: SnapshotStatus; output?: TOutput; error?: unknown; } & (Equals extends false ? { context: unknown; } : {})): MachineSnapshot; /** * Determines the next snapshot given the current `snapshot` and received * `event`. Calculates a full macrostep from all microsteps. * * @param snapshot The current snapshot * @param event The received event */ transition(snapshot: MachineSnapshot, event: TEvent, actorScope: ActorScope): MachineSnapshot; /** * Determines the next state given the current `state` and `event`. Calculates * a microstep. * * @param state The current state * @param event The received event */ microstep(snapshot: MachineSnapshot, event: TEvent, actorScope: AnyActorScope): Array>; getTransitionData(snapshot: MachineSnapshot, event: TEvent): Array>; /** * The initial state _before_ evaluating any microsteps. This "pre-initial" * state is provided to initial actions executed in the initial state. */ private getPreInitialState; /** * Returns the initial `State` instance, with reference to `self` as an * `ActorRef`. */ getInitialSnapshot(actorScope: ActorScope, TEvent, AnyActorSystem, TEmitted>, input?: TInput): MachineSnapshot; start(snapshot: MachineSnapshot): void; getStateNodeById(stateId: string): StateNode; get definition(): StateMachineDefinition; toJSON(): StateMachineDefinition; getPersistedSnapshot(snapshot: MachineSnapshot, options?: unknown): Snapshot; restoreSnapshot(snapshot: Snapshot, _actorScope: ActorScope, TEvent, AnyActorSystem, TEmitted>): MachineSnapshot; } interface StateNodeOptions { _key: string; _parent?: StateNode; _machine: AnyStateMachine; } declare class StateNode { /** The raw config used to create the machine. */ config: StateNodeConfig; /** * The relative key of the state node, which represents its location in the * overall state value. */ key: string; /** The unique ID of the state node. */ id: string; /** * The type of this state node: * * - `'atomic'` - no child state nodes * - `'compound'` - nested child state nodes (XOR) * - `'parallel'` - orthogonal nested child state nodes (AND) * - `'history'` - history state node * - `'final'` - final state node */ type: 'atomic' | 'compound' | 'parallel' | 'final' | 'history'; /** The string path from the root machine node to this node. */ path: string[]; /** The child state nodes. */ states: StateNodesConfig; /** * The type of history on this state node. Can be: * * - `'shallow'` - recalls only top-level historical state value * - `'deep'` - recalls historical state value at all levels */ history: false | 'shallow' | 'deep'; /** The action(s) to be executed upon entering the state node. */ entry: UnknownAction[]; /** The action(s) to be executed upon exiting the state node. */ exit: UnknownAction[]; /** The parent state node. */ parent?: StateNode; /** The root machine node. */ machine: StateMachine; /** * The meta data associated with this state node, which will be returned in * State instances. */ meta?: any; /** * The output data sent with the "xstate.done.state._id_" event if this is a * final state node. */ output?: Mapper | NonReducibleUnknown; /** * The order this state node appears. Corresponds to the implicit document * order. */ order: number; description?: string; tags: string[]; transitions: Map[]>; always?: Array>; constructor( /** The raw config used to create the machine. */ config: StateNodeConfig, options: StateNodeOptions); /** The well-structured state node definition. */ get definition(): StateNodeDefinition; /** The logic invoked as actors by this state node. */ get invoke(): Array>; /** The mapping of events to transitions. */ get on(): TransitionDefinitionMap; get after(): Array>; get initial(): InitialTransitionDefinition; /** All the event types accepted by this state node and its descendants. */ get events(): Array>; /** * All the events that have transitions directly from this state node. * * Excludes any inert events. */ get ownEvents(): Array>; } type ToTestStateValue = TStateValue extends string ? TStateValue : IsNever extends true ? never : keyof TStateValue | { [K in keyof TStateValue]?: ToTestStateValue>; }; interface MachineSnapshotBase, TStateValue extends StateValue, TTag extends string, TOutput, TMeta, TStateSchema extends StateSchema = StateSchema> { /** The state machine that produced this state snapshot. */ machine: StateMachine; /** The tags of the active state nodes that represent the current state value. */ tags: Set; /** * The current state value. * * This represents the active state nodes in the state machine. * * - For atomic state nodes, it is a string. * - For compound parent state nodes, it is an object where: * * - The key is the parent state node's key * - The value is the current state value of the active child state node(s) * * @example * * ```ts * // single-level state node * snapshot.value; // => 'yellow' * * // nested state nodes * snapshot.value; // => { red: 'wait' } * ``` */ value: TStateValue; /** The current status of this snapshot. */ status: SnapshotStatus; error: unknown; context: TContext; historyValue: Readonly>; /** The enabled state nodes representative of the state value. */ _nodes: Array>; /** An object mapping actor names to spawned/invoked actors. */ children: TChildren; /** * Whether the current state value is a subset of the given partial state * value. * * @param partialStateValue */ matches: (partialStateValue: ToTestStateValue) => boolean; /** * Whether the current state nodes has a state node with the specified `tag`. * * @param tag */ hasTag: (tag: TTag) => boolean; /** * Determines whether sending the `event` will cause a non-forbidden * transition to be selected, even if the transitions have no actions nor * change the state value. * * @param event The event to test * @returns Whether the event will cause a transition */ can: (event: TEvent) => boolean; getMeta: () => Record & string, TMeta | undefined>; toJSON: () => unknown; } interface ActiveMachineSnapshot, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TConfig extends StateSchema> extends MachineSnapshotBase { status: 'active'; output: undefined; error: undefined; } interface DoneMachineSnapshot, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TConfig extends StateSchema> extends MachineSnapshotBase { status: 'done'; output: TOutput; error: undefined; } interface ErrorMachineSnapshot, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TConfig extends StateSchema> extends MachineSnapshotBase { status: 'error'; output: undefined; error: unknown; } interface StoppedMachineSnapshot, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TConfig extends StateSchema> extends MachineSnapshotBase { status: 'stopped'; output: undefined; error: undefined; } type MachineSnapshot, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TConfig extends StateSchema> = ActiveMachineSnapshot | DoneMachineSnapshot | ErrorMachineSnapshot | StoppedMachineSnapshot; declare const symbolObservable: typeof Symbol.observable; /** * An Actor is a running process that can receive events, send events and change * its behavior based on the events it receives, which can cause effects outside * of the actor. When you run a state machine, it becomes an actor. */ declare class Actor implements ActorRef, EventFromLogic, EmittedFrom> { logic: TLogic; /** The current internal state of the actor. */ private _snapshot; /** * The clock that is responsible for setting and clearing timeouts, such as * delayed events and transitions. */ clock: Clock; options: Readonly>; /** The unique identifier for this actor relative to its parent. */ id: string; private mailbox; private observers; private eventListeners; private logger; _parent?: AnyActorRef; ref: ActorRef, EventFromLogic, EmittedFrom>; private _actorScope; private _systemId; /** The globally unique process ID for this invocation. */ sessionId: string; /** The system to which this actor belongs. */ system: AnyActorSystem; private _doneEvent?; src: string | AnyActorLogic; /** * Creates a new actor instance for the given logic with the provided options, * if any. * * @param logic The logic to create an actor from * @param options Actor options */ constructor(logic: TLogic, options?: ActorOptions); private _initState; private _deferred; private update; /** * Subscribe an observer to an actor’s snapshot values. * * @remarks * The observer will receive the actor’s snapshot value when it is emitted. * The observer can be: * * - A plain function that receives the latest snapshot, or * - An observer object whose `.next(snapshot)` method receives the latest * snapshot * * @example * * ```ts * // Observer as a plain function * const subscription = actor.subscribe((snapshot) => { * console.log(snapshot); * }); * ``` * * @example * * ```ts * // Observer as an object * const subscription = actor.subscribe({ * next(snapshot) { * console.log(snapshot); * }, * error(err) { * // ... * }, * complete() { * // ... * } * }); * ``` * * The return value of `actor.subscribe(observer)` is a subscription object * that has an `.unsubscribe()` method. You can call * `subscription.unsubscribe()` to unsubscribe the observer: * * @example * * ```ts * const subscription = actor.subscribe((snapshot) => { * // ... * }); * * // Unsubscribe the observer * subscription.unsubscribe(); * ``` * * When the actor is stopped, all of its observers will automatically be * unsubscribed. * * @param observer - Either a plain function that receives the latest * snapshot, or an observer object whose `.next(snapshot)` method receives * the latest snapshot */ subscribe(observer: Observer>): Subscription; subscribe(nextListener?: (snapshot: SnapshotFrom) => void, errorListener?: (error: any) => void, completeListener?: () => void): Subscription; on['type'] | '*'>(type: TType, handler: (emitted: EmittedFrom & (TType extends '*' ? unknown : { type: TType; })) => void): Subscription; /** Starts the Actor from the initial state */ start(): this; private _process; private _stop; /** Stops the Actor and unsubscribe all listeners. */ stop(): this; private _complete; private _reportError; private _error; private _stopProcedure; /** * Sends an event to the running Actor to trigger a transition. * * @param event The event to send */ send(event: EventFromLogic): void; private attachDevTools; toJSON(): { xstate$$type: number; id: string; }; /** * Obtain the internal state of the actor, which can be persisted. * * @remarks * The internal state can be persisted from any actor, not only machines. * * Note that the persisted state is not the same as the snapshot from * {@link Actor.getSnapshot}. Persisted state represents the internal state of * the actor, while snapshots represent the actor's last emitted value. * * Can be restored with {@link ActorOptions.state} * @see https://stately.ai/docs/persistence */ getPersistedSnapshot(): Snapshot; [symbolObservable](): InteropSubscribable>; /** * Read an actor’s snapshot synchronously. * * @remarks * The snapshot represent an actor's last emitted value. * * When an actor receives an event, its internal state may change. An actor * may emit a snapshot when a state transition occurs. * * Note that some actors, such as callback actors generated with * `fromCallback`, will not emit snapshots. * @see {@link Actor.subscribe} to subscribe to an actor’s snapshot values. * @see {@link Actor.getPersistedSnapshot} to persist the internal state of an actor (which is more than just a snapshot). */ getSnapshot(): SnapshotFrom; } type GuardPredicate = { (args: GuardArgs, params: TParams): boolean; _out_TGuard?: TGuard; }; interface GuardArgs { context: TContext; event: TExpressionEvent; } type Guard = NoRequiredParams | WithDynamicParams | GuardPredicate; type UnknownGuard = UnknownReferencedGuard | UnknownInlineGuard; type UnknownReferencedGuard = Guard; type UnknownInlineGuard = Guard; type GetParameterizedParams = T extends any ? ('params' extends keyof T ? T['params'] : undefined) : never; /** * @remarks * `T | unknown` reduces to `unknown` and that can be problematic when it comes * to contextual typing. It especially is a problem when the union has a * function member, like here: * * ```ts * declare function test( * cbOrVal: ((arg: number) => unknown) | unknown * ): void; * test((arg) => {}); // oops, implicit any * ``` * * This type can be used to avoid this problem. This union represents the same * value space as `unknown`. */ type NonReducibleUnknown = {} | null | undefined; type AnyFunction = (...args: any[]) => any; type ReturnTypeOrValue = T extends AnyFunction ? ReturnType : T; type IsNever = [T] extends [never] ? true : false; type IsNotNever = [T] extends [never] ? false : true; type Compute = { [K in keyof A]: A[K]; } & unknown; type Values = T[keyof T]; type Equals = (() => A extends A2 ? true : false) extends () => A extends A1 ? true : false ? true : false; type DoNotInfer = [T][T extends any ? 0 : any]; type LowInfer = T & NonNullable; type MetaObject = Record; /** The full definition of an event, with a string `type`. */ type EventObject = { /** The type of event that is sent. */ type: string; }; interface AnyEventObject extends EventObject { [key: string]: any; } interface ParameterizedObject { type: string; params?: NonReducibleUnknown; } interface UnifiedArg { context: TContext; event: TExpressionEvent; self: ActorRef, // TODO: this should be replaced with `TChildren` StateValue, string, unknown, TODO, // TMeta TODO>, TEvent, AnyEventObject>; system: AnyActorSystem; } type MachineContext = Record; interface ActionArgs extends UnifiedArg { } type InputFrom = T extends StateMachine ? TInput : T extends ActorLogic ? TInput : never; type OutputFrom = T extends ActorLogic ? (TSnapshot & { status: 'done'; })['output'] : T extends ActorRef ? (TSnapshot & { status: 'done'; })['output'] : never; type ActionFunction = { (args: ActionArgs, params: TParams): void; _out_TEvent?: TEvent; _out_TActor?: TActor; _out_TAction?: TAction; _out_TGuard?: TGuard; _out_TDelay?: TDelay; _out_TEmitted?: TEmitted; }; type NoRequiredParams = T extends any ? undefined extends T['params'] ? T['type'] : never : never; type ConditionalRequired = Condition extends true ? Required : T; type WithDynamicParams = T extends any ? ConditionalRequired<{ type: T['type']; params?: T['params'] | (({ context, event }: { context: TContext; event: TExpressionEvent; }) => T['params']); }, undefined extends T['params'] ? false : true> : never; type Action = NoRequiredParams | WithDynamicParams | ActionFunction; type UnknownAction = Action; type Actions = SingleOrArray>; interface StateValueMap { [key: string]: StateValue | undefined; } /** * The string or object representing the state value relative to the parent * state node. * * @remarks * - For a child atomic state node, this is a string, e.g., `"pending"`. * - For complex state nodes, this is an object, e.g., `{ success: * "someChildState" }`. */ type StateValue = string | StateValueMap; type TransitionTarget = SingleOrArray; interface TransitionConfig { guard?: Guard; actions?: Actions; reenter?: boolean; target?: TransitionTarget | undefined; meta?: TMeta; description?: string; } interface InitialTransitionConfig extends TransitionConfig { target: string; } interface InvokeDefinition { id: string; systemId: string | undefined; /** The source of the actor logic to be invoked */ src: AnyActorLogic | string; input?: Mapper | NonReducibleUnknown; /** * The transition to take upon the invoked child machine reaching its final * top-level state. */ onDone?: string | SingleOrArray, TEvent, TActor, TAction, TGuard, TDelay, TEmitted, TMeta>>; /** * The transition to take upon the invoked child machine sending an error * event. */ onError?: string | SingleOrArray>; onSnapshot?: string | SingleOrArray>; toJSON: () => Omit, 'onDone' | 'onError' | 'toJSON'>; } type Delay = TDelay | number; type DelayedTransitions = { [K in Delay]?: string | SingleOrArray>; }; type SingleOrArray = readonly T[] | T; type StateNodesConfig = { [K in string]: StateNode; }; type StatesConfig = { [K in string]: StateNodeConfig; }; type StatesDefinition = { [K in string]: StateNodeDefinition; }; type TransitionConfigTarget = string | undefined; type TransitionConfigOrTarget = SingleOrArray>; type TransitionsConfig = { [K in EventDescriptor]?: TransitionConfigOrTarget, TEvent, TActor, TAction, TGuard, TDelay, TEmitted, TMeta>; }; type PartialEventDescriptor = TEventType extends `${infer TLeading}.${infer TTail}` ? `${TLeading}.*` | `${TLeading}.${PartialEventDescriptor}` : never; type EventDescriptor = TEvent['type'] | PartialEventDescriptor | '*'; type NormalizeDescriptor = TDescriptor extends '*' ? string : TDescriptor extends `${infer TLeading}.*` ? `${TLeading}.${string}` : TDescriptor; type IsLiteralString = string extends T ? false : true; type DistributeActors = TSpecificActor extends { src: infer TSrc; } ? Compute<{ systemId?: string; /** The source of the machine to be invoked, or the machine itself. */ src: TSrc; /** * The unique identifier for the invoked machine. If not specified, * this will be the machine's own `id`, or the URL (from `src`). */ id?: TSpecificActor['id']; input?: Mapper, TEvent> | InputFrom; /** * The transition to take upon the invoked child machine reaching * its final top-level state. */ onDone?: string | SingleOrArray>, TEvent, TActor, TAction, TGuard, TDelay, TEmitted, TMeta>>; /** * The transition to take upon the invoked child machine sending an * error event. */ onError?: string | SingleOrArray>; onSnapshot?: string | SingleOrArray>, TEvent, TActor, TAction, TGuard, TDelay, TEmitted, TMeta>>; } & { [K in RequiredActorOptions]: unknown; }> | { id?: never; systemId?: string; src: AnyActorLogic; input?: Mapper | NonReducibleUnknown; onDone?: string | SingleOrArray, TEvent, TActor, TAction, TGuard, TDelay, TEmitted, TMeta>>; onError?: string | SingleOrArray>; onSnapshot?: string | SingleOrArray>; } : never; type InvokeConfig = IsLiteralString extends true ? DistributeActors : { /** * The unique identifier for the invoked machine. If not specified, this * will be the machine's own `id`, or the URL (from `src`). */ id?: string; systemId?: string; /** The source of the machine to be invoked, or the machine itself. */ src: AnyActorLogic | string; input?: Mapper | NonReducibleUnknown; /** * The transition to take upon the invoked child machine reaching its * final top-level state. */ onDone?: string | SingleOrArray, // TODO: consider replacing with `unknown` TEvent, TActor, TAction, TGuard, TDelay, TEmitted, TMeta>>; /** * The transition to take upon the invoked child machine sending an * error event. */ onError?: string | SingleOrArray>; onSnapshot?: string | SingleOrArray>; }; interface StateNodeConfig { /** The initial state transition. */ initial?: InitialTransitionConfig | string | undefined; /** * The type of this state node: * * - `'atomic'` - no child state nodes * - `'compound'` - nested child state nodes (XOR) * - `'parallel'` - orthogonal nested child state nodes (AND) * - `'history'` - history state node * - `'final'` - final state node */ type?: 'atomic' | 'compound' | 'parallel' | 'final' | 'history'; /** * Indicates whether the state node is a history state node, and what type of * history: shallow, deep, true (shallow), false (none), undefined (none) */ history?: 'shallow' | 'deep' | boolean | undefined; /** * The mapping of state node keys to their state node configurations * (recursive). */ states?: StatesConfig | undefined; /** * The services to invoke upon entering this state node. These services will * be stopped upon exiting this state node. */ invoke?: SingleOrArray>; /** The mapping of event types to their potential transition(s). */ on?: TransitionsConfig; /** The action(s) to be executed upon entering the state node. */ entry?: Actions; /** The action(s) to be executed upon exiting the state node. */ exit?: Actions; /** * The potential transition(s) to be taken upon reaching a final child state * node. * * This is equivalent to defining a `[done(id)]` transition on this state * node's `on` property. */ onDone?: string | SingleOrArray> | undefined; /** * The mapping (or array) of delays (in milliseconds) to their potential * transition(s). The delayed transitions are taken after the specified delay * in an interpreter. */ after?: DelayedTransitions; /** * An eventless transition that is always taken when this state node is * active. */ always?: TransitionConfigOrTarget; parent?: StateNode; /** * The meta data associated with this state node, which will be returned in * State instances. */ meta?: TMeta; /** * The output data sent with the "xstate.done.state._id_" event if this is a * final state node. * * The output data will be evaluated with the current `context` and placed on * the `.data` property of the event. */ output?: Mapper | NonReducibleUnknown; /** * The unique ID of the state node, which can be referenced as a transition * target via the `#id` syntax. */ id?: string | undefined; /** * The order this state node appears. Corresponds to the implicit document * order. */ order?: number; /** * The tags for this state node, which are accumulated into the `state.tags` * property. */ tags?: SingleOrArray; /** A text description of the state node */ description?: string; /** A default target for a history state */ target?: string | undefined; } interface StateNodeDefinition { id: string; version?: string | undefined; key: string; type: 'atomic' | 'compound' | 'parallel' | 'final' | 'history'; initial: InitialTransitionDefinition | undefined; history: boolean | 'shallow' | 'deep' | undefined; states: StatesDefinition; on: TransitionDefinitionMap; transitions: Array>; entry: UnknownAction[]; exit: UnknownAction[]; meta: any; order: number; output?: StateNodeConfig['output']; invoke: Array>; description?: string; tags: string[]; } interface StateMachineDefinition extends StateNodeDefinition { } type AnyStateMachine = StateMachine; type ActionFunctionMap = { [K in TAction['type']]?: ActionFunction, TActor, TAction, TGuard, TDelay, TEmitted>; }; type GuardMap = { [K in TGuard['type']]?: GuardPredicate, TGuard>; }; type DelayFunctionMap = Record>; type DelayConfig = number | DelayExpr; /** @ignore */ interface MachineImplementationsSimplified { guards: GuardMap; actions: ActionFunctionMap; actors: Record | NonReducibleUnknown; }>; delays: DelayFunctionMap; } type MachineImplementationsActions = { [K in TTypes['actions']['type']]?: ActionFunction['params'], TTypes['actors'], TTypes['actions'], TTypes['guards'], TTypes['delays'], TTypes['emitted']>; }; type MachineImplementationsActors = { [K in TTypes['actors']['src']]?: GetConcreteByKey['logic']; }; type MachineImplementationsDelays = { [K in TTypes['delays']]?: DelayConfig; }; type MachineImplementationsGuards = { [K in TTypes['guards']['type']]?: Guard['params'], TTypes['guards']>; }; type InternalMachineImplementations = { actions?: MachineImplementationsActions; actors?: MachineImplementationsActors; delays?: MachineImplementationsDelays; guards?: MachineImplementationsGuards; }; type InitialContext = TContext | ContextFactory; type ContextFactory = ({ spawn, input, self }: { spawn: Spawner; input: TInput; self: ActorRef, // TODO: this should be replaced with `TChildren` StateValue, string, unknown, TODO, // TMeta TODO>, TEvent, AnyEventObject>; }) => TContext; type MachineConfig = (Omit, DoNotInfer, DoNotInfer, DoNotInfer, DoNotInfer, DoNotInfer, DoNotInfer, DoNotInfer, DoNotInfer, DoNotInfer>, 'output'> & { /** The initial context (extended state) */ /** The machine's own version. */ version?: string; output?: Mapper | TOutput; }) & (MachineContext extends TContext ? { context?: InitialContext, TActor, TInput, TEvent>; } : { context: InitialContext, TActor, TInput, TEvent>; }); interface ProvidedActor { src: string; logic: UnknownActorLogic; id?: string | undefined; } type HistoryValue = Record>>; interface DoneActorEvent extends EventObject { type: `xstate.done.actor.${TId}`; output: TOutput; actorId: TId; } interface ErrorActorEvent extends EventObject { type: `xstate.error.actor.${TId}`; error: TErrorData; actorId: TId; } interface SnapshotEvent = Snapshot> extends EventObject { type: `xstate.snapshot.${string}`; snapshot: TSnapshot; } interface DoneStateEvent extends EventObject { type: `xstate.done.state.${string}`; output: TOutput; } type DelayExpr = (args: ActionArgs, params: TParams) => number; type Mapper = (args: { context: TContext; event: TExpressionEvent; self: ActorRef, // TODO: this should be replaced with `TChildren` StateValue, string, unknown, TODO, // TMeta TODO>, TEvent, AnyEventObject>; }) => TResult; interface TransitionDefinition extends Omit, 'target' | 'guard'> { target: ReadonlyArray> | undefined; source: StateNode; actions: readonly UnknownAction[]; reenter: boolean; guard?: UnknownGuard; eventType: EventDescriptor; toJSON: () => { target: string[] | undefined; source: string; actions: readonly UnknownAction[]; guard?: UnknownGuard; eventType: EventDescriptor; meta?: Record; }; } type AnyTransitionDefinition = TransitionDefinition; interface InitialTransitionDefinition extends TransitionDefinition { target: ReadonlyArray>; guard?: never; } type TransitionDefinitionMap = { [K in EventDescriptor]: Array>>; }; interface DelayedTransitionDefinition extends TransitionDefinition { delay: number | string | DelayExpr; } interface ActorOptions { /** * The clock that is responsible for setting and clearing timeouts, such as * delayed events and transitions. * * @remarks * You can create your own “clock”. The clock interface is an object with two * functions/methods: * * - `setTimeout` - same arguments as `window.setTimeout(fn, timeout)` * - `clearTimeout` - same arguments as `window.clearTimeout(id)` * * By default, the native `setTimeout` and `clearTimeout` functions are used. * * For testing, XState provides `SimulatedClock`. * @see {@link Clock} * @see {@link SimulatedClock} */ clock?: Clock; /** * Specifies the logger to be used for `log(...)` actions. Defaults to the * native `console.log(...)` method. */ logger?: (...args: any[]) => void; parent?: AnyActorRef; /** The custom `id` for referencing this service. */ id?: string; /** @deprecated Use `inspect` instead. */ devTools?: never; /** The system ID to register this actor under. */ systemId?: string; /** The input data to pass to the actor. */ input?: InputFrom; /** * Initializes actor logic from a specific persisted internal state. * * @remarks * If the state is compatible with the actor logic, when the actor is started * it will be at that persisted state. Actions from machine actors will not be * re-executed, because they are assumed to have been already executed. * However, invocations will be restarted, and spawned actors will be restored * recursively. * * Can be generated with {@link Actor.getPersistedSnapshot}. * @see https://stately.ai/docs/persistence */ snapshot?: Snapshot; /** @deprecated Use `snapshot` instead. */ state?: Snapshot; /** The source actor logic. */ src?: string | AnyActorLogic; /** * A callback function or observer object which can be used to inspect actor * system updates. * * @remarks * If a callback function is provided, it can accept an inspection event * argument. The types of inspection events that can be observed include: * * - `@xstate.actor` - An actor ref has been created in the system * - `@xstate.event` - An event was sent from a source actor ref to a target * actor ref in the system * - `@xstate.snapshot` - An actor ref emitted a snapshot due to a received * event * * @example * * ```ts * import { createMachine } from 'xstate'; * * const machine = createMachine({ * // ... * }); * * const actor = createActor(machine, { * inspect: (inspectionEvent) => { * if (inspectionEvent.actorRef === actor) { * // This event is for the root actor * } * * if (inspectionEvent.type === '@xstate.actor') { * console.log(inspectionEvent.actorRef); * } * * if (inspectionEvent.type === '@xstate.event') { * console.log(inspectionEvent.sourceRef); * console.log(inspectionEvent.actorRef); * console.log(inspectionEvent.event); * } * * if (inspectionEvent.type === '@xstate.snapshot') { * console.log(inspectionEvent.actorRef); * console.log(inspectionEvent.event); * console.log(inspectionEvent.snapshot); * } * } * }); * ``` * * Alternately, an observer object (`{ next?, error?, complete? }`) can be * provided: * * @example * * ```ts * const actor = createActor(machine, { * inspect: { * next: (inspectionEvent) => { * if (inspectionEvent.actorRef === actor) { * // This event is for the root actor * } * * if (inspectionEvent.type === '@xstate.actor') { * console.log(inspectionEvent.actorRef); * } * * if (inspectionEvent.type === '@xstate.event') { * console.log(inspectionEvent.sourceRef); * console.log(inspectionEvent.actorRef); * console.log(inspectionEvent.event); * } * * if (inspectionEvent.type === '@xstate.snapshot') { * console.log(inspectionEvent.actorRef); * console.log(inspectionEvent.event); * console.log(inspectionEvent.snapshot); * } * } * } * }); * ``` */ inspect?: Observer | ((inspectionEvent: InspectionEvent) => void); } type Observer = { next?: (value: T) => void; error?: (err: unknown) => void; complete?: () => void; }; interface Subscription { unsubscribe(): void; } interface InteropObservable { [Symbol.observable]: () => InteropSubscribable; } interface InteropSubscribable { subscribe(observer: Observer): Subscription; } interface Subscribable extends InteropSubscribable { subscribe(observer: Observer): Subscription; subscribe(next: (value: T) => void, error?: (error: any) => void, complete?: () => void): Subscription; } type EventDescriptorMatches = TEventType extends TNormalizedDescriptor ? true : false; type ExtractEvent> = string extends TEvent['type'] ? TEvent : NormalizeDescriptor extends infer TNormalizedDescriptor ? TEvent extends any ? true extends EventDescriptorMatches ? TEvent : never : never : never; interface ActorRef, TEvent extends EventObject, TEmitted extends EventObject = EventObject> extends Subscribable, InteropObservable { /** The unique identifier for this actor relative to its parent. */ id: string; sessionId: string; send: (event: TEvent) => void; start: () => void; getSnapshot: () => TSnapshot; getPersistedSnapshot: () => Snapshot; stop: () => void; toJSON?: () => any; _parent?: AnyActorRef; system: AnyActorSystem; src: string | AnyActorLogic; on: (type: TType, handler: (emitted: TEmitted & (TType extends '*' ? unknown : { type: TType; })) => void) => Subscription; } type AnyActorRef = ActorRef; type ActorRefLike = Pick; type ActorRefFromLogic = ActorRef, EventFromLogic, EmittedFrom>; interface ActorScope, TEvent extends EventObject, TSystem extends AnyActorSystem = AnyActorSystem, TEmitted extends EventObject = EventObject> { self: ActorRef; id: string; sessionId: string; logger: (...args: any[]) => void; defer: (fn: () => void) => void; emit: (event: TEmitted) => void; system: TSystem; stopChild: (child: AnyActorRef) => void; actionExecutor: ActionExecutor; } type AnyActorScope = ActorScope; type SnapshotStatus = 'active' | 'done' | 'error' | 'stopped'; type Snapshot = { status: 'active'; output: undefined; error: undefined; } | { status: 'done'; output: TOutput; error: undefined; } | { status: 'error'; output: undefined; error: unknown; } | { status: 'stopped'; output: undefined; error: undefined; }; /** * Represents logic which can be used by an actor. * * @template TSnapshot - The type of the snapshot. * @template TEvent - The type of the event object. * @template TInput - The type of the input. * @template TSystem - The type of the actor system. */ interface ActorLogic, // it's invariant because it's also part of `ActorScope["self"]["getSnapshot"]` in out TEvent extends EventObject, // it's invariant because it's also part of `ActorScope["self"]["send"]` in TInput = NonReducibleUnknown, TSystem extends AnyActorSystem = AnyActorSystem, in out TEmitted extends EventObject = EventObject> { /** The initial setup/configuration used to create the actor logic. */ config?: unknown; /** * Transition function that processes the current state and an incoming event * to produce a new state. * * @param snapshot - The current state. * @param event - The incoming event. * @param actorScope - The actor scope. * @returns The new state. */ transition: (snapshot: TSnapshot, event: TEvent, actorScope: ActorScope) => TSnapshot; /** * Called to provide the initial state of the actor. * * @param actorScope - The actor scope. * @param input - The input for the initial state. * @returns The initial state. */ getInitialSnapshot: (actorScope: ActorScope, input: TInput) => TSnapshot; /** * Called when Actor is created to restore the internal state of the actor * given a persisted state. The persisted state can be created by * `getPersistedSnapshot`. * * @param persistedState - The persisted state to restore from. * @param actorScope - The actor scope. * @returns The restored state. */ restoreSnapshot?: (persistedState: Snapshot, actorScope: ActorScope) => TSnapshot; /** * Called when the actor is started. * * @param snapshot - The starting state. * @param actorScope - The actor scope. */ start?: (snapshot: TSnapshot, actorScope: ActorScope) => void; /** * Obtains the internal state of the actor in a representation which can be be * persisted. The persisted state can be restored by `restoreSnapshot`. * * @param snapshot - The current state. * @returns The a representation of the internal state to be persisted. */ getPersistedSnapshot: (snapshot: TSnapshot, options?: unknown) => Snapshot; } type AnyActorLogic = ActorLogic; type UnknownActorLogic = ActorLogic; type SnapshotFrom = ReturnTypeOrValue extends infer R ? R extends ActorRef ? TSnapshot : R extends Actor ? SnapshotFrom : R extends ActorLogic ? ReturnType : R extends ActorScope ? TSnapshot : never : never; type EventFromLogic = TLogic extends ActorLogic ? TEvent : never; type EmittedFrom = TLogic extends ActorLogic ? TEmitted : never; type TODO = any; interface ActorSystemInfo { actors: Record; } type RequiredActorOptions = (undefined extends TActor['id'] ? never : 'id') | (undefined extends InputFrom ? never : 'input'); type RequiredLogicInput = undefined extends InputFrom ? never : 'input'; type StateSchema = { id?: string; states?: Record; type?: unknown; invoke?: unknown; on?: unknown; entry?: unknown; exit?: unknown; onDone?: unknown; after?: unknown; always?: unknown; meta?: unknown; output?: unknown; tags?: unknown; description?: unknown; }; type StateId = (TSchema extends { id: string; } ? TSchema['id'] : TParentKey extends null ? TKey : `${TParentKey}.${TKey}`) | (TSchema['states'] extends Record ? Values<{ [K in keyof TSchema['states'] & string]: StateId; }> : never); interface StateMachineTypes { context: MachineContext; events: EventObject; actors: ProvidedActor; actions: ParameterizedObject; guards: ParameterizedObject; delays: string; tags: string; emitted: EventObject; } /** @deprecated */ interface ResolvedStateMachineTypes { context: TContext; events: TEvent; actors: TActor; actions: TAction; guards: TGuard; delays: TDelay; tags: TTag; emitted: TEmitted; } type GetConcreteByKey = T & Record; interface ExecutableActionObject { type: string; info: ActionArgs; params: NonReducibleUnknown; exec: ((info: ActionArgs, params: unknown) => void) | undefined; } type ActionExecutor = (actionToExecute: ExecutableActionObject) => void; type SpawnOptions = TActor extends { src: TSrc; } ? ConditionalRequired<[ options?: { id?: TActor['id']; systemId?: string; input?: InputFrom; syncSnapshot?: boolean; } & { [K in RequiredActorOptions]: unknown; } ], IsNotNever>> : never; type Spawner = IsLiteralString extends true ? { (logic: TSrc, ...[options]: SpawnOptions): ActorRefFromLogic['logic']>; (src: TLogic, ...[options]: ConditionalRequired<[ options?: { id?: never; systemId?: string; input?: InputFrom; syncSnapshot?: boolean; } & { [K in RequiredLogicInput]: unknown; } ], IsNotNever>>): ActorRefFromLogic; } : (src: TLogic, ...[options]: ConditionalRequired<[ options?: { id?: string; systemId?: string; input?: TLogic extends string ? unknown : InputFrom; syncSnapshot?: boolean; } & (TLogic extends AnyActorLogic ? { [K in RequiredLogicInput]: unknown; } : {}) ], IsNotNever : never>>) => TLogic extends AnyActorLogic ? ActorRefFromLogic : AnyActorRef; declare global { interface SymbolConstructor { readonly observable: symbol; } } declare const Subscriptions = { TaskMonitor: { Updated: 'TaskMonitor.Updated', }, } as const; // If T is an object, it maps over its keys and recursively applies DeepValue to each value. // Finally, it indexes into the resulting mapped type with [keyof T] to form a union of all values. // If T is not an object (i.e. it’s a string), it just returns T. type DeepValue = T extends object ? { [K in keyof T]: DeepValue }[keyof T] : T; type SubscriptionEvents = DeepValue; interface WorkhorseEventMap { // Task notifications 'task.added': { taskId: string }; 'task.success': { taskId: string }; 'task.failure': { taskId: string }; // Actions 'Executors.Start': []; 'Executors.Stop': []; log: { message: string }; // Subscriptions 'TaskMonitor.Updated': { total: number; remaining: number; progress: number; }; } type LogLevel$1 = 'trace' | 'debug' | 'info' | 'warn' | 'error'; interface WorkhorsePlugin$1 { name: string; onStart(): void; onStop(): void; } interface WorkhorseConfig$1 { backoff: BackoffSettings$1; duplicates: DuplicateStrategy$1; concurrency: number; taskExecution: TaskExecutorStrategy$1; logLevel: LogLevel$1; poll: { auto: boolean; interval: number; pre: { wait: 'ready'; timeout?: number; }; }; plugins: WorkhorsePlugin$1[]; } declare enum DuplicateStrategy$1 { IGNORE = "ignore", FORBID = "forbid" } declare enum TaskExecutorStrategy$1 { SERIAL = "serial", PARALLEL = "parallel", DETACHED = "detached" } interface BackoffSettings$1 { initial: number; multiplier: number; maxTime: number; } declare const defaultOptions: () => WorkhorseConfig$1; type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error'; type QueryResult = Record[]; type RunQuery = (query: string) => Promise; type SubscriptionHandler = (payload: WorkhorseEventMap[K]) => void; interface Workhorse { subscribe(event: K, handler: SubscriptionHandler): () => void; queue: (taskId: string, payload: Payload) => Promise; run: (taskId: string, payload: Payload) => Promise; getStatus: () => Promise; startPoller: () => void; stopPoller: () => void; poll: () => Promise; requeue: () => Promise; shutdown: () => Promise; } interface WorkhorsePlugin { name: string; onStart(): void; onStop(): void; } type Inspector = | Observer | ((inspectionEvent: InspectionEvent) => void) | undefined; interface WorkhorseConfig { backoff: BackoffSettings; duplicates: DuplicateStrategy; concurrency: number; taskExecution: TaskExecutorStrategy; logLevel: LogLevel; poll: { auto: boolean; interval: number; pre: { wait: 'ready'; timeout?: number; }; }; plugins: WorkhorsePlugin[]; } interface Factories { createDatabase: (config: WorkhorseConfig) => Promise; createTaskQueue: (config: WorkhorseConfig, runQuery: RunQuery) => TaskQueue; createExecutorHooks: (config: WorkhorseConfig, queue: TaskQueue, run: RunTask) => TaskHooks; createTaskExecutor: ( config: WorkhorseConfig, taskRunner: TaskHooks, inspect?: Inspector ) => SingleTaskExecutor; createExecutorPool: ( config: WorkhorseConfig, executors: SingleTaskExecutor[], inspect?: Inspector ) => TaskExecutorPool; } declare enum TaskState { queued = 1, executing = 2, successful = 3, failed = 4, } type RowId = number; interface TaskRow { id: RowId; taskId: string; payload: Payload; } interface TaskQueue { addTask(taskId: string, payload: Payload): Promise; reserveTask(): Promise; taskSuccessful(taskRow: TaskRow): Promise; taskFailed(taskRow: TaskRow): Promise; requeue: () => Promise; queryTaskCount(status: TaskState): Promise; getStatus(): Promise; } declare enum DuplicateStrategy { // if a task is added with an id that already exist ignore it IGNORE = 'ignore', // if a task is added with an id that already throw an error FORBID = 'forbid', } declare enum TaskExecutorStrategy { // loops over each executor, waits until its ready - and then performs a poll. SERIAL = 'serial', // like 'serial', but stores each wait-promise - and performs a Promise.all() PARALLEL = 'parallel', // does not wait, sends a poll message to executor and immediately returns DETACHED = 'detached', } // Holds TaskExecutors, determined by config.concurrency interface TaskExecutorPool { startAll(): Promise; stopAll(): Promise; pollAll(): Promise