@systemfsoftware/xstate 0.0.0-bootstrap.0 → 6.0.0-beta.65
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +57 -0
- package/LICENSE +22 -0
- package/README.md +640 -2
- package/dist/actors-LxMBvgxO.mjs +472 -0
- package/dist/actors.d.ts +3 -0
- package/dist/actors.mjs +3 -0
- package/dist/base.types-DF8ZPiXj.d.ts +210 -0
- package/dist/createActor-BGHd7i8Q.mjs +4851 -0
- package/dist/durable.d.ts +211 -0
- package/dist/durable.mjs +283 -0
- package/dist/effectDescriptor-EvNuy6U3.d.ts +91 -0
- package/dist/fsm.d.ts +139 -0
- package/dist/fsm.mjs +60 -0
- package/dist/graph.d.ts +160 -0
- package/dist/graph.mjs +667 -0
- package/dist/index-CKUyiMZC.d.ts +1832 -0
- package/dist/index-DDWoKIF5.d.ts +512 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.mjs +7 -0
- package/dist/schema.types-tsIbgQd-.mjs +46 -0
- package/dist/src-zLWug7SF.mjs +2641 -0
- package/dist/transition-ZMXyPI-x.mjs +258 -0
- package/dist/types-B2EAwOk-.d.ts +3511 -0
- package/dist/utils-CXBxxp3Z.mjs +146 -0
- package/dist/validation.d.ts +49 -0
- package/dist/validation.mjs +216 -0
- package/package.json +81 -5
|
@@ -0,0 +1,3511 @@
|
|
|
1
|
+
import { a as InferInternalEvents, d as SetupStateSchemas, f as StandardSchemaV1, i as InferEvents, n as EventObject, o as MachineContext, r as GuardSchemas, t as ActionSchemas, u as Values$1 } from "./base.types-DF8ZPiXj.js";
|
|
2
|
+
/** @public */
|
|
3
|
+
declare function isMachineSnapshot(value: unknown): value is AnyMachineSnapshot;
|
|
4
|
+
type Values<T> = T[keyof T];
|
|
5
|
+
type MatchingObjectStateValue<TStateValue extends Record<string, unknown>, TTestStateValue extends Record<string, unknown>> = false extends Values<{ [K in keyof TTestStateValue]: K extends keyof TStateValue ? NonNullable<TStateValue[K]> extends StateValue ? NonNullable<TTestStateValue[K]> extends StateValue ? [MatchingStateValue<NonNullable<TStateValue[K]>, NonNullable<TTestStateValue[K]>>] extends [never] ? false : true : false : false : false; }> ? never : { [K in keyof TStateValue]: K extends keyof TTestStateValue ? MatchingStateValue<NonNullable<TStateValue[K]>, NonNullable<TTestStateValue[K]>> : TStateValue[K]; };
|
|
6
|
+
type MatchingStateValue<TStateValue extends StateValue, TTestStateValue extends StateValue> = StateValue extends TTestStateValue ? TStateValue : string extends TTestStateValue ? TStateValue : TStateValue extends unknown ? TTestStateValue extends string ? TStateValue extends string ? TTestStateValue extends TStateValue ? TTestStateValue : Extract<TStateValue, TTestStateValue> : TStateValue extends Record<string, unknown> ? TStateValue & Record<TTestStateValue, StateValue | undefined> : never : TTestStateValue extends Record<string, unknown> ? TStateValue extends Record<string, unknown> ? MatchingObjectStateValue<TStateValue, TTestStateValue> : never : never : never;
|
|
7
|
+
interface MachineSnapshotBase<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, _TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema = StateSchema> {
|
|
8
|
+
/** The state machine that produced this state snapshot. */
|
|
9
|
+
machine: AnyStateMachine;
|
|
10
|
+
/** The tags of the active state nodes that represent the current state value. */
|
|
11
|
+
tags: Set<string>;
|
|
12
|
+
/**
|
|
13
|
+
* The current state value.
|
|
14
|
+
*
|
|
15
|
+
* This represents the active state nodes in the state machine.
|
|
16
|
+
*
|
|
17
|
+
* - For atomic state nodes, it is a string.
|
|
18
|
+
* - For compound parent state nodes, it is an object where:
|
|
19
|
+
*
|
|
20
|
+
* - The key is the parent state node's key
|
|
21
|
+
* - The value is the current state value of the active child state node(s)
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
*
|
|
25
|
+
* ```ts
|
|
26
|
+
* // single-level state node
|
|
27
|
+
* snapshot.value; // => 'yellow'
|
|
28
|
+
*
|
|
29
|
+
* // nested state nodes
|
|
30
|
+
* snapshot.value; // => { red: 'wait' }
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
value: TStateValue;
|
|
34
|
+
/** The current status of this snapshot. */
|
|
35
|
+
status: SnapshotStatus;
|
|
36
|
+
error: unknown;
|
|
37
|
+
context: TContext;
|
|
38
|
+
historyValue: Readonly<HistoryValue>;
|
|
39
|
+
/** The enabled state nodes representative of the state value. */
|
|
40
|
+
nodes: Array<AnyStateNode>;
|
|
41
|
+
/** An object mapping actor names to spawned/invoked actors. */
|
|
42
|
+
children: TChildren;
|
|
43
|
+
/** Pending logical timers owned by this machine snapshot. */
|
|
44
|
+
timers: Readonly<Record<string, LogicalTimer>>;
|
|
45
|
+
/**
|
|
46
|
+
* Whether the current state value is a subset of the given partial state
|
|
47
|
+
* value.
|
|
48
|
+
*
|
|
49
|
+
* @param partialStateValue
|
|
50
|
+
*/
|
|
51
|
+
matches<const TTestStateValue extends string>(partialStateValue: TTestStateValue, ...args: string extends TTestStateValue ? [never] : []): this is MachineSnapshot<StateContextFromStateValue<TStateSchema, TContext, TTestStateValue>, TEvent, TChildren, MatchingStateValue<TStateValue, TTestStateValue>, TTag, _TOutput, TMeta, TStateSchema>;
|
|
52
|
+
matches<const TTestStateValue extends StateValueMap>(partialStateValue: TTestStateValue, ...args: string extends keyof TTestStateValue ? [never] : []): this is MachineSnapshot<StateContextFromStateValue<TStateSchema, TContext, TTestStateValue>, TEvent, TChildren, MatchingStateValue<TStateValue, TTestStateValue>, TTag, _TOutput, TMeta, TStateSchema>;
|
|
53
|
+
matches(partialStateValue: StateValue): boolean;
|
|
54
|
+
/**
|
|
55
|
+
* Whether the current state nodes has a state node with the specified `tag`.
|
|
56
|
+
*
|
|
57
|
+
* @param tag
|
|
58
|
+
*/
|
|
59
|
+
hasTag: (tag: TTag) => boolean;
|
|
60
|
+
/**
|
|
61
|
+
* Determines whether sending the `event` will cause a non-forbidden
|
|
62
|
+
* transition to be selected, even if the transitions have no actions nor
|
|
63
|
+
* change the state value.
|
|
64
|
+
*
|
|
65
|
+
* @param event The event to test
|
|
66
|
+
* @returns Whether the event will cause a transition
|
|
67
|
+
*/
|
|
68
|
+
can: (event: TEvent) => boolean;
|
|
69
|
+
getMeta: () => Record<StateId<TStateSchema> & string, TMeta | undefined>;
|
|
70
|
+
/**
|
|
71
|
+
* Returns the inputs for the current active state nodes, keyed by state node
|
|
72
|
+
* id.
|
|
73
|
+
*/
|
|
74
|
+
getInputs: () => StateIdInputs<TStateSchema>;
|
|
75
|
+
toJSON: () => unknown;
|
|
76
|
+
}
|
|
77
|
+
interface ActiveMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema> extends MachineSnapshotBase<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> {
|
|
78
|
+
status: 'active';
|
|
79
|
+
output: undefined;
|
|
80
|
+
error: undefined;
|
|
81
|
+
}
|
|
82
|
+
interface DoneMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema> extends MachineSnapshotBase<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> {
|
|
83
|
+
status: 'done';
|
|
84
|
+
output: TOutput;
|
|
85
|
+
error: undefined;
|
|
86
|
+
}
|
|
87
|
+
interface ErrorMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema> extends MachineSnapshotBase<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> {
|
|
88
|
+
status: 'error';
|
|
89
|
+
output: undefined;
|
|
90
|
+
error: unknown;
|
|
91
|
+
}
|
|
92
|
+
interface StoppedMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema> extends MachineSnapshotBase<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> {
|
|
93
|
+
status: 'stopped';
|
|
94
|
+
output: undefined;
|
|
95
|
+
error: undefined;
|
|
96
|
+
}
|
|
97
|
+
/** @public */
|
|
98
|
+
type MachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema> = ActiveMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> | DoneMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> | ErrorMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema> | StoppedMachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema>;
|
|
99
|
+
/** Type-only metadata for validating setup-created invoke transitions. */
|
|
100
|
+
declare const createdInvokeConfig: unique symbol;
|
|
101
|
+
type InferOutput<T extends StandardSchemaV1, U> = Compute<StandardSchemaV1.InferOutput<T> extends U ? StandardSchemaV1.InferOutput<T> : never>;
|
|
102
|
+
/**
|
|
103
|
+
* The machine input type declared by an input schema, or `unknown` when no
|
|
104
|
+
* input schema is declared (the unresolved schema parameter infers `unknown`).
|
|
105
|
+
*/
|
|
106
|
+
type InferMachineInput<T extends StandardSchemaV1> = unknown extends StandardSchemaV1.InferOutput<T> ? unknown : InferOutput<T, unknown>;
|
|
107
|
+
/**
|
|
108
|
+
* Extracts the machine output type from the config's `output` property: the
|
|
109
|
+
* return type of an output mapper, or the type of a static output value.
|
|
110
|
+
* Falls back to `TFallback` when the config declares no `output`.
|
|
111
|
+
*/
|
|
112
|
+
type OutputFromConfig<TConfig, TFallback> = TConfig extends {
|
|
113
|
+
output: infer TOutput;
|
|
114
|
+
} ? TOutput extends ((...args: never[]) => infer TResult) ? TResult : TOutput : TFallback;
|
|
115
|
+
/**
|
|
116
|
+
* The output type contributed by a single top-level final state: its
|
|
117
|
+
* `schemas.output` if declared, otherwise its `output` mapper's return type
|
|
118
|
+
* (or static value), otherwise `undefined` (a final state with no `output`
|
|
119
|
+
* completes the machine with `undefined` output).
|
|
120
|
+
*/
|
|
121
|
+
type FinalStateConfigOutput<TStateConfig> = TStateConfig extends {
|
|
122
|
+
schemas: {
|
|
123
|
+
output: infer TOutputSchema extends StandardSchemaV1;
|
|
124
|
+
};
|
|
125
|
+
} ? StandardSchemaV1.InferOutput<TOutputSchema> : OutputFromConfig<TStateConfig, undefined>;
|
|
126
|
+
/**
|
|
127
|
+
* The union of output types across the config's top-level final states, or
|
|
128
|
+
* `never` when it has none. Reaching a top-level final state completes the
|
|
129
|
+
* machine with that state's output when no root `output` mapper is declared.
|
|
130
|
+
*/
|
|
131
|
+
type TopLevelFinalOutput<TConfig> = TConfig extends {
|
|
132
|
+
states: infer TStates;
|
|
133
|
+
} ? { [K in keyof TStates]: TStates[K] extends {
|
|
134
|
+
type: 'final';
|
|
135
|
+
} ? FinalStateConfigOutput<TStates[K]> : never; }[keyof TStates] : never;
|
|
136
|
+
/**
|
|
137
|
+
* The machine's output type when no output schema is declared in `setup()`: a
|
|
138
|
+
* declared `schemas.output` is authoritative, otherwise the output type is
|
|
139
|
+
* inferred from the config's `output` property, falling back to the union of
|
|
140
|
+
* top-level final-state output types.
|
|
141
|
+
*/
|
|
142
|
+
type SchemaOrConfigOutput<TOutputSchema extends StandardSchemaV1, TConfig> = StandardSchemaV1 extends TOutputSchema ? OutputFromConfig<TConfig, [TopLevelFinalOutput<TConfig>] extends [never] ? InferOutput<TOutputSchema, unknown> : TopLevelFinalOutput<TConfig>> : InferOutput<TOutputSchema, unknown>;
|
|
143
|
+
type InferChildren<TChildrenSchemaMap extends Record<string, StandardSchemaV1>> = string extends keyof TChildrenSchemaMap ? {} : { [K in keyof TChildrenSchemaMap & string]?: StandardSchemaV1.InferOutput<TChildrenSchemaMap[K]> extends AnyActorRef ? NormalizeActorRef<StandardSchemaV1.InferOutput<TChildrenSchemaMap[K]>> : never; };
|
|
144
|
+
type InferActions<TActionSchemaMap extends ActionSchemas> = string extends keyof TActionSchemaMap ? {} : { [K in keyof TActionSchemaMap & string]: (params: StandardSchemaV1.InferOutput<TActionSchemaMap[K]['params']>) => void | {
|
|
145
|
+
context?: any;
|
|
146
|
+
children?: any;
|
|
147
|
+
}; };
|
|
148
|
+
type InferGuards<TGuardSchemaMap extends GuardSchemas> = string extends keyof TGuardSchemaMap ? {} : { [K in keyof TGuardSchemaMap & string]: (params: StandardSchemaV1.InferOutput<TGuardSchemaMap[K]['params']>) => boolean; };
|
|
149
|
+
type OutputMapper<TContext extends MachineContext, TEvent extends EventObject, TResult, TInput = Record<string, unknown> | undefined> = (args: Parameters<Mapper<TContext, TEvent, TResult, TEvent>>[0] & {
|
|
150
|
+
input: TInput;
|
|
151
|
+
}) => TResult;
|
|
152
|
+
type OutputConfig<TContext extends MachineContext, TEvent extends EventObject, TOutput, TInput = Record<string, unknown> | undefined> = unknown extends TOutput ? OutputMapper<TContext, TEvent, NonReducibleUnknown, TInput> | NonReducibleUnknown : OutputMapper<TContext, TEvent, TOutput, TInput> | TOutput;
|
|
153
|
+
type ValidateTopLevelFinalOutputs<TConfig, TContext extends MachineContext, TEvent extends EventObject> = TConfig extends {
|
|
154
|
+
schemas: {
|
|
155
|
+
output: infer TOutputSchema extends StandardSchemaV1;
|
|
156
|
+
};
|
|
157
|
+
states: infer TStates;
|
|
158
|
+
} ? {
|
|
159
|
+
states?: { [K in keyof TStates]: TStates[K] extends {
|
|
160
|
+
type: 'final';
|
|
161
|
+
} ? TStates[K] & {
|
|
162
|
+
output?: OutputConfig<TContext, TEvent, StandardSchemaV1.InferOutput<TOutputSchema>>;
|
|
163
|
+
} : TStates[K]; };
|
|
164
|
+
} : {};
|
|
165
|
+
type NormalizeActorRef<TActorRef> = TActorRef extends ActorRef<infer TSnapshot, infer TEvent, infer TEmitted, infer TSendEvent> ? ActorRef<TSnapshot, TEvent, TEmitted, TSendEvent> : never;
|
|
166
|
+
type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
|
|
167
|
+
/**
|
|
168
|
+
* Runtime options for state machine execution.
|
|
169
|
+
*
|
|
170
|
+
* @example
|
|
171
|
+
*
|
|
172
|
+
* ```ts
|
|
173
|
+
* const machine = createMachine({
|
|
174
|
+
* // ... machine config
|
|
175
|
+
* options: {
|
|
176
|
+
* maxIterations: 5000
|
|
177
|
+
* // other runtime options can be added here
|
|
178
|
+
* }
|
|
179
|
+
* });
|
|
180
|
+
* ```
|
|
181
|
+
*/
|
|
182
|
+
interface MachineOptions {
|
|
183
|
+
/**
|
|
184
|
+
* Maximum number of microsteps one macrostep may take before an
|
|
185
|
+
* `InfiniteTransitionError` is thrown. Raise it for machines that
|
|
186
|
+
* legitimately take many eventless or raised-event steps per event.
|
|
187
|
+
*
|
|
188
|
+
* @default 1000
|
|
189
|
+
*/
|
|
190
|
+
maxIterations?: number;
|
|
191
|
+
}
|
|
192
|
+
type MachineSchemas<TContextSchema extends StandardSchemaV1, TEventSchemaMap extends Record<string, StandardSchemaV1>, TInternalEventSchemaMap extends Record<string, StandardSchemaV1>, TEmittedSchemaMap extends Record<string, StandardSchemaV1>, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TTransitionMetaSchema extends StandardSchemaV1, TTagSchema extends StandardSchemaV1, TChildrenSchemaMap extends Record<string, StandardSchemaV1>> = {
|
|
193
|
+
events?: TEventSchemaMap;
|
|
194
|
+
internalEvents?: TInternalEventSchemaMap;
|
|
195
|
+
actions?: ActionSchemas;
|
|
196
|
+
guards?: GuardSchemas;
|
|
197
|
+
context?: TContextSchema;
|
|
198
|
+
emitted?: TEmittedSchemaMap;
|
|
199
|
+
input?: TInputSchema;
|
|
200
|
+
output?: TOutputSchema;
|
|
201
|
+
meta?: TMetaSchema;
|
|
202
|
+
transitionMeta?: TTransitionMetaSchema;
|
|
203
|
+
tags?: TTagSchema;
|
|
204
|
+
children?: TChildrenSchemaMap;
|
|
205
|
+
};
|
|
206
|
+
type AnyMachineSchemas = MachineSchemas<StandardSchemaV1, Record<string, StandardSchemaV1>, Record<string, StandardSchemaV1>, Record<string, StandardSchemaV1>, StandardSchemaV1, StandardSchemaV1, StandardSchemaV1, StandardSchemaV1, StandardSchemaV1, Record<string, StandardSchemaV1>>;
|
|
207
|
+
/**
|
|
208
|
+
* The v5 `types` key has no v6 equivalent. Typing it as this message makes the
|
|
209
|
+
* compiler print the replacement rather than accepting dead configuration.
|
|
210
|
+
*/
|
|
211
|
+
type RemovedTypesKey = '`types` was replaced by `schemas` in v6. Declare `context`, `events` and the other contracts under `schemas`, or run `xstate-codemod migrate --transform types-to-schemas`.';
|
|
212
|
+
/** @public */
|
|
213
|
+
type Next_MachineConfig<TContextSchema extends StandardSchemaV1, TEventSchemaMap extends Record<string, StandardSchemaV1>, TInternalEventSchemaMap extends Record<string, StandardSchemaV1>, TEmittedSchemaMap extends Record<string, StandardSchemaV1>, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TTransitionMetaSchema extends StandardSchemaV1, TTagSchema extends StandardSchemaV1, TChildrenSchemaMap extends Record<string, StandardSchemaV1>, TContext extends MachineContext = InferOutput<TContextSchema, MachineContext>, TEvent extends EventObject = InferEvents<TEventSchemaMap> | InferInternalEvents<TInternalEventSchemaMap>, TChildren extends Record<string, AnyActorRef | undefined> = InferChildren<TChildrenSchemaMap>, TDelays extends string = string, _TTag extends string = string, TActionMap extends Sources['actions'] = Sources['actions'], TActorMap extends Sources['actors'] = Sources['actors'], TGuardMap extends Sources['guards'] = Sources['guards'], TDelayMap extends Sources['delays'] = Sources['delays'], TContextRequired extends boolean = IsNever<TContext> extends true ? false : true, TSystemRegistry extends SystemRegistry = SystemRegistry> = (DistributiveOmit<Next_StateNodeConfig<TContext, DoNotInfer<TEvent>, DoNotInfer<TDelays>, DoNotInfer<StandardSchemaV1.InferOutput<TTagSchema> & string>, DoNotInfer<StandardSchemaV1.InferOutput<TOutputSchema>>, DoNotInfer<InferEvents<TEmittedSchemaMap>>, DoNotInfer<InferOutput<TMetaSchema, MetaObject>>, DoNotInfer<TChildren>, DoNotInfer<TActionMap>, DoNotInfer<TActorMap>, DoNotInfer<TGuardMap>, DoNotInfer<TDelayMap>, Record<string, unknown> | undefined, Record<string, unknown>, DoNotInfer<TSystemRegistry>, DoNotInfer<InferOutput<TOutputSchema, unknown>>, DoNotInfer<StandardSchemaV1 extends TTransitionMetaSchema ? InferOutput<TMetaSchema, MetaObject> : InferOutput<TTransitionMetaSchema, MetaObject>>>, 'output' | 'schemas'> & {
|
|
214
|
+
/**
|
|
215
|
+
* Declared only so that a leftover v5 `types` key is rejected instead of
|
|
216
|
+
* being accepted and silently ignored: nothing reads it in v6.
|
|
217
|
+
*/
|
|
218
|
+
types?: RemovedTypesKey;
|
|
219
|
+
schemas?: MachineSchemas<TContextSchema, TEventSchemaMap, TInternalEventSchemaMap, TEmittedSchemaMap, TInputSchema, TOutputSchema, TMetaSchema, TTransitionMetaSchema, TTagSchema, TChildrenSchemaMap>;
|
|
220
|
+
actions?: TActionMap;
|
|
221
|
+
guards?: TGuardMap & GuardSourceMap<TContext, TEvent>;
|
|
222
|
+
actors?: TActorMap;
|
|
223
|
+
/** The machine's own version. */
|
|
224
|
+
version?: string;
|
|
225
|
+
/**
|
|
226
|
+
* Migrates a persisted snapshot created by a different version of this
|
|
227
|
+
* machine to the current `version`. Called during restore when the persisted
|
|
228
|
+
* snapshot's `version` does not match the machine's `version` (`fromVersion`
|
|
229
|
+
* is the persisted version, possibly `undefined`). Restoring a
|
|
230
|
+
* version-mismatched snapshot without a `migrate` function throws.
|
|
231
|
+
*/
|
|
232
|
+
migrate?: (persistedSnapshot: any, fromVersion: string | undefined) => unknown;
|
|
233
|
+
output?: Mapper<TContext, DoneStateEvent<DoNotInfer<InferOutput<TOutputSchema, unknown>>>, DoNotInfer<InferOutput<TOutputSchema, unknown>>, TEvent> | DoNotInfer<InferOutput<TOutputSchema, unknown>>;
|
|
234
|
+
delays?: { [K in TDelays | number]?: number | (({ context, event, stateNode }: {
|
|
235
|
+
context: TContext;
|
|
236
|
+
event: TEvent;
|
|
237
|
+
stateNode: AnyStateNode;
|
|
238
|
+
}) => number); };
|
|
239
|
+
options?: MachineOptions;
|
|
240
|
+
}) & (TContextRequired extends false ? {
|
|
241
|
+
context?: InitialContext<LowInfer<TContext>, TActorMap, InferOutput<TInputSchema, unknown>, TEvent>;
|
|
242
|
+
} : {
|
|
243
|
+
context: InitialContext<LowInfer<TContext>, TActorMap, InferOutput<TInputSchema, unknown>, TEvent>;
|
|
244
|
+
});
|
|
245
|
+
/**
|
|
246
|
+
* Recursively widens literal types and strips `readonly`. Used to widen context
|
|
247
|
+
* inferred from a literal initial value: `{ count: 0 }` becomes
|
|
248
|
+
* `{ count: number }`, since `createMachine`'s `const` state-schema inference
|
|
249
|
+
* would otherwise freeze context at its initial literal type and make every
|
|
250
|
+
* context update a type error.
|
|
251
|
+
*
|
|
252
|
+
* @public
|
|
253
|
+
*/
|
|
254
|
+
type WidenLiterals<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends bigint ? bigint : T extends ((...args: any[]) => any) ? T : T extends readonly (infer U)[] ? WidenLiterals<U>[] : T extends object ? { -readonly [K in keyof T]: WidenLiterals<T[K]>; } : T;
|
|
255
|
+
type InvokeSrcArgs<TContext extends MachineContext, TEvent extends EventObject, TActorMap extends Sources['actors']> = {
|
|
256
|
+
actors: TActorMap;
|
|
257
|
+
context: TContext;
|
|
258
|
+
event: TEvent;
|
|
259
|
+
self: AnyActorRef;
|
|
260
|
+
};
|
|
261
|
+
type InvokeInputArgs<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TInput = undefined> = {
|
|
262
|
+
context: TContext;
|
|
263
|
+
event: TEvent;
|
|
264
|
+
input: TInput;
|
|
265
|
+
self: ActorSelf<MachineSnapshot<TContext, TEvent, TChildren, StateValue, string, unknown, TODO, TODO>, TEvent, TEmitted>;
|
|
266
|
+
};
|
|
267
|
+
type HasExplicitChildren<TChildren extends Record<string, AnyActorRef | undefined>> = string extends keyof TChildren ? false : [keyof TChildren] extends [never] ? false : true;
|
|
268
|
+
/**
|
|
269
|
+
* @public Completion events (`xstate.done.actor` / `xstate.error.actor`) of
|
|
270
|
+
* the children declared in `schemas.children`, keyed by `actorId`. Folded into
|
|
271
|
+
* the event union seen by `entry`, `exit`, guards and transition functions.
|
|
272
|
+
*/
|
|
273
|
+
type ChildCompletionEvents<TChildren extends Record<string, AnyActorRef | undefined>> = HasExplicitChildren<TChildren> extends true ? Values$1<{ [K in keyof TChildren & string]: DoneActorEvent<OutputFrom<NonNullable<TChildren[K]>>, K> | ErrorActorEvent<ErrorFrom<NonNullable<TChildren[K]>>, K>; }> : never;
|
|
274
|
+
type ChildIdForLogic<TLogic extends AnyActorLogic, TChildren extends Record<string, AnyActorRef | undefined>> = HasExplicitChildren<TChildren> extends true ? Values$1<{ [K in keyof TChildren & string]: ActorRefFromLogic<TLogic> extends NonNullable<TChildren[K]> ? K : never; }> : string;
|
|
275
|
+
type LogicForChildRef<TActorRef> = NonNullable<TActorRef> extends ActorRef<infer TSnapshot, infer TEvent, infer TEmitted, any> ? ActorLogic<TSnapshot, TEvent, any, any, TEmitted> : never;
|
|
276
|
+
/**
|
|
277
|
+
* The `onDone` config for inline (unregistered-logic) invoke branches.
|
|
278
|
+
*
|
|
279
|
+
* When the actor map has registered sources, this deliberately has no
|
|
280
|
+
* function forms (no transition function, no context mapper): passing a
|
|
281
|
+
* registered logic value as `src` makes TypeScript narrow the invoke union to
|
|
282
|
+
* the matching registered branch plus the inline branch, and per-actor
|
|
283
|
+
* `event.output` inference in `onDone` callbacks only survives if the
|
|
284
|
+
* registered branch contributes the union's only call signature. Inline
|
|
285
|
+
* (unregistered) logic in such setups can use the object/target forms, or be
|
|
286
|
+
* registered to get function-form transitions.
|
|
287
|
+
*
|
|
288
|
+
* With no registered sources (empty or permissive maps) there is no competing
|
|
289
|
+
* branch, so the full transition config is allowed.
|
|
290
|
+
*/
|
|
291
|
+
type InlineInvokeOnDone<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, TChildren extends Record<string, AnyActorRef | undefined>> = [keyof TActorMap & string] extends [never] ? Next_TransitionConfigOrTarget<TContext, DoneActorEvent<any>, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, undefined, TChildren> : string extends keyof TActorMap ? Next_TransitionConfigOrTarget<TContext, DoneActorEvent<OutputFrom<TActorMap[keyof TActorMap & string]>>, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, undefined, TChildren> : undefined | {
|
|
292
|
+
matches?: EventPayloadPattern<DoneActorEvent>;
|
|
293
|
+
target?: string | string[];
|
|
294
|
+
context?: TransitionContextPatch<TContext>;
|
|
295
|
+
description?: string;
|
|
296
|
+
reenter?: boolean;
|
|
297
|
+
meta?: TMeta;
|
|
298
|
+
input?: Record<string, unknown> | ((args: {
|
|
299
|
+
context: any;
|
|
300
|
+
event: any;
|
|
301
|
+
}) => Record<string, unknown>);
|
|
302
|
+
};
|
|
303
|
+
type InlineChildInvokeConfig<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, TSystemRegistry extends SystemRegistry, TInput = undefined> = Values$1<{ [K in keyof TChildren & string]: Omit<Next_InvokeConfigBase<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TSystemRegistry>, 'onDone'> & {
|
|
304
|
+
onDone?: InlineInvokeOnDone<TContext, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TChildren>;
|
|
305
|
+
id: K;
|
|
306
|
+
src: LogicForChildRef<TChildren[K]>;
|
|
307
|
+
input?: ((args: InvokeInputArgs<TContext, TEvent, TEmitted, TChildren, TInput>) => unknown) | NonReducibleUnknown;
|
|
308
|
+
}; }>;
|
|
309
|
+
type InlineInvokeConfig<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, TSystemRegistry extends SystemRegistry, TInput = undefined> = HasExplicitChildren<TChildren> extends true ? InlineChildInvokeConfig<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TSystemRegistry, TInput> : Omit<Next_InvokeConfigBase<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TSystemRegistry>, 'onDone'> & {
|
|
310
|
+
onDone?: InlineInvokeOnDone<TContext, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TChildren>;
|
|
311
|
+
src: AnyActorLogic;
|
|
312
|
+
input?: ((args: InvokeInputArgs<TContext, TEvent, TEmitted, TChildren, TInput>) => unknown) | NonReducibleUnknown;
|
|
313
|
+
};
|
|
314
|
+
/**
|
|
315
|
+
* Invoke config. A union of:
|
|
316
|
+
*
|
|
317
|
+
* - One branch per registered actor source (distributed over the `actors` map),
|
|
318
|
+
* where `src` — a key, the logic itself, or a resolver function returning
|
|
319
|
+
* either — is correlated with `input`, so static and mapped inputs typecheck
|
|
320
|
+
* against that logic's input type.
|
|
321
|
+
* - A branch for inline (unregistered) actor logic values, whose `input` cannot
|
|
322
|
+
* be correlated (the config is not generic over inline logic).
|
|
323
|
+
*
|
|
324
|
+
* @public
|
|
325
|
+
*/
|
|
326
|
+
type Next_InvokeConfig<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, TSystemRegistry extends SystemRegistry = SystemRegistry, TInput = undefined> = string extends keyof TActorMap ? HasExplicitChildren<TChildren> extends true ? InlineInvokeConfig<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TSystemRegistry, TInput> : Next_InvokeConfigBase<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TSystemRegistry> & {
|
|
327
|
+
src: string | AnyActorLogic | ((args: InvokeSrcArgs<TContext, TEvent, TActorMap>) => string | AnyActorLogic);
|
|
328
|
+
input?: ((args: InvokeInputArgs<TContext, TEvent, TEmitted, TChildren, TInput>) => unknown) | NonReducibleUnknown;
|
|
329
|
+
} : { [K in keyof TActorMap & string]: Next_InvokeConfigBase<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TSystemRegistry, DoneActorEvent<OutputFrom<TActorMap[K]>>, ErrorActorEvent<ErrorFrom<TActorMap[K]>>> & {
|
|
330
|
+
id?: ChildIdForLogic<TActorMap[K], TChildren>;
|
|
331
|
+
input?: ((args: InvokeInputArgs<TContext, TEvent, TEmitted, TChildren, TInput>) => InputFrom<TActorMap[K]>) | InputFrom<TActorMap[K]>;
|
|
332
|
+
} & ({
|
|
333
|
+
src: K;
|
|
334
|
+
} | {
|
|
335
|
+
src: TActorMap[K];
|
|
336
|
+
} | {
|
|
337
|
+
src: (args: InvokeSrcArgs<TContext, TEvent, TActorMap>) => K | TActorMap[K];
|
|
338
|
+
}); }[keyof TActorMap & string] | InlineInvokeConfig<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TSystemRegistry, TInput>;
|
|
339
|
+
interface Next_InvokeConfigBase<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, TSystemRegistry extends SystemRegistry, TDoneEvent extends EventObject = [keyof TActorMap & string] extends [never] ? DoneActorEvent<any> : DoneActorEvent<OutputFrom<TActorMap[keyof TActorMap & string]>>, TErrorEvent extends EventObject = [keyof TActorMap & string] extends [never] ? ErrorActorEvent<any> : ErrorActorEvent<ErrorFrom<TActorMap[keyof TActorMap & string]>>> {
|
|
340
|
+
id?: string;
|
|
341
|
+
registryKey?: keyof TSystemRegistry & string;
|
|
342
|
+
onDone?: Next_TransitionConfigOrTarget<TContext, TDoneEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, undefined, TChildren>;
|
|
343
|
+
onError?: Next_TransitionConfigOrTarget<TContext, TErrorEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, undefined, TChildren>;
|
|
344
|
+
onSnapshot?: Next_TransitionConfigOrTarget<TContext, SnapshotEvent<any>, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, undefined, TChildren>;
|
|
345
|
+
/**
|
|
346
|
+
* The duration (in ms) after which this invocation will time out if it has
|
|
347
|
+
* not completed. "This task is taking too long."
|
|
348
|
+
*
|
|
349
|
+
* When the timeout expires, the `onTimeout` transition is taken. If the
|
|
350
|
+
* invoke completes first, the timeout is cancelled.
|
|
351
|
+
*/
|
|
352
|
+
timeout?: number | ((args: {
|
|
353
|
+
context: TContext;
|
|
354
|
+
event: TEvent;
|
|
355
|
+
}) => number);
|
|
356
|
+
/**
|
|
357
|
+
* Transition taken when the invoke-level `timeout` expires. Required when
|
|
358
|
+
* `timeout` is set on an invoke.
|
|
359
|
+
*/
|
|
360
|
+
onTimeout?: Next_TransitionConfigOrTarget<TContext, ActorTimeoutEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, undefined, TChildren>;
|
|
361
|
+
}
|
|
362
|
+
/** Lookup state input type from an input map, with fallback to undefined */
|
|
363
|
+
type LookupInput<TInputMap extends Record<string, unknown>, K extends string> = K extends keyof TInputMap ? TInputMap[K] : undefined;
|
|
364
|
+
type StateAction<TContext extends MachineContext, TEvent extends EventObject, TEmittedEvent extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TInput = Record<string, unknown> | undefined, TChildren extends Record<string, AnyActorRef | undefined> = {}> = (_: Omit<Parameters<Action<TContext, TEvent, TEmittedEvent, TActionMap, TActorMap, TGuardMap, TDelayMap, never>>[0], 'params'> & {
|
|
365
|
+
input: TInput;
|
|
366
|
+
/** The state node being entered (`entry`) or exited (`exit`). */
|
|
367
|
+
stateNode: AnyStateNode;
|
|
368
|
+
}, enqueue: EnqueueObject<TEvent, TEmittedEvent, SystemRegistry, TActorMap, TChildren>) => ReturnType<Action<TContext, TEvent, TEmittedEvent, TActionMap, TActorMap, TGuardMap, TDelayMap, never>>;
|
|
369
|
+
type Next_ChoiceTarget<TMeta extends MetaObject> = {
|
|
370
|
+
target: string | string[];
|
|
371
|
+
description?: string;
|
|
372
|
+
reenter?: boolean;
|
|
373
|
+
meta?: TMeta;
|
|
374
|
+
input?: Record<string, unknown> | ((args: {
|
|
375
|
+
context: any;
|
|
376
|
+
event: any;
|
|
377
|
+
}) => Record<string, unknown>);
|
|
378
|
+
};
|
|
379
|
+
type Next_ChoiceArgs<TContext extends MachineContext, TCurrentEvent extends EventObject, TEvent extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], _TCtx extends MachineContext = [TContext] extends [never] ? any : TContext> = Parameters<TransitionConfigFunction<TContext, TCurrentEvent, TEvent, EventObject, TActionMap, TActorMap, TGuardMap, TDelayMap, MetaObject, undefined, // TInput
|
|
380
|
+
_TCtx>>[0];
|
|
381
|
+
/**
|
|
382
|
+
* Route config: either a static config object, or a transition-style function
|
|
383
|
+
* that acts as the route's guard and resolver — returning `undefined`/`false`
|
|
384
|
+
* blocks the route; returning `true` or a config object allows it (optionally
|
|
385
|
+
* updating `context` and providing `input`/`reenter`/`meta`).
|
|
386
|
+
*
|
|
387
|
+
* Guard objects/strings on routes are only produced by the JSON layer
|
|
388
|
+
* (`createMachineFromConfig`) — authoring uses the function form.
|
|
389
|
+
*/
|
|
390
|
+
type Next_RouteConfig<TContext extends MachineContext, TEvent extends EventObject, TMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> = {
|
|
391
|
+
description?: string;
|
|
392
|
+
reenter?: boolean;
|
|
393
|
+
meta?: TMeta;
|
|
394
|
+
input?: Record<string, unknown> | ((args: {
|
|
395
|
+
context: any;
|
|
396
|
+
event: any;
|
|
397
|
+
}) => Record<string, unknown>);
|
|
398
|
+
} | ((args: Next_ChoiceArgs<TContext, TEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap>) => boolean | void | {
|
|
399
|
+
context?: TContext;
|
|
400
|
+
reenter?: boolean;
|
|
401
|
+
meta?: TMeta;
|
|
402
|
+
input?: Record<string, unknown> | ((args: {
|
|
403
|
+
context: any;
|
|
404
|
+
event: any;
|
|
405
|
+
}) => Record<string, unknown>);
|
|
406
|
+
});
|
|
407
|
+
type Next_ChoiceConfigFunction<TContext extends MachineContext, TCurrentEvent extends EventObject, TEvent extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, _TCtx extends MachineContext = [TContext] extends [never] ? any : TContext> = (args: Next_ChoiceArgs<TContext, TCurrentEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap, _TCtx>) => Next_ChoiceTarget<TMeta>;
|
|
408
|
+
/** @public */
|
|
409
|
+
type Next_StateNodeConfig<TContext extends MachineContext, TEvent extends EventObject, TDelays extends string, TTag extends string, _TOutput, TEmitted extends EventObject, TStateMeta extends MetaObject, TChildren extends Record<string, AnyActorRef | undefined>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TInput = Record<string, unknown> | undefined, TInputMap extends Record<string, unknown> = Record<string, unknown>, TSystemRegistry extends SystemRegistry = SystemRegistry, TChildOutput = unknown, TTransitionMeta extends MetaObject = TStateMeta> = Next_RegularStateNodeConfig<TContext, TEvent, TDelays, TTag, _TOutput, TEmitted, TStateMeta, TTransitionMeta, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TInput, TInputMap, TSystemRegistry, TChildOutput> | Next_ChoiceStateNodeConfig<TContext, TEvent, TTag, TStateMeta, TTransitionMeta, TActionMap, TActorMap, TGuardMap, TDelayMap>;
|
|
410
|
+
/** @public Referenced by emitted declarations of `Next_StateNodeConfig`. */
|
|
411
|
+
interface Next_ChoiceStateNodeConfig<TContext extends MachineContext, TEvent extends EventObject, TTag extends string, TStateMeta extends MetaObject, TTransitionMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> {
|
|
412
|
+
contextSchema?: StandardSchemaV1;
|
|
413
|
+
schemas?: SetupStateSchemas;
|
|
414
|
+
type: 'choice';
|
|
415
|
+
/** Function that resolves this choice state to a target. */
|
|
416
|
+
choice: Next_ChoiceConfigFunction<TContext, TEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta>;
|
|
417
|
+
id?: string | undefined;
|
|
418
|
+
order?: number;
|
|
419
|
+
tags?: TTag[];
|
|
420
|
+
description?: string;
|
|
421
|
+
meta?: TStateMeta;
|
|
422
|
+
route?: Next_RouteConfig<TContext, TEvent, TTransitionMeta, TActionMap, TActorMap, TGuardMap, TDelayMap> | undefined;
|
|
423
|
+
initial?: never;
|
|
424
|
+
history?: never;
|
|
425
|
+
states?: never;
|
|
426
|
+
invoke?: never;
|
|
427
|
+
on?: never;
|
|
428
|
+
entry?: never;
|
|
429
|
+
exit?: never;
|
|
430
|
+
onDone?: never;
|
|
431
|
+
onError?: never;
|
|
432
|
+
after?: never;
|
|
433
|
+
timeout?: never;
|
|
434
|
+
onTimeout?: never;
|
|
435
|
+
always?: never;
|
|
436
|
+
output?: never;
|
|
437
|
+
target?: never;
|
|
438
|
+
}
|
|
439
|
+
/** @public Referenced by emitted declarations of `Next_StateNodeConfig`. */
|
|
440
|
+
interface Next_RegularStateNodeConfig<TContext extends MachineContext, TEvent extends EventObject, TDelays extends string, TTag extends string, TOutput, TEmitted extends EventObject, TStateMeta extends MetaObject, TTransitionMeta extends MetaObject, TChildren extends Record<string, AnyActorRef | undefined>, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TInput = Record<string, unknown> | undefined, TInputMap extends Record<string, unknown> = Record<string, unknown>, TSystemRegistry extends SystemRegistry = SystemRegistry, TChildOutput = unknown> {
|
|
441
|
+
contextSchema?: StandardSchemaV1;
|
|
442
|
+
schemas?: SetupStateSchemas;
|
|
443
|
+
/** The initial state transition. */
|
|
444
|
+
initial?: string | {
|
|
445
|
+
target: string;
|
|
446
|
+
meta?: TTransitionMeta;
|
|
447
|
+
description?: string;
|
|
448
|
+
input?: Record<string, unknown> | ((args: {
|
|
449
|
+
context: TContext;
|
|
450
|
+
event: TEvent;
|
|
451
|
+
}) => Record<string, unknown>);
|
|
452
|
+
} | undefined;
|
|
453
|
+
/**
|
|
454
|
+
* The type of this state node:
|
|
455
|
+
*
|
|
456
|
+
* - `'atomic'` - no child state nodes
|
|
457
|
+
* - `'compound'` - nested child state nodes (XOR)
|
|
458
|
+
* - `'parallel'` - orthogonal nested child state nodes (AND)
|
|
459
|
+
* - `'history'` - history state node
|
|
460
|
+
* - `'final'` - final state node
|
|
461
|
+
*/
|
|
462
|
+
type?: 'atomic' | 'compound' | 'parallel' | 'final' | 'history';
|
|
463
|
+
/**
|
|
464
|
+
* Indicates whether the state node is a history state node, and what type of
|
|
465
|
+
* history: shallow, deep, true (shallow), false (none), undefined (none)
|
|
466
|
+
*/
|
|
467
|
+
history?: 'shallow' | 'deep' | boolean | undefined;
|
|
468
|
+
/**
|
|
469
|
+
* The mapping of state node keys to their state node configurations
|
|
470
|
+
* (recursive).
|
|
471
|
+
*/
|
|
472
|
+
states?: { [K in string]: Next_StateNodeConfig<TContext, TEvent, TDelays, TTag, any, // TOutput,
|
|
473
|
+
TEmitted, TStateMeta, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, LookupInput<TInputMap, K>, TInputMap, TSystemRegistry, TChildOutput, TTransitionMeta>; };
|
|
474
|
+
/**
|
|
475
|
+
* The services to invoke upon entering this state node. These services will
|
|
476
|
+
* be stopped upon exiting this state node.
|
|
477
|
+
*/
|
|
478
|
+
invoke?: SingleOrArray<Next_InvokeConfig<TContext, TEvent, TEmitted, TChildren, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, TSystemRegistry, TInput>>;
|
|
479
|
+
/** The mapping of event types to their potential transition(s). */
|
|
480
|
+
on?: { [K in EventDescriptor<TEvent>]?: Next_TransitionConfigOrTarget<TContext, ExtractEvent<TEvent, K>, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, TInput, TChildren>; } & (string extends TEvent['type'] ? unknown : { [K in `xstate.${string}`]?: Next_TransitionConfigOrTarget<TContext, {
|
|
481
|
+
type: K;
|
|
482
|
+
}, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, TInput, TChildren>; });
|
|
483
|
+
/**
|
|
484
|
+
* Enables routing to this state via `{ type: 'xstate.route', to: '#id' }`.
|
|
485
|
+
* Requires this state node to have an explicit `id`.
|
|
486
|
+
*/
|
|
487
|
+
route?: Next_RouteConfig<TContext, TEvent, TTransitionMeta, TActionMap, TActorMap, TGuardMap, TDelayMap> | undefined;
|
|
488
|
+
entry?: StateAction<TContext, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TInput, TChildren>;
|
|
489
|
+
exit?: StateAction<TContext, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TInput, TChildren>;
|
|
490
|
+
/**
|
|
491
|
+
* The potential transition(s) to be taken upon reaching a final child state
|
|
492
|
+
* node.
|
|
493
|
+
*
|
|
494
|
+
* This is equivalent to defining a `[done(id)]` transition on this state
|
|
495
|
+
* node's `on` property.
|
|
496
|
+
*/
|
|
497
|
+
onDone?: Next_TransitionConfigOrTarget<TContext, DoneStateEvent<TChildOutput>, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, undefined, TChildren>;
|
|
498
|
+
/**
|
|
499
|
+
* The transition to take when an `xstate.error.*` event is raised while this
|
|
500
|
+
* state node or one of its descendants is active.
|
|
501
|
+
*/
|
|
502
|
+
onError?: Next_TransitionConfigOrTarget<TContext, ErrorEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, undefined, TChildren>;
|
|
503
|
+
/**
|
|
504
|
+
* The mapping (or array) of delays (in milliseconds) to their potential
|
|
505
|
+
* transition(s). The delayed transitions are taken after the specified delay
|
|
506
|
+
* in an interpreter.
|
|
507
|
+
*/
|
|
508
|
+
after?: { [K in NoInfer<TDelays> | number | DelayDurationKey]?: Next_StaticTransitionConfig<TContext, AfterEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta> | TransitionConfigFunction<TContext, AfterEvent, TEvent, TODO, // TEmitted
|
|
509
|
+
TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, TInput, [TContext] extends [never] ? any : TContext, TChildren>; };
|
|
510
|
+
/**
|
|
511
|
+
* The duration (in ms) after which this state will transition via `onTimeout`
|
|
512
|
+
* if still active. "We've been in this state too long."
|
|
513
|
+
*
|
|
514
|
+
* Independent of `after` - both can coexist on the same state. Both cancel on
|
|
515
|
+
* state exit.
|
|
516
|
+
*
|
|
517
|
+
* Can be a static number, a delay reference string, or a dynamic function.
|
|
518
|
+
*/
|
|
519
|
+
timeout?: number | NoInfer<TDelays> | ((args: {
|
|
520
|
+
context: TContext;
|
|
521
|
+
event: TEvent;
|
|
522
|
+
stateNode: AnyStateNode;
|
|
523
|
+
input: TInput;
|
|
524
|
+
}) => number);
|
|
525
|
+
/** Transition taken when `timeout` expires. Required when `timeout` is set. */
|
|
526
|
+
onTimeout?: Next_TransitionConfigOrTarget<TContext, TimeoutEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, TInput, TChildren>;
|
|
527
|
+
/**
|
|
528
|
+
* An eventless transition that is always taken when this state node is
|
|
529
|
+
* active.
|
|
530
|
+
*/
|
|
531
|
+
always?: Next_TransitionConfigOrTarget<TContext, TEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TTransitionMeta, undefined, TChildren>;
|
|
532
|
+
choice?: never;
|
|
533
|
+
/**
|
|
534
|
+
* The meta data associated with this state node, which will be returned in
|
|
535
|
+
* State instances.
|
|
536
|
+
*/
|
|
537
|
+
meta?: TStateMeta;
|
|
538
|
+
/**
|
|
539
|
+
* The output data sent with the `xstate.done.state` event if this is a final
|
|
540
|
+
* state node.
|
|
541
|
+
*
|
|
542
|
+
* The output data will be evaluated with the current `context` and placed on
|
|
543
|
+
* the `.data` property of the event.
|
|
544
|
+
*/
|
|
545
|
+
output?: OutputConfig<TContext, TEvent, TOutput, TInput>;
|
|
546
|
+
/**
|
|
547
|
+
* The unique ID of the state node, which can be referenced as a transition
|
|
548
|
+
* target via the `#id` syntax.
|
|
549
|
+
*/
|
|
550
|
+
id?: string | undefined;
|
|
551
|
+
/**
|
|
552
|
+
* The order this state node appears. Corresponds to the implicit document
|
|
553
|
+
* order.
|
|
554
|
+
*/
|
|
555
|
+
order?: number;
|
|
556
|
+
/**
|
|
557
|
+
* The tags for this state node, which are accumulated into the `state.tags`
|
|
558
|
+
* property.
|
|
559
|
+
*/
|
|
560
|
+
tags?: TTag[];
|
|
561
|
+
/** A text description of the state node */
|
|
562
|
+
description?: string;
|
|
563
|
+
/** A default target for a history state */
|
|
564
|
+
target?: string | string[] | undefined;
|
|
565
|
+
}
|
|
566
|
+
type Next_StaticTransitionConfig<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject> = {
|
|
567
|
+
matches?: EventPayloadPattern<TExpressionEvent>;
|
|
568
|
+
target?: string | string[];
|
|
569
|
+
context?: TransitionContextPatch<TContext> | TransitionContextMapper<TContext, TExpressionEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap>;
|
|
570
|
+
description?: string;
|
|
571
|
+
reenter?: boolean;
|
|
572
|
+
meta?: TMeta;
|
|
573
|
+
input?: Record<string, unknown> | ((args: {
|
|
574
|
+
context: any;
|
|
575
|
+
event: any;
|
|
576
|
+
}) => Record<string, unknown>);
|
|
577
|
+
};
|
|
578
|
+
/** @public */
|
|
579
|
+
type Next_TransitionConfigOrTarget<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject, TEmitted extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, TInput = undefined, TChildren extends Record<string, AnyActorRef | undefined> = {}> = undefined | Next_StaticTransitionConfig<TContext, TExpressionEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta> | {
|
|
580
|
+
matches?: EventPayloadPattern<TExpressionEvent>;
|
|
581
|
+
to?: TransitionConfigFunction<TContext, TExpressionEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TInput, [TContext] extends [never] ? any : TContext, TChildren>;
|
|
582
|
+
context?: TransitionContextPatch<TContext> | TransitionContextMapper<TContext, TExpressionEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap>;
|
|
583
|
+
description?: string;
|
|
584
|
+
reenter?: boolean;
|
|
585
|
+
meta?: TMeta;
|
|
586
|
+
input?: Record<string, unknown> | ((args: {
|
|
587
|
+
context: any;
|
|
588
|
+
event: any;
|
|
589
|
+
}) => Record<string, unknown>);
|
|
590
|
+
} | TransitionConfigFunction<TContext, TExpressionEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta, TInput, [TContext] extends [never] ? any : TContext, TChildren>;
|
|
591
|
+
type WithDefault<T, Default> = IsNever<T> extends true ? Default : T;
|
|
592
|
+
/** @public */
|
|
593
|
+
interface Sources {
|
|
594
|
+
actions: Record<string, (...args: any[]) => void | {
|
|
595
|
+
context?: any;
|
|
596
|
+
children?: any;
|
|
597
|
+
}>;
|
|
598
|
+
guards: Record<string, Function>;
|
|
599
|
+
delays: Record<string, number | Function>;
|
|
600
|
+
actors: Record<string, AnyActorLogic>;
|
|
601
|
+
}
|
|
602
|
+
/**
|
|
603
|
+
* Contextually types the entries of a `guards: { ... }` source map. Guards
|
|
604
|
+
* are plain predicates: they receive only caller-supplied params (no injected
|
|
605
|
+
* transition args) and are called the same way they are declared.
|
|
606
|
+
*/
|
|
607
|
+
type GuardSourceMap<_TContext extends MachineContext, _TEvent extends EventObject> = Record<string, (...params: any[]) => boolean>;
|
|
608
|
+
/**
|
|
609
|
+
* Contextually types the entries of a `delays: { ... }` source map. Delay
|
|
610
|
+
* functions receive `{ context, event, stateNode }` at runtime.
|
|
611
|
+
*/
|
|
612
|
+
type DelaySourceMap<TContext extends MachineContext, TEvent extends EventObject, _TCtx = [TContext] extends [never] ? any : TContext> = Record<string, number | ((args: {
|
|
613
|
+
context: _TCtx;
|
|
614
|
+
event: TEvent;
|
|
615
|
+
stateNode: AnyStateNode;
|
|
616
|
+
}) => number)>;
|
|
617
|
+
type DelayMapFromNames<TDelays extends string, TDelayMap extends Sources['delays']> = string extends TDelays ? Sources['delays'] : { [K in TDelays]: K extends keyof TDelayMap ? TDelayMap[K] : number | ((...args: any[]) => number); };
|
|
618
|
+
type DelayNamesFromConfig<TConfig> = TConfig extends {
|
|
619
|
+
delays: infer TDelays;
|
|
620
|
+
} ? Extract<keyof TDelays, string> : string;
|
|
621
|
+
type DurationInt = `${bigint}`;
|
|
622
|
+
type DurationFraction = DurationInt | `0${DurationInt}` | `00${DurationInt}`;
|
|
623
|
+
type DurationDecimal = DurationInt | `${DurationInt}.${DurationFraction}` | `.${DurationFraction}`;
|
|
624
|
+
type IsoDateParts = `${DurationInt}W` | `${DurationInt}D` | `${DurationInt}W${DurationInt}D`;
|
|
625
|
+
type IsoSeconds = `${DurationInt}` | `${DurationInt}.${DurationFraction}`;
|
|
626
|
+
type IsoTimeParts = `${DurationInt}H` | `${DurationInt}M` | `${IsoSeconds}S` | `${DurationInt}H${DurationInt}M` | `${DurationInt}H${IsoSeconds}S` | `${DurationInt}M${IsoSeconds}S` | `${DurationInt}H${DurationInt}M${IsoSeconds}S`;
|
|
627
|
+
/**
|
|
628
|
+
* @public Duration-string `after` keys, which are parsed rather than looked
|
|
629
|
+
* up: numeric strings (milliseconds), `ms` / `s` suffixes (case-insensitive)
|
|
630
|
+
* and uppercase ISO 8601 durations (`PT1M30S`, `P1D`, `P1DT12H`).
|
|
631
|
+
*/
|
|
632
|
+
type DelayDurationKey = `${number}` | `${DurationInt}${'ms' | 'MS' | 'Ms' | 'mS'}` | `${DurationDecimal}${'s' | 'S'}` | `P${IsoDateParts}` | `P${IsoDateParts | ''}T${IsoTimeParts}`;
|
|
633
|
+
type InvalidDelayReferences<TConfig, TDelays extends string> = 0 extends 1 & TConfig ? never : (TConfig extends {
|
|
634
|
+
after: infer TAfter;
|
|
635
|
+
} ? Exclude<Extract<keyof TAfter, string>, TDelays | DelayDurationKey> : never) | (TConfig extends {
|
|
636
|
+
states: infer TStates;
|
|
637
|
+
} ? TStates extends Record<string, unknown> ? { [K in keyof TStates]: InvalidDelayReferences<TStates[K], TDelays>; }[keyof TStates] : never : never);
|
|
638
|
+
type InvalidDelayReferenceErrors<TConfig, TDelays extends string> = (TConfig extends {
|
|
639
|
+
after: infer TAfter;
|
|
640
|
+
} ? [Exclude<Extract<keyof TAfter, string>, TDelays | DelayDurationKey>] extends [never] ? {} : {
|
|
641
|
+
after: { [K in Exclude<Extract<keyof TAfter, string>, TDelays | DelayDurationKey>]: `Delay '${K}' is not declared in delays.`; };
|
|
642
|
+
} : {}) & (TConfig extends {
|
|
643
|
+
states: infer TStates;
|
|
644
|
+
} ? TStates extends Record<string, unknown> ? {
|
|
645
|
+
states: { [K in keyof TStates]: InvalidDelayReferenceErrors<TStates[K], TDelays>; };
|
|
646
|
+
} : {} : {});
|
|
647
|
+
/**
|
|
648
|
+
* @public Rejects `after` keys that are neither a declared delay name, a number nor a
|
|
649
|
+
* duration string. Only applies when delay names are known; the error is
|
|
650
|
+
* reported at the offending key.
|
|
651
|
+
*/
|
|
652
|
+
type ValidateDelayNames<TConfig, TDelays extends string> = string extends TDelays ? unknown : [InvalidDelayReferences<TConfig, TDelays>] extends [never] ? unknown : InvalidDelayReferenceErrors<TConfig, TDelays>;
|
|
653
|
+
type ValidateDelayReferences<TConfig> = ValidateDelayNames<TConfig, DelayNamesFromConfig<TConfig>>;
|
|
654
|
+
type UndeclaredEventDescriptors<TConfig, TAllowed extends string> = 0 extends 1 & TConfig ? never : (TConfig extends {
|
|
655
|
+
on: infer TOn;
|
|
656
|
+
} ? Exclude<Extract<keyof TOn, string>, TAllowed> : never) | (TConfig extends {
|
|
657
|
+
states: infer TStates;
|
|
658
|
+
} ? TStates extends Record<string, unknown> ? { [K in keyof TStates]: UndeclaredEventDescriptors<TStates[K], TAllowed>; }[keyof TStates] : never : never);
|
|
659
|
+
type UndeclaredEventDescriptorErrors<TConfig, TAllowed extends string> = (TConfig extends {
|
|
660
|
+
on: infer TOn;
|
|
661
|
+
} ? [Exclude<Extract<keyof TOn, string>, TAllowed>] extends [never] ? {} : {
|
|
662
|
+
on: { [K in Exclude<Extract<keyof TOn, string>, TAllowed>]: `Event type '${K}' is not declared in schemas.events.`; };
|
|
663
|
+
} : {}) & (TConfig extends {
|
|
664
|
+
states: infer TStates;
|
|
665
|
+
} ? TStates extends Record<string, unknown> ? {
|
|
666
|
+
states: { [K in keyof TStates]: UndeclaredEventDescriptorErrors<TStates[K], TAllowed>; };
|
|
667
|
+
} : {} : {});
|
|
668
|
+
/**
|
|
669
|
+
* @public Rejects `on` keys that match no declared event type. Only applies when the
|
|
670
|
+
* event union is closed (e.g. `schemas.events` is declared); wildcards,
|
|
671
|
+
* partial wildcards and reserved `xstate.*` event types are always allowed.
|
|
672
|
+
* The error is reported at the offending key.
|
|
673
|
+
*/
|
|
674
|
+
type ValidateEventDescriptors<TConfig, TEvent extends EventObject> = string extends TEvent['type'] ? unknown : [UndeclaredEventDescriptors<TConfig, EventDescriptor<TEvent> | `xstate.${string}`>] extends [never] ? unknown : UndeclaredEventDescriptorErrors<TConfig, EventDescriptor<TEvent> | `xstate.${string}`>;
|
|
675
|
+
type IsHistoryStateConfig<TConfig> = TConfig extends {
|
|
676
|
+
type: 'history';
|
|
677
|
+
} ? true : TConfig extends {
|
|
678
|
+
history: false | undefined;
|
|
679
|
+
} ? false : TConfig extends {
|
|
680
|
+
history: unknown;
|
|
681
|
+
} ? true : false;
|
|
682
|
+
type MissingHistoryDefault<TConfig> = 0 extends 1 & TConfig ? never : IsHistoryStateConfig<TConfig> extends true ? TConfig extends {
|
|
683
|
+
target: string | readonly [string, ...string[]];
|
|
684
|
+
} ? never : true : TConfig extends {
|
|
685
|
+
states: infer TStates;
|
|
686
|
+
} ? TStates extends Record<string, unknown> ? { [K in keyof TStates]: MissingHistoryDefault<TStates[K]>; }[keyof TStates] : never : never;
|
|
687
|
+
/**
|
|
688
|
+
* Rejects authored machines containing a history state without its SCXML
|
|
689
|
+
* default target.
|
|
690
|
+
*/
|
|
691
|
+
type ValidateHistoryDefaults<TConfig> = MissingHistoryDefault<TConfig> extends never ? unknown : never;
|
|
692
|
+
type StatePath = readonly string[];
|
|
693
|
+
type AppendStatePath<TPrefix extends StatePath, TKey extends string> = [...TPrefix, TKey];
|
|
694
|
+
type EscapeStatePathDots<TValue extends string> = TValue extends `${infer THead}.${infer TTail}` ? `${THead}\\.${EscapeStatePathDots<TTail>}` : TValue;
|
|
695
|
+
type ProtectEscapedStatePathDots<TValue extends string> = TValue extends `${infer THead}\\.${infer TTail}` ? `${THead}__XSTATE_ESCAPED_DOT__${ProtectEscapedStatePathDots<TTail>}` : TValue;
|
|
696
|
+
type RestoreEscapedStatePathDots<TValue extends string> = TValue extends `${infer THead}__XSTATE_ESCAPED_DOT__${infer TTail}` ? `${THead}.${RestoreEscapedStatePathDots<TTail>}` : TValue;
|
|
697
|
+
type SplitStatePath<TPath extends string> = ProtectEscapedStatePathDots<TPath> extends (infer TProtected extends string) ? TProtected extends '' ? [] : TProtected extends `${infer THead}.${infer TTail}` ? [RestoreEscapedStatePathDots<THead>, ...SplitStatePath<TTail>] : [RestoreEscapedStatePathDots<TProtected>] : never;
|
|
698
|
+
type ParentStatePath<TPath extends StatePath> = TPath extends readonly [...infer TParent extends string[], string] ? TParent : [];
|
|
699
|
+
type StatePathsFromStates<TStates, TPrefix extends StatePath = []> = TStates extends Record<string, unknown> ? { [K in keyof TStates & string]: AppendStatePath<TPrefix, K> | (0 extends 1 & TStates[K] ? never : TStates[K] extends {
|
|
700
|
+
states: infer TChildren;
|
|
701
|
+
} ? StatePathsFromStates<TChildren, AppendStatePath<TPrefix, K>> : never); }[keyof TStates & string] : never;
|
|
702
|
+
type AuthoredStatePaths<TConfig> = TConfig extends {
|
|
703
|
+
states: infer TStates;
|
|
704
|
+
} ? StatePathsFromStates<TStates> : never;
|
|
705
|
+
type OpaqueStatePathsFromStates<TStates, TPrefix extends StatePath = []> = TStates extends Record<string, unknown> ? { [K in keyof TStates & string]: 0 extends 1 & TStates[K] ? AppendStatePath<TPrefix, K> : TStates[K] extends {
|
|
706
|
+
states: infer TChildren;
|
|
707
|
+
} ? OpaqueStatePathsFromStates<TChildren, AppendStatePath<TPrefix, K>> : never; }[keyof TStates & string] : never;
|
|
708
|
+
type OpaqueStatePaths<TConfig> = TConfig extends {
|
|
709
|
+
states: infer TStates;
|
|
710
|
+
} ? OpaqueStatePathsFromStates<TStates> : never;
|
|
711
|
+
type IsWithinStatePath<TPath extends StatePath, TAncestor> = TAncestor extends StatePath ? TPath extends readonly [...TAncestor, ...string[]] ? true : false : false;
|
|
712
|
+
type JoinStateTargetString<TPrefix extends string, TKey extends string> = TPrefix extends '' ? TKey : `${TPrefix}.${TKey}`;
|
|
713
|
+
type StateTargetStringsFromStates<TStates, TPrefix extends string = ''> = TStates extends Record<string, unknown> ? { [K in keyof TStates & string]: JoinStateTargetString<TPrefix, EscapeStatePathDots<K>> | (0 extends 1 & TStates[K] ? never : TStates[K] extends {
|
|
714
|
+
states: infer TChildren;
|
|
715
|
+
} ? StateTargetStringsFromStates<TChildren, JoinStateTargetString<TPrefix, EscapeStatePathDots<K>>> : never); }[keyof TStates & string] : never;
|
|
716
|
+
type IdTargetsForNode<TNode> = TNode extends {
|
|
717
|
+
id: infer TId extends string;
|
|
718
|
+
} ? string extends TId ? never : TNode extends {
|
|
719
|
+
states: infer TStates;
|
|
720
|
+
} ? `#${EscapeStatePathDots<TId>}` | `#${EscapeStatePathDots<TId>}.${StateTargetStringsFromStates<TStates>}` : `#${EscapeStatePathDots<TId>}` : never;
|
|
721
|
+
type IdTargetsFromStates<TStates> = TStates extends Record<string, unknown> ? { [K in keyof TStates & string]: IdTargetsForNode<TStates[K]> | (0 extends 1 & TStates[K] ? never : TStates[K] extends {
|
|
722
|
+
states: infer TChildren;
|
|
723
|
+
} ? IdTargetsFromStates<TChildren> : never); }[keyof TStates & string] : never;
|
|
724
|
+
type AuthoredIdTargets<TConfig> = IdTargetsForNode<TConfig> | (TConfig extends {
|
|
725
|
+
states: infer TStates;
|
|
726
|
+
} ? IdTargetsFromStates<TStates> : never);
|
|
727
|
+
type ResolveIdTargetAtNode<TNode, TNodePath extends StatePath, TTarget extends string> = TNode extends {
|
|
728
|
+
id: infer TId extends string;
|
|
729
|
+
} ? string extends TId ? never : TTarget extends `#${EscapeStatePathDots<TId>}` ? TNodePath : TTarget extends `#${EscapeStatePathDots<TId>}.${infer TDescendant}` ? [...TNodePath, ...SplitStatePath<TDescendant>] : never : never;
|
|
730
|
+
type ResolveIdTargetInStates<TStates, TTarget extends string, TPrefix extends StatePath = []> = TStates extends Record<string, unknown> ? { [K in keyof TStates & string]: ResolveIdTargetAtNode<TStates[K], AppendStatePath<TPrefix, K>, TTarget> | (0 extends 1 & TStates[K] ? never : TStates[K] extends {
|
|
731
|
+
states: infer TChildren;
|
|
732
|
+
} ? ResolveIdTargetInStates<TChildren, TTarget, AppendStatePath<TPrefix, K>> : never); }[keyof TStates & string] : never;
|
|
733
|
+
type ResolveIdTargetPath<TConfig, TTarget extends string> = ResolveIdTargetAtNode<TConfig, [], TTarget> | (TConfig extends {
|
|
734
|
+
states: infer TStates;
|
|
735
|
+
} ? ResolveIdTargetInStates<TStates, TTarget> : never);
|
|
736
|
+
type ResolveAuthoredTarget<TSourcePath extends StatePath, TTarget extends string> = TTarget extends `#${string}` ? never : TTarget extends '.' ? TSourcePath : TTarget extends `.${infer TDescendant}` ? [...TSourcePath, ...SplitStatePath<TDescendant>] : [...ParentStatePath<TSourcePath>, ...SplitStatePath<TTarget>];
|
|
737
|
+
type StateNodeAtPath<TConfig, TPath extends StatePath> = TConfig extends {
|
|
738
|
+
states: infer TStates;
|
|
739
|
+
} ? TPath extends readonly [infer THead extends string, ...infer TTail extends string[]] ? THead extends keyof TStates ? TTail extends [] ? TStates[THead] : StateNodeAtPath<TStates[THead], TTail> : never : TConfig : never;
|
|
740
|
+
type CommonStatePathSegments<TLeft extends readonly string[], TRight extends readonly string[], TCommon extends readonly string[] = []> = TLeft extends readonly [infer TLeftHead extends string, ...infer TLeftTail extends string[]] ? TRight extends readonly [infer TRightHead extends string, ...infer TRightTail extends string[]] ? TLeftHead extends TRightHead ? CommonStatePathSegments<TLeftTail, TRightTail, [...TCommon, TLeftHead]> : TCommon : TCommon : TCommon;
|
|
741
|
+
type NearestCommonStatePath<TLeft extends StatePath, TRight extends StatePath> = CommonStatePathSegments<TLeft, TRight>;
|
|
742
|
+
type IsAncestorStatePath<TAncestor extends StatePath, TDescendant extends StatePath> = TDescendant extends readonly [...TAncestor, ...infer TRest] ? TRest extends [] ? false : true : false;
|
|
743
|
+
type IsParallelStatePath<TConfig, TPath extends StatePath> = TPath extends readonly [] ? TConfig extends {
|
|
744
|
+
type: 'parallel';
|
|
745
|
+
} ? true : false : StateNodeAtPath<TConfig, TPath> extends {
|
|
746
|
+
type: 'parallel';
|
|
747
|
+
} ? true : false;
|
|
748
|
+
type ResolvedAuthoredTargetPath<TRootConfig, TSourcePath extends StatePath, TTarget> = TTarget extends string ? TTarget extends `#${string}` ? ResolveIdTargetPath<TRootConfig, TTarget> : ResolveAuthoredTarget<TSourcePath, TTarget> : never;
|
|
749
|
+
type InvalidTargetPair<TRootConfig, TLeftPath extends StatePath, TRightPath extends StatePath> = TLeftPath extends TRightPath ? TRightPath extends TLeftPath ? true : never : IsAncestorStatePath<TLeftPath, TRightPath> extends true ? true : IsAncestorStatePath<TRightPath, TLeftPath> extends true ? true : IsParallelStatePath<TRootConfig, NearestCommonStatePath<TLeftPath, TRightPath>> extends true ? never : true;
|
|
750
|
+
type InvalidTargetPairsWithHead<TRootConfig, TSourcePath extends StatePath, THead, TRest extends readonly unknown[]> = TRest extends readonly [infer TNext, ...infer TTail] ? (ResolvedAuthoredTargetPath<TRootConfig, TSourcePath, THead> extends (infer THeadPath extends StatePath) ? ResolvedAuthoredTargetPath<TRootConfig, TSourcePath, TNext> extends (infer TNextPath extends StatePath) ? InvalidTargetPair<TRootConfig, THeadPath, TNextPath> : never : never) | InvalidTargetPairsWithHead<TRootConfig, TSourcePath, THead, TTail> : never;
|
|
751
|
+
type InvalidTargetSet<TRootConfig, TSourcePath extends StatePath, TTargets> = TTargets extends readonly [infer THead, ...infer TRest] ? InvalidTargetPairsWithHead<TRootConfig, TSourcePath, THead, TRest> | InvalidTargetSet<TRootConfig, TSourcePath, TRest> : never;
|
|
752
|
+
type InvalidTargetValue<TRootConfig, TSourcePath extends StatePath, TTarget> = TTarget extends string ? string extends TTarget ? never : TTarget extends `#${string}` ? TTarget extends AuthoredIdTargets<TRootConfig> ? never : TTarget : ResolveAuthoredTarget<TSourcePath, TTarget> extends (infer TResolvedTarget extends StatePath) ? TResolvedTarget extends AuthoredStatePaths<TRootConfig> ? never : true extends IsWithinStatePath<TResolvedTarget, OpaqueStatePaths<TRootConfig>> ? never : TTarget : TTarget : TTarget extends readonly unknown[] ? InvalidTargetValue<TRootConfig, TSourcePath, TTarget[number]> : never;
|
|
753
|
+
type InvalidTransitionTarget<TRootConfig, TSourcePath extends StatePath, TTransition> = 0 extends 1 & TTransition ? never : TTransition extends ((...args: any[]) => any) ? InvalidTransitionTarget<TRootConfig, TSourcePath, ReturnType<TTransition>> : TTransition extends readonly unknown[] ? InvalidTransitionTarget<TRootConfig, TSourcePath, TTransition[number]> : TTransition extends {
|
|
754
|
+
target: infer TTarget;
|
|
755
|
+
} ? InvalidTargetValue<TRootConfig, TSourcePath, TTarget> | InvalidTargetSet<TRootConfig, TSourcePath, TTarget> : never;
|
|
756
|
+
type InvalidTransitionMapTargets<TRootConfig, TSourcePath extends StatePath, TTransitionMap> = 0 extends 1 & TTransitionMap ? never : TTransitionMap extends Record<string, unknown> ? { [K in keyof TTransitionMap]: InvalidTransitionTarget<TRootConfig, TSourcePath, TTransitionMap[K]>; }[keyof TTransitionMap] : never;
|
|
757
|
+
type InvalidInitialTarget<TRootConfig, TChildStates, TInitialTarget> = TInitialTarget extends string ? string extends TInitialTarget ? never : TInitialTarget extends keyof TChildStates ? never : TInitialTarget extends `#${string}` ? TInitialTarget extends AuthoredIdTargets<TRootConfig> ? never : TInitialTarget : TInitialTarget : never;
|
|
758
|
+
type InvalidInvokeTargets<TRootConfig, TSourcePath extends StatePath, TInvoke> = 0 extends 1 & TInvoke ? never : TInvoke extends {
|
|
759
|
+
readonly [createdInvokeConfig]: infer TConfig;
|
|
760
|
+
} ? InvalidInvokeTargets<TRootConfig, TSourcePath, TConfig> : TInvoke extends readonly unknown[] ? InvalidInvokeTargets<TRootConfig, TSourcePath, TInvoke[number]> : TInvoke extends Record<string, unknown> ? (TInvoke extends {
|
|
761
|
+
onDone: infer TOnDone;
|
|
762
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TOnDone> : never) | (TInvoke extends {
|
|
763
|
+
onError: infer TOnError;
|
|
764
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TOnError> : never) | (TInvoke extends {
|
|
765
|
+
onSnapshot: infer TOnSnapshot;
|
|
766
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TOnSnapshot> : never) | (TInvoke extends {
|
|
767
|
+
onTimeout: infer TOnTimeout;
|
|
768
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TOnTimeout> : never) : never;
|
|
769
|
+
type InvalidNodeTargets<TRootConfig, TNode, TSourcePath extends StatePath> = 0 extends 1 & TNode ? never : (TNode extends {
|
|
770
|
+
initial: infer TInitial;
|
|
771
|
+
states: infer TChildStates;
|
|
772
|
+
} ? (TInitial extends {
|
|
773
|
+
target: infer TInitialTarget;
|
|
774
|
+
} ? TInitialTarget : TInitial) extends (infer TInitialTarget) ? InvalidInitialTarget<TRootConfig, TChildStates, TInitialTarget> : never : never) | (TNode extends {
|
|
775
|
+
on: infer TOn;
|
|
776
|
+
} ? InvalidTransitionMapTargets<TRootConfig, TSourcePath, TOn> : never) | (TNode extends {
|
|
777
|
+
always: infer TAlways;
|
|
778
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TAlways> : never) | (TNode extends {
|
|
779
|
+
choice: infer TChoice;
|
|
780
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TChoice> : never) | (TNode extends {
|
|
781
|
+
after: infer TAfter;
|
|
782
|
+
} ? InvalidTransitionMapTargets<TRootConfig, TSourcePath, TAfter> : never) | (TNode extends {
|
|
783
|
+
onDone: infer TOnDone;
|
|
784
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TOnDone> : never) | (TNode extends {
|
|
785
|
+
onError: infer TOnError;
|
|
786
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TOnError> : never) | (TNode extends {
|
|
787
|
+
onTimeout: infer TOnTimeout;
|
|
788
|
+
} ? InvalidTransitionTarget<TRootConfig, TSourcePath, TOnTimeout> : never) | (TNode extends {
|
|
789
|
+
invoke: infer TInvoke;
|
|
790
|
+
} ? InvalidInvokeTargets<TRootConfig, TSourcePath, TInvoke> : never) | (TNode extends {
|
|
791
|
+
target: infer THistoryTarget;
|
|
792
|
+
} ? InvalidTargetValue<TRootConfig, TSourcePath, THistoryTarget> : never);
|
|
793
|
+
type InvalidTargetsInStates<TRootConfig, TStates, TPrefix extends StatePath = []> = TStates extends Record<string, unknown> ? { [K in keyof TStates & string]: 0 extends 1 & TStates[K] ? never : InvalidNodeTargets<TRootConfig, TStates[K], AppendStatePath<TPrefix, K>> | (TStates[K] extends {
|
|
794
|
+
states: infer TChildren;
|
|
795
|
+
} ? InvalidTargetsInStates<TRootConfig, TChildren, AppendStatePath<TPrefix, K>> : never); }[keyof TStates & string] : never;
|
|
796
|
+
/**
|
|
797
|
+
* Rejects authored literal transition targets that do not resolve in the
|
|
798
|
+
* machine topology.
|
|
799
|
+
*/
|
|
800
|
+
type ValidateStateTargets<TConfig> = 0 extends 1 & TConfig ? unknown : TConfig extends {
|
|
801
|
+
states: infer TStates;
|
|
802
|
+
} ? (TConfig extends {
|
|
803
|
+
initial: infer TInitial;
|
|
804
|
+
} ? (TInitial extends {
|
|
805
|
+
target: infer TInitialTarget;
|
|
806
|
+
} ? TInitialTarget : TInitial) extends (infer TInitialTarget) ? InvalidInitialTarget<TConfig, TStates, TInitialTarget> : never : never) | InvalidNodeTargets<TConfig, TConfig, []> | InvalidTargetsInStates<TConfig, TStates> extends never ? unknown : never : unknown;
|
|
807
|
+
/**
|
|
808
|
+
* Durable machine snapshot fields that a historical snapshot schema describes.
|
|
809
|
+
*
|
|
810
|
+
* @public
|
|
811
|
+
*/
|
|
812
|
+
type PersistedMachineSnapshot = {
|
|
813
|
+
status: Snapshot<unknown>['status'];
|
|
814
|
+
output?: unknown;
|
|
815
|
+
error?: unknown;
|
|
816
|
+
value: unknown;
|
|
817
|
+
context: unknown;
|
|
818
|
+
children: Record<string, unknown>;
|
|
819
|
+
historyValue: Record<string, unknown>;
|
|
820
|
+
timers: Record<string, unknown>;
|
|
821
|
+
_nextActorId?: number;
|
|
822
|
+
_nextActorIds?: Record<string, number>;
|
|
823
|
+
_nextTimerId?: number;
|
|
824
|
+
stateInputs?: Record<string, Record<string, unknown>>;
|
|
825
|
+
machine?: {
|
|
826
|
+
id: string;
|
|
827
|
+
version: string;
|
|
828
|
+
};
|
|
829
|
+
version?: string;
|
|
830
|
+
[key: string]: unknown;
|
|
831
|
+
};
|
|
832
|
+
/**
|
|
833
|
+
* A Standard Schema for a complete persisted machine snapshot.
|
|
834
|
+
*
|
|
835
|
+
* @public
|
|
836
|
+
*/
|
|
837
|
+
type MachineSnapshotSchema = StandardSchemaV1<unknown, PersistedMachineSnapshot>;
|
|
838
|
+
/**
|
|
839
|
+
* A Standard Schema for a complete persisted event object.
|
|
840
|
+
*
|
|
841
|
+
* @public
|
|
842
|
+
*/
|
|
843
|
+
type MachineEventSchema = StandardSchemaV1<unknown, EventObject>;
|
|
844
|
+
/**
|
|
845
|
+
* Schema-backed capabilities for one machine version.
|
|
846
|
+
*
|
|
847
|
+
* @public
|
|
848
|
+
*/
|
|
849
|
+
type MachineVersionDescriptor = {
|
|
850
|
+
id: string;
|
|
851
|
+
version: string;
|
|
852
|
+
} & ({
|
|
853
|
+
snapshotSchema: MachineSnapshotSchema;
|
|
854
|
+
eventSchema?: MachineEventSchema;
|
|
855
|
+
} | {
|
|
856
|
+
snapshotSchema?: MachineSnapshotSchema;
|
|
857
|
+
eventSchema: MachineEventSchema;
|
|
858
|
+
});
|
|
859
|
+
/** @experimental */
|
|
860
|
+
type ActorValidationBoundary = 'input' | 'event' | 'context' | 'state.input' | 'state.context' | 'emitted' | 'output' | 'child';
|
|
861
|
+
/** @experimental */
|
|
862
|
+
type ActorValidationEventOrigin = 'external' | 'actor' | 'raised';
|
|
863
|
+
/** @experimental */
|
|
864
|
+
type ActorValidationRequest = {
|
|
865
|
+
kind: 'input';
|
|
866
|
+
logic: AnyActorLogic;
|
|
867
|
+
input: unknown;
|
|
868
|
+
} | {
|
|
869
|
+
kind: 'event';
|
|
870
|
+
logic: AnyActorLogic;
|
|
871
|
+
event: AnyEventObject;
|
|
872
|
+
eventOrigin: Exclude<ActorValidationEventOrigin, 'raised'>;
|
|
873
|
+
} | {
|
|
874
|
+
kind: 'result';
|
|
875
|
+
logic: AnyActorLogic;
|
|
876
|
+
snapshot: Snapshot<unknown>;
|
|
877
|
+
effects: readonly ExecutableActionObject[];
|
|
878
|
+
};
|
|
879
|
+
/**
|
|
880
|
+
* Runtime schema validator installed on actor logic.
|
|
881
|
+
*
|
|
882
|
+
* @experimental
|
|
883
|
+
*/
|
|
884
|
+
interface ActorLogicValidator {
|
|
885
|
+
check(request: ActorValidationRequest): Error | undefined;
|
|
886
|
+
}
|
|
887
|
+
/**
|
|
888
|
+
* A record of a single action executed during a transition.
|
|
889
|
+
*
|
|
890
|
+
* Carried in {@link TransitionInspectionEvent.actions}, this replaces the v5
|
|
891
|
+
* standalone `@xstate.action` inspection event.
|
|
892
|
+
*
|
|
893
|
+
* @experimental
|
|
894
|
+
*/
|
|
895
|
+
interface ActionRecord {
|
|
896
|
+
/** The action type (e.g. the action creator name or `'(anonymous)'`). */
|
|
897
|
+
type: string;
|
|
898
|
+
/** The resolved params for the action, if any. */
|
|
899
|
+
params: unknown;
|
|
900
|
+
}
|
|
901
|
+
/**
|
|
902
|
+
* A record of a single event relayed to another actor during a transition.
|
|
903
|
+
*
|
|
904
|
+
* Carried in {@link TransitionInspectionEvent.sent}, this captures the send on
|
|
905
|
+
* the _sender's_ transition — including delayed/scheduled sends that may never
|
|
906
|
+
* deliver — distinct from the target actor's own processed-event transition.
|
|
907
|
+
*
|
|
908
|
+
* @experimental
|
|
909
|
+
*/
|
|
910
|
+
interface SentRecord {
|
|
911
|
+
/** The actor the event was sent to. */
|
|
912
|
+
targetRef: ActorRefLike;
|
|
913
|
+
/** The `id` of the target actor. */
|
|
914
|
+
targetId: string;
|
|
915
|
+
/** The event that was sent. */
|
|
916
|
+
event: AnyEventObject;
|
|
917
|
+
/** The delay (ms) for a scheduled send, or `undefined` for an immediate send. */
|
|
918
|
+
delay?: number | undefined;
|
|
919
|
+
/** The scheduling id for a scheduled send, used for cancellation. */
|
|
920
|
+
id?: string | undefined;
|
|
921
|
+
}
|
|
922
|
+
interface BaseInspectionEventProperties {
|
|
923
|
+
/** The session ID of the root actor. */
|
|
924
|
+
rootId: string;
|
|
925
|
+
/**
|
|
926
|
+
* The relevant actorRef for the inspection event.
|
|
927
|
+
*
|
|
928
|
+
* - For `@xstate.actor` events, this is the registered actor.
|
|
929
|
+
* - For `@xstate.transition` events, this is the actor that transitioned.
|
|
930
|
+
*/
|
|
931
|
+
actorRef: ActorRefLike;
|
|
932
|
+
}
|
|
933
|
+
/**
|
|
934
|
+
* Announces that an actor was created in the system (the root actor and every
|
|
935
|
+
* spawned/invoked child). This is the single topology event — it carries the
|
|
936
|
+
* actor identity and parent relationship needed to draw the actor graph before
|
|
937
|
+
* any transitions occur.
|
|
938
|
+
*
|
|
939
|
+
* Actor _stop_ is derivable from `snapshot.status` on the actor's final
|
|
940
|
+
* `@xstate.transition` event, so there is no separate stop event.
|
|
941
|
+
*
|
|
942
|
+
* @experimental
|
|
943
|
+
*/
|
|
944
|
+
interface ActorInspectionEvent extends BaseInspectionEventProperties {
|
|
945
|
+
type: '@xstate.actor';
|
|
946
|
+
/** The parent actor, or `undefined` for the root actor. */
|
|
947
|
+
parentRef: ActorRefLike | undefined;
|
|
948
|
+
/** The `id` of the actor. */
|
|
949
|
+
id: string;
|
|
950
|
+
/** The source logic (or its referenced string) the actor was created from. */
|
|
951
|
+
src: string | AnyActorLogic;
|
|
952
|
+
/** The initial snapshot of the actor. */
|
|
953
|
+
snapshot: Snapshot<unknown>;
|
|
954
|
+
}
|
|
955
|
+
/**
|
|
956
|
+
* Announces an actor transition.
|
|
957
|
+
*
|
|
958
|
+
* All facets are flat and always present so consumers can read `event.actions`,
|
|
959
|
+
* `event.sent`, and `event.microsteps` directly without narrowing on absent
|
|
960
|
+
* properties. This is a superset of the v5
|
|
961
|
+
* `@xstate.event`/`@xstate.snapshot`/`@xstate.action`/`@xstate.microstep`
|
|
962
|
+
* events.
|
|
963
|
+
*
|
|
964
|
+
* @experimental
|
|
965
|
+
*/
|
|
966
|
+
interface TransitionInspectionEvent extends BaseInspectionEventProperties {
|
|
967
|
+
type: '@xstate.transition';
|
|
968
|
+
eventType: string;
|
|
969
|
+
/** The event that caused the transition. */
|
|
970
|
+
event: AnyEventObject;
|
|
971
|
+
/** The source actor that sent the event, if any. */
|
|
972
|
+
sourceRef: ActorRefLike | undefined;
|
|
973
|
+
/** The target actor of the transition (usually the same as `actorRef`). */
|
|
974
|
+
targetRef: ActorRefLike | undefined;
|
|
975
|
+
/** The resulting snapshot of the transition. */
|
|
976
|
+
snapshot: Snapshot<unknown>;
|
|
977
|
+
/** The microstep transition definitions taken (always present). */
|
|
978
|
+
microsteps: AnyTransitionDefinition[];
|
|
979
|
+
/** The actions executed during the transition (always present). */
|
|
980
|
+
actions: ActionRecord[];
|
|
981
|
+
/** The events relayed to other actors during the transition (always present). */
|
|
982
|
+
sent: SentRecord[];
|
|
983
|
+
}
|
|
984
|
+
/**
|
|
985
|
+
* A lossless inspection protocol:
|
|
986
|
+
*
|
|
987
|
+
* - `@xstate.actor` — actor topology (identity + parent), drawable up front.
|
|
988
|
+
* - `@xstate.transition` — every transition facet: event, snapshot, source,
|
|
989
|
+
* microsteps, executed actions, and sent/scheduled events.
|
|
990
|
+
*
|
|
991
|
+
* POLICY: the protocol is exactly `@xstate.actor` and `@xstate.transition`. Do
|
|
992
|
+
* not add event types to this union. Dead letters (undeliverable events) are
|
|
993
|
+
* not inspection events: observe them with `system.onRejectedEvent`, the
|
|
994
|
+
* `onRejectedEvent` actor option, the `deadLetter` runtime operation, or the
|
|
995
|
+
* development warning. The protocol is deliberately
|
|
996
|
+
* minimal so inspectors can be written against a fixed set. New observable
|
|
997
|
+
* facets belong as fields on `@xstate.transition` (or on the existing events),
|
|
998
|
+
* or are derived by the consumer. Examples of derivation: an unhandled event
|
|
999
|
+
* is a `@xstate.transition` whose `snapshot` is the same reference as the
|
|
1000
|
+
* previous one with no `actions`; actor stop is the final transition's
|
|
1001
|
+
* `snapshot.status`. The `inspection.conformance.v6.test.ts` type test pins
|
|
1002
|
+
* the member list.
|
|
1003
|
+
*
|
|
1004
|
+
* @experimental
|
|
1005
|
+
*/
|
|
1006
|
+
type InspectionEvent = ActorInspectionEvent | TransitionInspectionEvent;
|
|
1007
|
+
interface ScheduledTimer {
|
|
1008
|
+
id: string;
|
|
1009
|
+
scheduledAt: number;
|
|
1010
|
+
dueAt: number;
|
|
1011
|
+
delay: number;
|
|
1012
|
+
source: AnyActor;
|
|
1013
|
+
}
|
|
1014
|
+
interface Clock {
|
|
1015
|
+
/** Returns the clock's current time in milliseconds. */
|
|
1016
|
+
now?(): number;
|
|
1017
|
+
setTimeout(fn: (...args: any[]) => void, timeout: number): any;
|
|
1018
|
+
clearTimeout(id: any): void;
|
|
1019
|
+
}
|
|
1020
|
+
interface WallClock {
|
|
1021
|
+
now(): number;
|
|
1022
|
+
}
|
|
1023
|
+
interface CryptoSource {
|
|
1024
|
+
getRandomValues?(array: Uint32Array<ArrayBuffer>): Uint32Array<ArrayBuffer>;
|
|
1025
|
+
randomUUID?(): string;
|
|
1026
|
+
}
|
|
1027
|
+
interface Scheduler {
|
|
1028
|
+
schedule(source: AnyActor, id: string, delay: number): void;
|
|
1029
|
+
cancel(source: AnyActor, id: string): void;
|
|
1030
|
+
cancelAll(actor: AnyActor): void;
|
|
1031
|
+
}
|
|
1032
|
+
/**
|
|
1033
|
+
* Runtime operations used to execute effects.
|
|
1034
|
+
*
|
|
1035
|
+
* XState calculates pure transitions; a runtime executes their effects. The
|
|
1036
|
+
* built-in local runtime is one implementation at the same level as any
|
|
1037
|
+
* other: install a different one via `system.runtime` (for durable hosts,
|
|
1038
|
+
* through `createDurable`'s adapter runtime operations).
|
|
1039
|
+
*/
|
|
1040
|
+
/**
|
|
1041
|
+
* Why an event was not delivered: `'invalidEvent'` (payload failed its
|
|
1042
|
+
* declared schema), `'internalEvent'` (an internal event type sent from
|
|
1043
|
+
* outside its owning actor), `'stopped'` (the target actor already stopped)
|
|
1044
|
+
* or `'missingTarget'` (`enq.sendTo` received an undefined ref, an unknown
|
|
1045
|
+
* child id, or the `parent` of a root actor). Hosts may report additional
|
|
1046
|
+
* reasons.
|
|
1047
|
+
*
|
|
1048
|
+
* @public
|
|
1049
|
+
*/
|
|
1050
|
+
type EventRejectionReason = 'invalidEvent' | 'internalEvent' | 'stopped' | 'missingTarget' | (string & {});
|
|
1051
|
+
/**
|
|
1052
|
+
* Extra detail attached to a dead letter.
|
|
1053
|
+
*
|
|
1054
|
+
* @public
|
|
1055
|
+
*/
|
|
1056
|
+
interface DeadLetterDetail {
|
|
1057
|
+
/** Standard Schema issues for `invalidEvent` rejections. */
|
|
1058
|
+
issues?: readonly StandardSchemaV1.Issue[] | undefined;
|
|
1059
|
+
/** The underlying error describing the rejection. */
|
|
1060
|
+
error?: Error | undefined;
|
|
1061
|
+
/**
|
|
1062
|
+
* The unresolved target id for `missingTarget` rejections (the child id
|
|
1063
|
+
* passed to `enq.sendTo`), when one was given.
|
|
1064
|
+
*/
|
|
1065
|
+
targetId?: string | undefined;
|
|
1066
|
+
}
|
|
1067
|
+
/**
|
|
1068
|
+
* Describes an event that was rejected at the delivery boundary instead of
|
|
1069
|
+
* being delivered to its target actor (a dead letter).
|
|
1070
|
+
*
|
|
1071
|
+
* @public
|
|
1072
|
+
*/
|
|
1073
|
+
interface EventRejection extends DeadLetterDetail {
|
|
1074
|
+
/** The event that was rejected. */
|
|
1075
|
+
event: AnyEventObject;
|
|
1076
|
+
/** The actor the event was addressed to. */
|
|
1077
|
+
targetRef: AnyActor | undefined;
|
|
1078
|
+
/** The `id` of the target actor. */
|
|
1079
|
+
targetId: string | undefined;
|
|
1080
|
+
/** The actor that sent the event, or `undefined` for an external send. */
|
|
1081
|
+
sourceRef: AnyActor | undefined;
|
|
1082
|
+
/** Whether the event came from outside the system or from another actor. */
|
|
1083
|
+
eventOrigin: 'external' | 'actor';
|
|
1084
|
+
reason: EventRejectionReason;
|
|
1085
|
+
}
|
|
1086
|
+
/** @experimental */
|
|
1087
|
+
interface ActorSystemRuntime {
|
|
1088
|
+
/** Publishes a newly created actor to the runtime. */
|
|
1089
|
+
spawnActor(source: AnyActor | undefined, actor: AnyActor): void | PromiseLike<void>;
|
|
1090
|
+
/** Starts an actor. */
|
|
1091
|
+
startActor(actor: AnyActor): void | PromiseLike<void>;
|
|
1092
|
+
/** Stops an actor without producing a completion result. */
|
|
1093
|
+
stopActor(actor: AnyActor): void | PromiseLike<void>;
|
|
1094
|
+
/** Completes or errors an actor and publishes its terminal result. */
|
|
1095
|
+
terminateActor(actor: AnyActor, termination: ActorTermination): void | PromiseLike<void>;
|
|
1096
|
+
/** Delivers an event between actors. */
|
|
1097
|
+
sendEvent(source: AnyActor | undefined, target: AnyActor, event: AnyEventObject): void | PromiseLike<void>;
|
|
1098
|
+
/** Publishes an emitted event. */
|
|
1099
|
+
emitEvent(source: AnyActor, event: EventObject): void | PromiseLike<void>;
|
|
1100
|
+
/** Schedules a logical timer. */
|
|
1101
|
+
scheduleTimer(source: AnyActor, id: string, delay: number): void | PromiseLike<void>;
|
|
1102
|
+
/** Cancels one logical timer. */
|
|
1103
|
+
cancelTimer(source: AnyActor, id: string): void | PromiseLike<void>;
|
|
1104
|
+
/**
|
|
1105
|
+
* Runs an async actor's entire body as one durable unit. The actor is the
|
|
1106
|
+
* natural journal entry: its identity — `address`, string `src` key and
|
|
1107
|
+
* serializable `input` — crosses any boundary, so a host can wrap `exec`
|
|
1108
|
+
* in its own step primitive, or ignore `exec` entirely and re-run the
|
|
1109
|
+
* registered logic on a remote executor from `(src, input)` alone. The
|
|
1110
|
+
* default runs the body in this process, unjournaled.
|
|
1111
|
+
*
|
|
1112
|
+
* Like `runStep`, this is an orchestration frame: it may span external
|
|
1113
|
+
* events and must never be serialized behind other runtime operations.
|
|
1114
|
+
*/
|
|
1115
|
+
runLogic(actor: AnyActor, exec: () => PromiseLike<unknown>): PromiseLike<unknown>;
|
|
1116
|
+
/**
|
|
1117
|
+
* Runs one keyed step of an async actor (`enq.step`). The default journals
|
|
1118
|
+
* the result in the actor's own snapshot; a durable host implements this
|
|
1119
|
+
* to journal steps in its own journal instead — memoized results replay
|
|
1120
|
+
* without re-running `exec`.
|
|
1121
|
+
*
|
|
1122
|
+
* Unlike other runtime operations, a step is an orchestration frame that
|
|
1123
|
+
* may itself await runtime operations, so implementations must not
|
|
1124
|
+
* serialize it behind them.
|
|
1125
|
+
*/
|
|
1126
|
+
runStep(actor: AnyActor, key: string, exec: () => unknown | PromiseLike<unknown>): unknown | PromiseLike<unknown>;
|
|
1127
|
+
/**
|
|
1128
|
+
* Reports an undeliverable event. Delivery stays at-most-once — this is
|
|
1129
|
+
* observability, not retry. The system always calls its
|
|
1130
|
+
* `onRejectedEvent` listeners first; the default then logs in development.
|
|
1131
|
+
* `detail` carries validation issues and the underlying error for events
|
|
1132
|
+
* rejected at the delivery boundary.
|
|
1133
|
+
*/
|
|
1134
|
+
deadLetter(source: AnyActor | undefined, target: AnyActor | undefined, event: AnyEventObject, reason: EventRejectionReason, detail?: DeadLetterDetail): void | PromiseLike<void>;
|
|
1135
|
+
/** Cancels all logical timers owned by an actor. */
|
|
1136
|
+
cancelAllTimers(source: AnyActor): void | PromiseLike<void>;
|
|
1137
|
+
}
|
|
1138
|
+
/** @public */
|
|
1139
|
+
interface ActorSystem<T extends ActorSystemInfo> extends ActorSystemRuntime {
|
|
1140
|
+
get: <K extends keyof T['actors']>(key: K) => T['actors'][K] | undefined;
|
|
1141
|
+
getAll: () => Partial<T['actors']>;
|
|
1142
|
+
inspect: (observer: Observer<InspectionEvent> | ((inspectionEvent: InspectionEvent) => void)) => Subscription;
|
|
1143
|
+
/**
|
|
1144
|
+
* Subscribes to events the system could not deliver (dead letters): sends
|
|
1145
|
+
* to a stopped actor, events rejected at the delivery boundary
|
|
1146
|
+
* and internal events sent from outside their owner. Listeners run in
|
|
1147
|
+
* registration order; a listener that throws does not prevent the others.
|
|
1148
|
+
* The `onRejectedEvent` option on `createActor` registers a listener the
|
|
1149
|
+
* same way.
|
|
1150
|
+
*
|
|
1151
|
+
* @public
|
|
1152
|
+
*/
|
|
1153
|
+
onRejectedEvent: (listener: (rejection: EventRejection) => void) => Subscription;
|
|
1154
|
+
scheduler: Scheduler;
|
|
1155
|
+
getSnapshot: () => {
|
|
1156
|
+
_scheduledTimers: Record<string, ScheduledTimer>;
|
|
1157
|
+
};
|
|
1158
|
+
start: () => void;
|
|
1159
|
+
_clock: Clock;
|
|
1160
|
+
_wallClock: WallClock;
|
|
1161
|
+
_logger: (...args: any[]) => void;
|
|
1162
|
+
_reportUnhandledError: (error: unknown) => void;
|
|
1163
|
+
_warn: (message: string) => void;
|
|
1164
|
+
/**
|
|
1165
|
+
* The runtime executing this system's effects. When unset, the built-in
|
|
1166
|
+
* local in-memory runtime runs them; `createActor(machine).start()` is just
|
|
1167
|
+
* that built-in runtime. A host runtime installed here applies to every
|
|
1168
|
+
* actor in the system — snapshot-scoped views and children created later
|
|
1169
|
+
* included — and may implement any subset of operations, with the rest
|
|
1170
|
+
* keeping the built-in behavior.
|
|
1171
|
+
*
|
|
1172
|
+
* An operation that returns a promise owns its own failure handling: the
|
|
1173
|
+
* paths that hand work to a runtime do not await it. `createDurable`
|
|
1174
|
+
* tracks its adapter's operations and fails `executeEffects` when one
|
|
1175
|
+
* rejects.
|
|
1176
|
+
*
|
|
1177
|
+
* Durable hosts should provide this through `createDurable`'s
|
|
1178
|
+
* adapter runtime operations rather than assigning it directly.
|
|
1179
|
+
*/
|
|
1180
|
+
runtime?: Partial<ActorSystemRuntime>;
|
|
1181
|
+
}
|
|
1182
|
+
/** @public */
|
|
1183
|
+
type AnyActorSystem = ActorSystem<any>;
|
|
1184
|
+
/** @public */
|
|
1185
|
+
type AsyncSnapshot<TOutput, TInput, TError = unknown> = Snapshot<TOutput, TError> & {
|
|
1186
|
+
input: TInput | undefined;
|
|
1187
|
+
effects?: Record<string, {
|
|
1188
|
+
status: 'active';
|
|
1189
|
+
} | {
|
|
1190
|
+
status: 'done';
|
|
1191
|
+
output?: unknown;
|
|
1192
|
+
} | {
|
|
1193
|
+
status: 'error';
|
|
1194
|
+
error: unknown;
|
|
1195
|
+
}>;
|
|
1196
|
+
};
|
|
1197
|
+
/** @public */
|
|
1198
|
+
type AsyncActorLogic<TOutput, TInput = unknown, TEmitted extends EventObject = EventObject, TError = unknown> = ActorLogic<AsyncSnapshot<TOutput, TInput, TError>, {
|
|
1199
|
+
type: string;
|
|
1200
|
+
[k: string]: unknown;
|
|
1201
|
+
}, TInput, AnyActorSystem, TEmitted>;
|
|
1202
|
+
/** @public */
|
|
1203
|
+
type AsyncActorRef<TOutput> = ActorRefFromLogic<AsyncActorLogic<TOutput, unknown>>;
|
|
1204
|
+
type AsyncActor<TOutput, TInput = unknown, TEmitted extends EventObject = EventObject> = ActorFromLogic<AsyncActorLogic<TOutput, TInput, TEmitted>>;
|
|
1205
|
+
/** @public */
|
|
1206
|
+
interface LogicArgs<TOutput, TInput> {
|
|
1207
|
+
/** Data that was provided to the async actor. */
|
|
1208
|
+
input: TInput;
|
|
1209
|
+
/** The actor system to which the async actor belongs. */
|
|
1210
|
+
system: AnyActorSystem;
|
|
1211
|
+
/** The async actor. */
|
|
1212
|
+
self: AsyncActor<TOutput, TInput>;
|
|
1213
|
+
/** Aborted when the async actor is stopped or times out. */
|
|
1214
|
+
signal: AbortSignal;
|
|
1215
|
+
}
|
|
1216
|
+
/** @public */
|
|
1217
|
+
interface LogicEnqueue<TEmitted extends EventObject> {
|
|
1218
|
+
/** Emits an event that can be observed with `actor.on(...)`. */
|
|
1219
|
+
emit: (emitted: TEmitted) => void;
|
|
1220
|
+
/**
|
|
1221
|
+
* Executes async work as a durable effect keyed by `key`.
|
|
1222
|
+
*
|
|
1223
|
+
* @experimental The durability semantics (step journaling, replay, and
|
|
1224
|
+
* resumption across persistence) are not finalized and may change.
|
|
1225
|
+
*/
|
|
1226
|
+
step: <TStepOutput>(key: string, exec: () => TStepOutput | PromiseLike<TStepOutput>) => Promise<TStepOutput>;
|
|
1227
|
+
}
|
|
1228
|
+
/** @public */
|
|
1229
|
+
type LogicFunction<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject> = (args: LogicArgs<TOutput, TInput>, enq: LogicEnqueue<TEmitted>) => PromiseLike<TOutput>;
|
|
1230
|
+
type AsyncLogicFunctionOutput<TLogicFunction extends (...args: any[]) => PromiseLike<any>> = Awaited<ReturnType<TLogicFunction>>;
|
|
1231
|
+
/** @public */
|
|
1232
|
+
interface LogicConfig<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject, TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1, TErrorSchema extends StandardSchemaV1 = StandardSchemaV1> {
|
|
1233
|
+
/**
|
|
1234
|
+
* Stable identifier for this async logic. This identifies the logic, not a
|
|
1235
|
+
* particular actor instance.
|
|
1236
|
+
*/
|
|
1237
|
+
id?: string | undefined;
|
|
1238
|
+
validator?: ActorLogicValidator | undefined;
|
|
1239
|
+
/** Schemas for inferring async logic types. */
|
|
1240
|
+
schemas?: {
|
|
1241
|
+
input?: TInputSchema;
|
|
1242
|
+
output?: TOutputSchema;
|
|
1243
|
+
/**
|
|
1244
|
+
* Types the error this logic fails with: the `error` snapshot field and
|
|
1245
|
+
* `event.error` in the invoking machine's `onError`. Type-only.
|
|
1246
|
+
*/
|
|
1247
|
+
error?: TErrorSchema;
|
|
1248
|
+
} | undefined;
|
|
1249
|
+
/** Maximum time this async logic may run before it is aborted and errors. */
|
|
1250
|
+
timeout?: number | string;
|
|
1251
|
+
/** The async work to execute when the actor starts. */
|
|
1252
|
+
run: LogicFunction<TOutput, TInput, TEmitted>;
|
|
1253
|
+
}
|
|
1254
|
+
/** @public */
|
|
1255
|
+
declare class TimeoutError extends Error {
|
|
1256
|
+
constructor(timeout: number | string);
|
|
1257
|
+
}
|
|
1258
|
+
/**
|
|
1259
|
+
* The error type of async logic: the `schemas.error` output, plus
|
|
1260
|
+
* {@link TimeoutError} when a `timeout` is configured.
|
|
1261
|
+
*
|
|
1262
|
+
* @public
|
|
1263
|
+
*/
|
|
1264
|
+
type AsyncLogicError<TErrorSchema extends StandardSchemaV1, TTimeout> = [TTimeout] extends [undefined] ? StandardSchemaV1.InferOutput<TErrorSchema> : StandardSchemaV1.InferOutput<TErrorSchema> | TimeoutError;
|
|
1265
|
+
/**
|
|
1266
|
+
* Represents an actor created by `createAsyncLogic`.
|
|
1267
|
+
*
|
|
1268
|
+
* The type of `self` within the actor's logic.
|
|
1269
|
+
*
|
|
1270
|
+
* @example
|
|
1271
|
+
*
|
|
1272
|
+
* ```ts
|
|
1273
|
+
* import { createAsyncLogic, createActor } from '@systemfsoftware/xstate';
|
|
1274
|
+
*
|
|
1275
|
+
* // The actor's resolved output
|
|
1276
|
+
* type Output = string;
|
|
1277
|
+
* // The actor's input.
|
|
1278
|
+
* type Input = { message: string };
|
|
1279
|
+
*
|
|
1280
|
+
* // Actor logic that fetches the url of an image of a cat saying `input.message`.
|
|
1281
|
+
* const logic = createAsyncLogic<Output, Input>({
|
|
1282
|
+
* run: async ({ input, self }, enq) => {
|
|
1283
|
+
* self;
|
|
1284
|
+
* // ^? AsyncActor<Output, Input>
|
|
1285
|
+
* enq.emit({ type: 'request.start' });
|
|
1286
|
+
*
|
|
1287
|
+
* const data = await fetch(
|
|
1288
|
+
* `https://cataas.com/cat/says/${input.message}`
|
|
1289
|
+
* );
|
|
1290
|
+
* const url = await data.json();
|
|
1291
|
+
* return url;
|
|
1292
|
+
* }
|
|
1293
|
+
* });
|
|
1294
|
+
*
|
|
1295
|
+
* const actor = createActor(logic, { input: { message: 'hello world' } });
|
|
1296
|
+
* // ^? AsyncActor<Output, Input>
|
|
1297
|
+
* ```
|
|
1298
|
+
*
|
|
1299
|
+
* @see {@link (createAsyncLogic:1)}
|
|
1300
|
+
*/
|
|
1301
|
+
/**
|
|
1302
|
+
* An actor logic creator which returns async logic as defined by an async
|
|
1303
|
+
* process that resolves or rejects after some time.
|
|
1304
|
+
*
|
|
1305
|
+
* Actors created from async actor logic can:
|
|
1306
|
+
*
|
|
1307
|
+
* - Output the resolved value of the async process
|
|
1308
|
+
* - Error with the rejected value of the async process
|
|
1309
|
+
* - Abort when stopped or timed out
|
|
1310
|
+
*
|
|
1311
|
+
* Sending events to async actors will have no effect.
|
|
1312
|
+
*
|
|
1313
|
+
* @example
|
|
1314
|
+
*
|
|
1315
|
+
* ```ts
|
|
1316
|
+
* const asyncLogic = createAsyncLogic({
|
|
1317
|
+
* id: 'fetch-user',
|
|
1318
|
+
* timeout: '30s',
|
|
1319
|
+
* run: async ({ signal }, enq) => {
|
|
1320
|
+
* enq.emit({ type: 'request.start' });
|
|
1321
|
+
* const result = await fetch('https://example.com/...', {
|
|
1322
|
+
* signal
|
|
1323
|
+
* }).then((data) => data.json());
|
|
1324
|
+
*
|
|
1325
|
+
* return result;
|
|
1326
|
+
* }
|
|
1327
|
+
* });
|
|
1328
|
+
*
|
|
1329
|
+
* const asyncActor = createActor(asyncLogic);
|
|
1330
|
+
* asyncActor.subscribe((snapshot) => {
|
|
1331
|
+
* console.log(snapshot);
|
|
1332
|
+
* });
|
|
1333
|
+
* asyncActor.start();
|
|
1334
|
+
* // => {
|
|
1335
|
+
* // output: undefined,
|
|
1336
|
+
* // status: 'active'
|
|
1337
|
+
* // ...
|
|
1338
|
+
* // }
|
|
1339
|
+
*
|
|
1340
|
+
* // After promise resolves
|
|
1341
|
+
* // => {
|
|
1342
|
+
* // output: { ... },
|
|
1343
|
+
* // status: 'done',
|
|
1344
|
+
* // ...
|
|
1345
|
+
* // }
|
|
1346
|
+
* ```
|
|
1347
|
+
*
|
|
1348
|
+
* @param asyncLogic A config object with a `run` function which returns a
|
|
1349
|
+
* Promise, and accepts an object with the following properties:
|
|
1350
|
+
*
|
|
1351
|
+
* - `input` - Data that was provided to the async actor
|
|
1352
|
+
* - `self` - The async actor ref
|
|
1353
|
+
* - `system` - The actor system to which the async actor belongs
|
|
1354
|
+
* - `signal` - An abort signal for cancellation
|
|
1355
|
+
*
|
|
1356
|
+
* `run` also receives an `enq` object with the following properties:
|
|
1357
|
+
*
|
|
1358
|
+
* - `emit` - Emits an event that can be observed with `actor.on(...)`
|
|
1359
|
+
*
|
|
1360
|
+
* @see {@link https://stately.ai/docs/input | Input docs} for more information about how input is passed
|
|
1361
|
+
* @public
|
|
1362
|
+
*/
|
|
1363
|
+
declare function createAsyncLogic<const TInputSchema extends StandardSchemaV1, const TOutputSchema extends StandardSchemaV1, TEmitted extends EventObject = EventObject, const TErrorSchema extends StandardSchemaV1 = StandardSchemaV1, TTimeout extends number | string | undefined = undefined>(asyncLogic: LogicConfig<StandardSchemaV1.InferOutput<TOutputSchema>, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, TInputSchema, TOutputSchema, TErrorSchema> & {
|
|
1364
|
+
schemas: {
|
|
1365
|
+
input: TInputSchema;
|
|
1366
|
+
output: TOutputSchema;
|
|
1367
|
+
error?: TErrorSchema;
|
|
1368
|
+
};
|
|
1369
|
+
} & {
|
|
1370
|
+
timeout?: TTimeout;
|
|
1371
|
+
}): AsyncActorLogic<StandardSchemaV1.InferOutput<TOutputSchema>, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, AsyncLogicError<TErrorSchema, TTimeout>> & {
|
|
1372
|
+
id?: string;
|
|
1373
|
+
};
|
|
1374
|
+
declare function createAsyncLogic<const TInputSchema extends StandardSchemaV1, TEmitted extends EventObject = EventObject, TLogicFunction extends LogicFunction<any, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted> = LogicFunction<any, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted>, const TErrorSchema extends StandardSchemaV1 = StandardSchemaV1, TTimeout extends number | string | undefined = undefined>(asyncLogic: Omit<LogicConfig<never, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, TInputSchema>, 'run' | 'schemas'> & {
|
|
1375
|
+
schemas: {
|
|
1376
|
+
input: TInputSchema;
|
|
1377
|
+
output?: never;
|
|
1378
|
+
error?: TErrorSchema;
|
|
1379
|
+
};
|
|
1380
|
+
run: TLogicFunction;
|
|
1381
|
+
} & {
|
|
1382
|
+
timeout?: TTimeout;
|
|
1383
|
+
}): AsyncActorLogic<AsyncLogicFunctionOutput<TLogicFunction>, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, AsyncLogicError<TErrorSchema, TTimeout>> & {
|
|
1384
|
+
id?: string;
|
|
1385
|
+
};
|
|
1386
|
+
declare function createAsyncLogic<const TOutputSchema extends StandardSchemaV1, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject, const TErrorSchema extends StandardSchemaV1 = StandardSchemaV1, TTimeout extends number | string | undefined = undefined>(asyncLogic: LogicConfig<StandardSchemaV1.InferOutput<TOutputSchema>, TInput, TEmitted, StandardSchemaV1, TOutputSchema, TErrorSchema> & {
|
|
1387
|
+
schemas: {
|
|
1388
|
+
input?: never;
|
|
1389
|
+
output: TOutputSchema;
|
|
1390
|
+
error?: TErrorSchema;
|
|
1391
|
+
};
|
|
1392
|
+
} & {
|
|
1393
|
+
timeout?: TTimeout;
|
|
1394
|
+
}): AsyncActorLogic<StandardSchemaV1.InferOutput<TOutputSchema>, TInput, TEmitted, AsyncLogicError<TErrorSchema, TTimeout>> & {
|
|
1395
|
+
id?: string;
|
|
1396
|
+
};
|
|
1397
|
+
declare function createAsyncLogic<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject, const TErrorSchema extends StandardSchemaV1 = StandardSchemaV1, TTimeout extends number | string | undefined = undefined>(asyncLogic: Omit<LogicConfig<TOutput, TInput, TEmitted>, 'schemas'> & {
|
|
1398
|
+
schemas: {
|
|
1399
|
+
input?: never;
|
|
1400
|
+
output?: never;
|
|
1401
|
+
error: TErrorSchema;
|
|
1402
|
+
};
|
|
1403
|
+
} & {
|
|
1404
|
+
timeout?: TTimeout;
|
|
1405
|
+
}): AsyncActorLogic<TOutput, TInput, TEmitted, AsyncLogicError<TErrorSchema, TTimeout>> & {
|
|
1406
|
+
id?: string;
|
|
1407
|
+
};
|
|
1408
|
+
declare function createAsyncLogic<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject>(asyncLogic: Omit<LogicConfig<TOutput, TInput, TEmitted>, 'schemas'> & {
|
|
1409
|
+
schemas?: undefined;
|
|
1410
|
+
}): AsyncActorLogic<TOutput, TInput, TEmitted> & {
|
|
1411
|
+
id?: string;
|
|
1412
|
+
};
|
|
1413
|
+
declare const symbolObservable: typeof Symbol.observable;
|
|
1414
|
+
/**
|
|
1415
|
+
* An Actor is a running process that can receive events, send events and change
|
|
1416
|
+
* its behavior based on the events it receives, which can cause effects outside
|
|
1417
|
+
* of the actor. When you run a state machine, it becomes an actor.
|
|
1418
|
+
*
|
|
1419
|
+
* An `Actor` is the concrete runtime instance with lifecycle methods and
|
|
1420
|
+
* system-owned internals. It also satisfies the narrower `ActorRef` contract,
|
|
1421
|
+
* so consumer APIs should accept `ActorRef` when they only need to send events
|
|
1422
|
+
* or read snapshots.
|
|
1423
|
+
*
|
|
1424
|
+
* @public
|
|
1425
|
+
*/
|
|
1426
|
+
declare class Actor<TLogic extends AnyActorLogic> implements ActorInstance<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>, SendableEventFromLogic<TLogic>> {
|
|
1427
|
+
logic: TLogic;
|
|
1428
|
+
/** The current internal state of the actor. */
|
|
1429
|
+
private _snapshot;
|
|
1430
|
+
/**
|
|
1431
|
+
* The clock that is responsible for setting and clearing timeouts, such as
|
|
1432
|
+
* delayed events and transitions.
|
|
1433
|
+
*/
|
|
1434
|
+
clock: Clock;
|
|
1435
|
+
wallClock: WallClock;
|
|
1436
|
+
options: Readonly<ActorOptions<TLogic>>;
|
|
1437
|
+
/** The unique identifier for this actor relative to its parent. */
|
|
1438
|
+
id: string;
|
|
1439
|
+
private _boundProcess?;
|
|
1440
|
+
private mailbox?;
|
|
1441
|
+
private _mailboxStarted;
|
|
1442
|
+
private observers?;
|
|
1443
|
+
/** Whether a consumer subscribed to this actor's error after it errored. */
|
|
1444
|
+
private _errorObserved;
|
|
1445
|
+
private eventListeners;
|
|
1446
|
+
private logger;
|
|
1447
|
+
private warn;
|
|
1448
|
+
private _forceDeferredActions;
|
|
1449
|
+
_parent?: AnyActor | undefined;
|
|
1450
|
+
ref: ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>, SendableEventFromLogic<TLogic>>;
|
|
1451
|
+
private _actorScope;
|
|
1452
|
+
private _initialEffects;
|
|
1453
|
+
registryKey: string | undefined;
|
|
1454
|
+
/** The globally unique process ID for this invocation. */
|
|
1455
|
+
sessionId: string;
|
|
1456
|
+
private _address?;
|
|
1457
|
+
/**
|
|
1458
|
+
* The deterministic logical address of this actor within its system: the
|
|
1459
|
+
* `/`-joined path of actor ids from the root. Stable across persistence and
|
|
1460
|
+
* restore, unlike `sessionId`, which identifies one incarnation.
|
|
1461
|
+
*
|
|
1462
|
+
* `/` separates segments, so an id containing one (a state name with a
|
|
1463
|
+
* slash reaches its invoked child's id) is percent-encoded to keep the
|
|
1464
|
+
* path unambiguous.
|
|
1465
|
+
*/
|
|
1466
|
+
get address(): string;
|
|
1467
|
+
/** The system to which this actor belongs. */
|
|
1468
|
+
system: AnyActorSystem;
|
|
1469
|
+
private _trigger?;
|
|
1470
|
+
get trigger(): ActorTrigger<SendableEventFromLogic<TLogic>>;
|
|
1471
|
+
private _boundSend?;
|
|
1472
|
+
get send(): ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>, SendableEventFromLogic<TLogic>>['send'];
|
|
1473
|
+
src: string | AnyActorLogic;
|
|
1474
|
+
/**
|
|
1475
|
+
* Creates a new actor instance for the given logic with the provided options,
|
|
1476
|
+
* if any.
|
|
1477
|
+
*
|
|
1478
|
+
* @param logic The logic to create an actor from
|
|
1479
|
+
* @param options Actor options
|
|
1480
|
+
*/
|
|
1481
|
+
constructor(logic: TLogic, options?: ActorOptions<TLogic>);
|
|
1482
|
+
private _deferred;
|
|
1483
|
+
private _restored;
|
|
1484
|
+
private get self();
|
|
1485
|
+
private get defer();
|
|
1486
|
+
private get stopChild();
|
|
1487
|
+
private get emit();
|
|
1488
|
+
private get actionExecutor();
|
|
1489
|
+
/** Associates each live snapshot with this actor for later pure transitions. */
|
|
1490
|
+
private _setSnapshot;
|
|
1491
|
+
private _setErrorSnapshot;
|
|
1492
|
+
/** Recover via the logic's error event if possible; otherwise error out. */
|
|
1493
|
+
private _recoverOrError;
|
|
1494
|
+
private _tryHandleExecutionError;
|
|
1495
|
+
private _next;
|
|
1496
|
+
private update;
|
|
1497
|
+
private _flushInitialEffects;
|
|
1498
|
+
/**
|
|
1499
|
+
* Subscribe an observer to an actor’s snapshot values.
|
|
1500
|
+
*
|
|
1501
|
+
* @remarks
|
|
1502
|
+
* The observer will receive the actor’s snapshot value when it is emitted.
|
|
1503
|
+
* The observer can be:
|
|
1504
|
+
*
|
|
1505
|
+
* - A plain function that receives the latest snapshot, or
|
|
1506
|
+
* - An observer object whose `.next(snapshot)` method receives the latest
|
|
1507
|
+
* snapshot
|
|
1508
|
+
*
|
|
1509
|
+
* @example
|
|
1510
|
+
*
|
|
1511
|
+
* ```ts
|
|
1512
|
+
* // Observer as a plain function
|
|
1513
|
+
* const subscription = actor.subscribe((snapshot) => {
|
|
1514
|
+
* console.log(snapshot);
|
|
1515
|
+
* });
|
|
1516
|
+
* ```
|
|
1517
|
+
*
|
|
1518
|
+
* @example
|
|
1519
|
+
*
|
|
1520
|
+
* ```ts
|
|
1521
|
+
* // Observer as an object
|
|
1522
|
+
* const subscription = actor.subscribe({
|
|
1523
|
+
* next(snapshot) {
|
|
1524
|
+
* console.log(snapshot);
|
|
1525
|
+
* },
|
|
1526
|
+
* error(err) {
|
|
1527
|
+
* // ...
|
|
1528
|
+
* },
|
|
1529
|
+
* complete() {
|
|
1530
|
+
* // ...
|
|
1531
|
+
* }
|
|
1532
|
+
* });
|
|
1533
|
+
* ```
|
|
1534
|
+
*
|
|
1535
|
+
* The return value of `actor.subscribe(observer)` is a subscription object
|
|
1536
|
+
* that has an `.unsubscribe()` method. You can call
|
|
1537
|
+
* `subscription.unsubscribe()` to unsubscribe the observer:
|
|
1538
|
+
*
|
|
1539
|
+
* @example
|
|
1540
|
+
*
|
|
1541
|
+
* ```ts
|
|
1542
|
+
* const subscription = actor.subscribe((snapshot) => {
|
|
1543
|
+
* // ...
|
|
1544
|
+
* });
|
|
1545
|
+
*
|
|
1546
|
+
* // Unsubscribe the observer
|
|
1547
|
+
* subscription.unsubscribe();
|
|
1548
|
+
* ```
|
|
1549
|
+
*
|
|
1550
|
+
* When the actor is stopped, all of its observers will automatically be
|
|
1551
|
+
* unsubscribed.
|
|
1552
|
+
*
|
|
1553
|
+
* @param observer - Either a plain function that receives the latest
|
|
1554
|
+
* snapshot, or an observer object whose `.next(snapshot)` method receives
|
|
1555
|
+
* the latest snapshot
|
|
1556
|
+
*/
|
|
1557
|
+
subscribe(observer: Observer<SnapshotFrom<TLogic>>): Subscription;
|
|
1558
|
+
subscribe(nextListener?: (snapshot: SnapshotFrom<TLogic>) => void, errorListener?: (error: any) => void, completeListener?: () => void): Subscription;
|
|
1559
|
+
on<TType extends EmittedFrom<TLogic>['type'] | '*'>(type: TType, handler: (emitted: EmittedFrom<TLogic> & (TType extends '*' ? unknown : {
|
|
1560
|
+
type: TType;
|
|
1561
|
+
})) => void): Subscription;
|
|
1562
|
+
select<TSelected>(selector: (snapshot: SnapshotFrom<TLogic>) => TSelected, equalityFn?: (a: TSelected, b: TSelected) => boolean): Readable<TSelected>;
|
|
1563
|
+
/** Starts the Actor from the initial state */
|
|
1564
|
+
start(): this;
|
|
1565
|
+
private _process;
|
|
1566
|
+
private _warnedUnhandledTypes?;
|
|
1567
|
+
private _reportUnhandledEvent;
|
|
1568
|
+
/** Stops the Actor and unsubscribe all listeners. */
|
|
1569
|
+
stop(): this;
|
|
1570
|
+
private _complete;
|
|
1571
|
+
/**
|
|
1572
|
+
* Reports an unhandled error unless a consumer observes it before the
|
|
1573
|
+
* report runs. An actor can error before its creator has a chance to
|
|
1574
|
+
* subscribe, so the check waits one macrotask for a subscriber with an
|
|
1575
|
+
* `error` callback.
|
|
1576
|
+
*/
|
|
1577
|
+
private _reportUnlessObserved;
|
|
1578
|
+
private _error;
|
|
1579
|
+
private _stopProcedure;
|
|
1580
|
+
/**
|
|
1581
|
+
* Sends an event to the running Actor to trigger a transition.
|
|
1582
|
+
*
|
|
1583
|
+
* @param event The event to send
|
|
1584
|
+
*/
|
|
1585
|
+
private _sendPublic;
|
|
1586
|
+
/**
|
|
1587
|
+
* Returns the actor's serializable logical identity: its `id`, `address`,
|
|
1588
|
+
* and registered source key (when the actor was created from one).
|
|
1589
|
+
*/
|
|
1590
|
+
toJSON(): {
|
|
1591
|
+
xstate$type: string;
|
|
1592
|
+
id: string;
|
|
1593
|
+
address: string;
|
|
1594
|
+
src: string | undefined;
|
|
1595
|
+
};
|
|
1596
|
+
/**
|
|
1597
|
+
* Obtain the internal state of the actor, which can be persisted.
|
|
1598
|
+
*
|
|
1599
|
+
* @remarks
|
|
1600
|
+
* The internal state can be persisted from any actor, not only machines.
|
|
1601
|
+
*
|
|
1602
|
+
* Note that the persisted state is not the same as the snapshot from
|
|
1603
|
+
* {@link Actor.getSnapshot}. Persisted state represents the internal state of
|
|
1604
|
+
* the actor, while snapshots represent the actor's last emitted value.
|
|
1605
|
+
*
|
|
1606
|
+
* Can be restored with {@link ActorOptions.snapshot}
|
|
1607
|
+
* @see https://stately.ai/docs/persistence
|
|
1608
|
+
*/
|
|
1609
|
+
getPersistedSnapshot(options?: {
|
|
1610
|
+
/**
|
|
1611
|
+
* Whether persisted machine children embed their own persisted state
|
|
1612
|
+
* (the co-locating runtime's whole-tree checkpoint) or are referenced by
|
|
1613
|
+
* logical address only, leaving each child's state with the runtime that
|
|
1614
|
+
* owns it. Defaults to `true`.
|
|
1615
|
+
*/
|
|
1616
|
+
embedChildren?: boolean;
|
|
1617
|
+
}): PersistedSnapshotOf<TLogic>;
|
|
1618
|
+
[symbolObservable](): InteropSubscribable<SnapshotFrom<TLogic>>;
|
|
1619
|
+
/**
|
|
1620
|
+
* Read an actor’s snapshot synchronously.
|
|
1621
|
+
*
|
|
1622
|
+
* @remarks
|
|
1623
|
+
* The snapshot is the last value the actor published, not a query of its
|
|
1624
|
+
* private state: the actor emits a snapshot when it transitions, and this
|
|
1625
|
+
* returns that cached last emission. The read is coherent within one
|
|
1626
|
+
* synchronous transition turn because event processing runs to completion;
|
|
1627
|
+
* across asynchronous boundaries it may be stale, like any observed value.
|
|
1628
|
+
*
|
|
1629
|
+
* Only co-located actors publish full snapshots. A location-transparent
|
|
1630
|
+
* remote handle exposes lifecycle only (`{ status, output?, error? }`): while
|
|
1631
|
+
* the handle exists among its parent's children the child is presumed
|
|
1632
|
+
* `active`, and its terminal result arrives as a completion event.
|
|
1633
|
+
*
|
|
1634
|
+
* Note that some actors, such as callback actors generated with
|
|
1635
|
+
* `createCallbackLogic`, will not emit snapshots.
|
|
1636
|
+
* @see {@link Actor.(subscribe:1)} to subscribe to an actor’s snapshot values.
|
|
1637
|
+
* @see {@link Actor.getPersistedSnapshot} to persist the internal state of an actor (which is more than just a snapshot).
|
|
1638
|
+
*/
|
|
1639
|
+
getSnapshot(): SnapshotFrom<TLogic>;
|
|
1640
|
+
}
|
|
1641
|
+
/**
|
|
1642
|
+
* `'input'` when creating an actor from `TLogic` requires input (its input type
|
|
1643
|
+
* does not accept `undefined`), otherwise `never`.
|
|
1644
|
+
*
|
|
1645
|
+
* @public
|
|
1646
|
+
*/
|
|
1647
|
+
type RequiredActorOptionsKeys<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? never : 'input';
|
|
1648
|
+
/**
|
|
1649
|
+
* The options `createActor` (and framework hooks) require for `TLogic`:
|
|
1650
|
+
* `{ input }` or a persisted `{ snapshot }` when
|
|
1651
|
+
* the logic requires input, otherwise nothing.
|
|
1652
|
+
*
|
|
1653
|
+
* @public
|
|
1654
|
+
*/
|
|
1655
|
+
type RequiredActorOptionsFor<TLogic extends AnyActorLogic> = [RequiredActorOptionsKeys<TLogic>] extends [never] ? {} : { [K in RequiredActorOptionsKeys<TLogic>]: unknown; } | {
|
|
1656
|
+
snapshot: NonNullable<ActorOptions<TLogic>['snapshot']>;
|
|
1657
|
+
};
|
|
1658
|
+
/** Options accepted by {@link createActor}. */
|
|
1659
|
+
type CreateActorOptionsArgs<TLogic extends AnyActorLogic> = [RequiredActorOptionsKeys<TLogic>] extends [never] ? [options?: ActorOptions<TLogic>] : [options: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>];
|
|
1660
|
+
/**
|
|
1661
|
+
* Creates a new actor instance for the given actor logic with the provided
|
|
1662
|
+
* options, if any.
|
|
1663
|
+
*
|
|
1664
|
+
* @remarks
|
|
1665
|
+
* When you create an actor from actor logic via `createActor(logic)`, you
|
|
1666
|
+
* implicitly create an actor system where the created actor is the root actor.
|
|
1667
|
+
* Any actors spawned from this root actor and its descendants are part of that
|
|
1668
|
+
* actor system.
|
|
1669
|
+
* @example
|
|
1670
|
+
*
|
|
1671
|
+
* ```ts
|
|
1672
|
+
* import { createActor } from '@systemfsoftware/xstate';
|
|
1673
|
+
* import { someActorLogic } from './someActorLogic.ts';
|
|
1674
|
+
*
|
|
1675
|
+
* // Creating the actor, which implicitly creates an actor system with itself as the root actor
|
|
1676
|
+
* const actor = createActor(someActorLogic);
|
|
1677
|
+
*
|
|
1678
|
+
* actor.subscribe((snapshot) => {
|
|
1679
|
+
* console.log(snapshot);
|
|
1680
|
+
* });
|
|
1681
|
+
*
|
|
1682
|
+
* // Actors must be started by calling `actor.start()`, which will also start the actor system.
|
|
1683
|
+
* actor.start();
|
|
1684
|
+
*
|
|
1685
|
+
* // Actors can receive events
|
|
1686
|
+
* actor.send({ type: 'someEvent' });
|
|
1687
|
+
*
|
|
1688
|
+
* // You can stop root actors by calling `actor.stop()`, which will also stop the actor system and all actors in that system.
|
|
1689
|
+
* actor.stop();
|
|
1690
|
+
* ```
|
|
1691
|
+
*
|
|
1692
|
+
* @param logic - The actor logic to create an actor from. For a state machine
|
|
1693
|
+
* actor logic creator, see {@link (createMachine:1)}. Other actor logic creators
|
|
1694
|
+
* include {@link (createCallbackLogic:1)}, {@link (createEventObservableLogic:1)},
|
|
1695
|
+
* {@link (createObservableLogic:1)}, {@link (createLogic:1)}, and
|
|
1696
|
+
* {@link (createAsyncLogic:1)}.
|
|
1697
|
+
* @param options - Actor options
|
|
1698
|
+
* @public
|
|
1699
|
+
*/
|
|
1700
|
+
declare function createActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: CreateActorOptionsArgs<TLogic>): Actor<TLogic>;
|
|
1701
|
+
/** @public */
|
|
1702
|
+
type Spawner<TSystemRegistry extends SystemRegistry = SystemRegistry> = <TLogic extends AnyActorLogic>(src: TLogic, ...[options]: ConditionalRequired<[options?: {
|
|
1703
|
+
id?: string;
|
|
1704
|
+
registryKey?: RegistryKeyForLogic<TLogic, TSystemRegistry>;
|
|
1705
|
+
input?: InputFrom<TLogic>;
|
|
1706
|
+
syncSnapshot?: boolean;
|
|
1707
|
+
} & { [K in RequiredLogicInput<TLogic>]: unknown; }], IsNotNever<RequiredLogicInput<TLogic>>>) => ActorFromLogic<TLogic>;
|
|
1708
|
+
interface StateNodeOptions<TStateMeta extends MetaObject, TTransitionMeta extends MetaObject> {
|
|
1709
|
+
_key: string;
|
|
1710
|
+
_parent?: StateNode<any, any, TStateMeta, TTransitionMeta>;
|
|
1711
|
+
_machine: AnyStateMachine;
|
|
1712
|
+
}
|
|
1713
|
+
/** @public */
|
|
1714
|
+
declare class StateNode<TContext extends MachineContext = MachineContext, TEvent extends EventObject = EventObject, TStateMeta extends MetaObject = any, TTransitionMeta extends MetaObject = TStateMeta> {
|
|
1715
|
+
/** The raw config used to create the machine. */
|
|
1716
|
+
config: AnyStateNodeConfig;
|
|
1717
|
+
/**
|
|
1718
|
+
* The relative key of the state node, which represents its location in the
|
|
1719
|
+
* overall state value.
|
|
1720
|
+
*/
|
|
1721
|
+
key: string;
|
|
1722
|
+
/** The unique ID of the state node. */
|
|
1723
|
+
id: string;
|
|
1724
|
+
/**
|
|
1725
|
+
* The type of this state node:
|
|
1726
|
+
*
|
|
1727
|
+
* - `'atomic'` - no child state nodes
|
|
1728
|
+
* - `'compound'` - nested child state nodes (XOR)
|
|
1729
|
+
* - `'parallel'` - orthogonal nested child state nodes (AND)
|
|
1730
|
+
* - `'history'` - history state node
|
|
1731
|
+
* - `'choice'` - pure routing decision state node
|
|
1732
|
+
* - `'final'` - final state node
|
|
1733
|
+
*/
|
|
1734
|
+
type: 'atomic' | 'compound' | 'parallel' | 'final' | 'history' | 'choice';
|
|
1735
|
+
/** The string path from the root machine node to this node. */
|
|
1736
|
+
path: string[];
|
|
1737
|
+
/** The child state nodes. */
|
|
1738
|
+
states: Record<string, StateNode<TContext, TEvent, TStateMeta, TTransitionMeta>>;
|
|
1739
|
+
/**
|
|
1740
|
+
* The type of history on this state node. Can be:
|
|
1741
|
+
*
|
|
1742
|
+
* - `'shallow'` - recalls only top-level historical state value
|
|
1743
|
+
* - `'deep'` - recalls historical state value at all levels
|
|
1744
|
+
*/
|
|
1745
|
+
history: false | 'shallow' | 'deep';
|
|
1746
|
+
/** The action(s) to be executed upon entering the state node. */
|
|
1747
|
+
entry: AnyAction | undefined;
|
|
1748
|
+
/** The action(s) to be executed upon exiting the state node. */
|
|
1749
|
+
exit: AnyAction | undefined;
|
|
1750
|
+
/** The parent state node. */
|
|
1751
|
+
parent?: StateNode<TContext, TEvent, TStateMeta, TTransitionMeta> | undefined;
|
|
1752
|
+
/** The root machine node. */
|
|
1753
|
+
machine: AnyStateMachine;
|
|
1754
|
+
/**
|
|
1755
|
+
* The meta data associated with this state node, which will be returned in
|
|
1756
|
+
* State instances.
|
|
1757
|
+
*/
|
|
1758
|
+
meta?: TStateMeta;
|
|
1759
|
+
/**
|
|
1760
|
+
* The output data sent with the `xstate.done.state` event if this is a final
|
|
1761
|
+
* state node.
|
|
1762
|
+
*/
|
|
1763
|
+
output?: Mapper<MachineContext, EventObject, unknown, EventObject> | NonReducibleUnknown;
|
|
1764
|
+
/**
|
|
1765
|
+
* The order this state node appears. Corresponds to the implicit document
|
|
1766
|
+
* order.
|
|
1767
|
+
*/
|
|
1768
|
+
order: number;
|
|
1769
|
+
description?: string | undefined;
|
|
1770
|
+
schemas: SetupStateSchemas | undefined;
|
|
1771
|
+
tags: string[];
|
|
1772
|
+
transitions: Map<string, TransitionDefinition<any, any, TTransitionMeta>[]>;
|
|
1773
|
+
always?: Array<TransitionDefinition<any, any, TTransitionMeta>> | undefined;
|
|
1774
|
+
invoke: Array<InvokeDefinition<any, any, any, TTransitionMeta, any, any, any, any>>;
|
|
1775
|
+
on: TransitionDefinitionMap<any, any, TTransitionMeta>;
|
|
1776
|
+
after: Array<DelayedTransitionDefinition<any, any, TTransitionMeta>>;
|
|
1777
|
+
events: Array<EventDescriptor<any>>;
|
|
1778
|
+
ownEvents: Array<EventDescriptor<any>>;
|
|
1779
|
+
private _candidateCache?;
|
|
1780
|
+
constructor(
|
|
1781
|
+
/** The raw config used to create the machine. */
|
|
1782
|
+
config: AnyStateNodeConfig, options: StateNodeOptions<TStateMeta, TTransitionMeta>);
|
|
1783
|
+
get initial(): InitialTransitionDefinition<TTransitionMeta>;
|
|
1784
|
+
}
|
|
1785
|
+
/** @public */
|
|
1786
|
+
declare function checkStateIn(stateValue: StateValue): (snapshot: AnyMachineSnapshot) => boolean;
|
|
1787
|
+
declare function checkStateIn(snapshot: AnyMachineSnapshot, stateValue: StateValue): boolean;
|
|
1788
|
+
/**
|
|
1789
|
+
* Returns the state nodes represented by the current state value.
|
|
1790
|
+
*
|
|
1791
|
+
* @param stateValue The state value or State instance
|
|
1792
|
+
* @public
|
|
1793
|
+
*/
|
|
1794
|
+
declare function getStateNodes(stateNode: AnyStateNode, stateValue: StateValue): Array<AnyStateNode>;
|
|
1795
|
+
type TransitionSelectionResult = {
|
|
1796
|
+
enabled: boolean;
|
|
1797
|
+
result: unknown;
|
|
1798
|
+
reusable: boolean;
|
|
1799
|
+
};
|
|
1800
|
+
type TransitionSelectionResults = Map<AnyTransitionDefinition, TransitionSelectionResult>;
|
|
1801
|
+
/**
|
|
1802
|
+
* Thrown when one macrostep takes more microsteps than the machine's
|
|
1803
|
+
* `options.maxIterations` (default `1000`) without reaching a stable state,
|
|
1804
|
+
* usually because eventless transitions or raised events form a cycle.
|
|
1805
|
+
*
|
|
1806
|
+
* @public
|
|
1807
|
+
*/
|
|
1808
|
+
declare class InfiniteTransitionError extends Error {
|
|
1809
|
+
/** The id of the actor that was transitioning, if any. */
|
|
1810
|
+
readonly actorId: string | undefined;
|
|
1811
|
+
/** The event being processed. */
|
|
1812
|
+
readonly event: EventObject;
|
|
1813
|
+
/** The microstep bound that was exceeded. */
|
|
1814
|
+
readonly maxIterations: number;
|
|
1815
|
+
/** The last (up to 5) state values visited, oldest first. */
|
|
1816
|
+
readonly states: StateValue[];
|
|
1817
|
+
constructor(actorId: string | undefined, event: EventObject, maxIterations: number, states: StateValue[]);
|
|
1818
|
+
}
|
|
1819
|
+
type CompatibleProvidedActorSource<TExpected extends AnyActorLogic, TActual extends AnyActorLogic> = IsAny<TActual> extends true ? TActual : [OutputFrom<TActual>] extends [OutputFrom<TExpected>] ? [Omit<SnapshotFrom<TActual>, 'input'>] extends [Omit<SnapshotFrom<TExpected>, 'input'>] ? [InputFrom<TExpected>] extends [InputFrom<TActual>] ? [EventFromLogic<TExpected>] extends [EventFromLogic<TActual>] ? [EmittedFrom<TActual>] extends [EmittedFrom<TExpected>] ? TActual : never : never : never : never : never;
|
|
1820
|
+
type ProvidedActors<TExpectedActorMap extends Sources['actors'], TProvidedActorMap extends Partial<Record<keyof TExpectedActorMap & string, AnyActorLogic>>> = { [K in keyof TProvidedActorMap]: K extends keyof TExpectedActorMap ? TProvidedActorMap[K] extends AnyActorLogic ? CompatibleProvidedActorSource<TExpectedActorMap[K], TProvidedActorMap[K]> : never : never; };
|
|
1821
|
+
type ProvidedSourceMap<TDeclared, TProvided> = { [K in keyof TDeclared]: K extends keyof TProvided ? {} extends Pick<TProvided, K> ? TDeclared[K] | Exclude<TProvided[K], undefined> : Exclude<TProvided[K], undefined> : TDeclared[K]; };
|
|
1822
|
+
type ProvidedActionContracts<T> = { [K in keyof T]: T[K] extends ((...args: infer TArgs) => any) ? (...args: TArgs) => void : never; };
|
|
1823
|
+
/** @public */
|
|
1824
|
+
declare class StateMachine<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TInput, TOutput, TEmitted extends EventObject, TMeta extends MetaObject, TConfig extends StateSchema, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TInternalEvent extends EventObject = never, TTransitionMeta extends MetaObject = TMeta> implements ActorLogic<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, TInput, AnyActorSystem, TEmitted> {
|
|
1825
|
+
/** The raw config used to create the machine. */
|
|
1826
|
+
config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any, any, any> & {
|
|
1827
|
+
schemas?: AnyMachineSchemas;
|
|
1828
|
+
};
|
|
1829
|
+
validator?: ActorLogicValidator | undefined;
|
|
1830
|
+
/**
|
|
1831
|
+
* Type-only marker for the actor's internal event protocol. `actor.send` and
|
|
1832
|
+
* `actor.trigger` read it to drop internal events from the public protocol,
|
|
1833
|
+
* so it must survive `stripInternal` into the published declarations. Not
|
|
1834
|
+
* `declare` (the build's babel pipeline rejects declare class fields); the
|
|
1835
|
+
* one `undefined` property this emits per machine instance is inert.
|
|
1836
|
+
*/
|
|
1837
|
+
readonly _internalEventType: TInternalEvent;
|
|
1838
|
+
/** Type-only marker for transition metadata. Never assigned at runtime. */
|
|
1839
|
+
readonly _transitionMetaType: TTransitionMeta;
|
|
1840
|
+
/**
|
|
1841
|
+
* Type-only marker for the declared input type. `getInitialSnapshot` takes
|
|
1842
|
+
* input optionally, so inferring input from it always adds `undefined`;
|
|
1843
|
+
* `InputFrom` reads this carrier instead. Method-shaped so it stays
|
|
1844
|
+
* bivariant like `getInitialSnapshot`. Never assigned at runtime.
|
|
1845
|
+
*/
|
|
1846
|
+
readonly _inputType: {
|
|
1847
|
+
carry(input: TInput): void;
|
|
1848
|
+
}['carry'];
|
|
1849
|
+
/**
|
|
1850
|
+
* Type-level carriers for the machine's source maps and state schema. Type
|
|
1851
|
+
* helpers in integration packages read these to walk a machine's declared
|
|
1852
|
+
* actions, actors and invoked sources. They are never assigned at runtime.
|
|
1853
|
+
*/
|
|
1854
|
+
readonly _actionMap: TActionMap;
|
|
1855
|
+
readonly _actorMap: TActorMap;
|
|
1856
|
+
readonly _stateSchema: TConfig;
|
|
1857
|
+
/** The machine's own version. */
|
|
1858
|
+
version: TConfig extends {
|
|
1859
|
+
version: infer TVersion extends string;
|
|
1860
|
+
} ? TVersion : undefined;
|
|
1861
|
+
schemas: AnyMachineSchemas | undefined;
|
|
1862
|
+
/** Standard Schema for snapshots persisted by this machine version. */
|
|
1863
|
+
readonly snapshotSchema: StandardSchemaV1<unknown, Snapshot<unknown> & PersistedMachineSnapshot & {
|
|
1864
|
+
context: TContext;
|
|
1865
|
+
}>;
|
|
1866
|
+
/** Standard Schema for complete events accepted by this machine version. */
|
|
1867
|
+
readonly eventSchema: StandardSchemaV1<unknown, TEvent>;
|
|
1868
|
+
sources: Sources;
|
|
1869
|
+
/** Runtime options for machine execution. */
|
|
1870
|
+
options: MachineOptions;
|
|
1871
|
+
root: StateNode<TContext, TEvent, TMeta, TTransitionMeta>;
|
|
1872
|
+
id: TConfig extends {
|
|
1873
|
+
id: infer TId extends string;
|
|
1874
|
+
} ? TId : '(machine)';
|
|
1875
|
+
states: StateNode<TContext, TEvent, TMeta, TTransitionMeta>['states'];
|
|
1876
|
+
events: Array<EventDescriptor<TEvent>>;
|
|
1877
|
+
internalEventDescriptors: ReadonlyArray<string>;
|
|
1878
|
+
/**
|
|
1879
|
+
* Adapter hooks for actor-local transition evaluation state. Used by
|
|
1880
|
+
* `@xstate/scxml`; not part of the stable API.
|
|
1881
|
+
*
|
|
1882
|
+
* @experimental
|
|
1883
|
+
*/
|
|
1884
|
+
_microstepHooks?: AnyStateMachine['_microstepHooks'];
|
|
1885
|
+
constructor(
|
|
1886
|
+
/** The raw config used to create the machine. */
|
|
1887
|
+
config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any, any, any> & {
|
|
1888
|
+
schemas?: AnyMachineSchemas;
|
|
1889
|
+
}, sources?: Sources, validator?: ActorLogicValidator | undefined);
|
|
1890
|
+
/**
|
|
1891
|
+
* Clones this state machine with the provided sources.
|
|
1892
|
+
*
|
|
1893
|
+
* @param sources Options (`actions`, `guards`, `actors`, `delays`) to
|
|
1894
|
+
* recursively merge with the existing options.
|
|
1895
|
+
* @returns A new `StateMachine` instance with the provided sources.
|
|
1896
|
+
*/
|
|
1897
|
+
provide<const TProvidedActorMap extends Partial<Record<keyof TActorMap & string, AnyActorLogic>> = {}, const TProvidedActionMap extends Partial<ProvidedActionContracts<TActionMap>> = {}>(sources: {
|
|
1898
|
+
actions?: TProvidedActionMap & Partial<ProvidedActionContracts<TActionMap>> & Record<Exclude<keyof TProvidedActionMap, keyof TActionMap>, never>;
|
|
1899
|
+
actors?: TProvidedActorMap & ProvidedActors<TActorMap, TProvidedActorMap>;
|
|
1900
|
+
guards?: Partial<TGuardMap> & { [K in keyof TGuardMap]?: GuardSourceMap<TContext, TEvent>[string]; };
|
|
1901
|
+
delays?: { [K in keyof TDelayMap]?: DelaySourceMap<TContext, TEvent>[string]; };
|
|
1902
|
+
}): StateMachine<TContext, TEvent, TChildren, TStateValue, TTag, TInput, TOutput, TEmitted, TMeta, TConfig, ProvidedSourceMap<TActionMap, TProvidedActionMap>, ProvidedSourceMap<TActorMap, TProvidedActorMap>, TGuardMap, TDelayMap, TInternalEvent, TTransitionMeta>;
|
|
1903
|
+
resolveState(config: {
|
|
1904
|
+
value: StateValue;
|
|
1905
|
+
context?: TContext;
|
|
1906
|
+
historyValue?: HistoryValue;
|
|
1907
|
+
status?: SnapshotStatus;
|
|
1908
|
+
output?: TOutput;
|
|
1909
|
+
error?: unknown;
|
|
1910
|
+
} & ([TContext] extends [never] ? {} : Equals<TContext, MachineContext> extends false ? {
|
|
1911
|
+
context: unknown;
|
|
1912
|
+
} : {})): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>;
|
|
1913
|
+
/**
|
|
1914
|
+
* Determines the next snapshot given the current `snapshot` and received
|
|
1915
|
+
* `event`. Calculates a full macrostep from all microsteps.
|
|
1916
|
+
*
|
|
1917
|
+
* @param snapshot The current snapshot
|
|
1918
|
+
* @param event The received event
|
|
1919
|
+
*/
|
|
1920
|
+
transition(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, event: TEvent, actorScope?: ActorScope<typeof snapshot, TEvent, AnyActorSystem, TEmitted>): ActorLogicTransitionResult<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, ExecutableActionObjectFromLogic<this>>;
|
|
1921
|
+
private _collectEffects;
|
|
1922
|
+
private _attachPureActorRef;
|
|
1923
|
+
private _transitionFast;
|
|
1924
|
+
/**
|
|
1925
|
+
* Determines the next state given the current `state` and `event`. Calculates
|
|
1926
|
+
* a microstep.
|
|
1927
|
+
*
|
|
1928
|
+
* @param state The current state
|
|
1929
|
+
* @param event The received event
|
|
1930
|
+
*/
|
|
1931
|
+
microstep(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, event: TEvent, actorScope: AnyActorScope): Array<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>>;
|
|
1932
|
+
getTransitionData(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, event: TEvent, actorScope: AnyActorScope, selectionResults?: TransitionSelectionResults): Array<AnyTransitionDefinition>;
|
|
1933
|
+
isInternalEventType(eventType: string): boolean;
|
|
1934
|
+
/**
|
|
1935
|
+
* Returns the initial `State` instance, with reference to `self` as an
|
|
1936
|
+
* `ActorRef`.
|
|
1937
|
+
*/
|
|
1938
|
+
getInitialSnapshot(actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>, input?: TInput): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>;
|
|
1939
|
+
initialTransition(input: TInput | undefined, actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>): ActorLogicTransitionResult<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, ExecutableActionObjectFromLogic<this>>;
|
|
1940
|
+
start(snapshot?: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>): void;
|
|
1941
|
+
getStateNodeById(stateId: string): StateNode<TContext, TEvent, TMeta, TTransitionMeta>;
|
|
1942
|
+
getPersistedSnapshot(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, options?: unknown, warn?: (message: string) => void): Snapshot<unknown>;
|
|
1943
|
+
restoreSnapshot(snapshot: Snapshot<unknown>, actorScope?: ActorScope<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, AnyActorSystem, TEmitted>): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>;
|
|
1944
|
+
}
|
|
1945
|
+
declare const builtInActions: {
|
|
1946
|
+
"@xstate.spawn": (actor: AnyActor) => any;
|
|
1947
|
+
"@xstate.start": (actor: AnyActor) => any;
|
|
1948
|
+
"@xstate.raise": (actorScope: AnyActorScope, _event: EventObject, options: {
|
|
1949
|
+
id?: string;
|
|
1950
|
+
delay?: number;
|
|
1951
|
+
}) => void | PromiseLike<void>;
|
|
1952
|
+
"@xstate.sendTo": (actorScope: AnyActorScope, actor: AnyActor, event: EventObject, options: {
|
|
1953
|
+
id?: string;
|
|
1954
|
+
delay?: number;
|
|
1955
|
+
}) => void | PromiseLike<void>;
|
|
1956
|
+
"@xstate.cancel": (actorScope: AnyActorScope, sendId: string) => void | PromiseLike<void>;
|
|
1957
|
+
"@xstate.stop": (actorScope: AnyActorScope, actor: AnyActor) => void | PromiseLike<void>;
|
|
1958
|
+
"@xstate.terminate": (actor: AnyActor, termination: ActorTermination) => any;
|
|
1959
|
+
};
|
|
1960
|
+
/** @public */
|
|
1961
|
+
type HomomorphicOmit<T, K extends keyof any> = { [P in keyof T as Exclude<P, K>]: T[P]; };
|
|
1962
|
+
/**
|
|
1963
|
+
* @remarks
|
|
1964
|
+
* `T | unknown` reduces to `unknown` and that can be problematic when it comes
|
|
1965
|
+
* to contextual typing. It especially is a problem when the union has a
|
|
1966
|
+
* function member, like here:
|
|
1967
|
+
*
|
|
1968
|
+
* ```ts
|
|
1969
|
+
* declare function test(
|
|
1970
|
+
* cbOrVal: ((arg: number) => unknown) | unknown
|
|
1971
|
+
* ): void;
|
|
1972
|
+
* test((arg) => {}); // oops, implicit any
|
|
1973
|
+
* ```
|
|
1974
|
+
*
|
|
1975
|
+
* This type can be used to avoid this problem. This union represents the same
|
|
1976
|
+
* value space as `unknown`.
|
|
1977
|
+
* @public
|
|
1978
|
+
*/
|
|
1979
|
+
type NonReducibleUnknown = {} | null | undefined;
|
|
1980
|
+
/** @public */
|
|
1981
|
+
type AnyFunction = (...args: any[]) => any;
|
|
1982
|
+
type ReturnTypeOrValue<T> = T extends AnyFunction ? ReturnType<T> : T;
|
|
1983
|
+
/** @public */
|
|
1984
|
+
type IsNever<T> = [T] extends [never] ? true : false;
|
|
1985
|
+
/** @public */
|
|
1986
|
+
type IsNotNever<T> = [T] extends [never] ? false : true;
|
|
1987
|
+
/** @public */
|
|
1988
|
+
type Compute<A> = { [K in keyof A]: A[K]; } & unknown;
|
|
1989
|
+
/** @public */
|
|
1990
|
+
type Prop<T, K> = K extends keyof T ? T[K] : never;
|
|
1991
|
+
/** @public */
|
|
1992
|
+
type Equals<A1, A2> = (<A>() => A extends A2 ? true : false) extends (<A>() => (A extends A1 ? true : false)) ? true : false;
|
|
1993
|
+
/** @public */
|
|
1994
|
+
type IsAny<T> = Equals<T, any>;
|
|
1995
|
+
/** @public */
|
|
1996
|
+
type Cast<A, B> = A extends B ? A : B;
|
|
1997
|
+
/** @public */
|
|
1998
|
+
type DoNotInfer<T> = [T][T extends any ? 0 : any];
|
|
1999
|
+
/** @public */
|
|
2000
|
+
type LowInfer<T> = T & NonNullable<unknown>;
|
|
2001
|
+
/** @public */
|
|
2002
|
+
type MetaObject = Record<string, any>;
|
|
2003
|
+
/** @public */
|
|
2004
|
+
type Lazy<T> = () => T;
|
|
2005
|
+
/** @public */
|
|
2006
|
+
type MaybeLazy<T> = T | Lazy<T>;
|
|
2007
|
+
/** @public */
|
|
2008
|
+
type EventPayloadPattern<TEvent extends EventObject> = TEvent extends any ? Partial<Omit<TEvent, 'type'>> : never;
|
|
2009
|
+
/** @public */
|
|
2010
|
+
interface AnyEventObject extends EventObject {
|
|
2011
|
+
[key: string]: any;
|
|
2012
|
+
}
|
|
2013
|
+
/** @public */
|
|
2014
|
+
interface ParameterizedObject {
|
|
2015
|
+
type: string;
|
|
2016
|
+
params?: NonReducibleUnknown;
|
|
2017
|
+
}
|
|
2018
|
+
/** @public */
|
|
2019
|
+
type UnifiedArg<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject> = {
|
|
2020
|
+
context: TContext;
|
|
2021
|
+
event: TExpressionEvent;
|
|
2022
|
+
self: ActorSelf<MachineSnapshot<TContext, TEvent, Record<string, AnyActorRef | undefined>, // TODO: this should be replaced with `TChildren`
|
|
2023
|
+
StateValue, string, unknown, TODO, // TMeta
|
|
2024
|
+
TODO>, TEvent, AnyEventObject>;
|
|
2025
|
+
system: AnyActorSystem;
|
|
2026
|
+
} & OutputArg<TExpressionEvent>;
|
|
2027
|
+
type DoneEventType = 'xstate.done.actor' | 'xstate.done.state';
|
|
2028
|
+
/** @public */
|
|
2029
|
+
type OutputArg<TEvent extends EventObject> = TEvent extends {
|
|
2030
|
+
type: DoneEventType;
|
|
2031
|
+
output: infer TOutput;
|
|
2032
|
+
} ? {
|
|
2033
|
+
output: TOutput;
|
|
2034
|
+
} : {
|
|
2035
|
+
output: undefined;
|
|
2036
|
+
};
|
|
2037
|
+
/** @public */
|
|
2038
|
+
type ActionArgs<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject> = UnifiedArg<TContext, TExpressionEvent, TEvent> & {
|
|
2039
|
+
children: Record<string, AnyActor>;
|
|
2040
|
+
};
|
|
2041
|
+
/** @public */
|
|
2042
|
+
type InputFrom<T> = T extends {
|
|
2043
|
+
_inputType: (input: infer TMachineInput) => void;
|
|
2044
|
+
} ? TMachineInput : T extends ActorLogic<infer _TSnapshot, infer _TEvent, infer TInput, infer _TSystem, infer _TEmitted> ? TInput : T extends StateMachine<infer _TContext, infer _TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer TInput, infer _TOutput, infer _TEmitted, infer _TMeta, infer _TStateSchema, infer _TActionMap, infer _TActorMap, infer _TGuardMap, infer _TDelayMap> ? TInput : never;
|
|
2045
|
+
/** @public */
|
|
2046
|
+
type OutputFrom<T> = T extends ActorLogic<infer TSnapshot, infer _TEvent, infer _TInput, infer _TSystem, infer _TEmitted> ? (TSnapshot & {
|
|
2047
|
+
status: 'done';
|
|
2048
|
+
})['output'] : T extends ActorRef<infer TSnapshot, infer _TEvent, infer _TEmitted> ? (TSnapshot & {
|
|
2049
|
+
status: 'done';
|
|
2050
|
+
})['output'] : never;
|
|
2051
|
+
type ErrorFromSnapshot<TSnapshot> = TSnapshot extends {
|
|
2052
|
+
error: infer TError;
|
|
2053
|
+
} ? Exclude<TError, undefined> : unknown;
|
|
2054
|
+
/** @public */
|
|
2055
|
+
type ErrorFrom<T> = T extends {
|
|
2056
|
+
transition: (snapshot: infer TSnapshot, ...args: any[]) => any;
|
|
2057
|
+
} ? ErrorFromSnapshot<TSnapshot> : T extends ActorRef<infer TSnapshot, infer _TEvent, infer _TEmitted> ? ErrorFromSnapshot<TSnapshot> : never;
|
|
2058
|
+
/** @public */
|
|
2059
|
+
type ConditionalRequired<T, Condition extends boolean> = Condition extends true ? Required<T> : T;
|
|
2060
|
+
/** @public */
|
|
2061
|
+
type StateKey = string | AnyMachineSnapshot;
|
|
2062
|
+
/** @public */
|
|
2063
|
+
interface StateValueMap {
|
|
2064
|
+
[key: string]: StateValue | undefined;
|
|
2065
|
+
}
|
|
2066
|
+
/**
|
|
2067
|
+
* The string or object representing the state value relative to the parent
|
|
2068
|
+
* state node.
|
|
2069
|
+
*
|
|
2070
|
+
* @remarks
|
|
2071
|
+
* - For a child atomic state node, this is a string, e.g., `"pending"`.
|
|
2072
|
+
* - For complex state nodes, this is an object, e.g.,
|
|
2073
|
+
* `{ success: "someChildState" }`.
|
|
2074
|
+
* @public
|
|
2075
|
+
*/
|
|
2076
|
+
type StateValue = string | StateValueMap;
|
|
2077
|
+
/** @public */
|
|
2078
|
+
type TransitionTarget = SingleOrArray<string>;
|
|
2079
|
+
/** @public */
|
|
2080
|
+
type TransitionContextPatch<TContext extends MachineContext> = Partial<TContext> & {
|
|
2081
|
+
call?: never;
|
|
2082
|
+
apply?: never;
|
|
2083
|
+
bind?: never;
|
|
2084
|
+
};
|
|
2085
|
+
/** @public */
|
|
2086
|
+
type TransitionContextMapper<TContext extends MachineContext, TCurrentEvent extends EventObject, TEvent extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], _TCtx extends MachineContext = [TContext] extends [never] ? any : TContext> = (args: TransitionFunctionArgs<_TCtx, TCurrentEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap>) => TransitionContextPatch<_TCtx>;
|
|
2087
|
+
/** @public */
|
|
2088
|
+
interface TransitionConfig<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject, TEmitted extends EventObject, TMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> {
|
|
2089
|
+
actions?: never;
|
|
2090
|
+
/** A shallow partial event pattern that must match before guards run. */
|
|
2091
|
+
matches?: EventPayloadPattern<TExpressionEvent>;
|
|
2092
|
+
guard?: unknown;
|
|
2093
|
+
reenter?: boolean;
|
|
2094
|
+
target?: TransitionTarget | undefined;
|
|
2095
|
+
context?: TransitionContextPatch<TContext> | TransitionContextMapper<TContext, TExpressionEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap>;
|
|
2096
|
+
to?: TransitionConfigFunction<TContext, TExpressionEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta>;
|
|
2097
|
+
meta?: TMeta;
|
|
2098
|
+
description?: string;
|
|
2099
|
+
}
|
|
2100
|
+
/** @public */
|
|
2101
|
+
interface InitialTransitionConfig<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> extends TransitionConfig<TContext, TEvent, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap> {
|
|
2102
|
+
target: string;
|
|
2103
|
+
}
|
|
2104
|
+
/** @public */
|
|
2105
|
+
type AnyTransitionConfig = TransitionConfig<any, // TContext
|
|
2106
|
+
any, // TExpressionEvent
|
|
2107
|
+
any, // TEvent
|
|
2108
|
+
any, // TEmitted
|
|
2109
|
+
any, // TMeta
|
|
2110
|
+
any, // TActionMap
|
|
2111
|
+
any, // TActorMap
|
|
2112
|
+
any, // TGuardMap
|
|
2113
|
+
any>;
|
|
2114
|
+
/** @public */
|
|
2115
|
+
interface InvokeDefinition<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> {
|
|
2116
|
+
id: string;
|
|
2117
|
+
registryKey: string | undefined;
|
|
2118
|
+
logic: string | AnyActorLogic | (({ actors, context, event, self }: {
|
|
2119
|
+
actors: TActorMap;
|
|
2120
|
+
context: TContext;
|
|
2121
|
+
event: TEvent;
|
|
2122
|
+
self: AnyActorRef;
|
|
2123
|
+
}) => string | AnyActorLogic);
|
|
2124
|
+
/** The source of the actor logic to be invoked */
|
|
2125
|
+
src: AnyActorLogic | string;
|
|
2126
|
+
input?: Mapper<TContext, TEvent, NonReducibleUnknown, TEvent> | NonReducibleUnknown;
|
|
2127
|
+
/**
|
|
2128
|
+
* The transition to take upon the invoked child machine reaching its final
|
|
2129
|
+
* top-level state.
|
|
2130
|
+
*/
|
|
2131
|
+
onDone?: string | SingleOrArray<TransitionConfig<TContext, DoneActorEvent<unknown>, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap>>;
|
|
2132
|
+
/**
|
|
2133
|
+
* The transition to take upon the invoked child machine sending an error
|
|
2134
|
+
* event.
|
|
2135
|
+
*/
|
|
2136
|
+
onError?: string | SingleOrArray<TransitionConfig<TContext, ErrorActorEvent, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap>>;
|
|
2137
|
+
onSnapshot?: string | SingleOrArray<TransitionConfig<TContext, SnapshotEvent, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap>>;
|
|
2138
|
+
/**
|
|
2139
|
+
* The duration (in ms) after which this invocation times out if it has not
|
|
2140
|
+
* completed.
|
|
2141
|
+
*/
|
|
2142
|
+
timeout?: number | ((args: {
|
|
2143
|
+
context: TContext;
|
|
2144
|
+
event: TEvent;
|
|
2145
|
+
}) => number);
|
|
2146
|
+
/** The transition to take when the invoke-level `timeout` expires. */
|
|
2147
|
+
onTimeout?: string | SingleOrArray<TransitionConfig<TContext, ActorTimeoutEvent, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap>>;
|
|
2148
|
+
}
|
|
2149
|
+
/** @public */
|
|
2150
|
+
type AnyInvokeDefinition = InvokeDefinition<MachineContext, EventObject, EventObject, any, // TMeta
|
|
2151
|
+
Sources['actions'], Sources['actors'], Sources['guards'], Sources['delays']>;
|
|
2152
|
+
type Delay<TDelay extends string> = TDelay | number;
|
|
2153
|
+
/** @public */
|
|
2154
|
+
type DelayedTransitions<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> = { [K in Delay<keyof TDelayMap & string>]?: string | SingleOrArray<TransitionConfig<TContext, TEvent, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap>> | TransitionConfigFunction<TContext, TEvent, TEvent, TODO, any, any, any, any, any>; };
|
|
2155
|
+
/** @public */
|
|
2156
|
+
type StateTypes = 'atomic' | 'compound' | 'parallel' | 'final' | 'choice' | 'history' | ({} & string);
|
|
2157
|
+
/** @public */
|
|
2158
|
+
type SingleOrArray<T> = readonly T[] | T;
|
|
2159
|
+
/** @public */
|
|
2160
|
+
type StateNodesConfig<TContext extends MachineContext, TEvent extends EventObject> = { [K in string]: StateNode<TContext, TEvent>; };
|
|
2161
|
+
/** @public */
|
|
2162
|
+
type TransitionConfigTarget = string | undefined;
|
|
2163
|
+
type LegacyTransitionConfigOrTarget<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject, TEmitted extends EventObject, TMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> = SingleOrArray<TransitionConfigTarget | TransitionConfig<TContext, TExpressionEvent, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap> | TransitionConfigFunction<TContext, TExpressionEvent, TEvent, TEmitted, TActionMap, TActorMap, TGuardMap, TDelayMap, TMeta>>;
|
|
2164
|
+
/** @public */
|
|
2165
|
+
type TransitionConfigFunction<TContext extends MachineContext, TCurrentEvent extends EventObject, TEvent extends EventObject, TEmitted extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TMeta extends MetaObject, TInput = undefined, _TCtx extends MachineContext = [TContext] extends [never] ? any : TContext, TChildren extends Record<string, AnyActorRef | undefined> = {}> = (args: TransitionFunctionArgs<_TCtx, TCurrentEvent, TEvent, TActionMap, TActorMap, TGuardMap, TDelayMap, TChildren> & {
|
|
2166
|
+
input: TInput;
|
|
2167
|
+
}, enq: EnqueueObject<TEvent, TEmitted, SystemRegistry, Compute<CallbackActors<TActorMap>>, TChildren>) => {
|
|
2168
|
+
target?: string | string[];
|
|
2169
|
+
context?: TransitionContextPatch<_TCtx>;
|
|
2170
|
+
reenter?: boolean;
|
|
2171
|
+
meta?: TMeta;
|
|
2172
|
+
input?: Record<string, unknown>;
|
|
2173
|
+
} | void;
|
|
2174
|
+
declare const sendableEvent: unique symbol;
|
|
2175
|
+
type SendableEventCarrier<TEvent extends EventObject> = {
|
|
2176
|
+
readonly [sendableEvent]?: TEvent;
|
|
2177
|
+
};
|
|
2178
|
+
/**
|
|
2179
|
+
* The actor-logic surface available in inline callbacks. The outer `Compute`
|
|
2180
|
+
* at each use site is necessary: otherwise declaration emit repeats the
|
|
2181
|
+
* registered machine's structural type in every callback signature.
|
|
2182
|
+
*
|
|
2183
|
+
* @public
|
|
2184
|
+
*/
|
|
2185
|
+
type CallbackActors<T extends Sources['actors']> = { [K in keyof T]: ActorLogic<OpaqueMachineSnapshot<SnapshotFrom<T[K]>>, EventFromLogic<T[K]>, InputFrom<T[K]>, AnyActorSystem, EmittedFrom<T[K]>> & SendableEventCarrier<SendableEventFromLogic<T[K]>>; };
|
|
2186
|
+
type TransitionFunctionArgs<TContext, TCurrentEvent extends EventObject, TEvent extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TChildren extends Record<string, AnyActorRef | undefined> = Record<string, AnyActor>> = {
|
|
2187
|
+
context: TContext;
|
|
2188
|
+
event: TCurrentEvent;
|
|
2189
|
+
self: ActorSelf<MachineSnapshot<TContext & MachineContext, TEvent, TODO, TODO, TODO, TODO, TODO, TODO>, TEvent>;
|
|
2190
|
+
parent: UnknownActorRef | undefined;
|
|
2191
|
+
value: StateValue;
|
|
2192
|
+
children: TChildren;
|
|
2193
|
+
system: AnyActorSystem;
|
|
2194
|
+
actions: TActionMap;
|
|
2195
|
+
actors: Compute<CallbackActors<TActorMap>>;
|
|
2196
|
+
guards: TGuardMap;
|
|
2197
|
+
delays: TDelayMap;
|
|
2198
|
+
} & OutputArg<TCurrentEvent>;
|
|
2199
|
+
/** @public */
|
|
2200
|
+
type AnyTransitionConfigFunction = TransitionConfigFunction<any, any, any, any, any, any, any, any, any, any, any, // _TCtx
|
|
2201
|
+
any>;
|
|
2202
|
+
/** @public */
|
|
2203
|
+
type TransitionsConfig<TContext extends MachineContext, TEvent extends EventObject, TEmitted extends EventObject, TMeta extends MetaObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays']> = { [K in EventDescriptor<TEvent>]?: LegacyTransitionConfigOrTarget<TContext, ExtractEvent<TEvent, K>, TEvent, TEmitted, TMeta, TActionMap, TActorMap, TGuardMap, TDelayMap>; };
|
|
2204
|
+
type PartialEventDescriptor<TEventType extends string> = TEventType extends `${infer TLeading}.${infer TTail}` ? `${TLeading}.*` | `${TLeading}.${PartialEventDescriptor<TTail>}` : never;
|
|
2205
|
+
/** @public */
|
|
2206
|
+
type EventDescriptor<TEvent extends EventObject> = TEvent['type'] | PartialEventDescriptor<TEvent['type']> | '*';
|
|
2207
|
+
/** @public */
|
|
2208
|
+
type NormalizeDescriptor<TDescriptor extends string> = TDescriptor extends '*' ? string : TDescriptor extends `${infer TLeading}.*` ? `${TLeading}.${string}` : TDescriptor;
|
|
2209
|
+
type EventTypeMatchesDescriptor<TEventType extends string, TDescriptor extends string> = TEventType extends NormalizeDescriptor<TDescriptor> ? true : false;
|
|
2210
|
+
type IsInternalEventType<TEventType extends string, TDescriptors extends string> = string extends TDescriptors ? false : true extends (TDescriptors extends any ? EventTypeMatchesDescriptor<TEventType, TDescriptors> : never) ? true : false;
|
|
2211
|
+
type ExcludeInternalEvents<TEvent extends EventObject, TDescriptors extends string> = TEvent extends any ? IsInternalEventType<TEvent['type'], TDescriptors> extends true ? never : TEvent : never;
|
|
2212
|
+
type InternalEventTypes<TInternalEvent extends EventObject> = TInternalEvent extends any ? TInternalEvent['type'] : never;
|
|
2213
|
+
type SendableEventFromMachine<TEvent extends EventObject, TInternalEvent extends EventObject> = IsAny<TInternalEvent> extends true ? TEvent : ExcludeInternalEvents<TEvent, InternalEventTypes<TInternalEvent>>;
|
|
2214
|
+
/** @public */
|
|
2215
|
+
type IsLiteralString<T extends string> = string extends T ? false : true;
|
|
2216
|
+
type ActorsBySrc<TActor extends ProvidedActor> = { [A in TActor as A['src']]: A['logic']; };
|
|
2217
|
+
type DistributeActors<TContext extends MachineContext, TEvent extends EventObject, TActor extends ProvidedActor, _TAction extends ParameterizedObject, _TGuard extends ParameterizedObject, _TDelay extends string, TEmitted extends EventObject, TMeta extends MetaObject, TSpecificActor extends ProvidedActor> = TSpecificActor extends {
|
|
2218
|
+
src: infer TSrc;
|
|
2219
|
+
} ? Compute<{
|
|
2220
|
+
registryKey?: string;
|
|
2221
|
+
/** The source of the machine to be invoked, or the machine itself. */
|
|
2222
|
+
src: TSrc | (({ actors, context, event, self }: {
|
|
2223
|
+
actors: ActorsBySrc<TActor>;
|
|
2224
|
+
context: TContext;
|
|
2225
|
+
event: TEvent;
|
|
2226
|
+
self: AnyActorRef;
|
|
2227
|
+
}) => TSrc | TSpecificActor['logic']);
|
|
2228
|
+
/**
|
|
2229
|
+
* The unique identifier for the invoked machine. If not specified,
|
|
2230
|
+
* this will be the machine's own `id`, or the URL (from `src`).
|
|
2231
|
+
*/
|
|
2232
|
+
id?: TSpecificActor['id'];
|
|
2233
|
+
input?: Mapper<TContext, TEvent, InputFrom<TSpecificActor['logic']>, TEvent> | InputFrom<TSpecificActor['logic']>;
|
|
2234
|
+
/**
|
|
2235
|
+
* The transition to take upon the invoked child machine reaching
|
|
2236
|
+
* its final top-level state.
|
|
2237
|
+
*/
|
|
2238
|
+
onDone?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, DoneActorEvent<OutputFrom<TSpecificActor['logic']>>, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2239
|
+
/**
|
|
2240
|
+
* The transition to take upon the invoked child machine sending an
|
|
2241
|
+
* error event.
|
|
2242
|
+
*/
|
|
2243
|
+
onError?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, ErrorActorEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2244
|
+
onSnapshot?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, SnapshotEvent<SnapshotFrom<TSpecificActor['logic']>>, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2245
|
+
timeout?: number | ((args: {
|
|
2246
|
+
context: TContext;
|
|
2247
|
+
event: TEvent;
|
|
2248
|
+
}) => number);
|
|
2249
|
+
onTimeout?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, ActorTimeoutEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2250
|
+
} & { [K in RequiredActorOptions<TSpecificActor>]: unknown; }> | {
|
|
2251
|
+
id?: never;
|
|
2252
|
+
registryKey?: string;
|
|
2253
|
+
src: string | AnyActorLogic | (({ actors, context, event, self }: {
|
|
2254
|
+
actors: ActorsBySrc<TActor>;
|
|
2255
|
+
context: TContext;
|
|
2256
|
+
event: TEvent;
|
|
2257
|
+
self: AnyActorRef;
|
|
2258
|
+
}) => string | AnyActorLogic);
|
|
2259
|
+
input?: Mapper<TContext, TEvent, NonReducibleUnknown, TEvent> | NonReducibleUnknown;
|
|
2260
|
+
onDone?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, DoneActorEvent<unknown>, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2261
|
+
onError?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, ErrorActorEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2262
|
+
onSnapshot?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, SnapshotEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2263
|
+
timeout?: number | ((args: {
|
|
2264
|
+
context: TContext;
|
|
2265
|
+
event: TEvent;
|
|
2266
|
+
}) => number);
|
|
2267
|
+
onTimeout?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, ActorTimeoutEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2268
|
+
} : never;
|
|
2269
|
+
type LegacyInvokeConfig<TContext extends MachineContext, TEvent extends EventObject, TActor extends ProvidedActor, TAction extends ParameterizedObject, TGuard extends ParameterizedObject, TDelay extends string, TEmitted extends EventObject, TMeta extends MetaObject> = IsLiteralString<TActor['src']> extends true ? DistributeActors<TContext, TEvent, TActor, TAction, TGuard, TDelay, TEmitted, TMeta, TActor> : {
|
|
2270
|
+
/**
|
|
2271
|
+
* The unique identifier for the invoked machine. If not specified, this
|
|
2272
|
+
* will be the machine's own `id`, or the URL (from `src`).
|
|
2273
|
+
*/
|
|
2274
|
+
id?: string;
|
|
2275
|
+
registryKey?: string;
|
|
2276
|
+
/** The source of the machine to be invoked, or the machine itself. */
|
|
2277
|
+
src: string | AnyActorLogic | (({ actors, context, event, self }: {
|
|
2278
|
+
actors: ActorsBySrc<TActor>;
|
|
2279
|
+
context: TContext;
|
|
2280
|
+
event: TEvent;
|
|
2281
|
+
self: AnyActorRef;
|
|
2282
|
+
}) => string | AnyActorLogic);
|
|
2283
|
+
input?: Mapper<TContext, TEvent, NonReducibleUnknown, TEvent> | NonReducibleUnknown;
|
|
2284
|
+
/**
|
|
2285
|
+
* The transition to take upon the invoked child machine reaching its
|
|
2286
|
+
* final top-level state.
|
|
2287
|
+
*/
|
|
2288
|
+
onDone?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, DoneActorEvent<unknown>, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2289
|
+
/**
|
|
2290
|
+
* The transition to take upon the invoked child machine sending an
|
|
2291
|
+
* error event.
|
|
2292
|
+
*/
|
|
2293
|
+
onError?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, ErrorActorEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2294
|
+
onSnapshot?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, SnapshotEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2295
|
+
timeout?: number | ((args: {
|
|
2296
|
+
context: TContext;
|
|
2297
|
+
event: TEvent;
|
|
2298
|
+
}) => number);
|
|
2299
|
+
onTimeout?: string | SingleOrArray<LegacyTransitionConfigOrTarget<TContext, ActorTimeoutEvent, TEvent, TEmitted, TMeta, any, any, any, any>>;
|
|
2300
|
+
};
|
|
2301
|
+
/** @public */
|
|
2302
|
+
type AnyInvokeConfig = LegacyInvokeConfig<any, any, any, any, any, any, any, any>;
|
|
2303
|
+
/** @public */
|
|
2304
|
+
type AnyStateNodeConfig = Next_StateNodeConfig<any, any, any, any, any, any, any, any, any, any, any, any, any, // TInput
|
|
2305
|
+
any, // TInputMap
|
|
2306
|
+
any, // TSystemRegistry
|
|
2307
|
+
any, // TChildOutput
|
|
2308
|
+
any>;
|
|
2309
|
+
/** @public */
|
|
2310
|
+
type AnyStateNode = StateNode<any, any> | StateNode<never, EventObject> | StateNode<any, EventObject> | StateNode<never, any>;
|
|
2311
|
+
type LoosenMachineSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, any, any, any, any, any, any, any> ? Omit<TSnapshot, 'matches' | 'can'> & {
|
|
2312
|
+
matches(partialStateValue: StateValue): boolean;
|
|
2313
|
+
can(event: any): boolean;
|
|
2314
|
+
} : never;
|
|
2315
|
+
/** @public */
|
|
2316
|
+
type AnyMachineSnapshot = LoosenMachineSnapshot<MachineSnapshot<any, any, any, any, any, any, any, any>>;
|
|
2317
|
+
/** @public */
|
|
2318
|
+
interface AnyStateMachine extends AnyActorLogic {
|
|
2319
|
+
id: string;
|
|
2320
|
+
root: AnyStateNode;
|
|
2321
|
+
/**
|
|
2322
|
+
* Adapter hooks for actor-local transition evaluation state. Used by
|
|
2323
|
+
* `@xstate/scxml`; not part of the stable API.
|
|
2324
|
+
*
|
|
2325
|
+
* @experimental
|
|
2326
|
+
*/
|
|
2327
|
+
_microstepHooks?: {
|
|
2328
|
+
begin(self: AnyActor): void;
|
|
2329
|
+
drain(self: AnyActor): AnyEventObject[];
|
|
2330
|
+
} | undefined;
|
|
2331
|
+
options?: {
|
|
2332
|
+
maxIterations?: number;
|
|
2333
|
+
};
|
|
2334
|
+
states: StateNodesConfig<any, any>;
|
|
2335
|
+
events: Array<EventDescriptor<any>>;
|
|
2336
|
+
sources: Sources;
|
|
2337
|
+
config: any;
|
|
2338
|
+
version?: string | undefined;
|
|
2339
|
+
schemas?: AnyMachineSchemas | undefined;
|
|
2340
|
+
snapshotSchema: MachineSnapshotSchema;
|
|
2341
|
+
eventSchema: MachineEventSchema;
|
|
2342
|
+
provide(sources: any): AnyStateMachine;
|
|
2343
|
+
resolveState(config: any): any;
|
|
2344
|
+
getTransitionData(snapshot: any, event: any, actorScope: AnyActorScope, selectionResults?: Map<AnyTransitionDefinition, unknown>): AnyTransitionDefinition[];
|
|
2345
|
+
getStateNodeById(stateId: string): AnyStateNode;
|
|
2346
|
+
getPersistedSnapshot(snapshot: any, options?: unknown): Snapshot<unknown>;
|
|
2347
|
+
}
|
|
2348
|
+
/** @public */
|
|
2349
|
+
type AnyStateConfig = StateConfig<any, AnyEventObject>;
|
|
2350
|
+
/** @public */
|
|
2351
|
+
type DelayConfig<TContext extends MachineContext, TExpressionEvent extends EventObject> = number | DelayExpr<TContext, TExpressionEvent>;
|
|
2352
|
+
/** @public */
|
|
2353
|
+
type InitialContext<TContext extends MachineContext, TActorMap extends Sources['actors'], TInput, TEvent extends EventObject> = TContext | ContextFactory<TContext, TActorMap, TInput, TEvent>;
|
|
2354
|
+
/** @public */
|
|
2355
|
+
type ContextFactory<TContext extends MachineContext, TActorMap extends Sources['actors'], TInput, TEvent extends EventObject = EventObject> = ({ spawn, actors, input, self }: {
|
|
2356
|
+
spawn: Spawner;
|
|
2357
|
+
actors: TActorMap;
|
|
2358
|
+
input: TInput;
|
|
2359
|
+
self: ActorSelf<MachineSnapshot<[TContext] extends [never] ? any : TContext, TEvent, Record<string, AnyActorRef | undefined>, // TODO: this should be replaced with `TChildren`
|
|
2360
|
+
StateValue, string, unknown, TODO, // TMeta
|
|
2361
|
+
TODO>, TEvent, AnyEventObject>;
|
|
2362
|
+
}) => [TContext] extends [never] ? MachineContext : TContext;
|
|
2363
|
+
/** @public */
|
|
2364
|
+
interface ProvidedActor {
|
|
2365
|
+
src: string;
|
|
2366
|
+
logic: UnknownActorLogic;
|
|
2367
|
+
id?: string | undefined;
|
|
2368
|
+
}
|
|
2369
|
+
/** @public */
|
|
2370
|
+
interface SetupTypes<TContext extends MachineContext, TEvent extends EventObject, TChildrenMap extends Record<string, string>, TTag extends string, TInput, TOutput, TEmitted extends EventObject, TMeta extends MetaObject> {
|
|
2371
|
+
context?: TContext;
|
|
2372
|
+
events?: TEvent;
|
|
2373
|
+
children?: TChildrenMap;
|
|
2374
|
+
tags?: TTag;
|
|
2375
|
+
input?: TInput;
|
|
2376
|
+
output?: TOutput;
|
|
2377
|
+
emitted?: TEmitted;
|
|
2378
|
+
meta?: TMeta;
|
|
2379
|
+
}
|
|
2380
|
+
/** @public */
|
|
2381
|
+
interface MachineTypes<TContext extends MachineContext, TEvent extends EventObject, TActor extends ProvidedActor, TAction extends ParameterizedObject, TGuard extends ParameterizedObject, TDelay extends string, TTag extends string, TInput, TOutput, TEmitted extends EventObject, TMeta extends MetaObject> extends SetupTypes<TContext, TEvent, never, TTag, TInput, TOutput, TEmitted, TMeta> {
|
|
2382
|
+
actors?: TActor;
|
|
2383
|
+
actions?: TAction;
|
|
2384
|
+
guards?: TGuard;
|
|
2385
|
+
delays?: TDelay;
|
|
2386
|
+
meta?: TMeta;
|
|
2387
|
+
}
|
|
2388
|
+
/** @public */
|
|
2389
|
+
interface HistoryStateNode<TContext extends MachineContext> extends StateNode<TContext> {
|
|
2390
|
+
history: 'shallow' | 'deep';
|
|
2391
|
+
target: string | undefined;
|
|
2392
|
+
}
|
|
2393
|
+
/** @public */
|
|
2394
|
+
type HistoryValue = Record<string, Array<AnyStateNode>>;
|
|
2395
|
+
/** @public */
|
|
2396
|
+
type PersistedHistoryValue = Record<string, Array<{
|
|
2397
|
+
id: string;
|
|
2398
|
+
}>>;
|
|
2399
|
+
/** @public */
|
|
2400
|
+
type AnyHistoryValue = HistoryValue;
|
|
2401
|
+
/** @public */
|
|
2402
|
+
type StateFrom<T extends AnyStateMachine | ((...args: any[]) => AnyStateMachine)> = T extends AnyStateMachine ? StateSnapshotFromMachine<T> : T extends ((...args: any[]) => AnyStateMachine) ? StateSnapshotFromMachine<ReturnType<T>> : never;
|
|
2403
|
+
/** @public */
|
|
2404
|
+
type StateValueFromStateSchema<T extends StateSchema> = StateSchema extends T ? StateValue : ToStateValue<T> extends (infer TStateValue) ? TStateValue extends StateValue ? TStateValue : StateValue : StateValue;
|
|
2405
|
+
type MatchingStateValueForStateFrom<TStateValue extends StateValue, TTestStateValue extends StateValue> = TStateValue extends unknown ? TTestStateValue extends string ? TStateValue extends string ? TTestStateValue extends TStateValue ? TTestStateValue : Extract<TStateValue, TTestStateValue> : TStateValue extends StateValueMap ? TStateValue & Record<TTestStateValue, StateValue | undefined> : never : TTestStateValue extends StateValueMap ? TStateValue extends StateValueMap ? MatchingStateValueMapForStateFrom<TStateValue, TTestStateValue> : never : never : never;
|
|
2406
|
+
type MatchingStateValueMapForStateFrom<TStateValue extends StateValueMap, TTestStateValue extends StateValueMap> = false extends { [K in keyof TTestStateValue & string]: K extends keyof TStateValue ? IsNever<MatchingStateValueForStateFrom<NonNullable<TStateValue[K]>, NonNullable<TTestStateValue[K]>>> extends true ? false : true : false; }[keyof TTestStateValue & string] ? never : { [K in keyof TStateValue]: K extends keyof TTestStateValue ? MatchingStateValueForStateFrom<NonNullable<TStateValue[K]>, NonNullable<TTestStateValue[K]>> : TStateValue[K]; };
|
|
2407
|
+
type StateSnapshotFromStateValue<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject, TStateSchema extends StateSchema, TAllStateValue extends StateValue = TStateValue> = TStateValue extends unknown ? Omit<MachineSnapshot<StateContextFromStateValue<TStateSchema, TContext, TStateValue>, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TStateSchema>, 'matches'> & {
|
|
2408
|
+
matches<const TTestStateValue extends string>(partialStateValue: TTestStateValue, ...args: string extends TTestStateValue ? [never] : []): this is StateSnapshotFromStateValue<StateContextFromStateValue<TStateSchema, TContext, TTestStateValue>, TEvent, TChildren, MatchingStateValueForStateFrom<TAllStateValue, TTestStateValue>, TTag, TOutput, TMeta, TStateSchema, TAllStateValue>;
|
|
2409
|
+
matches<const TTestStateValue extends StateValueMap>(partialStateValue: TTestStateValue, ...args: string extends keyof TTestStateValue ? [never] : []): this is StateSnapshotFromStateValue<StateContextFromStateValue<TStateSchema, TContext, TTestStateValue>, TEvent, TChildren, MatchingStateValueForStateFrom<TAllStateValue, TTestStateValue>, TTag, TOutput, TMeta, TStateSchema, TAllStateValue>;
|
|
2410
|
+
matches(partialStateValue: StateValue): boolean;
|
|
2411
|
+
} : never;
|
|
2412
|
+
type StateSnapshotFromMachine<T extends AnyStateMachine> = SnapshotFrom<T> extends MachineSnapshot<infer TContext, infer TEvent, infer TChildren, infer _TStateValue, infer TTag, infer TOutput, infer TMeta, infer TStateSchema> ? StateSnapshotFromStateValue<TContext, TEvent, TChildren, StateValueFromStateSchema<TStateSchema>, TTag, TOutput, TMeta, TStateSchema, StateValueFromStateSchema<TStateSchema>> : SnapshotFrom<T>;
|
|
2413
|
+
/** @public */
|
|
2414
|
+
interface DoneActorEvent<TOutput = unknown, TId extends string = string> extends EventObject {
|
|
2415
|
+
type: 'xstate.done.actor';
|
|
2416
|
+
output: TOutput;
|
|
2417
|
+
actorId: TId;
|
|
2418
|
+
sessionId: string;
|
|
2419
|
+
}
|
|
2420
|
+
/** @public */
|
|
2421
|
+
interface ErrorActorEvent<TErrorData = unknown, TId extends string = string> extends EventObject {
|
|
2422
|
+
type: 'xstate.error.actor';
|
|
2423
|
+
error: TErrorData;
|
|
2424
|
+
actorId: TId;
|
|
2425
|
+
sessionId: string;
|
|
2426
|
+
}
|
|
2427
|
+
/** @public */
|
|
2428
|
+
interface ErrorPlatformEvent<TErrorData = unknown, TKind extends string = string> extends EventObject {
|
|
2429
|
+
type: `xstate.error.${TKind}`;
|
|
2430
|
+
error: TErrorData;
|
|
2431
|
+
}
|
|
2432
|
+
/** @public */
|
|
2433
|
+
type ErrorEvent = ErrorActorEvent | ErrorPlatformEvent;
|
|
2434
|
+
/** @public */
|
|
2435
|
+
interface SnapshotEvent<TSnapshot extends Snapshot<unknown> = Snapshot<unknown>> extends EventObject {
|
|
2436
|
+
type: 'xstate.snapshot.actor';
|
|
2437
|
+
actorId: string;
|
|
2438
|
+
sessionId: string;
|
|
2439
|
+
snapshot: TSnapshot;
|
|
2440
|
+
}
|
|
2441
|
+
/** @public */
|
|
2442
|
+
interface DoneStateEvent<TOutput = unknown, TId extends string = string> extends EventObject {
|
|
2443
|
+
type: 'xstate.done.state';
|
|
2444
|
+
stateId: TId;
|
|
2445
|
+
output: TOutput;
|
|
2446
|
+
}
|
|
2447
|
+
/** @public */
|
|
2448
|
+
interface AfterEvent extends EventObject {
|
|
2449
|
+
type: 'xstate.after';
|
|
2450
|
+
delay: number | string;
|
|
2451
|
+
stateId: string;
|
|
2452
|
+
}
|
|
2453
|
+
/** @public */
|
|
2454
|
+
interface TimeoutEvent extends EventObject {
|
|
2455
|
+
type: 'xstate.timeout';
|
|
2456
|
+
stateId: string;
|
|
2457
|
+
}
|
|
2458
|
+
/** @public */
|
|
2459
|
+
interface ActorTimeoutEvent extends EventObject {
|
|
2460
|
+
type: 'xstate.timeout.actor';
|
|
2461
|
+
actorId: string;
|
|
2462
|
+
sessionId?: string | undefined;
|
|
2463
|
+
}
|
|
2464
|
+
/** @public */
|
|
2465
|
+
declare enum SpecialTargets {
|
|
2466
|
+
Internal = "#_internal"
|
|
2467
|
+
}
|
|
2468
|
+
/** @public */
|
|
2469
|
+
type Mapper<TContext extends MachineContext, TExpressionEvent extends EventObject, TResult, TEvent extends EventObject, _TCtx = [TContext] extends [never] ? any : TContext> = (args: {
|
|
2470
|
+
context: _TCtx;
|
|
2471
|
+
event: TExpressionEvent;
|
|
2472
|
+
input?: Record<string, unknown>;
|
|
2473
|
+
self: ActorSelf<MachineSnapshot<_TCtx & MachineContext, TEvent, Record<string, AnyActorRef>, // TODO: this should be replaced with `TChildren`
|
|
2474
|
+
StateValue, string, unknown, TODO, // TMeta
|
|
2475
|
+
TODO>, TEvent, AnyEventObject>;
|
|
2476
|
+
} & OutputArg<TExpressionEvent>) => TResult;
|
|
2477
|
+
/** @public */
|
|
2478
|
+
interface TransitionDefinition<TContext extends MachineContext, TEvent extends EventObject, TMeta extends MetaObject = any> extends Omit<TransitionConfig<TContext, TEvent, TEvent, TODO, TMeta, TODO, TODO, TODO, TODO>, 'target' | 'to'> {
|
|
2479
|
+
target: ReadonlyArray<AnyStateNode> | undefined;
|
|
2480
|
+
source: AnyStateNode;
|
|
2481
|
+
reenter: boolean;
|
|
2482
|
+
eventType: EventDescriptor<TEvent>;
|
|
2483
|
+
to?: ((...args: any[]) => any) | undefined;
|
|
2484
|
+
input?: Record<string, unknown> | ((args: {
|
|
2485
|
+
context: any;
|
|
2486
|
+
event: any;
|
|
2487
|
+
output: any;
|
|
2488
|
+
}) => Record<string, unknown>);
|
|
2489
|
+
}
|
|
2490
|
+
/** @public */
|
|
2491
|
+
type AnyTransitionDefinition = TransitionDefinition<any, any>;
|
|
2492
|
+
/** @public */
|
|
2493
|
+
type InitialTransitionDefinition<TMeta extends MetaObject = any> = {
|
|
2494
|
+
source: AnyStateNode;
|
|
2495
|
+
target: AnyStateNode[] | undefined;
|
|
2496
|
+
reenter?: boolean;
|
|
2497
|
+
eventType?: EventDescriptor<any>;
|
|
2498
|
+
meta?: TMeta;
|
|
2499
|
+
description?: string | undefined;
|
|
2500
|
+
input?: Record<string, unknown> | ((args: {
|
|
2501
|
+
context: MachineContext;
|
|
2502
|
+
event: EventObject;
|
|
2503
|
+
}) => Record<string, unknown>);
|
|
2504
|
+
to?: ((...args: any[]) => any) | undefined;
|
|
2505
|
+
};
|
|
2506
|
+
/** @public */
|
|
2507
|
+
type TransitionDefinitionMap<TContext extends MachineContext, TEvent extends EventObject, TMeta extends MetaObject = any> = { [K in EventDescriptor<TEvent>]: Array<TransitionDefinition<TContext, ExtractEvent<TEvent, K>, TMeta>>; };
|
|
2508
|
+
/** @public */
|
|
2509
|
+
type DelayExpr<TContext extends MachineContext, TEvent extends EventObject> = (args: {
|
|
2510
|
+
context: [TContext] extends [never] ? any : TContext;
|
|
2511
|
+
event: TEvent;
|
|
2512
|
+
stateNode: AnyStateNode;
|
|
2513
|
+
}) => number;
|
|
2514
|
+
/** @public */
|
|
2515
|
+
interface DelayedTransitionDefinition<TContext extends MachineContext, TEvent extends EventObject, TMeta extends MetaObject = any> extends TransitionDefinition<TContext, TEvent, TMeta> {
|
|
2516
|
+
delay: number | string | DelayExpr<TContext, TEvent>;
|
|
2517
|
+
}
|
|
2518
|
+
/** @public */
|
|
2519
|
+
interface StateLike<TContext extends MachineContext> {
|
|
2520
|
+
value: StateValue;
|
|
2521
|
+
context: TContext;
|
|
2522
|
+
event: EventObject;
|
|
2523
|
+
}
|
|
2524
|
+
/** @public */
|
|
2525
|
+
interface StateConfig<TContext extends MachineContext, TEvent extends EventObject> {
|
|
2526
|
+
context: TContext;
|
|
2527
|
+
historyValue?: HistoryValue | undefined;
|
|
2528
|
+
children: Record<string, AnyActorRef | undefined>;
|
|
2529
|
+
timers?: Record<string, LogicalTimer>;
|
|
2530
|
+
status: SnapshotStatus;
|
|
2531
|
+
output?: any;
|
|
2532
|
+
error?: unknown;
|
|
2533
|
+
machine?: StateMachine<TContext, TEvent, any, any, any, any, any, any, any, any, any, any, any, any>;
|
|
2534
|
+
}
|
|
2535
|
+
/**
|
|
2536
|
+
* A deterministic delayed-delivery declaration owned by a logic snapshot.
|
|
2537
|
+
*
|
|
2538
|
+
* @public
|
|
2539
|
+
*/
|
|
2540
|
+
interface LogicalTimer {
|
|
2541
|
+
id: string;
|
|
2542
|
+
delay: number;
|
|
2543
|
+
type: '@xstate.raise' | '@xstate.sendTo';
|
|
2544
|
+
event: EventObject;
|
|
2545
|
+
/** `self` or the logical actor that will receive `event`. */
|
|
2546
|
+
target: 'self' | AnyActor;
|
|
2547
|
+
/**
|
|
2548
|
+
* The timer's absolute start in milliseconds, persisted from a running
|
|
2549
|
+
* wall-clock actor or a successfully scheduled durable timer. Carried
|
|
2550
|
+
* through restore so re-persisting keeps the original deadline.
|
|
2551
|
+
*/
|
|
2552
|
+
startedAt?: number;
|
|
2553
|
+
}
|
|
2554
|
+
/**
|
|
2555
|
+
* The logical input delivered to a timer's source when its runtime delay ends.
|
|
2556
|
+
*
|
|
2557
|
+
* @public
|
|
2558
|
+
*/
|
|
2559
|
+
interface TimerEvent extends EventObject {
|
|
2560
|
+
type: 'xstate.timer';
|
|
2561
|
+
id: string;
|
|
2562
|
+
}
|
|
2563
|
+
declare const persistedSnapshotLogic: unique symbol;
|
|
2564
|
+
type PersistedSnapshotLogicIdentity<TLogic> = TLogic extends {
|
|
2565
|
+
readonly id: infer TId extends string;
|
|
2566
|
+
} ? {
|
|
2567
|
+
readonly id: TId;
|
|
2568
|
+
readonly version: TLogic extends {
|
|
2569
|
+
readonly version: infer TVersion extends string;
|
|
2570
|
+
} ? TVersion : string;
|
|
2571
|
+
} : never;
|
|
2572
|
+
/**
|
|
2573
|
+
* A persisted snapshot tied to a versioned actor logic identity.
|
|
2574
|
+
*
|
|
2575
|
+
* @remarks
|
|
2576
|
+
* This is a _brand only_: it carries the machine `id`/`version` identity used
|
|
2577
|
+
* to constrain which persisted snapshots may be restored into which logic, and
|
|
2578
|
+
* says nothing about the snapshot's shape. To annotate a value produced by
|
|
2579
|
+
* {@link Actor.getPersistedSnapshot}, use {@link PersistedSnapshotFrom}
|
|
2580
|
+
* instead.
|
|
2581
|
+
* @public
|
|
2582
|
+
*/
|
|
2583
|
+
type PersistedSnapshotFor<TLogic> = {
|
|
2584
|
+
readonly [persistedSnapshotLogic]: PersistedSnapshotLogicIdentity<TLogic>;
|
|
2585
|
+
};
|
|
2586
|
+
/**
|
|
2587
|
+
* The identity stamp persisted by a machine that declares a `version`.
|
|
2588
|
+
*
|
|
2589
|
+
* @public
|
|
2590
|
+
*/
|
|
2591
|
+
type PersistedMachineIdentity<TMachine extends AnyStateMachine = AnyStateMachine> = {
|
|
2592
|
+
id: TMachine['id'];
|
|
2593
|
+
version: NonNullable<TMachine['version']>;
|
|
2594
|
+
};
|
|
2595
|
+
/**
|
|
2596
|
+
* The persisted snapshot produced by `actor.getPersistedSnapshot()` for a given
|
|
2597
|
+
* state machine:
|
|
2598
|
+
*
|
|
2599
|
+
* ```ts
|
|
2600
|
+
* const persisted: PersistedSnapshotFrom<typeof machine> =
|
|
2601
|
+
* actor.getPersistedSnapshot();
|
|
2602
|
+
* ```
|
|
2603
|
+
*
|
|
2604
|
+
* @remarks
|
|
2605
|
+
* The `machine` identity field is only present for machines that declare a
|
|
2606
|
+
* `version`; unversioned machines persist no identity stamp.
|
|
2607
|
+
*
|
|
2608
|
+
* Unlike {@link PersistedSnapshotFor}, which is only the restore-time identity
|
|
2609
|
+
* brand, this describes the persisted snapshot's actual shape.
|
|
2610
|
+
*/
|
|
2611
|
+
/**
|
|
2612
|
+
* One entry in a persisted snapshot's `children`.
|
|
2613
|
+
*
|
|
2614
|
+
* @remarks
|
|
2615
|
+
* An embedded child carries its own persisted `snapshot` — the co-locating
|
|
2616
|
+
* runtime's whole-tree checkpoint. A child persisted by address
|
|
2617
|
+
* (`getPersistedSnapshot({ embedChildren: false })`) and a remote handle carry
|
|
2618
|
+
* `remote: true` instead, leaving each child's state with the runtime that
|
|
2619
|
+
* owns it.
|
|
2620
|
+
* @public
|
|
2621
|
+
*/
|
|
2622
|
+
type PersistedActorRef = {
|
|
2623
|
+
/** The child's logical address, stable across incarnations. */
|
|
2624
|
+
address?: string;
|
|
2625
|
+
/** The registered source key the child is restored from. */
|
|
2626
|
+
src: string;
|
|
2627
|
+
registryKey?: string;
|
|
2628
|
+
syncSnapshot?: boolean;
|
|
2629
|
+
} & ({
|
|
2630
|
+
snapshot: unknown;
|
|
2631
|
+
remote?: undefined;
|
|
2632
|
+
} | {
|
|
2633
|
+
snapshot?: undefined;
|
|
2634
|
+
remote: true;
|
|
2635
|
+
incarnation?: string;
|
|
2636
|
+
});
|
|
2637
|
+
/** @public */
|
|
2638
|
+
type PersistedSnapshotFrom<TMachine extends AnyStateMachine> = Snapshot<unknown> & PersistedSnapshotFor<TMachine> & {
|
|
2639
|
+
context: ContextFrom<TMachine>;
|
|
2640
|
+
children: Record<string, PersistedActorRef>;
|
|
2641
|
+
[key: string]: unknown;
|
|
2642
|
+
} & (undefined extends TMachine['version'] ? {
|
|
2643
|
+
machine?: PersistedMachineIdentity<TMachine>;
|
|
2644
|
+
} : {
|
|
2645
|
+
machine: PersistedMachineIdentity<TMachine>;
|
|
2646
|
+
});
|
|
2647
|
+
/**
|
|
2648
|
+
* The persisted snapshot produced by `actor.getPersistedSnapshot()`.
|
|
2649
|
+
*
|
|
2650
|
+
* @public
|
|
2651
|
+
*/
|
|
2652
|
+
type PersistedSnapshotOf<TLogic extends AnyActorLogic> = TLogic extends AnyStateMachine ? PersistedSnapshotFrom<TLogic> : Snapshot<unknown> & PersistedSnapshotFor<TLogic>;
|
|
2653
|
+
/**
|
|
2654
|
+
* A persisted snapshot restorable into the given actor logic: any snapshot
|
|
2655
|
+
* created by logic with the same machine `id` is accepted, regardless of
|
|
2656
|
+
* version (version mismatches are handled at runtime, e.g. by `migrate`).
|
|
2657
|
+
*
|
|
2658
|
+
* @public
|
|
2659
|
+
*/
|
|
2660
|
+
type RestorablePersistedSnapshotFor<TLogic> = {
|
|
2661
|
+
readonly [persistedSnapshotLogic]: TLogic extends {
|
|
2662
|
+
readonly id: infer TId extends string;
|
|
2663
|
+
} ? {
|
|
2664
|
+
readonly id: TId;
|
|
2665
|
+
readonly version: string;
|
|
2666
|
+
} : never;
|
|
2667
|
+
};
|
|
2668
|
+
/** @public */
|
|
2669
|
+
interface ActorOptions<TLogic extends AnyActorLogic> {
|
|
2670
|
+
/**
|
|
2671
|
+
* The clock that is responsible for setting and clearing timeouts, such as
|
|
2672
|
+
* delayed events and transitions.
|
|
2673
|
+
*
|
|
2674
|
+
* @remarks
|
|
2675
|
+
* You can create your own “clock”. The clock interface supports these
|
|
2676
|
+
* methods:
|
|
2677
|
+
*
|
|
2678
|
+
* - `now` - optional; returns the current time in milliseconds
|
|
2679
|
+
* - `setTimeout` - same arguments as `window.setTimeout(fn, timeout)`
|
|
2680
|
+
* - `clearTimeout` - same arguments as `window.clearTimeout(id)`
|
|
2681
|
+
*
|
|
2682
|
+
* By default, `Date.now`, native `setTimeout`, and native `clearTimeout` are
|
|
2683
|
+
* used.
|
|
2684
|
+
*
|
|
2685
|
+
* For testing, XState provides `SimulatedClock`.
|
|
2686
|
+
* @see `Clock`
|
|
2687
|
+
* @see {@link (SimulatedClock:class)}
|
|
2688
|
+
*/
|
|
2689
|
+
clock?: Clock;
|
|
2690
|
+
wallClock?: WallClock;
|
|
2691
|
+
crypto?: CryptoSource;
|
|
2692
|
+
/**
|
|
2693
|
+
* Specifies the logger to be used for `log(...)` actions. Defaults to the
|
|
2694
|
+
* native `console.log(...)` method.
|
|
2695
|
+
*/
|
|
2696
|
+
logger?: (...args: any[]) => void;
|
|
2697
|
+
reportUnhandledError?: (error: unknown) => void;
|
|
2698
|
+
warn?: (message: string) => void;
|
|
2699
|
+
parent?: AnyActor;
|
|
2700
|
+
/** The custom `id` for referencing this service. */
|
|
2701
|
+
id?: string;
|
|
2702
|
+
/** @deprecated Use `inspect` instead. */
|
|
2703
|
+
devTools?: never;
|
|
2704
|
+
/** The registry key to register this actor under. */
|
|
2705
|
+
registryKey?: string | undefined;
|
|
2706
|
+
/** The input data to pass to the actor. */
|
|
2707
|
+
input?: InputFrom<TLogic>;
|
|
2708
|
+
/**
|
|
2709
|
+
* Initializes actor logic from a specific persisted internal state.
|
|
2710
|
+
*
|
|
2711
|
+
* @remarks
|
|
2712
|
+
* If the state is compatible with the actor logic, when the actor is started
|
|
2713
|
+
* it will be at that persisted state. Actions from machine actors will not be
|
|
2714
|
+
* re-executed, because they are assumed to have been already executed.
|
|
2715
|
+
* However, invocations will be restarted, and spawned actors will be restored
|
|
2716
|
+
* recursively.
|
|
2717
|
+
*
|
|
2718
|
+
* Can be generated with {@link Actor.getPersistedSnapshot}.
|
|
2719
|
+
* @see https://stately.ai/docs/persistence
|
|
2720
|
+
*/
|
|
2721
|
+
snapshot?: Snapshot<unknown> & Partial<RestorablePersistedSnapshotFor<DoNotInfer<TLogic>>>;
|
|
2722
|
+
/** The source actor logic. */
|
|
2723
|
+
src?: string | AnyActorLogic;
|
|
2724
|
+
/**
|
|
2725
|
+
* A callback function or observer object which can be used to inspect actor
|
|
2726
|
+
* system updates.
|
|
2727
|
+
*
|
|
2728
|
+
* @remarks
|
|
2729
|
+
* If a callback function is provided, it can accept an inspection event
|
|
2730
|
+
* argument. The inspection protocol has two event types:
|
|
2731
|
+
*
|
|
2732
|
+
* - `@xstate.actor` - An actor ref was created in the system (announces actor
|
|
2733
|
+
* topology: identity + parent).
|
|
2734
|
+
* - `@xstate.transition` - An actor transitioned. Carries every facet of the
|
|
2735
|
+
* transition with flat, always-present fields: `event`, `snapshot`,
|
|
2736
|
+
* `sourceRef`, `microsteps`, executed `actions`, and `sent`/scheduled
|
|
2737
|
+
* events.
|
|
2738
|
+
*
|
|
2739
|
+
* Undelivered events (dead letters) are not inspection events; observe them
|
|
2740
|
+
* with `onRejectedEvent`.
|
|
2741
|
+
*
|
|
2742
|
+
* @example
|
|
2743
|
+
*
|
|
2744
|
+
* ```ts
|
|
2745
|
+
* import { createMachine } from '@systemfsoftware/xstate';
|
|
2746
|
+
*
|
|
2747
|
+
* const machine = createMachine({
|
|
2748
|
+
* // ...
|
|
2749
|
+
* });
|
|
2750
|
+
*
|
|
2751
|
+
* const actor = createActor(machine, {
|
|
2752
|
+
* inspect: (inspectionEvent) => {
|
|
2753
|
+
* if (inspectionEvent.actorRef === actor) {
|
|
2754
|
+
* // This event is for the root actor
|
|
2755
|
+
* }
|
|
2756
|
+
*
|
|
2757
|
+
* if (inspectionEvent.type === '@xstate.actor') {
|
|
2758
|
+
* console.log(inspectionEvent.actorRef, inspectionEvent.parentRef);
|
|
2759
|
+
* }
|
|
2760
|
+
*
|
|
2761
|
+
* if (inspectionEvent.type === '@xstate.transition') {
|
|
2762
|
+
* console.log(inspectionEvent.sourceRef);
|
|
2763
|
+
* console.log(inspectionEvent.actorRef);
|
|
2764
|
+
* console.log(inspectionEvent.event);
|
|
2765
|
+
* console.log(inspectionEvent.snapshot);
|
|
2766
|
+
* // flat, always-present facets — no narrowing required
|
|
2767
|
+
* console.log(inspectionEvent.actions);
|
|
2768
|
+
* console.log(inspectionEvent.sent);
|
|
2769
|
+
* console.log(inspectionEvent.microsteps);
|
|
2770
|
+
* }
|
|
2771
|
+
* }
|
|
2772
|
+
* });
|
|
2773
|
+
* ```
|
|
2774
|
+
*
|
|
2775
|
+
* Alternately, an observer object (`{ next?, error?, complete? }`) can be
|
|
2776
|
+
* provided:
|
|
2777
|
+
*
|
|
2778
|
+
* @example
|
|
2779
|
+
*
|
|
2780
|
+
* ```ts
|
|
2781
|
+
* const actor = createActor(machine, {
|
|
2782
|
+
* inspect: {
|
|
2783
|
+
* next: (inspectionEvent) => {
|
|
2784
|
+
* if (inspectionEvent.actorRef === actor) {
|
|
2785
|
+
* // This event is for the root actor
|
|
2786
|
+
* }
|
|
2787
|
+
*
|
|
2788
|
+
* if (inspectionEvent.type === '@xstate.actor') {
|
|
2789
|
+
* console.log(
|
|
2790
|
+
* inspectionEvent.actorRef,
|
|
2791
|
+
* inspectionEvent.parentRef
|
|
2792
|
+
* );
|
|
2793
|
+
* }
|
|
2794
|
+
*
|
|
2795
|
+
* if (inspectionEvent.type === '@xstate.transition') {
|
|
2796
|
+
* console.log(inspectionEvent.sourceRef);
|
|
2797
|
+
* console.log(inspectionEvent.actorRef);
|
|
2798
|
+
* console.log(inspectionEvent.event);
|
|
2799
|
+
* console.log(inspectionEvent.snapshot);
|
|
2800
|
+
* console.log(inspectionEvent.actions);
|
|
2801
|
+
* console.log(inspectionEvent.sent);
|
|
2802
|
+
* console.log(inspectionEvent.microsteps);
|
|
2803
|
+
* }
|
|
2804
|
+
* }
|
|
2805
|
+
* }
|
|
2806
|
+
* });
|
|
2807
|
+
* ```
|
|
2808
|
+
*/
|
|
2809
|
+
inspect?: Observer<InspectionEvent> | ((inspectionEvent: InspectionEvent) => void);
|
|
2810
|
+
/**
|
|
2811
|
+
* A dead-letter hook called whenever an event is rejected at the delivery
|
|
2812
|
+
* boundary of this actor system — an invalid external event payload or an
|
|
2813
|
+
* internal event type sent from outside its owning actor. Rejected events
|
|
2814
|
+
* are never delivered and never error the target actor.
|
|
2815
|
+
*
|
|
2816
|
+
* Registers the listener with `actor.system.onRejectedEvent(...)`, which
|
|
2817
|
+
* also accepts listeners added later. Ignored when this actor has a parent.
|
|
2818
|
+
*/
|
|
2819
|
+
onRejectedEvent?: (rejection: EventRejection) => void;
|
|
2820
|
+
/**
|
|
2821
|
+
* Called when this state machine actor processes an event that no
|
|
2822
|
+
* transition handled: the snapshot is unchanged and no effects ran.
|
|
2823
|
+
* Internal `xstate.*` events are not reported.
|
|
2824
|
+
*
|
|
2825
|
+
* @param event The unhandled event.
|
|
2826
|
+
* @param snapshot The actor's (unchanged) snapshot.
|
|
2827
|
+
*/
|
|
2828
|
+
onUnhandledEvent?: (event: EventFromLogic<TLogic>, snapshot: SnapshotFrom<TLogic>) => void;
|
|
2829
|
+
}
|
|
2830
|
+
/** @public */
|
|
2831
|
+
type AnyActor = ActorInstance<any, any, any, any>;
|
|
2832
|
+
/** @public */
|
|
2833
|
+
type Observer<T> = {
|
|
2834
|
+
next?: ((value: T) => void) | undefined;
|
|
2835
|
+
error?: ((err: unknown) => void) | undefined;
|
|
2836
|
+
complete?: (() => void) | undefined;
|
|
2837
|
+
/**
|
|
2838
|
+
* Marks an observer that only tracks the actor's lifecycle, such as one
|
|
2839
|
+
* installed by a runtime integration. A passive observer does not count as
|
|
2840
|
+
* an error handler: an unhandled actor error is still reported when every
|
|
2841
|
+
* observer with an `error` callback is passive.
|
|
2842
|
+
*/
|
|
2843
|
+
passive?: boolean;
|
|
2844
|
+
};
|
|
2845
|
+
/** @public */
|
|
2846
|
+
interface Subscription {
|
|
2847
|
+
unsubscribe(): void;
|
|
2848
|
+
}
|
|
2849
|
+
/** @public */
|
|
2850
|
+
interface Readable<T> extends Subscribable<T> {
|
|
2851
|
+
get: () => T;
|
|
2852
|
+
}
|
|
2853
|
+
/** @public */
|
|
2854
|
+
interface InteropObservable<T> {
|
|
2855
|
+
[Symbol.observable]: () => InteropSubscribable<T>;
|
|
2856
|
+
}
|
|
2857
|
+
/** @public */
|
|
2858
|
+
interface InteropSubscribable<T> {
|
|
2859
|
+
subscribe(observer: Observer<T>): Subscription;
|
|
2860
|
+
}
|
|
2861
|
+
/** @public */
|
|
2862
|
+
interface Subscribable<T> extends InteropSubscribable<T> {
|
|
2863
|
+
subscribe(observer: Observer<T>): Subscription;
|
|
2864
|
+
subscribe(next: (value: T) => void, error?: (error: any) => void, complete?: () => void): Subscription;
|
|
2865
|
+
}
|
|
2866
|
+
type EventDescriptorMatches<TEventType extends string, TNormalizedDescriptor> = TEventType extends TNormalizedDescriptor ? true : TNormalizedDescriptor extends TEventType ? true : false;
|
|
2867
|
+
type LiteralEventMatching<TEvent extends EventObject, TDescriptor> = TEvent extends any ? string extends TEvent['type'] ? never : TEvent['type'] extends TDescriptor ? TEvent : never : never;
|
|
2868
|
+
/**
|
|
2869
|
+
* A catch-all event union (`{ type: string }` plus literal members, e.g.
|
|
2870
|
+
* declared children's completion events) narrows an exact descriptor to its
|
|
2871
|
+
* literal members, falling back to the catch-all members when none match
|
|
2872
|
+
* (and for the `string` index key of `on`). Wildcard descriptors keep the
|
|
2873
|
+
* whole union.
|
|
2874
|
+
*/
|
|
2875
|
+
type ExtractEventFromCatchAll<TEvent extends EventObject, TDescriptor> = TDescriptor extends `${string}*` ? TEvent : string extends TDescriptor ? CatchAllEvent<TEvent> : LiteralEventMatching<TEvent, TDescriptor> extends (infer TLiteral extends TEvent) ? [TLiteral] extends [never] ? CatchAllEvent<TEvent> : TLiteral : never;
|
|
2876
|
+
type CatchAllEvent<TEvent extends EventObject> = TEvent extends any ? string extends TEvent['type'] ? TEvent : never : never;
|
|
2877
|
+
/** @public */
|
|
2878
|
+
type ExtractEvent<TEvent extends EventObject, TDescriptor extends EventDescriptor<TEvent>> = string extends TEvent['type'] ? ExtractEventFromCatchAll<TEvent, TDescriptor> : NormalizeDescriptor<TDescriptor> extends (infer TNormalizedDescriptor) ? TEvent extends any ? true extends EventDescriptorMatches<TEvent['type'], TNormalizedDescriptor> ? TEvent : never : never : never;
|
|
2879
|
+
/** @public */
|
|
2880
|
+
interface BaseActorRef<TEvent extends EventObject> {
|
|
2881
|
+
send: (event: TEvent) => void;
|
|
2882
|
+
}
|
|
2883
|
+
/** @public */
|
|
2884
|
+
interface ActorLike<TCurrent, TEvent extends EventObject> extends Subscribable<TCurrent> {
|
|
2885
|
+
send: (event: TEvent) => void;
|
|
2886
|
+
}
|
|
2887
|
+
/**
|
|
2888
|
+
* A consumer-facing actor handle.
|
|
2889
|
+
*
|
|
2890
|
+
* `ActorRef` describes the contract a consumer needs: which events can be sent
|
|
2891
|
+
* to the actor, which snapshot it publishes for observation, and which emitted
|
|
2892
|
+
* events can be listened to. It intentionally does not expose lifecycle control
|
|
2893
|
+
* or runtime internals. A concrete `Actor` satisfies this interface, so APIs
|
|
2894
|
+
* should accept `ActorRef` whenever they only need to send events, read
|
|
2895
|
+
* snapshots, or listen to emitted events.
|
|
2896
|
+
*
|
|
2897
|
+
* @public
|
|
2898
|
+
*/
|
|
2899
|
+
interface ActorRef<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TEmitted extends EventObject = EventObject, TSendEvent extends EventObject = TEvent> extends Subscribable<TSnapshot>, InteropObservable<TSnapshot> {
|
|
2900
|
+
send: (event: TSendEvent) => void;
|
|
2901
|
+
getSnapshot: () => TSnapshot;
|
|
2902
|
+
on: <TType extends TEmitted['type'] | '*'>(type: TType, handler: (emitted: TEmitted & (TType extends '*' ? unknown : {
|
|
2903
|
+
type: TType;
|
|
2904
|
+
})) => void) => Subscription;
|
|
2905
|
+
}
|
|
2906
|
+
type EventPayload<TEvent extends EventObject, TType extends TEvent['type']> = HomomorphicOmit<ExtractEvent<TEvent, TType>, 'type'>;
|
|
2907
|
+
/** @public */
|
|
2908
|
+
type ActorTrigger<TEvent extends EventObject> = { [K in TEvent['type']]: {} extends EventPayload<TEvent, K> ? () => void : (payload: EventPayload<TEvent, K>) => void; };
|
|
2909
|
+
/**
|
|
2910
|
+
* Runtime-only actor capabilities.
|
|
2911
|
+
*
|
|
2912
|
+
* These members are needed by the interpreter, scheduler, inspection, and child
|
|
2913
|
+
* management code. Public consumer APIs should prefer `ActorRef` unless they
|
|
2914
|
+
* genuinely need lifecycle control such as starting, stopping, or accessing
|
|
2915
|
+
* system-owned runtime state.
|
|
2916
|
+
*
|
|
2917
|
+
* @public
|
|
2918
|
+
*/
|
|
2919
|
+
interface ActorRuntime<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, _TEmitted extends EventObject = EventObject, TSendEvent extends EventObject = TEvent> {
|
|
2920
|
+
/** The unique identifier for this actor relative to its parent. */
|
|
2921
|
+
id: string;
|
|
2922
|
+
/**
|
|
2923
|
+
* The deterministic logical address of this actor within its system: the
|
|
2924
|
+
* `/`-joined path of actor ids from the root. Stable across persistence and
|
|
2925
|
+
* restore, unlike `sessionId`.
|
|
2926
|
+
*/
|
|
2927
|
+
readonly address: string;
|
|
2928
|
+
/**
|
|
2929
|
+
* The globally unique process ID for this invocation.
|
|
2930
|
+
*
|
|
2931
|
+
* @remarks
|
|
2932
|
+
* This is only defined once the actor is started.
|
|
2933
|
+
*/
|
|
2934
|
+
sessionId: string | undefined;
|
|
2935
|
+
start: () => this;
|
|
2936
|
+
getPersistedSnapshot: () => Snapshot<unknown>;
|
|
2937
|
+
stop: () => void;
|
|
2938
|
+
toJSON?: () => any;
|
|
2939
|
+
_parent?: any;
|
|
2940
|
+
system: any;
|
|
2941
|
+
src: string | AnyActorLogic;
|
|
2942
|
+
/** Registry key used by the actor system receptionist. */
|
|
2943
|
+
registryKey?: string | undefined;
|
|
2944
|
+
trigger: ActorTrigger<TSendEvent>;
|
|
2945
|
+
select<TSelected>(selector: (snapshot: TSnapshot) => TSelected, equalityFn?: (a: TSelected, b: TSelected) => boolean): Readable<TSelected>;
|
|
2946
|
+
}
|
|
2947
|
+
/**
|
|
2948
|
+
* A concrete actor instance type.
|
|
2949
|
+
*
|
|
2950
|
+
* `ActorInstance` combines the consumer `ActorRef` contract with runtime
|
|
2951
|
+
* lifecycle capabilities. Values returned by `createActor(...)` and
|
|
2952
|
+
* `spawn(...)` naturally satisfy narrower `ActorRef` contracts.
|
|
2953
|
+
*
|
|
2954
|
+
* @public
|
|
2955
|
+
*/
|
|
2956
|
+
interface ActorInstance<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TEmitted extends EventObject = EventObject, TSendEvent extends EventObject = TEvent> extends ActorRuntime<TSnapshot, TEvent, TEmitted, TSendEvent>, ActorRef<TSnapshot, TEvent, TEmitted, TSendEvent> {}
|
|
2957
|
+
/**
|
|
2958
|
+
* The actor's own full self handle.
|
|
2959
|
+
*
|
|
2960
|
+
* Internals and action/guard sources receive this shape because `self` can
|
|
2961
|
+
* participate in runtime-owned behavior while still being usable wherever an
|
|
2962
|
+
* `ActorRef` is expected.
|
|
2963
|
+
*
|
|
2964
|
+
* @public
|
|
2965
|
+
*/
|
|
2966
|
+
type ActorSelf<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TEmitted extends EventObject = EventObject, TSendEvent extends EventObject = TEvent> = ActorRuntime<TSnapshot, TEvent, TEmitted, TSendEvent> & ActorRef<TSnapshot, TEvent, TEmitted, TSendEvent>;
|
|
2967
|
+
type MachineContextOf<T> = T extends {
|
|
2968
|
+
root: StateNode<infer TContext, any, any, any>;
|
|
2969
|
+
} ? TContext : never;
|
|
2970
|
+
/** @public */
|
|
2971
|
+
type ActorRefFrom<T> = T extends StateMachine<any, infer TEvent, infer TChildren, infer TStateValue, infer TTag, infer _TInput, infer TOutput, infer TEmitted, infer TMeta, infer _TConfig, infer _TActionMap, infer _TActorMap, infer _TGuardMap, infer _TDelayMap, infer TInternalEvent> ? ActorRef<MachineSnapshot<MachineContextOf<T>, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, any>, TEvent, TEmitted, SendableEventFromMachine<TEvent, TInternalEvent>> : T extends Promise<infer U> ? ActorRefFrom<AsyncActorLogic<U>> : T extends ActorLogic<infer TSnapshot, infer TEvent, infer _TInput, infer _TSystem, infer TEmitted> ? ActorRef<TSnapshot, TEvent, TEmitted, SendableEventFromLogic<T>> : never;
|
|
2972
|
+
/** @public */
|
|
2973
|
+
type SendableEventFromLogic<TLogic extends AnyActorLogic> = TLogic extends StateMachine<infer _TContext, infer TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TInput, infer _TOutput, infer _TEmitted, infer _TMeta, infer _TConfig, infer _TActionMap, infer _TActorMap, infer _TGuardMap, infer _TDelayMap, infer TInternalEvent> ? SendableEventFromMachine<TEvent, TInternalEvent> : TLogic extends SendableEventCarrier<infer TSendableEvent> ? TSendableEvent : EventFromLogic<TLogic>;
|
|
2974
|
+
type OpaqueMachineSnapshot<TSnapshot extends Snapshot<unknown>> = TSnapshot extends MachineSnapshot<infer TContext, infer TEvent, infer TChildren, infer TStateValue, infer TTag, infer TOutput, infer TMeta, infer _TStateSchema> ? MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, any> : TSnapshot;
|
|
2975
|
+
/** @public */
|
|
2976
|
+
type ActorRefFromLogic<T extends AnyActorLogic> = ActorRef<OpaqueMachineSnapshot<SnapshotFrom<T>>, EventFromLogic<T>, EmittedFrom<T>, SendableEventFromLogic<T>>;
|
|
2977
|
+
/** @public */
|
|
2978
|
+
interface AnyActorRef extends Subscribable<any>, InteropObservable<any> {
|
|
2979
|
+
send(event: any): void;
|
|
2980
|
+
getSnapshot(): any;
|
|
2981
|
+
on(type: string, handler: (emitted: any) => void): Subscription;
|
|
2982
|
+
}
|
|
2983
|
+
/**
|
|
2984
|
+
* The concrete actor instance type produced from actor logic.
|
|
2985
|
+
*
|
|
2986
|
+
* @public
|
|
2987
|
+
*/
|
|
2988
|
+
type ActorFromLogic<T extends AnyActorLogic> = ActorInstance<SnapshotFrom<T>, EventFromLogic<T>, EmittedFrom<T>, SendableEventFromLogic<T>>;
|
|
2989
|
+
type SendableEventFromActorRef<TActorRef, TFallback extends EventObject = AnyEventObject> = [NonNullable<TActorRef>] extends [never] ? TFallback : NonNullable<TActorRef> extends (infer TNonNullableActorRef) ? TNonNullableActorRef extends {
|
|
2990
|
+
send: (event: infer TEvent) => void;
|
|
2991
|
+
} ? [TEvent] extends [never] ? TFallback : TEvent extends EventObject ? TEvent : TFallback : never : never;
|
|
2992
|
+
/** @public */
|
|
2993
|
+
type ActorRefLike = Pick<AnyActor, 'sessionId' | 'send' | 'getSnapshot'>;
|
|
2994
|
+
/** @public */
|
|
2995
|
+
type UnknownActorRef = ActorRef<Snapshot<unknown>, EventObject>;
|
|
2996
|
+
/** @public */
|
|
2997
|
+
type DevToolsAdapter = (service: AnyActor) => void;
|
|
2998
|
+
/** @public */
|
|
2999
|
+
type MachineSourcesFrom<T extends AnyStateMachine | ((...args: any[]) => AnyStateMachine)> = T extends StateMachine<infer _TContext, infer _TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TInput, infer _TOutput, infer _TEmitted, infer _TMeta, infer _TConfig, infer TActionMap, infer TActorMap, infer TGuardMap, infer TDelayMap> ? {
|
|
3000
|
+
actions: TActionMap;
|
|
3001
|
+
actors: TActorMap;
|
|
3002
|
+
guards: TGuardMap;
|
|
3003
|
+
delays: TDelayMap;
|
|
3004
|
+
} : never;
|
|
3005
|
+
/** @public */
|
|
3006
|
+
interface ActorScope<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TSystem extends AnyActorSystem = AnyActorSystem, TEmitted extends EventObject = EventObject, TSendEvent extends EventObject = TEvent> {
|
|
3007
|
+
self: ActorSelf<TSnapshot, TEvent, TEmitted, TSendEvent>;
|
|
3008
|
+
id: string;
|
|
3009
|
+
sessionId: string;
|
|
3010
|
+
logger: (...args: any[]) => void;
|
|
3011
|
+
warn: (message: string) => void;
|
|
3012
|
+
defer: (fn: () => void) => void;
|
|
3013
|
+
emit: (event: TEmitted) => void | PromiseLike<void>;
|
|
3014
|
+
system: TSystem;
|
|
3015
|
+
stopChild: (child: AnyActor) => void;
|
|
3016
|
+
actionExecutor: ActionExecutor;
|
|
3017
|
+
}
|
|
3018
|
+
/** @public */
|
|
3019
|
+
type AnyActorScope = ActorScope<any, // TSnapshot
|
|
3020
|
+
any, // TEvent
|
|
3021
|
+
AnyActorSystem, any, // TEmitted
|
|
3022
|
+
any>;
|
|
3023
|
+
/** @public */
|
|
3024
|
+
type SnapshotStatus = 'active' | 'done' | 'error' | 'stopped';
|
|
3025
|
+
/** @public */
|
|
3026
|
+
type Snapshot<TOutput, TError = unknown> = {
|
|
3027
|
+
status: 'active';
|
|
3028
|
+
output: undefined;
|
|
3029
|
+
error: undefined;
|
|
3030
|
+
} | {
|
|
3031
|
+
status: 'done';
|
|
3032
|
+
output: TOutput;
|
|
3033
|
+
error: undefined;
|
|
3034
|
+
} | {
|
|
3035
|
+
status: 'error';
|
|
3036
|
+
output: undefined;
|
|
3037
|
+
error: TError;
|
|
3038
|
+
} | {
|
|
3039
|
+
status: 'stopped';
|
|
3040
|
+
output: undefined;
|
|
3041
|
+
error: undefined;
|
|
3042
|
+
};
|
|
3043
|
+
/** @public */
|
|
3044
|
+
type ActorLogicTransitionResult<TSnapshot extends Snapshot<unknown>, TEffect = ExecutableActionObject> = [nextSnapshot: TSnapshot, effects: TEffect[]];
|
|
3045
|
+
/**
|
|
3046
|
+
* Represents logic which can be used by an actor.
|
|
3047
|
+
*
|
|
3048
|
+
* @template TSnapshot - The type of the snapshot.
|
|
3049
|
+
* @template TEvent - The type of the event object.
|
|
3050
|
+
* @template TInput - The type of the input.
|
|
3051
|
+
* @template TSystem - The type of the actor system.
|
|
3052
|
+
* @public
|
|
3053
|
+
*/
|
|
3054
|
+
interface ActorLogic<in out TSnapshot extends Snapshot<unknown>, // it's invariant because it's also part of `ActorScope["self"]["getSnapshot"]`
|
|
3055
|
+
in out TEvent extends EventObject, // it's invariant because it's also part of `ActorScope["self"]["send"]`
|
|
3056
|
+
in TInput = NonReducibleUnknown, TSystem extends AnyActorSystem = AnyActorSystem, in out TEmitted extends EventObject = EventObject> {
|
|
3057
|
+
/** The initial setup/configuration used to create the actor logic. */
|
|
3058
|
+
config?: unknown;
|
|
3059
|
+
/** Optional runtime validator for pure calculation boundaries. */
|
|
3060
|
+
validator?: ActorLogicValidator | undefined;
|
|
3061
|
+
/**
|
|
3062
|
+
* Transition function that processes the current state and an incoming event
|
|
3063
|
+
* to produce a new state and effects.
|
|
3064
|
+
*
|
|
3065
|
+
* @param snapshot - The current state.
|
|
3066
|
+
* @param event - The incoming event.
|
|
3067
|
+
* @param actorScope - The actor scope.
|
|
3068
|
+
* @returns A tuple of the next state and effects.
|
|
3069
|
+
*/
|
|
3070
|
+
transition: (snapshot: TSnapshot, event: TEvent, actorScope: ActorScope<TSnapshot, TEvent, TSystem, TEmitted>) => ActorLogicTransitionResult<TSnapshot>;
|
|
3071
|
+
/**
|
|
3072
|
+
* Transition function that produces the initial state and effects.
|
|
3073
|
+
*
|
|
3074
|
+
* @param actorScope - The actor scope.
|
|
3075
|
+
* @param input - The input for the initial state.
|
|
3076
|
+
* @returns A tuple of the initial state and effects.
|
|
3077
|
+
*/
|
|
3078
|
+
initialTransition: (input: TInput, actorScope: ActorScope<TSnapshot, TEvent, TSystem, TEmitted>) => ActorLogicTransitionResult<TSnapshot>;
|
|
3079
|
+
/**
|
|
3080
|
+
* Called to provide the initial state of the actor.
|
|
3081
|
+
*
|
|
3082
|
+
* @param actorScope - The actor scope.
|
|
3083
|
+
* @param input - The input for the initial state.
|
|
3084
|
+
* @returns The initial state.
|
|
3085
|
+
*/
|
|
3086
|
+
getInitialSnapshot: (actorScope: ActorScope<TSnapshot, TEvent, TSystem, TEmitted>, input: TInput) => TSnapshot;
|
|
3087
|
+
/**
|
|
3088
|
+
* Called when Actor is created to restore the internal state of the actor
|
|
3089
|
+
* given a persisted state. The persisted state can be created by
|
|
3090
|
+
* `getPersistedSnapshot`.
|
|
3091
|
+
*
|
|
3092
|
+
* @param persistedState - The persisted state to restore from.
|
|
3093
|
+
* @param actorScope - The actor scope.
|
|
3094
|
+
* @returns The restored state.
|
|
3095
|
+
*/
|
|
3096
|
+
restoreSnapshot?: (persistedState: Snapshot<unknown>, actorScope: ActorScope<TSnapshot, TEvent, AnyActorSystem, TEmitted>) => TSnapshot;
|
|
3097
|
+
/**
|
|
3098
|
+
* Called when the actor is started.
|
|
3099
|
+
*
|
|
3100
|
+
* @param snapshot - The starting state.
|
|
3101
|
+
* @param actorScope - The actor scope.
|
|
3102
|
+
* @param options - Start metadata, including whether the snapshot was
|
|
3103
|
+
* restored.
|
|
3104
|
+
*/
|
|
3105
|
+
start?: (snapshot: TSnapshot, actorScope: ActorScope<TSnapshot, TEvent, AnyActorSystem, TEmitted>, options?: {
|
|
3106
|
+
restored: boolean;
|
|
3107
|
+
}) => void;
|
|
3108
|
+
/**
|
|
3109
|
+
* Obtains the internal state of the actor in a representation which can be be
|
|
3110
|
+
* persisted. The persisted state can be restored by `restoreSnapshot`.
|
|
3111
|
+
*
|
|
3112
|
+
* @param snapshot - The current state.
|
|
3113
|
+
* @returns The a representation of the internal state to be persisted.
|
|
3114
|
+
*/
|
|
3115
|
+
getPersistedSnapshot: (snapshot: TSnapshot, options?: unknown, warn?: (message: string) => void) => Snapshot<unknown>;
|
|
3116
|
+
/**
|
|
3117
|
+
* Returns an event that the actor should transition with to recover from an
|
|
3118
|
+
* execution error, or `undefined` if the given snapshot cannot handle it.
|
|
3119
|
+
* Actor logic without error-recovery semantics can omit this.
|
|
3120
|
+
*/
|
|
3121
|
+
getExecutionErrorEvent?: (snapshot: TSnapshot, error: unknown) => TEvent | undefined;
|
|
3122
|
+
}
|
|
3123
|
+
/** @public */
|
|
3124
|
+
interface AnyActorLogic {
|
|
3125
|
+
config?: unknown;
|
|
3126
|
+
validator?: ActorLogicValidator | undefined;
|
|
3127
|
+
transition(snapshot: any, event: any, actorScope: any): ActorLogicTransitionResult<any>;
|
|
3128
|
+
initialTransition(input: any, actorScope: any): ActorLogicTransitionResult<any>;
|
|
3129
|
+
getInitialSnapshot(actorScope: any, input: any): any;
|
|
3130
|
+
restoreSnapshot?(persistedState: Snapshot<unknown>, actorScope: any): any;
|
|
3131
|
+
start?(snapshot: any, actorScope: any, options?: {
|
|
3132
|
+
restored: boolean;
|
|
3133
|
+
}): void;
|
|
3134
|
+
getPersistedSnapshot(snapshot: any, options?: unknown, warn?: (message: string) => void): Snapshot<unknown>;
|
|
3135
|
+
getExecutionErrorEvent?(snapshot: any, error: unknown): any;
|
|
3136
|
+
}
|
|
3137
|
+
/** @public */
|
|
3138
|
+
type UnknownActorLogic = ActorLogic<any, // snapshot
|
|
3139
|
+
any, // event
|
|
3140
|
+
any, // input
|
|
3141
|
+
AnyActorSystem, any>;
|
|
3142
|
+
/** @public */
|
|
3143
|
+
type SnapshotFrom<T> = ReturnTypeOrValue<T> extends (infer R) ? R extends ActorRef<infer TSnapshot, infer _, infer __> ? TSnapshot : R extends Actor<infer TLogic> ? SnapshotFrom<TLogic> : R extends ActorLogic<infer TSnapshot, infer _TEvent, infer _TInput, infer _TSystem, infer _TEmitted> ? TSnapshot : R extends ActorScope<infer TSnapshot, infer _TEvent, infer _TEmitted, infer _TSystem> ? TSnapshot : never : never;
|
|
3144
|
+
/** @public */
|
|
3145
|
+
type EventFromLogic<TLogic extends AnyActorLogic> = TLogic extends ActorLogic<infer _TSnapshot, infer TEvent, infer _TInput, infer _TSystem, infer _TEmitted> ? TEvent : never;
|
|
3146
|
+
/** @public */
|
|
3147
|
+
type EmittedFrom<TLogic extends AnyActorLogic> = TLogic extends StateMachine<infer _TContext, infer _TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TInput, infer _TOutput, infer TEmitted, infer _TMeta, infer _TStateSchema, infer _TActionMap, infer _TActorMap, infer _TGuardMap, infer _TDelayMap> ? TEmitted : [TLogic] extends [AnyStateMachine] ? AnyEventObject : TLogic extends ActorLogic<infer _TSnapshot, infer _TEvent, infer _TInput, infer _TSystem, infer TEmitted> ? TEmitted : AnyEventObject;
|
|
3148
|
+
type ResolveEventType<T> = T extends (infer R) ? R extends StateMachine<infer _TContext, infer TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TInput, infer _TOutput, infer _TEmitted, infer _TMeta, infer _TConfig, infer _TActionMap, infer _TActorMap, infer _TGuardMap, infer _TDelayMap> ? TEvent : R extends MachineSnapshot<infer _TContext, infer TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TOutput, infer _TMeta, infer _TStateSchema> ? TEvent : R extends ActorRef<infer _TSnapshot, infer TEvent, infer _TEmitted> ? TEvent : never : never;
|
|
3149
|
+
/** @public */
|
|
3150
|
+
type EventFrom<T, K extends Prop<TEvent, 'type'> = never, TEvent extends EventObject = ResolveEventType<T>> = IsNever<K> extends true ? TEvent : ExtractEvent<TEvent, K>;
|
|
3151
|
+
/** @public */
|
|
3152
|
+
type ContextFrom<T> = T extends StateMachine<any, infer _TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TInput, infer _TOutput, infer _TEmitted, infer _TMeta, infer _TConfig, infer _TActionMap, infer _TActorMap, infer _TGuardMap, infer _TDelayMap> ? MachineContextOf<T> : T extends MachineSnapshot<infer TContext, infer _TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TOutput, infer _TMeta, infer _TStateSchema> ? TContext : T extends Actor<infer TActorLogic> ? TActorLogic extends AnyStateMachine ? ContextFrom<TActorLogic> : never : never;
|
|
3153
|
+
/** @public */
|
|
3154
|
+
type InferEvent<E extends EventObject> = { [T in E['type']]: {
|
|
3155
|
+
type: T;
|
|
3156
|
+
} & Extract<E, {
|
|
3157
|
+
type: T;
|
|
3158
|
+
}>; }[E['type']];
|
|
3159
|
+
/** @public */
|
|
3160
|
+
type TODO = any;
|
|
3161
|
+
/** @public */
|
|
3162
|
+
type StateValueFrom<TMachine extends AnyStateMachine> = Parameters<StateFrom<TMachine>['matches']>[0];
|
|
3163
|
+
/** @public */
|
|
3164
|
+
type TagsFrom<TMachine extends AnyStateMachine> = Parameters<StateFrom<TMachine>['hasTag']>[0];
|
|
3165
|
+
/** @public */
|
|
3166
|
+
interface ActorSystemInfo {
|
|
3167
|
+
actors: Record<string, AnyActorRef>;
|
|
3168
|
+
}
|
|
3169
|
+
/** @public */
|
|
3170
|
+
type SystemRegistry = Record<string, AnyActorLogic>;
|
|
3171
|
+
/** @public */
|
|
3172
|
+
type RegistryKeyForLogic<TLogic extends AnyActorLogic, TSystemRegistry extends SystemRegistry> = string extends keyof TSystemRegistry ? string : Values$1<{ [K in keyof TSystemRegistry & string]: ActorRefFromLogic<TLogic> extends ActorRefFromLogic<TSystemRegistry[K]> ? K : never; }>;
|
|
3173
|
+
/** @public */
|
|
3174
|
+
type RequiredActorOptions<TActor extends ProvidedActor> = (undefined extends TActor['id'] ? never : 'id') | (undefined extends InputFrom<TActor['logic']> ? never : 'input');
|
|
3175
|
+
/** @public */
|
|
3176
|
+
type RequiredLogicInput<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? never : 'input';
|
|
3177
|
+
type ExtractLiteralString<T extends string | undefined> = T extends string ? string extends T ? never : T : never;
|
|
3178
|
+
type ToConcreteChildren<TActor extends ProvidedActor> = { [A in TActor as ExtractLiteralString<A['id']>]?: ActorFromLogic<A['logic']>; };
|
|
3179
|
+
type NonConcreteActors<TActor extends ProvidedActor> = TActor extends any ? ExtractLiteralString<TActor['id']> extends never ? TActor : never : never;
|
|
3180
|
+
/** @public */
|
|
3181
|
+
type ToChildren<TActor extends ProvidedActor> = string extends TActor['src'] ? Record<string, AnyActor> : Compute<ToConcreteChildren<TActor> & {
|
|
3182
|
+
include: {
|
|
3183
|
+
[id: string]: NonConcreteActors<TActor> extends never ? AnyActor | undefined : NonConcreteActors<TActor> extends any ? ActorFromLogic<NonConcreteActors<TActor>['logic']> | undefined : never;
|
|
3184
|
+
};
|
|
3185
|
+
exclude: unknown;
|
|
3186
|
+
}[NonConcreteActors<TActor> extends never ? 'exclude' : 'include']>;
|
|
3187
|
+
/** @public */
|
|
3188
|
+
type StateSchema = {
|
|
3189
|
+
id?: string | undefined;
|
|
3190
|
+
route?: unknown;
|
|
3191
|
+
states?: Record<string, StateSchema> | undefined;
|
|
3192
|
+
contextSchema?: StandardSchemaV1 | undefined;
|
|
3193
|
+
outputSchema?: StandardSchemaV1 | undefined;
|
|
3194
|
+
input?: unknown;
|
|
3195
|
+
initial?: unknown;
|
|
3196
|
+
type?: unknown;
|
|
3197
|
+
history?: unknown;
|
|
3198
|
+
target?: unknown;
|
|
3199
|
+
invoke?: unknown;
|
|
3200
|
+
on?: unknown;
|
|
3201
|
+
entry?: unknown;
|
|
3202
|
+
exit?: unknown;
|
|
3203
|
+
onDone?: unknown;
|
|
3204
|
+
onError?: unknown;
|
|
3205
|
+
timeout?: unknown;
|
|
3206
|
+
onTimeout?: unknown;
|
|
3207
|
+
after?: unknown;
|
|
3208
|
+
always?: unknown;
|
|
3209
|
+
choice?: unknown;
|
|
3210
|
+
meta?: unknown;
|
|
3211
|
+
output?: unknown;
|
|
3212
|
+
tags?: unknown;
|
|
3213
|
+
description?: unknown;
|
|
3214
|
+
};
|
|
3215
|
+
/** @public */
|
|
3216
|
+
type StateSchemaFrom<T extends AnyStateMachine> = T extends StateMachine<infer _TContext, infer _TEvent, infer _TChildren, infer _TStateValue, infer _TTag, infer _TInput, infer _TOutput, infer _TEmitted, infer _TMeta, infer TStateSchema, infer _TActionMap, infer _TActorMap, infer _TGuardMap, infer _TDelayMap> ? TStateSchema : never;
|
|
3217
|
+
/** @public */
|
|
3218
|
+
type StateId<TSchema extends StateSchema, TKey extends string = '(machine)', TParentKey extends string | null = null> = (TSchema extends {
|
|
3219
|
+
id: string;
|
|
3220
|
+
} ? TSchema['id'] : TParentKey extends null ? TKey : `${TParentKey}.${TKey}`) | (TSchema['states'] extends Record<string, any> ? Values$1<{ [K in keyof TSchema['states'] & string]: StateId<TSchema['states'][K], K, TParentKey extends string ? `${TParentKey}.${TKey}` : TSchema['id'] extends string ? TSchema['id'] : TKey>; }> : never);
|
|
3221
|
+
/**
|
|
3222
|
+
* Maps state IDs to their input types based on the StateSchema.
|
|
3223
|
+
*
|
|
3224
|
+
* @public
|
|
3225
|
+
*/
|
|
3226
|
+
type StateIdInputs<TSchema extends StateSchema, TKey extends string = '(machine)', TParentKey extends string | null = null> = { [K in TSchema extends {
|
|
3227
|
+
id: string;
|
|
3228
|
+
} ? TSchema['id'] : TParentKey extends null ? TKey : `${TParentKey}.${TKey}`]: TSchema['input'] extends undefined ? undefined : TSchema['input']; } & (TSchema['states'] extends Record<string, StateSchema> ? UnionToIntersection<Values$1<{ [K in keyof TSchema['states'] & string]: StateIdInputs<TSchema['states'][K], K, TParentKey extends string ? `${TParentKey}.${TKey}` : TSchema['id'] extends string ? TSchema['id'] : TKey>; }>> : {});
|
|
3229
|
+
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
|
|
3230
|
+
type ContextFromStateSchema<TSchema extends StateSchema, TFallbackContext extends MachineContext> = TSchema['contextSchema'] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TSchema['contextSchema']> & TFallbackContext & MachineContext : TFallbackContext;
|
|
3231
|
+
type ContextFromChildStateValue<TChildSchema extends StateSchema, TFallbackContext extends MachineContext, TChildValue> = ContextFromStateSchema<TChildSchema, TFallbackContext> & StateContextFromStateValue<TChildSchema, ContextFromStateSchema<TChildSchema, TFallbackContext>, TChildValue>;
|
|
3232
|
+
/** @public */
|
|
3233
|
+
type StateContextFromStateValue<TSchema extends StateSchema, TFallbackContext extends MachineContext, TStateValue> = (TSchema['states'] extends Record<string, StateSchema> ? TStateValue extends keyof TSchema['states'] & string ? ContextFromStateSchema<TSchema['states'][TStateValue], TFallbackContext> : TStateValue extends Record<string, unknown> ? UnionToIntersection<Values$1<{ [K in keyof TStateValue & keyof TSchema['states'] & string]: ContextFromChildStateValue<TSchema['states'][K], TFallbackContext, NonNullable<TStateValue[K]>>; }>> : TFallbackContext : TFallbackContext) & MachineContext;
|
|
3234
|
+
/** @public */
|
|
3235
|
+
type RoutableStateId<TSchema extends StateSchema> = (TSchema extends {
|
|
3236
|
+
route: any;
|
|
3237
|
+
id: string;
|
|
3238
|
+
} ? `#${TSchema['id']}` : never) | (TSchema['states'] extends Record<string, any> ? Values$1<{ [K in keyof TSchema['states'] & string]: RoutableStateId<TSchema['states'][K]>; }> : never);
|
|
3239
|
+
/** @public */
|
|
3240
|
+
interface StateMachineTypes {
|
|
3241
|
+
context: MachineContext;
|
|
3242
|
+
events: EventObject;
|
|
3243
|
+
actors: ProvidedActor;
|
|
3244
|
+
actions: ParameterizedObject;
|
|
3245
|
+
guards: ParameterizedObject;
|
|
3246
|
+
delays: string;
|
|
3247
|
+
tags: string;
|
|
3248
|
+
emitted: EventObject;
|
|
3249
|
+
}
|
|
3250
|
+
type _GroupStateKeys<T extends StateSchema, S extends keyof T['states']> = S extends any ? T['states'][S] extends {
|
|
3251
|
+
type: 'history';
|
|
3252
|
+
} ? [never, never] : T extends {
|
|
3253
|
+
type: 'parallel';
|
|
3254
|
+
} ? [S, never] : T['states'][S] extends {
|
|
3255
|
+
states: Record<string, StateSchema>;
|
|
3256
|
+
} ? [S, never] : [never, S] : never;
|
|
3257
|
+
type GroupStateKeys<T extends StateSchema, S extends keyof T['states']> = {
|
|
3258
|
+
nonLeaf: _GroupStateKeys<T, S & string>[0];
|
|
3259
|
+
leaf: _GroupStateKeys<T, S & string>[1];
|
|
3260
|
+
};
|
|
3261
|
+
/** @public */
|
|
3262
|
+
type ToStateValue<T extends StateSchema> = T extends {
|
|
3263
|
+
states: Record<infer S, any>;
|
|
3264
|
+
} ? IsNever<S> extends true ? {} : GroupStateKeys<T, S>['leaf'] | (IsNever<GroupStateKeys<T, S>['nonLeaf']> extends false ? T extends {
|
|
3265
|
+
type: 'parallel';
|
|
3266
|
+
} ? { [K in GroupStateKeys<T, S>['nonLeaf']]: ToStateValue<T['states'][K]>; } : Compute<Values$1<{ [K in GroupStateKeys<T, S>['nonLeaf']]: { [StateKey in K]: ToStateValue<T['states'][K]>; }; }>> : never) : {};
|
|
3267
|
+
/** @public */
|
|
3268
|
+
interface BaseExecutableActionObject {
|
|
3269
|
+
params: NonReducibleUnknown;
|
|
3270
|
+
args: unknown[];
|
|
3271
|
+
exec(runtime?: Partial<ActorSystemRuntime>): void | PromiseLike<void> | undefined;
|
|
3272
|
+
}
|
|
3273
|
+
/**
|
|
3274
|
+
* The terminal result published when an actor completes or errors.
|
|
3275
|
+
*
|
|
3276
|
+
* @public
|
|
3277
|
+
*/
|
|
3278
|
+
type ActorTermination = {
|
|
3279
|
+
status: 'done';
|
|
3280
|
+
output: unknown;
|
|
3281
|
+
error: undefined;
|
|
3282
|
+
} | {
|
|
3283
|
+
status: 'error';
|
|
3284
|
+
output: undefined;
|
|
3285
|
+
error: unknown;
|
|
3286
|
+
};
|
|
3287
|
+
/** @public */
|
|
3288
|
+
interface CustomExecutableActionObject<TType extends string = string & {}> extends BaseExecutableActionObject {
|
|
3289
|
+
kind: 'action';
|
|
3290
|
+
type: TType;
|
|
3291
|
+
action: ((...args: any[]) => void | PromiseLike<void>) | undefined;
|
|
3292
|
+
}
|
|
3293
|
+
/** @public */
|
|
3294
|
+
interface EmitExecutableActionObject<TType extends string = string & {}> extends BaseExecutableActionObject {
|
|
3295
|
+
kind: 'emit';
|
|
3296
|
+
type: TType;
|
|
3297
|
+
source: AnyActor;
|
|
3298
|
+
event: EventObject & {
|
|
3299
|
+
type: TType;
|
|
3300
|
+
};
|
|
3301
|
+
}
|
|
3302
|
+
/** @public */
|
|
3303
|
+
interface SpawnExecutableActionObject extends BaseExecutableActionObject {
|
|
3304
|
+
kind: 'builtin';
|
|
3305
|
+
type: '@xstate.spawn';
|
|
3306
|
+
source: AnyActor | undefined;
|
|
3307
|
+
actor: AnyActor;
|
|
3308
|
+
id: string;
|
|
3309
|
+
logic: AnyActorLogic;
|
|
3310
|
+
src: string | AnyActorLogic;
|
|
3311
|
+
input: unknown;
|
|
3312
|
+
args: Parameters<(typeof builtInActions)['@xstate.spawn']>;
|
|
3313
|
+
}
|
|
3314
|
+
/** @public */
|
|
3315
|
+
interface StartExecutableActionObject extends BaseExecutableActionObject {
|
|
3316
|
+
kind: 'builtin';
|
|
3317
|
+
type: '@xstate.start';
|
|
3318
|
+
source: AnyActor | undefined;
|
|
3319
|
+
actor: AnyActor;
|
|
3320
|
+
id: string;
|
|
3321
|
+
args: Parameters<(typeof builtInActions)['@xstate.start']>;
|
|
3322
|
+
}
|
|
3323
|
+
/** @public */
|
|
3324
|
+
interface RaiseExecutableActionObject extends BaseExecutableActionObject {
|
|
3325
|
+
kind: 'builtin';
|
|
3326
|
+
type: '@xstate.raise';
|
|
3327
|
+
source: AnyActor;
|
|
3328
|
+
event: EventObject;
|
|
3329
|
+
id: string | undefined;
|
|
3330
|
+
delay: number | undefined;
|
|
3331
|
+
args: Parameters<(typeof builtInActions)['@xstate.raise']>;
|
|
3332
|
+
}
|
|
3333
|
+
/** @public */
|
|
3334
|
+
interface SendToExecutableActionObject extends BaseExecutableActionObject {
|
|
3335
|
+
kind: 'builtin';
|
|
3336
|
+
type: '@xstate.sendTo';
|
|
3337
|
+
source: AnyActor;
|
|
3338
|
+
target: AnyActor;
|
|
3339
|
+
event: EventObject;
|
|
3340
|
+
id: string | undefined;
|
|
3341
|
+
delay: number | undefined;
|
|
3342
|
+
args: Parameters<(typeof builtInActions)['@xstate.sendTo']>;
|
|
3343
|
+
}
|
|
3344
|
+
/** @public */
|
|
3345
|
+
interface CancelExecutableActionObject extends BaseExecutableActionObject {
|
|
3346
|
+
kind: 'builtin';
|
|
3347
|
+
type: '@xstate.cancel';
|
|
3348
|
+
source: AnyActor;
|
|
3349
|
+
id: string;
|
|
3350
|
+
args: Parameters<(typeof builtInActions)['@xstate.cancel']>;
|
|
3351
|
+
}
|
|
3352
|
+
/** @public */
|
|
3353
|
+
interface StopExecutableActionObject extends BaseExecutableActionObject {
|
|
3354
|
+
kind: 'builtin';
|
|
3355
|
+
type: '@xstate.stop';
|
|
3356
|
+
source: AnyActor;
|
|
3357
|
+
actor: AnyActor;
|
|
3358
|
+
id: string;
|
|
3359
|
+
args: Parameters<(typeof builtInActions)['@xstate.stop']>;
|
|
3360
|
+
}
|
|
3361
|
+
/**
|
|
3362
|
+
* An executable effect that publishes an actor's terminal result.
|
|
3363
|
+
*
|
|
3364
|
+
* @public
|
|
3365
|
+
*/
|
|
3366
|
+
type TerminateExecutableActionObject = BaseExecutableActionObject & {
|
|
3367
|
+
kind: 'builtin';
|
|
3368
|
+
type: '@xstate.terminate';
|
|
3369
|
+
source: AnyActor;
|
|
3370
|
+
actor: AnyActor;
|
|
3371
|
+
id: string;
|
|
3372
|
+
args: Parameters<(typeof builtInActions)['@xstate.terminate']>;
|
|
3373
|
+
} & ActorTermination;
|
|
3374
|
+
/**
|
|
3375
|
+
* An executable effect that reports an event rejected at the delivery boundary
|
|
3376
|
+
* (a dead letter). The snapshot paired with this effect is unchanged.
|
|
3377
|
+
*
|
|
3378
|
+
* @public
|
|
3379
|
+
*/
|
|
3380
|
+
interface DeadLetterExecutableActionObject extends BaseExecutableActionObject {
|
|
3381
|
+
kind: 'builtin';
|
|
3382
|
+
type: '@xstate.deadLetter';
|
|
3383
|
+
/** The actor that sent the event, or `undefined` for an external send. */
|
|
3384
|
+
source: AnyActor | undefined;
|
|
3385
|
+
/**
|
|
3386
|
+
* The actor that rejected the event, or `undefined` when the send target
|
|
3387
|
+
* was missing (`reason: 'missingTarget'`).
|
|
3388
|
+
*/
|
|
3389
|
+
target: AnyActor | undefined;
|
|
3390
|
+
/** The rejected event. */
|
|
3391
|
+
event: AnyEventObject;
|
|
3392
|
+
/** Why the event was rejected, such as `'invalidEvent'`. */
|
|
3393
|
+
reason: EventRejectionReason;
|
|
3394
|
+
detail?: DeadLetterDetail | undefined;
|
|
3395
|
+
args: [];
|
|
3396
|
+
}
|
|
3397
|
+
/** @public */
|
|
3398
|
+
type BuiltInExecutableActionObject = Values$1<{
|
|
3399
|
+
'@xstate.spawn': SpawnExecutableActionObject;
|
|
3400
|
+
'@xstate.start': StartExecutableActionObject;
|
|
3401
|
+
'@xstate.raise': RaiseExecutableActionObject;
|
|
3402
|
+
'@xstate.sendTo': SendToExecutableActionObject;
|
|
3403
|
+
'@xstate.cancel': CancelExecutableActionObject;
|
|
3404
|
+
'@xstate.stop': StopExecutableActionObject;
|
|
3405
|
+
'@xstate.terminate': TerminateExecutableActionObject;
|
|
3406
|
+
'@xstate.deadLetter': DeadLetterExecutableActionObject;
|
|
3407
|
+
}>;
|
|
3408
|
+
/** @public */
|
|
3409
|
+
type SpecialExecutableAction = BuiltInExecutableActionObject;
|
|
3410
|
+
type TransitionExecutableActionObject<TType extends string = never> = BuiltInExecutableActionObject | EmitExecutableActionObject | CustomExecutableActionObject<TType | (string & {})>;
|
|
3411
|
+
type KnownSourceKeys<TSourceMap> = string extends keyof TSourceMap ? never : Extract<keyof TSourceMap, string>;
|
|
3412
|
+
/** @public */
|
|
3413
|
+
type ExecutableActionObjectFromLogic<T extends AnyActorLogic> = T extends StateMachine<any, any, any, any, any, any, any, any, any, any, infer TActionMap, any, any, any> ? TransitionExecutableActionObject<KnownSourceKeys<TActionMap>> : ExecutableActionObject;
|
|
3414
|
+
/** @public */
|
|
3415
|
+
type ExecutableActionObject<TType extends string = string & {}> = BuiltInExecutableActionObject | EmitExecutableActionObject | CustomExecutableActionObject<TType>;
|
|
3416
|
+
/** @public */
|
|
3417
|
+
interface ToExecutableAction<T extends ParameterizedObject> extends CustomExecutableActionObject<T['type']> {
|
|
3418
|
+
type: T['type'];
|
|
3419
|
+
params: T['params'];
|
|
3420
|
+
action: undefined;
|
|
3421
|
+
}
|
|
3422
|
+
/** @public */
|
|
3423
|
+
type ActionExecutor = (actionToExecute: ExecutableActionObject) => void;
|
|
3424
|
+
/**
|
|
3425
|
+
* Mappers for subscribeTo - maps lifecycle events to machine events
|
|
3426
|
+
*
|
|
3427
|
+
* @public
|
|
3428
|
+
*/
|
|
3429
|
+
interface SubscribeToMappers<TSnapshot extends Snapshot<unknown>, TOutput, TMappedEvent extends EventObject> {
|
|
3430
|
+
snapshot?: (snapshot: TSnapshot) => TMappedEvent;
|
|
3431
|
+
done?: (output: TOutput) => TMappedEvent;
|
|
3432
|
+
error?: (error: unknown) => TMappedEvent;
|
|
3433
|
+
}
|
|
3434
|
+
type EnqueueSpawnOptions<TLogic extends AnyActorLogic, TSystemRegistry extends SystemRegistry> = {
|
|
3435
|
+
input?: InputFrom<TLogic>;
|
|
3436
|
+
id?: string;
|
|
3437
|
+
syncSnapshot?: boolean;
|
|
3438
|
+
registryKey?: RegistryKeyForLogic<TLogic, TSystemRegistry>;
|
|
3439
|
+
};
|
|
3440
|
+
type EnqueueSpawnArgs<TLogic extends AnyActorLogic, TSystemRegistry extends SystemRegistry> = ConditionalRequired<[options?: EnqueueSpawnOptions<TLogic, TSystemRegistry> & { [K in RequiredLogicInput<TLogic>]: unknown; }], IsNotNever<RequiredLogicInput<TLogic>>>;
|
|
3441
|
+
type EnqueueSpawner<TActorMap extends Sources['actors'], TSystemRegistry extends SystemRegistry> = {
|
|
3442
|
+
<TSource extends keyof TActorMap & string>(src: TSource, ...[options]: EnqueueSpawnArgs<TActorMap[TSource], TSystemRegistry>): ActorFromLogic<TActorMap[TSource]>;
|
|
3443
|
+
<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: EnqueueSpawnArgs<TLogic, TSystemRegistry>): ActorFromLogic<TLogic>;
|
|
3444
|
+
};
|
|
3445
|
+
/** @public */
|
|
3446
|
+
type EnqueueObject<TEvent extends EventObject, TEmittedEvent extends EventObject, TSystemRegistry extends SystemRegistry = SystemRegistry, TActorMap extends Sources['actors'] = Sources['actors'], TChildren extends Record<string, AnyActorRef | undefined> = {}> = {
|
|
3447
|
+
cancel: (id: string) => void;
|
|
3448
|
+
raise: (ev: TEvent, options?: {
|
|
3449
|
+
id?: string;
|
|
3450
|
+
delay?: number;
|
|
3451
|
+
}) => void;
|
|
3452
|
+
/**
|
|
3453
|
+
* Spawns a child actor from a registered source key or logic. Without an
|
|
3454
|
+
* explicit `id`, the child gets a deterministic src-keyed id (`worker:0`,
|
|
3455
|
+
* `worker:1`, …) allocated from the parent snapshot's own counters, so ids
|
|
3456
|
+
* replay identically and persist with the parent.
|
|
3457
|
+
*/
|
|
3458
|
+
spawn: EnqueueSpawner<TActorMap, TSystemRegistry>;
|
|
3459
|
+
emit: (emittedEvent: TEmittedEvent) => void;
|
|
3460
|
+
<T extends (...args: any[]) => any>(fn: T, ...args: Parameters<T>): void;
|
|
3461
|
+
log: (...args: any[]) => void;
|
|
3462
|
+
sendTo: <TTarget extends {
|
|
3463
|
+
send: (...args: any[]) => void;
|
|
3464
|
+
} | undefined | (keyof TChildren & string)>(target: TTarget, event: SendableEventFromActorRef<DoNotInfer<TTarget extends keyof TChildren & string ? TChildren[TTarget] : TTarget>>, options?: {
|
|
3465
|
+
id?: string;
|
|
3466
|
+
delay?: number;
|
|
3467
|
+
}) => void;
|
|
3468
|
+
stop: (actor?: AnyActorRef) => void;
|
|
3469
|
+
/**
|
|
3470
|
+
* Listen to emitted events from an actor. Returns a listener actor that can
|
|
3471
|
+
* be stopped via `enq.stop()`.
|
|
3472
|
+
*
|
|
3473
|
+
* @param actor - The actor to listen to
|
|
3474
|
+
* @param eventType - The emitted event type to listen for (supports
|
|
3475
|
+
* wildcards: 'event._', '_')
|
|
3476
|
+
* @param mapper - Function to transform emitted events into machine events
|
|
3477
|
+
*/
|
|
3478
|
+
listen: <TEmitted extends EventObject, TMappedEvent extends TEvent>(actor: AnyActorRef, eventType: string, mapper: (event: TEmitted) => TMappedEvent) => AnyActor;
|
|
3479
|
+
/**
|
|
3480
|
+
* Subscribe to lifecycle events (done/error/snapshot) from an actor. Returns
|
|
3481
|
+
* a subscription actor that can be stopped via `enq.stop()`.
|
|
3482
|
+
*
|
|
3483
|
+
* @param actor - The actor to subscribe to
|
|
3484
|
+
* @param mappers - Object with done/error/snapshot mappers, or a single
|
|
3485
|
+
* snapshot mapper function
|
|
3486
|
+
*/
|
|
3487
|
+
subscribeTo: <TActor extends AnyActorRef, TMappedEvent extends TEvent>(actor: TActor, mappers: SubscribeToMappers<SnapshotFrom<TActor>, OutputFrom<TActor>, TMappedEvent> | ((snapshot: SnapshotFrom<TActor>) => TMappedEvent)) => AnyActor;
|
|
3488
|
+
};
|
|
3489
|
+
/** @public */
|
|
3490
|
+
type Action<TContext extends MachineContext, TEvent extends EventObject, TEmittedEvent extends EventObject, TActionMap extends Sources['actions'], TActorMap extends Sources['actors'], TGuardMap extends Sources['guards'], TDelayMap extends Sources['delays'], TParams = Record<string, unknown> | undefined, _TCtx = [TContext] extends [never] ? any : TContext> = (_: {
|
|
3491
|
+
context: _TCtx;
|
|
3492
|
+
event: TEvent;
|
|
3493
|
+
parent: AnyActorRef | undefined;
|
|
3494
|
+
self: ActorSelf<MachineSnapshot<_TCtx & MachineContext, TEvent, TODO, TODO, TODO, TODO, TODO, TODO>, TEvent>;
|
|
3495
|
+
children: Record<string, AnyActor | undefined>;
|
|
3496
|
+
actions: TActionMap;
|
|
3497
|
+
actors: TActorMap;
|
|
3498
|
+
guards: TGuardMap;
|
|
3499
|
+
delays: TDelayMap;
|
|
3500
|
+
system?: AnyActorSystem;
|
|
3501
|
+
params: TParams;
|
|
3502
|
+
}, enqueue: EnqueueObject<TEvent, TEmittedEvent, SystemRegistry, TActorMap>) => {
|
|
3503
|
+
context?: Partial<_TCtx>;
|
|
3504
|
+
children?: Record<string, AnyActor | undefined>;
|
|
3505
|
+
} | void;
|
|
3506
|
+
/** @public */
|
|
3507
|
+
type AnyAction = Action<MachineContext, EventObject, EventObject, Sources['actions'], Sources['actors'], Sources['guards'], Sources['delays']> | {
|
|
3508
|
+
action: (...args: any[]) => any;
|
|
3509
|
+
args: any[];
|
|
3510
|
+
} | AnyEventObject;
|
|
3511
|
+
export { DelayExpr as $, TransitionConfigFunction as $n, DelayMapFromNames as $r, PersistedSnapshotFor as $t, AnyInvokeConfig as A, StateMachineTypes as An, ActorSystemRuntime as Ar, InteropSubscribable as At, BaseActorRef as B, Subscribable as Bn, InspectionEvent as Br, MachineTypes as Bt, AnyActor as C, ValidateStateTargets as Ci, StateConfig as Cn, LogicArgs as Cr, HomomorphicOmit as Ct, AnyEventObject as D, createdInvokeConfig as Di, StateIdInputs as Dn, TimeoutError as Dr, InitialTransitionDefinition as Dt, AnyActorScope as E, WithDefault as Ei, StateId as En, LogicFunction as Er, InitialTransitionConfig as Et, AnyStateNode as F, StateValue as Fn, EventRejection as Fr, IsNotNever as Ft, Cast as G, TagsFrom as Gn, ActorValidationEventOrigin as Gr, NormalizeDescriptor as Gt, BuiltInExecutableActionObject as H, Subscription as Hn, TransitionInspectionEvent as Hr, MaybeLazy as Ht, AnyStateNodeConfig as I, StateValueFrom as In, EventRejectionReason as Ir, Lazy as It, ContextFactory as J, TimerEvent as Jn, MachineSnapshotSchema as Jr, OutputFrom as Jt, Compute as K, TerminateExecutableActionObject as Kn, ActorValidationRequest as Kr, Observer as Kt, AnyTransitionConfig as L, StateValueFromStateSchema as Ln, WallClock as Lr, LogicalTimer as Lt, AnyMachineSnapshot as M, StateSchema as Mn, Clock as Mr, IsAny as Mt, AnyStateConfig as N, StateSchemaFrom as Nn, CryptoSource as Nr, IsLiteralString as Nt, AnyFunction as O, MachineSnapshot as Oi, StateKey as On, createAsyncLogic as Or, InputFrom as Ot, AnyStateMachine as P, StateTypes as Pn, DeadLetterDetail as Pr, IsNever as Pt, DelayConfig as Q, TransitionConfig as Qn, DelayDurationKey as Qr, PersistedMachineIdentity as Qt, AnyTransitionConfigFunction as R, StateValueMap as Rn, ActionRecord as Rr, LowInfer as Rt, AnyAction as S, ValidateHistoryDefaults as Si, StartExecutableActionObject as Sn, AsyncSnapshot as Sr, HistoryValue as St, AnyActorRef as T, WidenLiterals as Ti, StateFrom as Tn, LogicEnqueue as Tr, InitialContext as Tt, CallbackActors as U, SystemRegistry as Un, ActorLogicValidator as Ur, MetaObject as Ut, BaseExecutableActionObject as V, SubscribeToMappers as Vn, SentRecord as Vr, Mapper as Vt, CancelExecutableActionObject as W, TODO as Wn, ActorValidationBoundary as Wr, NonReducibleUnknown as Wt, CustomExecutableActionObject as X, ToExecutableAction as Xn, PersistedMachineSnapshot as Xr, PersistedActorRef as Xt, ContextFrom as Y, ToChildren as Yn, MachineVersionDescriptor as Yr, ParameterizedObject as Yt, DeadLetterExecutableActionObject as Z, ToStateValue as Zn, ChildCompletionEvents as Zr, PersistedHistoryValue as Zt, ActorSystemInfo as _, SchemaOrConfigOutput as _i, SnapshotFrom as _n, RequiredActorOptionsFor as _r, EventPayloadPattern as _t, ActorInstance as a, InferGuards as ai, Readable as an, TransitionTarget as ar, DoneStateEvent as at, ActorTrigger as b, ValidateDelayReferences as bi, SpecialExecutableAction as bn, AsyncActorLogic as br, ExtractEvent as bt, ActorLogicTransitionResult as c, InvokeInputArgs as ci, RequiredLogicInput as cn, UnknownActorLogic as cr, EnqueueObject as ct, ActorRefFrom as d, Next_InvokeConfigBase as di, SendToExecutableActionObject as dn, InfiniteTransitionError as dr, ErrorEvent as dt, DelaySourceMap as ei, PersistedSnapshotFrom as en, TransitionConfigTarget as er, DelayedTransitionDefinition as et, ActorRefFromLogic as f, Next_MachineConfig as fi, SendableEventFromLogic as fn, getStateNodes as fr, ErrorFrom as ft, ActorSelf as g, OutputFromConfig as gi, SnapshotEvent as gn, Actor as gr, EventFromLogic as gt, ActorScope as h, Next_TransitionConfigOrTarget as hi, Snapshot as hn, Spawner as hr, EventFrom as ht, ActorFromLogic as i, InferChildren as ii, RaiseExecutableActionObject as in, TransitionDefinitionMap as ir, DoneActorEvent as it, AnyInvokeDefinition as j, StateNodesConfig as jn, AnyActorSystem as jr, InvokeDefinition as jt, AnyHistoryValue as k, isMachineSnapshot as ki, StateLike as kn, ActorSystem as kr, InteropObservable as kt, ActorOptions as l, Next_ChoiceStateNodeConfig as li, RestorablePersistedSnapshotFor as ln, UnknownActorRef as lr, Equals as lt, ActorRuntime as m, Next_StateNodeConfig as mi, SingleOrArray as mn, StateNode as mr, EventDescriptor as mt, ActionArgs as n, GuardSourceMap as ni, Prop as nn, TransitionContextPatch as nr, DevToolsAdapter as nt, ActorLike as o, InferMachineInput as oi, RegistryKeyForLogic as on, TransitionsConfig as or, EmitExecutableActionObject as ot, ActorRefLike as p, Next_RegularStateNodeConfig as pi, SetupTypes as pn, checkStateIn as pr, ErrorPlatformEvent as pt, ConditionalRequired as q, TimeoutEvent as qn, MachineEventSchema as qr, OutputArg as qt, ActionExecutor as r, InferActions as ri, ProvidedActor as rn, TransitionDefinition as rr, DoNotInfer as rt, ActorLogic as s, InferOutput as si, RequiredActorOptions as sn, UnifiedArg as sr, EmittedFrom as st, Action as t, FinalStateConfigOutput as ti, PersistedSnapshotOf as tn, TransitionContextMapper as tr, DelayedTransitions as tt, ActorRef as u, Next_InvokeConfig as ui, RoutableStateId as un, StateMachine as ur, ErrorActorEvent as ut, ActorTermination as v, Sources as vi, SnapshotStatus as vn, RequiredActorOptionsKeys as vr, ExecutableActionObject as vt, AnyActorLogic as w, ValidateTopLevelFinalOutputs as wi, StateContextFromStateValue as wn, LogicConfig as wr, InferEvent as wt, AfterEvent as x, ValidateEventDescriptors as xi, SpecialTargets as xn, AsyncActorRef as xr, HistoryStateNode as xt, ActorTimeoutEvent as y, ValidateDelayNames as yi, SpawnExecutableActionObject as yn, createActor as yr, ExecutableActionObjectFromLogic as yt, AnyTransitionDefinition as z, StopExecutableActionObject as zn, ActorInspectionEvent as zr, MachineSourcesFrom as zt };
|