xstate 5.0.0-beta.42 → 5.0.0-beta.44

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

@@ -1,6 +1,6 @@
 import { MachineSnapshot } from "./State.js";
 import type { StateNode } from "./StateNode.js";
-import { AnyEventObject, AnyHistoryValue, AnyState, AnyStateNode, AnyTransitionDefinition, DelayedTransitionDefinition, EventObject, InitialTransitionConfig, InitialTransitionDefinition, MachineContext, StateValue, StateValueMap, TransitionDefinition, TODO, UnknownAction, AnyTransitionConfig, AnyActorScope } from "./types.js";
+import { AnyEventObject, AnyHistoryValue, AnyMachineSnapshot, AnyStateNode, AnyTransitionDefinition, DelayedTransitionDefinition, EventObject, InitialTransitionConfig, InitialTransitionDefinition, MachineContext, StateValue, StateValueMap, TransitionDefinition, TODO, UnknownAction, AnyTransitionConfig, AnyActorScope } from "./types.js";
 type Configuration<TContext extends MachineContext, TE extends EventObject> = Iterable<StateNode<TContext, TE>>;
 type AnyConfiguration = Configuration<any, any>;
 type AdjList = Map<AnyStateNode, Array<AnyStateNode>>;
@@ -45,9 +45,9 @@ export declare function removeConflictingTransitions(enabledTransitions: Array<A
 /**
  * https://www.w3.org/TR/scxml/#microstepProcedure
  */
-export declare function microstep<TContext extends MachineContext, TEvent extends EventObject>(transitions: Array<AnyTransitionDefinition>, currentState: AnyState, actorScope: AnyActorScope, event: AnyEventObject, isInitial: boolean, internalQueue: Array<AnyEventObject>): AnyState;
-export declare function resolveActionsAndContext(currentState: AnyState, event: AnyEventObject, actorScope: AnyActorScope, actions: UnknownAction[], internalQueue: AnyEventObject[], deferredActorIds?: string[]): AnyState;
-export declare function macrostep(state: AnyState, event: EventObject, actorScope: AnyActorScope, internalQueue?: AnyEventObject[]): {
+export declare function microstep<TContext extends MachineContext, TEvent extends EventObject>(transitions: Array<AnyTransitionDefinition>, currentState: AnyMachineSnapshot, actorScope: AnyActorScope, event: AnyEventObject, isInitial: boolean, internalQueue: Array<AnyEventObject>): AnyMachineSnapshot;
+export declare function resolveActionsAndContext(currentState: AnyMachineSnapshot, event: AnyEventObject, actorScope: AnyActorScope, actions: UnknownAction[], internalQueue: AnyEventObject[], deferredActorIds?: string[]): AnyMachineSnapshot;
+export declare function macrostep(state: AnyMachineSnapshot, event: EventObject, actorScope: AnyActorScope, internalQueue?: AnyEventObject[]): {
     state: typeof state;
     microstates: Array<typeof state>;
 };

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

@@ -33,6 +33,7 @@ export type NonReducibleUnknown = {} | null | undefined;
 export type AnyFunction = (...args: any[]) => any;
 type ReturnTypeOrValue<T> = T extends AnyFunction ? ReturnType<T> : T;
 export type IsNever<T> = [T] extends [never] ? true : false;
+export type IsNotNever<T> = [T] extends [never] ? false : true;
 export type Compute<A extends any> = {
     [K in keyof A]: A[K];
 } & unknown;
@@ -97,7 +98,7 @@ export interface ChooseBranch<TContext extends MachineContext, TExpressionEvent
 export type NoRequiredParams<T extends ParameterizedObject> = T extends any ? {
     type: T['type'];
 } extends T ? T['type'] : never : never;
-type ConditionalRequired<T, Condition extends boolean> = Condition extends true ? Required<T> : T;
+export type ConditionalRequired<T, Condition extends boolean> = Condition extends true ? Required<T> : T;
 export type WithDynamicParams<TContext extends MachineContext, TExpressionEvent extends EventObject, T extends ParameterizedObject> = T extends any ? ConditionalRequired<{
     type: T['type'];
     params?: T['params'] | (({ context, event }: {
@@ -108,7 +109,7 @@ export type WithDynamicParams<TContext extends MachineContext, TExpressionEvent
 export type Action<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject, TParams extends ParameterizedObject['params'] | undefined, TActor extends ProvidedActor, TAction extends ParameterizedObject, TGuard extends ParameterizedObject, TDelay extends string> = NoRequiredParams<TAction> | WithDynamicParams<TContext, TExpressionEvent, TAction> | ActionFunction<TContext, TExpressionEvent, TEvent, TParams, TActor, TAction, TGuard, TDelay>;
 export type UnknownAction = Action<MachineContext, EventObject, EventObject, ParameterizedObject['params'] | undefined, ProvidedActor, ParameterizedObject, ParameterizedObject, string>;
 export type Actions<TContext extends MachineContext, TExpressionEvent extends EventObject, TEvent extends EventObject, TParams extends ParameterizedObject['params'] | undefined, TActor extends ProvidedActor, TAction extends ParameterizedObject, TGuard extends ParameterizedObject, TDelay extends string> = SingleOrArray<Action<TContext, TExpressionEvent, TEvent, TParams, TActor, TAction, TGuard, TDelay>>;
-export type StateKey = string | AnyState;
+export type StateKey = string | AnyMachineSnapshot;
 export interface StateValueMap {
     [key: string]: StateValue;
 }
@@ -186,6 +187,11 @@ type DistributeActors<TContext extends MachineContext, TEvent extends EventObjec
      * The source of the machine to be invoked, or the machine itself.
      */
     src: TSrc;
+    /**
+     * The unique identifier for the invoked machine. If not specified, this
+     * will be the machine's own `id`, or the URL (from `src`).
+     */
+    id?: TSpecificActor['id'];
     input?: Mapper<TContext, TEvent, InputFrom<TSpecificActor['logic']>, TEvent> | InputFrom<TSpecificActor['logic']>;
     /**
      * The transition to take upon the invoked child machine reaching its final top-level state.
@@ -196,19 +202,9 @@ type DistributeActors<TContext extends MachineContext, TEvent extends EventObjec
      */
     onError?: string | SingleOrArray<TransitionConfigOrTarget<TContext, ErrorActorEvent, TEvent, TActor, TAction, TGuard, TDelay>>;
     onSnapshot?: string | SingleOrArray<TransitionConfigOrTarget<TContext, SnapshotEvent<SnapshotFrom<TSpecificActor['logic']>>, TEvent, TActor, TAction, TGuard, TDelay>>;
-} & (TSpecificActor['id'] extends string ? {
-    /**
-     * The unique identifier for the invoked machine. If not specified, this
-     * will be the machine's own `id`, or the URL (from `src`).
-     */
-    id: TSpecificActor['id'];
-} : {
-    /**
-     * The unique identifier for the invoked machine. If not specified, this
-     * will be the machine's own `id`, or the URL (from `src`).
-     */
-    id?: string;
-})> : never;
+} & {
+    [K in RequiredActorOptions<TSpecificActor>]: unknown;
+}> : never;
 export type InvokeConfig<TContext extends MachineContext, TEvent extends EventObject, TActor extends ProvidedActor, TAction extends ParameterizedObject, TGuard extends ParameterizedObject, TDelay extends string> = IsLiteralString<TActor['src']> extends true ? DistributeActors<TContext, TEvent, TActor, TAction, TGuard, TDelay, TActor> : {
     /**
      * The unique identifier for the invoked machine. If not specified, this
@@ -347,7 +343,9 @@ export interface StateMachineDefinition<TContext extends MachineContext, TEvent
 }
 export type AnyStateNode = StateNode<any, any>;
 export type AnyStateNodeDefinition = StateNodeDefinition<any, any>;
-export type AnyState = MachineSnapshot<any, any, any, any, any, any>;
+export type AnyMachineSnapshot = MachineSnapshot<any, any, any, any, any, any>;
+/** @deprecated use `AnyMachineSnapshot` instead */
+export type AnyState = AnyMachineSnapshot;
 export type AnyStateMachine = StateMachine<any, any, any, any, any, any, any, any, any, // delays
 any>;
 export type AnyStateConfig = StateConfig<any, AnyEventObject>;
@@ -387,11 +385,8 @@ type MaybeNarrowedEvent<TIndexedEvents, TCausingLookup, K> = Cast<Prop<TIndexedE
 type MachineImplementationsActions<TContext extends MachineContext, TResolvedTypesMeta, TEventsCausingActions = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'eventsCausingActions'>, TIndexedEvents = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedEvents'>, TIndexedActors = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedActors'>, TIndexedActions = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedActions'>, TIndexedGuards = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedGuards'>, TIndexedDelays = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedDelays'>> = {
     [K in keyof TIndexedActions]?: ActionFunction<TContext, MaybeNarrowedEvent<TIndexedEvents, TEventsCausingActions, K>, Cast<Prop<TIndexedEvents, keyof TIndexedEvents>, EventObject>, GetParameterizedParams<Cast<TIndexedActions[K], ParameterizedObject>>, Cast<Prop<TIndexedActors, keyof TIndexedActors>, ProvidedActor>, Cast<Prop<TIndexedActions, keyof TIndexedActions>, ParameterizedObject>, Cast<Prop<TIndexedGuards, keyof TIndexedGuards>, ParameterizedObject>, Cast<Prop<TIndexedDelays, keyof TIndexedDelays>, ParameterizedObject>['type']>;
 };
-type MachineImplementationsActors<TContext extends MachineContext, TResolvedTypesMeta, TEventsCausingActors = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'eventsCausingActors'>, TIndexedActors = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedActors'>, TIndexedEvents = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedEvents'>, _TInvokeSrcNameMap = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'invokeSrcNameMap'>> = {
-    [K in keyof TIndexedActors]?: Cast<Prop<TIndexedActors[K], 'logic'>, AnyActorLogic> | {
-        src: Cast<Prop<TIndexedActors[K], 'logic'>, AnyActorLogic>;
-        input: Mapper<TContext, MaybeNarrowedEvent<TIndexedEvents, TEventsCausingActors, K>, InputFrom<Cast<Prop<TIndexedActors[K], 'logic'>, AnyActorLogic>>, Cast<Prop<TIndexedEvents, keyof TIndexedEvents>, EventObject>> | InputFrom<Cast<Prop<TIndexedActors[K], 'logic'>, AnyActorLogic>>;
-    };
+type MachineImplementationsActors<_TContext extends MachineContext, TResolvedTypesMeta, TIndexedActors = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedActors'>, _TInvokeSrcNameMap = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'invokeSrcNameMap'>> = {
+    [K in keyof TIndexedActors]?: Cast<Prop<TIndexedActors[K], 'logic'>, AnyActorLogic>;
 };
 type MachineImplementationsDelays<TContext extends MachineContext, TResolvedTypesMeta, TEventsCausingDelays = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'eventsCausingDelays'>, TIndexedEvents = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedEvents'>, TIndexedActions = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedActions'>, TIndexedDelays = Prop<Prop<TResolvedTypesMeta, 'resolved'>, 'indexedDelays'>> = {
     [K in keyof TIndexedDelays]?: DelayConfig<TContext, MaybeNarrowedEvent<TIndexedEvents, TEventsCausingDelays, K>, Cast<Prop<Prop<TIndexedActions, keyof TIndexedActions>, 'params'>, ParameterizedObject['params'] | undefined> | undefined, Cast<Prop<TIndexedEvents, keyof TIndexedEvents>, EventObject>>;
@@ -777,14 +772,52 @@ export type Snapshot<TOutput> = {
     output: undefined;
     error: undefined;
 };
+/**
+ * Represents logic which can be used by an actor.
+ *
+ * @template TSnapshot - The type of the snapshot.
+ * @template TEvent - The type of the event object.
+ * @template TInput - The type of the input.
+ * @template TSystem - The type of the actor system.
+ */
 export interface ActorLogic<TSnapshot extends Snapshot<unknown>, TEvent extends EventObject, TInput = unknown, TSystem extends ActorSystem<any> = ActorSystem<any>> {
+    /** The initial setup/configuration used to create the actor logic. */
     config?: unknown;
+    /**
+     * Transition function that processes the current state and an incoming message
+     * to produce a new state.
+     * @param state - The current state.
+     * @param message - The incoming message.
+     * @param ctx - The actor scope.
+     * @returns The new state.
+     */
     transition: (state: TSnapshot, message: TEvent, ctx: ActorScope<TSnapshot, TEvent, TSystem>) => TSnapshot;
+    /**
+     * Called to provide the initial state of the actor.
+     * @param actorScope - The actor scope.
+     * @param input - The input for the initial state.
+     * @returns The initial state.
+     */
     getInitialState: (actorScope: ActorScope<TSnapshot, TEvent, TSystem>, input: TInput) => TSnapshot;
+    /**
+     * Called when Actor is created to restore the internal state of the actor given a persisted state.
+     * The persisted state can be created by `getPersistedState`.
+     * @param persistedState - The persisted state to restore from.
+     * @param actorScope - The actor scope.
+     * @returns The restored state.
+     */
     restoreState?: (persistedState: Snapshot<unknown>, actorScope: ActorScope<TSnapshot, TEvent>) => TSnapshot;
+    /**
+     * Called when the actor is started.
+     * @param state - The starting state.
+     * @param actorScope - The actor scope.
+     */
     start?: (state: TSnapshot, actorScope: ActorScope<TSnapshot, TEvent>) => void;
     /**
-     * @returns Persisted state
+     * Obtains the internal state of the actor in a representation which can be be persisted.
+     * The persisted state can be restored by `restoreState`.
+     * @param state - The current state.
+     * @returns The a representation of the internal state to be persisted.
      */
     getPersistedState: (state: TSnapshot, options?: unknown) => Snapshot<unknown>;
 }
@@ -815,4 +848,5 @@ export interface ActorSystem<T extends ActorSystemInfo> {
     inspect: (observer: Observer<InspectionEvent>) => void;
 }
 export type AnyActorSystem = ActorSystem<any>;
+export type RequiredActorOptions<TActor extends ProvidedActor> = ('id' extends keyof TActor ? 'id' : never) | (undefined extends InputFrom<TActor['logic']> ? never : 'input');
 export {};

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

@@ -1,11 +1,9 @@
-import { AnyActorLogic, AnyState } from "./index.js";
 import type { StateNode } from "./StateNode.js";
 import type { ActorLogic, AnyEventObject, EventObject, MachineContext, Mapper, Observer, ErrorActorEvent, SingleOrArray, StateLike, StateValue, Subscribable, TransitionConfigTarget, AnyActorRef, AnyTransitionConfig, NonReducibleUnknown, AnyStateMachine } from "./types.js";
 export declare function keys<T extends object>(value: T): Array<keyof T & string>;
 export declare function matchesState(parentStateId: StateValue, childStateId: StateValue): boolean;
 export declare function toStatePath(stateId: string | string[]): string[];
-export declare function isStateLike(state: any): state is AnyState;
-export declare function toStateValue(stateValue: StateLike<any> | StateValue | string[]): StateValue;
+export declare function toStateValue(stateValue: StateLike<any> | StateValue): StateValue;
 export declare function pathToStateValue(statePath: string[]): StateValue;
 export declare function mapValues<P, O extends Record<string, unknown>>(collection: O, iteratee: (item: O[keyof O], key: keyof O, collection: O, i: number) => P): {
     [key in keyof O]: P;
@@ -39,10 +37,4 @@ export declare function normalizeTarget<TContext extends MachineContext, TEvent
 export declare function reportUnhandledExceptionOnInvocation(originalError: any, currentError: any, id: string): void;
 export declare function toObserver<T>(nextHandler?: Observer<T> | ((value: T) => void), errorHandler?: (error: any) => void, completionHandler?: () => void): Observer<T>;
 export declare function createInvokeId(stateNodeId: string, index: number): string;
-export declare function resolveReferencedActor(machine: AnyStateMachine, src: string): {
-    src: AnyActorLogic;
-    input: NonReducibleUnknown | Mapper<any, any, unknown, any>;
-} | {
-    src: any;
-    input: undefined;
-} | undefined;
+export declare function resolveReferencedActor(machine: AnyStateMachine, src: string): any;