xstate 6.0.0-alpha.8 → 6.0.0-beta.0

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

@@ -1,4 +1,5 @@
 import { Clock } from "./system.js";
+/** @public */
 export interface SimulatedClock extends Clock {
     start(speed: number): void;
     increment(ms: number): void;
@@ -6,10 +7,10 @@ export interface SimulatedClock extends Clock {
 }
 export declare class SimulatedClock implements SimulatedClock {
     private timeouts;
+    private readonly deadlines;
     private _now;
     private _id;
     private _flushing;
-    private _flushingInvalidated;
     now(): number;
     private getId;
     setTimeout(fn: (...args: any[]) => void, timeout: number): number;

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

@@ -1,5 +1,51 @@
-import type { AnyMachineSnapshot, AnyStateMachine, EventObject, HistoryValue, MachineContext, StateConfig, StateValue, AnyActorRef, Snapshot, MetaObject, StateSchema, StateId, StateIdInputs, StateContextFromStateValue, SnapshotStatus, AnyStateNode } from "./types.js";
+import type { AnyMachineSnapshot, AnyStateMachine, AnyActor, EventObject, HistoryValue, MachineContext, StateConfig, StateValue, StateValueMap, AnyActorRef, Snapshot, MetaObject, StateSchema, StateId, StateIdInputs, StateContextFromStateValue, StateIdReference, SnapshotStatus, AnyStateNode, LogicalTimer } from "./types.js";
+export declare function freezeContext(value: any, visiting?: Set<object>): void;
+/** @public */
 export declare function isMachineSnapshot(value: unknown): value is AnyMachineSnapshot;
+type Values<T> = T[keyof T];
+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];
+};
+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;
+type StateValuePath<TStateValue extends StateValue> = TStateValue extends StateValueMap ? {
+    [K in keyof TStateValue & string]: K | (NonNullable<TStateValue[K]> extends infer TChild extends StateValue ? `${K}.${StateValuePath<TChild>}` : never);
+}[keyof TStateValue & string] : TStateValue;
+/**
+ * The values that `snapshot.matches(...)` accepts for a state value: a state
+ * key, a dot-delimited path to a descendant state, or a partial state value.
+ * Non-literal state values accept any value.
+ */
+export type ToTestStateValue<TStateValue extends StateValue> = StateValue extends TStateValue ? StateValue : TStateValue extends string ? TStateValue : TStateValue extends StateValueMap ? string extends keyof TStateValue ? StateValue : StateValuePath<TStateValue> | {
+    [K in keyof TStateValue]?: NonNullable<TStateValue[K]> extends infer TChild extends StateValue ? ToTestStateValue<TChild> : never;
+} : never;
+/**
+ * `true` if `TTestStateValue` can match `TStateValue`, checked per position:
+ * each literal key names a state at its level and each literal child matches
+ * that state. A non-literal value (`string`, or a map with `string` keys)
+ * passes at its own position only, so `{ checkout: string }` is accepted and
+ * `{ nope: 'payment', checkout: string }` is not.
+ */
+type IsTestStateValueValid<TStateValue extends StateValue, TTestStateValue> = StateValue extends TStateValue ? true : string extends TTestStateValue ? true : TTestStateValue extends string ? [TTestStateValue] extends [StateValuePath<TStateValue>] ? true : false : TTestStateValue extends StateValueMap ? string extends keyof TTestStateValue ? true : true extends (TStateValue extends StateValueMap ? IsTestStateValueMapValid<TStateValue, TTestStateValue> : never) ? true : false : false;
+type IsTestStateValueMapValid<TStateValueMap extends StateValueMap, TTestStateValue extends StateValueMap> = [Exclude<keyof TTestStateValue, keyof TStateValueMap>] extends [never] ? false extends {
+    [K in keyof TTestStateValue]-?: IsTestStateValueValid<NonNullable<TStateValueMap[K & keyof TStateValueMap]>, NonNullable<TTestStateValue[K]>>;
+}[keyof TTestStateValue] ? false : true : false;
+/**
+ * `unknown` if `matches(...)` accepts `TTestStateValue` for `TStateValue`,
+ * otherwise `never`. Literal values must name states; a non-literal value
+ * (such as a `string` leaf) is accepted at its own position.
+ */
+export type TestStateValueCheck<TStateValue extends StateValue, TTestStateValue extends StateValue> = [TTestStateValue] extends [ToTestStateValue<TStateValue>] ? unknown : false extends IsTestStateValueValid<TStateValue, TTestStateValue> ? never : unknown;
+/**
+ * The `#id` references a snapshot (or union of snapshots) accepts, read from
+ * its `getMeta()` keys so the overload does not depend on the state schema.
+ */
+type SnapshotStateIdReference<TSnapshot> = TSnapshot extends {
+    getMeta: () => Record<infer TStateId, any>;
+} ? string extends TStateId ? `#${string}` : `#${Exclude<TStateId, ''> & string}` : `#${string}`;
 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> {
     /** The state machine that produced this state snapshot. */
     machine: AnyStateMachine;
@@ -33,16 +79,27 @@ interface MachineSnapshotBase<TContext extends MachineContext, TEvent extends Ev
     context: TContext;
     historyValue: Readonly<HistoryValue>;
     /** The enabled state nodes representative of the state value. */
-    _nodes: Array<AnyStateNode>;
+    nodes: Array<AnyStateNode>;
     /** An object mapping actor names to spawned/invoked actors. */
     children: TChildren;
+    /** Pending logical timers owned by this machine snapshot. */
+    timers: readonly LogicalTimer[];
     /**
      * Whether the current state value is a subset of the given partial state
-     * value.
+     * value, or, for a `'#id'` reference, whether the state node with that `id`
+     * is active.
      *
      * @param partialStateValue
      */
-    matches<const TTestStateValue extends StateValue>(partialStateValue: TTestStateValue): this is MachineSnapshot<StateContextFromStateValue<TStateSchema, TContext, TTestStateValue>, TEvent, TChildren, TStateValue, TTag, _TOutput, TMeta, TStateSchema>;
+    matches<const TTestStateId extends StateIdReference<TStateSchema>>(stateId: TTestStateId): boolean;
+    matches<const TTestStateValue extends Extract<ToTestStateValue<TStateValue>, string>>(partialStateValue: TTestStateValue, ...args: string extends TTestStateValue ? [never] : []): this is MachineSnapshot<StateContextFromStateValue<TStateSchema, TContext, TTestStateValue>, TEvent, TChildren, MatchingStateValue<TStateValue, TTestStateValue>, TTag, _TOutput, TMeta, TStateSchema>;
+    matches<const TTestStateValue extends Extract<ToTestStateValue<TStateValue>, 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>;
+    matches<TSnapshot extends {
+        value: StateValue;
+    }>(this: TSnapshot, stateId: NoInfer<SnapshotStateIdReference<TSnapshot>>): boolean;
+    matches<TSnapshot extends {
+        value: StateValue;
+    }, const TTestStateValue extends StateValue>(this: TSnapshot, partialStateValue: TTestStateValue & NoInfer<TestStateValueCheck<TSnapshot['value'], TTestStateValue>>): boolean;
     /**
      * Whether the current state nodes has a state node with the specified `tag`.
      *
@@ -54,6 +111,9 @@ interface MachineSnapshotBase<TContext extends MachineContext, TEvent extends Ev
      * transition to be selected, even if the transitions have no actions nor
      * change the state value.
      *
+     * Returns false for terminal snapshots. Throws if transition evaluation
+     * throws; this dry run does not run onError recovery.
+     *
      * @param event The event to test
      * @returns Whether the event will cause a transition
      */
@@ -86,8 +146,9 @@ interface StoppedMachineSnapshot<TContext extends MachineContext, TEvent extends
     output: undefined;
     error: undefined;
 }
+/** @public */
 export 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>;
-export declare function createMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TMeta extends MetaObject, TStateSchema extends StateSchema>(config: StateConfig<TContext, TEvent>, machine: AnyStateMachine): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, undefined, TMeta, TStateSchema>;
+export declare function createMachineSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TMeta extends MetaObject, TStateSchema extends StateSchema>(config: StateConfig<TContext, TEvent>, machine: AnyStateMachine, actorRef?: AnyActor): MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, undefined, TMeta, TStateSchema>;
 export declare function cloneMachineSnapshot<TState extends AnyMachineSnapshot>(snapshot: TState, config?: Partial<StateConfig<any, any>>): TState;
 export declare function getPersistedSnapshot<TContext extends MachineContext, TEvent extends EventObject, TChildren extends Record<string, AnyActorRef | undefined>, TStateValue extends StateValue, TTag extends string, TOutput, TMeta extends MetaObject>(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, any>, options?: unknown): Snapshot<unknown>;
 export {};

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

@@ -1,44 +1,117 @@
 import { MachineSnapshot } from "./State.js";
 import { StateNode } from "./StateNode.js";
+import { type TransitionSelectionResults } from "./stateUtils.js";
 import { AnyActorSystem } from "./system.js";
-import type { ActorLogic, ActorLogicTransitionResult, ActorScope, AnyActor, AnyActorRef, AnyActorScope, AnyTransitionDefinition, Equals, EventDescriptor, EventObject, ExecutableActionObjectFromLogic, HistoryValue, MachineContext, MetaObject, Snapshot, StateValue, StateSchema, SnapshotStatus } from "./types.js";
-import { AnyMachineSchemas, Implementations, Next_MachineConfig, MachineOptions } from "./types.v6.js";
-export 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 Implementations['actions'], TActorMap extends Implementations['actorSources'], TGuardMap extends Implementations['guards'], TDelayMap extends Implementations['delays']> implements ActorLogic<MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, TEvent, TInput, AnyActorSystem, TEmitted> {
+import type { ActorLogic, ActorLogicTransitionResult, ActorScope, AnyActorLogic, AnyActorRef, AnyActorScope, AnyStateMachine, AnyTransitionDefinition, EventDescriptor, EmittedFrom, EventObject, EventFromLogic, ExecutableEffectFrom, HistoryValue, InputFrom, MachineContext, MetaObject, OutputFrom, SnapshotFrom, StateValue, StateSchema, SnapshotStatus } from "./types.js";
+import type { Equals, IsAny } from "./typeUtils.js";
+import { AnyMachineSchemas, DelaySourceMap, GuardSourceMap, Sources, Next_MachineConfig, MachineOptions } from "./types.v6.js";
+import type { ActorLogicValidator } from "./validation.types.js";
+export 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;
+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;
+};
+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];
+};
+type DeclaredAction<T> = T extends {
+    readonly '~declaredAction'?: infer TDeclared;
+} ? unknown extends TDeclared ? T : Exclude<TDeclared, undefined> : T;
+type ProvidedActionSourceMap<TDeclared, TProvided> = {
+    [K in keyof TDeclared]: K extends keyof TProvided ? ({} extends Pick<TProvided, K> ? TDeclared[K] | Exclude<TProvided[K], undefined> : Exclude<TProvided[K], undefined>) & {
+        readonly '~declaredAction'?: DeclaredAction<TDeclared[K]>;
+    } : TDeclared[K];
+};
+export type ProvidedActionContracts<T> = {
+    [K in keyof T]: DeclaredAction<T[K]> extends (...args: infer TArgs) => infer TResult ? (...args: TArgs) => ProvidedActionResult<TResult> : never;
+};
+type ProvidedActionResult<TResult> = void extends TResult ? void : Extract<TResult, ReturnType<Sources['actions'][string]>>;
+export { InvalidSnapshotError } from "./persistedSnapshotValidation.js";
+/** @public */
+export 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> {
     /** The raw config used to create the machine. */
-    config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any> & {
+    config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any, any, any> & {
         schemas?: AnyMachineSchemas;
-        internalEvents?: readonly string[];
     };
+    validator?: ActorLogicValidator | undefined;
+    /**
+     * Type-only marker for the actor's internal event protocol. `actor.send` and
+     * `actor.trigger` read it to drop internal events from the public protocol,
+     * so it must survive `stripInternal` into the published declarations. Not
+     * `declare` (the build's babel pipeline rejects declare class fields); the
+     * one `undefined` property this emits per machine instance is inert.
+     */
+    readonly _internalEventType: TInternalEvent;
+    /** Type-only marker for transition metadata. Never assigned at runtime. */
+    readonly _transitionMetaType: TTransitionMeta;
+    /**
+     * Type-only marker for the declared input type. `getInitialSnapshot` takes
+     * input optionally, so inferring input from it always adds `undefined`;
+     * `InputFrom` reads this carrier instead. Method-shaped so it stays
+     * bivariant like `getInitialSnapshot`. Never assigned at runtime.
+     */
+    readonly _inputType: {
+        carry(input: TInput): void;
+    }['carry'];
+    /**
+     * Type-level carriers for the machine's source maps and state schema. Type
+     * helpers in integration packages read these to walk a machine's declared
+     * actions, actors and invoked sources. They are never assigned at runtime.
+     */
+    readonly _actionMap: TActionMap;
+    readonly _actorMap: TActorMap;
+    readonly _stateSchema: TConfig;
     /** The machine's own version. */
-    version?: string;
-    schemas: AnyMachineSchemas | undefined;
-    implementations: Implementations;
+    version: TConfig extends {
+        version: infer TVersion extends string;
+    } ? TVersion : undefined;
+    schemas: (TConfig extends {
+        schemas: infer TSchemas extends AnyMachineSchemas;
+    } ? TSchemas : AnyMachineSchemas) | undefined;
+    sources: Sources;
     /** Runtime options for machine execution. */
     options: MachineOptions;
-    root: StateNode<TContext, TEvent>;
-    id: string;
-    states: StateNode<TContext, TEvent>['states'];
+    root: StateNode<TContext, TEvent, TMeta, TTransitionMeta>;
+    /**
+     * The machine's `id`, or the empty string when the config declares none.
+     * The root state node has this id; a machine without one has no `#id` root.
+     */
+    id: TConfig extends {
+        id: infer TId extends string;
+    } ? TId : '';
+    states: StateNode<TContext, TEvent, TMeta, TTransitionMeta>['states'];
     events: Array<EventDescriptor<TEvent>>;
     internalEventDescriptors: ReadonlyArray<string>;
+    /**
+     * Adapter hooks for actor-local transition evaluation state. Used by
+     * `@xstate/scxml`; not part of the stable API.
+     *
+     * @experimental
+     */
+    _microstepHooks?: AnyStateMachine['_microstepHooks'];
     constructor(
     /** The raw config used to create the machine. */
-    config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any> & {
+    config: Next_MachineConfig<any, any, any, any, any, any, any, any, any, any, any, any, any> & {
         schemas?: AnyMachineSchemas;
-        internalEvents?: readonly string[];
-    }, implementations?: Implementations);
+    }, sources?: Sources, validator?: ActorLogicValidator | undefined);
     /**
-     * Clones this state machine with the provided implementations.
+     * Clones this state machine with the provided sources.
      *
-     * @param implementations Options (`actions`, `guards`, `actorSources`,
-     *   `delays`) to recursively merge with the existing options.
-     * @returns A new `StateMachine` instance with the provided implementations.
+     * @param sources Options (`actions`, `guards`, `actors`, `delays`) to
+     *   recursively merge with the existing options.
+     * @returns A new `StateMachine` instance with the provided sources.
      */
-    provide(implementations: {
-        actions?: Partial<TActionMap>;
-        actorSources?: Partial<TActorMap>;
-        guards?: Partial<TGuardMap>;
-        delays?: Partial<TDelayMap>;
-    }): StateMachine<TContext, TEvent, TChildren, TStateValue, TTag, TInput, TOutput, TEmitted, TMeta, TConfig, TActionMap, TActorMap, TGuardMap, TDelayMap>;
+    provide<const TProvidedActorMap extends Partial<Record<keyof TActorMap & string, AnyActorLogic>> = {}, const TProvidedActionMap extends Partial<ProvidedActionContracts<TActionMap>> = {}>(sources: {
+        actions?: TProvidedActionMap & Partial<ProvidedActionContracts<TActionMap>> & Record<Exclude<keyof TProvidedActionMap, keyof TActionMap>, never>;
+        actors?: TProvidedActorMap & ProvidedActors<TActorMap, TProvidedActorMap>;
+        guards?: Partial<TGuardMap> & {
+            [K in keyof TGuardMap]?: GuardSourceMap<TContext, TEvent>[string];
+        };
+        delays?: {
+            [K in keyof TDelayMap]?: DelaySourceMap<TContext, TEvent>[string];
+        };
+    }): StateMachine<TContext, TEvent, TChildren, TStateValue, TTag, TInput, TOutput, TEmitted, TMeta, TConfig, ProvidedActionSourceMap<TActionMap, TProvidedActionMap>, ProvidedSourceMap<TActorMap, TProvidedActorMap>, TGuardMap, TDelayMap, TInternalEvent, TTransitionMeta>;
     resolveState(config: {
         value: StateValue;
         context?: TContext;
@@ -56,7 +129,10 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
      * @param snapshot The current snapshot
      * @param event The received event
      */
-    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>>;
+    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>, ExecutableEffectFrom<this>>;
+    private _collectEffects;
+    private _attachPureActorRef;
+    private _transitionFast;
     /**
      * Determines the next state given the current `state` and `event`. Calculates
      * a microstep.
@@ -65,16 +141,15 @@ export declare class StateMachine<TContext extends MachineContext, TEvent extend
      * @param event The received event
      */
     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>>;
-    getTransitionData(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, event: TEvent, self: AnyActor): Array<AnyTransitionDefinition>;
+    getTransitionData(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, event: TEvent, actorScope: AnyActorScope, selectionResults?: TransitionSelectionResults): Array<AnyTransitionDefinition>;
     isInternalEventType(eventType: string): boolean;
     /**
      * Returns the initial `State` instance, with reference to `self` as an
      * `ActorRef`.
      */
-    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>;
-    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>>;
-    start(snapshot?: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>): void;
-    getStateNodeById(stateId: string): StateNode<TContext, TEvent>;
-    getPersistedSnapshot(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, options?: unknown): Snapshot<unknown>;
-    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>;
+    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>;
+    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>, ExecutableEffectFrom<this>>;
+    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;
+    getStateNodeById(stateId: string): StateNode<TContext, TEvent, TMeta, TTransitionMeta>;
+    getPersistedSnapshot(snapshot: MachineSnapshot<TContext, TEvent, TChildren, TStateValue, TTag, TOutput, TMeta, TConfig>, options?: unknown): import("./types.js").Snapshot<unknown>;
 }

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

@@ -1,10 +1,13 @@
-import type { DelayedTransitionDefinition, EventObject, InitialTransitionDefinition, MachineContext, Mapper, StateNodesConfig, TransitionDefinitionMap, AnyStateMachine, AnyStateNodeConfig, NonReducibleUnknown, EventDescriptor, AnyAction, AnyTransitionDefinition, AnyInvokeDefinition } from "./types.js";
-interface StateNodeOptions<TContext extends MachineContext, TEvent extends EventObject> {
+import type { SetupStateSchemas } from "./schema.types.js";
+import type { DelayedTransitionDefinition, EventObject, InitialTransitionDefinition, MachineContext, Mapper, TransitionDefinition, TransitionDefinitionMap, AnyStateMachine, AnyStateNodeConfig, EventDescriptor, AnyAction, InvokeDefinition, MetaObject } from "./types.js";
+import type { NonReducibleUnknown } from "./typeUtils.js";
+interface StateNodeOptions<TStateMeta extends MetaObject, TTransitionMeta extends MetaObject> {
     _key: string;
-    _parent?: StateNode<TContext, TEvent>;
+    _parent?: StateNode<any, any, TStateMeta, TTransitionMeta>;
     _machine: AnyStateMachine;
 }
-export declare class StateNode<TContext extends MachineContext = MachineContext, TEvent extends EventObject = EventObject> {
+/** @public */
+export declare class StateNode<TContext extends MachineContext = MachineContext, TEvent extends EventObject = EventObject, TStateMeta extends MetaObject = any, TTransitionMeta extends MetaObject = TStateMeta> {
     /** The raw config used to create the machine. */
     config: AnyStateNodeConfig;
     /**
@@ -28,7 +31,7 @@ export declare class StateNode<TContext extends MachineContext = MachineContext,
     /** The string path from the root machine node to this node. */
     path: string[];
     /** The child state nodes. */
-    states: StateNodesConfig<any, any>;
+    states: Record<string, StateNode<TContext, TEvent, TStateMeta, TTransitionMeta>>;
     /**
      * The type of history on this state node. Can be:
      *
@@ -41,17 +44,17 @@ export declare class StateNode<TContext extends MachineContext = MachineContext,
     /** The action(s) to be executed upon exiting the state node. */
     exit: AnyAction | undefined;
     /** The parent state node. */
-    parent?: StateNode<any, any>;
+    parent?: StateNode<TContext, TEvent, TStateMeta, TTransitionMeta>;
     /** The root machine node. */
     machine: AnyStateMachine;
     /**
      * The meta data associated with this state node, which will be returned in
      * State instances.
      */
-    meta?: any;
+    meta?: TStateMeta;
     /**
-     * The output data sent with the "xstate.done.state._id_" event if this is a
-     * final state node.
+     * The output data sent with the `xstate.done.state` event if this is a final
+     * state node.
      */
     output?: Mapper<MachineContext, EventObject, unknown, EventObject> | NonReducibleUnknown;
     /**
@@ -60,17 +63,19 @@ export declare class StateNode<TContext extends MachineContext = MachineContext,
      */
     order: number;
     description?: string;
+    schemas: SetupStateSchemas | undefined;
     tags: string[];
-    transitions: Map<string, AnyTransitionDefinition[]>;
-    always?: Array<AnyTransitionDefinition>;
-    invoke: Array<AnyInvokeDefinition>;
-    on: TransitionDefinitionMap<any, any>;
-    after: Array<DelayedTransitionDefinition<any, any>>;
+    transitions: Map<string, TransitionDefinition<any, any, TTransitionMeta>[]>;
+    always?: Array<TransitionDefinition<any, any, TTransitionMeta>>;
+    invoke: Array<InvokeDefinition<any, any, any, TTransitionMeta, any, any, any, any>>;
+    on: TransitionDefinitionMap<any, any, TTransitionMeta>;
+    after: Array<DelayedTransitionDefinition<any, any, TTransitionMeta>>;
     events: Array<EventDescriptor<any>>;
     ownEvents: Array<EventDescriptor<any>>;
+    private _candidateCache?;
     constructor(
     /** The raw config used to create the machine. */
-    config: AnyStateNodeConfig, options: StateNodeOptions<TContext, TEvent>);
-    get initial(): InitialTransitionDefinition;
+    config: AnyStateNodeConfig, options: StateNodeOptions<TStateMeta, TTransitionMeta>);
+    get initial(): InitialTransitionDefinition<TTransitionMeta>;
 }
 export {};

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

@@ -1,14 +1,19 @@
-import { AnyActor, AnyActorScope, EventObject } from "./types.js";
+import { type ActorTermination, AnyActor, AnyActorScope, EventObject, TimerKey } from "./types.js";
+export declare function assertSendToEvent(event: EventObject): void;
 export declare const builtInActions: {
-    "@xstate.start": (actor: AnyActor) => void;
+    "@xstate.spawn": (actor: AnyActor) => any;
+    "@xstate.start": (actor: AnyActor) => any;
     "@xstate.raise": (actorScope: AnyActorScope, event: EventObject, options: {
         id?: string;
+        seq?: number;
         delay?: number;
-    }) => void;
+    }) => void | PromiseLike<void>;
     "@xstate.sendTo": (actorScope: AnyActorScope, actor: AnyActor, event: EventObject, options: {
         id?: string;
+        seq?: number;
         delay?: number;
-    }) => void;
-    "@xstate.cancel": (actorScope: AnyActorScope, sendId: string) => void;
-    "@xstate.stop": (actorScope: AnyActorScope, actor: AnyActor) => void;
+    }) => void | PromiseLike<void>;
+    "@xstate.cancel": (actorScope: AnyActorScope, key: TimerKey) => void | PromiseLike<void>;
+    "@xstate.stop": (actorScope: AnyActorScope, actor: AnyActor) => void | PromiseLike<void>;
+    "@xstate.terminate": (actor: AnyActor, termination: ActorTermination) => any;
 };

package/dist/declarations/src/actors/callback.d.ts

@@ -1,6 +1,9 @@
 import { AnyActorSystem } from "../system.js";
-import { ActorLogic, ActorRefFromLogic, AnyEventObject, EventObject, NonReducibleUnknown, Snapshot } from "../types.js";
+import { ActorLogic, ActorRefFrom, AnyEventObject, EventObject, Snapshot } from "../types.js";
+import type { NonReducibleUnknown } from "../typeUtils.js";
 import { StandardSchemaV1 } from "../schema.types.js";
+import type { ActorLogicValidator } from "../validation.types.js";
+/** @public */
 export type CallbackSnapshot<TInput> = Snapshot<undefined> & {
     input: TInput;
     effects?: Record<string, {
@@ -13,6 +16,7 @@ export type CallbackSnapshot<TInput> = Snapshot<undefined> & {
         error: unknown;
     }>;
 };
+/** @public */
 export type CallbackActorLogic<TEvent extends EventObject, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject> = ActorLogic<CallbackSnapshot<TInput>, TEvent, TInput, AnyActorSystem, TEmitted>;
 /**
  * Represents an actor created by `createCallbackLogic`.
@@ -49,11 +53,13 @@ export type CallbackActorLogic<TEvent extends EventObject, TInput = NonReducible
  * ```
  *
  * @see {@link createCallbackLogic}
+ * @public
  */
-export type CallbackActorRef<TEvent extends EventObject, TInput = NonReducibleUnknown> = ActorRefFromLogic<CallbackActorLogic<TEvent, TInput>>;
+export type CallbackActorRef<TEvent extends EventObject, TInput = NonReducibleUnknown> = ActorRefFrom<CallbackActorLogic<TEvent, TInput>>;
 type Receiver<TEvent extends EventObject> = (listener: {
     bivarianceHack(event: TEvent): void;
 }['bivarianceHack']) => void;
+/** @public */
 export type CallbackLogicFunction<TEvent extends EventObject = AnyEventObject, TSentEvent extends EventObject = AnyEventObject, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject> = ({ input, system, self, sendBack, receive, emit }: {
     /**
      * Data that was provided to the callback actor
@@ -74,7 +80,9 @@ export type CallbackLogicFunction<TEvent extends EventObject = AnyEventObject, T
     receive: Receiver<TEvent>;
     emit: (emitted: TEmitted) => void;
 }) => (() => void) | void;
+/** @public */
 export interface CallbackLogicConfig<TEvent extends EventObject = AnyEventObject, TSentEvent extends EventObject = AnyEventObject, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject, TInputSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    validator?: ActorLogicValidator;
     schemas?: {
         input?: TInputSchema;
     };
@@ -145,6 +153,7 @@ export interface CallbackLogicConfig<TEvent extends EventObject = AnyEventObject
  * @returns Callback logic
  * @see {@link CallbackLogicFunction} for more information about the callback function and its object argument
  * @see {@link https://stately.ai/docs/input | Input docs} for more information about how input is passed
+ * @public
  */
 export declare function createCallbackLogic<TEvent extends EventObject, const TInputSchema extends StandardSchemaV1, TEmitted extends EventObject = EventObject>(config: CallbackLogicConfig<TEvent, AnyEventObject, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, TInputSchema> & {
     schemas: {

package/dist/declarations/src/actors/index.d.ts

@@ -1,9 +1,10 @@
 import type { ActorFromLogic } from "../types.js";
 export { createCallbackLogic, type CallbackActorLogic, type CallbackActorRef, type CallbackLogicConfig, type CallbackSnapshot, type CallbackLogicFunction } from "./callback.js";
 export { createObservableLogic, createEventObservableLogic, type EventObservableLogicConfig, type EventObservableLogicFunction, type ObservableActorLogic, type ObservableActorRef, type ObservableLogicConfig, type ObservableLogicFunction, type ObservableSnapshot } from "./observable.js";
-export { createLogic, type LogicActorLogic, type LogicActorRef, type LogicArgs, type LogicConfig, type LogicEffect, type LogicEffectState, type LogicEnqueue, type LogicFunction, type LogicPatch, type LogicSnapshot } from "./logic.js";
-export { createAsyncLogic, type AsyncActorLogic, type AsyncActorRef, type AsyncSnapshot, type LogicArgs as AsyncLogicArgs, type LogicConfig as AsyncLogicConfig, type LogicEnqueue as AsyncLogicEnqueue, type LogicFunction as AsyncLogicFunction, TimeoutError } from "./promise.js";
-export { createListenerLogic, listenerLogic, type ListenerActorLogic, type ListenerActorRef, type ListenerSnapshot, type ListenerInput } from "./listener.js";
-export { createSubscriptionLogic, subscriptionLogic, type SubscriptionActorLogic, type SubscriptionActorRef, type SubscriptionSnapshot, type SubscriptionInput, type SubscriptionMappers } from "./subscription.js";
-declare const emptyLogic: import("./logic.js").LogicActorLogic<undefined, undefined, import("../types.js").EventObject, import("../types.js").NonReducibleUnknown, import("../types.js").EventObject>;
+export { createStepLogic, type StepActorLogic, type StepActorRef, type StepLogicArgs, type StepLogicConfig, type StepEffectState, type StepLogicEnqueue, type StepLogicFunction, type StepPatch, type StepSnapshot } from "./logic.js";
+export { createAsyncLogic, type AsyncActorLogic, type AsyncActorRef, type AsyncSnapshot, type AsyncLogicArgs, type AsyncLogicConfig, type AsyncLogicEnqueue, type AsyncLogicFunction, TimeoutError } from "./promise.js";
+export { createListenerLogic, type ListenerActorLogic, type ListenerActorRef, type ListenerSnapshot, type ListenerInput } from "./listener.js";
+export { createSubscriptionLogic, type SubscriptionActorLogic, type SubscriptionActorRef, type SubscriptionSnapshot, type SubscriptionInput, type SubscriptionMappers } from "./subscription.js";
+declare const emptyLogic: import("./logic.js").StepActorLogic<undefined, undefined, import("../base.types.js").EventObject, import("../typeUtils.js").NonReducibleUnknown, import("../base.types.js").EventObject>;
+/** @public */
 export declare function createEmptyActor(): ActorFromLogic<typeof emptyLogic>;

package/dist/declarations/src/actors/listener.d.ts

@@ -1,18 +1,23 @@
 import { AnyActorSystem } from "../system.js";
-import { ActorLogic, ActorRefFromLogic, AnyActor, EventObject, Snapshot } from "../types.js";
+import { ActorLogic, ActorRefFrom, AnyActor, EventObject, Snapshot } from "../types.js";
+/** @public */
 export type ListenerSnapshot = Snapshot<undefined> & {
     input: ListenerInput<any, any>;
 };
+/** @public */
 export interface ListenerInput<TEmitted extends EventObject, TMappedEvent extends EventObject> {
     actor: AnyActor;
     eventType: string;
     mapper: (event: TEmitted) => TMappedEvent;
 }
+/** @public */
 export type ListenerActorLogic<TEmitted extends EventObject = EventObject, TMappedEvent extends EventObject = EventObject> = ActorLogic<ListenerSnapshot, EventObject, ListenerInput<TEmitted, TMappedEvent>, AnyActorSystem, EventObject>;
-export type ListenerActorRef<TEmitted extends EventObject = EventObject, TMappedEvent extends EventObject = EventObject> = ActorRefFromLogic<ListenerActorLogic<TEmitted, TMappedEvent>>;
+/** @public */
+export type ListenerActorRef<TEmitted extends EventObject = EventObject, TMappedEvent extends EventObject = EventObject> = ActorRefFrom<ListenerActorLogic<TEmitted, TMappedEvent>>;
 /**
  * Creates actor logic for listening to emitted events from another actor. Used
  * internally by `enq.listen()`.
+ *
+ * @public
  */
 export declare function createListenerLogic<TEmitted extends EventObject = EventObject, TMappedEvent extends EventObject = EventObject>(): ListenerActorLogic<TEmitted, TMappedEvent>;
-export declare const listenerLogic: ListenerActorLogic<EventObject, EventObject>;