xstate 5.14.0 → 5.16.0

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

@@ -4,6 +4,40 @@ export type CallbackSnapshot<TInput> = Snapshot<undefined> & {
     input: TInput;
 };
 export type CallbackActorLogic<TEvent extends EventObject, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject> = ActorLogic<CallbackSnapshot<TInput>, TEvent, TInput, AnyActorSystem, TEmitted>;
+/**
+ * Represents an actor created by `fromCallback`.
+ *
+ * The type of `self` within the actor's logic.
+ *
+ * @example
+ *
+ * ```ts
+ * import { fromCallback, createActor } from 'xstate';
+ *
+ * // The events the actor receives.
+ * type Event = { type: 'someEvent' };
+ * // The actor's input.
+ * type Input = { name: string };
+ *
+ * // Actor logic that logs whenever it receives an event of type `someEvent`.
+ * const logic = fromCallback<Event, Input>(({ self, input, receive }) => {
+ *   self;
+ *   // ^? CallbackActorRef<Event, Input>
+ *
+ *   receive((event) => {
+ *     if (event.type === 'someEvent') {
+ *       console.log(`${input.name}: received "someEvent" event`);
+ *       // logs 'myActor: received "someEvent" event'
+ *     }
+ *   });
+ * });
+ *
+ * const actor = createActor(logic, { input: { name: 'myActor' } });
+ * //    ^? CallbackActorRef<Event, Input>
+ * ```
+ *
+ * @see {@link fromCallback}
+ */
 export type CallbackActorRef<TEvent extends EventObject, TInput = NonReducibleUnknown> = ActorRefFrom<CallbackActorLogic<TEvent, TInput>>;
 export type Receiver<TEvent extends EventObject> = (listener: {
     bivarianceHack(event: TEvent): void;
@@ -11,58 +45,45 @@ export type Receiver<TEvent extends EventObject> = (listener: {
 export type InvokeCallback<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
+     *
      * @see {@link https://stately.ai/docs/input | Input docs}
      */
     input: TInput;
-    /**
-     * The actor system to which the callback actor belongs
-     */
+    /** The actor system to which the callback actor belongs */
     system: AnyActorSystem;
-    /**
-     * The parent actor of the callback actor
-     */
+    /** The parent actor of the callback actor */
     self: CallbackActorRef<TEvent>;
-    /**
-     * A function that can send events back to the parent actor
-     */
+    /** A function that can send events back to the parent actor */
     sendBack: (event: TSentEvent) => void;
     /**
-     * A function that can be called with a listener function argument;
-     * the listener is then called whenever events are received by the callback actor
+     * A function that can be called with a listener function argument; the
+     * listener is then called whenever events are received by the callback actor
      */
     receive: Receiver<TEvent>;
     emit: (emitted: TEmitted) => void;
 }) => (() => void) | void;
 /**
- * An actor logic creator which returns callback logic as defined by a callback function.
+ * An actor logic creator which returns callback logic as defined by a callback
+ * function.
  *
  * @remarks
- * Useful for subscription-based or other free-form logic that can send events back to the parent actor.
+ * Useful for subscription-based or other free-form logic that can send events
+ * back to the parent actor.
  *
  * Actors created from callback logic (“callback actors”) can:
+ *
  * - Receive events via the `receive` function
  * - Send events to the parent actor via the `sendBack` function
  *
  * Callback actors are a bit different from other actors in that they:
+ *
  * - Do not work with `onDone`
  * - Do not produce a snapshot using `.getSnapshot()`
  * - Do not emit values when used with `.subscribe()`
  * - Can not be stopped with `.stop()`
  *
- * @param invokeCallback - The callback function used to describe the callback logic
- * The callback function is passed an object with the following properties:
- * - `receive` - A function that can send events back to the parent actor; the listener is then called whenever events are received by the callback actor
- * - `sendBack` - A function that can send events back to the parent actor
- * - `input` - Data that was provided to the callback actor
- * - `self` - The parent actor of the callback actor
- * - `system` - The actor system to which the callback actor belongs
- * The callback function can (optionally) return a cleanup function, which is called when the actor is stopped.
- * @see {@link InvokeCallback} 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
-
- * @returns Callback logic
- *
  * @example
+ *
  * ```typescript
  * const callbackLogic = fromCallback(({ sendBack, receive }) => {
  *   let lockStatus = 'unlocked';
@@ -89,5 +110,23 @@ export type InvokeCallback<TEvent extends EventObject = AnyEventObject, TSentEve
  *   };
  * });
  * ```
+ *
+ * @param invokeCallback - The callback function used to describe the callback
+ *   logic The callback function is passed an object with the following
+ *   properties:
+ *
+ *   - `receive` - A function that can send events back to the parent actor; the
+ *       listener is then called whenever events are received by the callback
+ *       actor
+ *   - `sendBack` - A function that can send events back to the parent actor
+ *   - `input` - Data that was provided to the callback actor
+ *   - `self` - The parent actor of the callback actor
+ *   - `system` - The actor system to which the callback actor belongs The callback
+ *       function can (optionally) return a cleanup function, which is called
+ *       when the actor is stopped.
+ *
+ * @returns Callback logic
+ * @see {@link InvokeCallback} 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
  */
 export declare function fromCallback<TEvent extends EventObject, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject>(invokeCallback: InvokeCallback<TEvent, AnyEventObject, TInput, TEmitted>): CallbackActorLogic<TEvent, TInput, TEmitted>;

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

@@ -1,6 +1,6 @@
 import type { ActorRef, AnyEventObject, Snapshot } from "../types.js";
-export { fromCallback, type CallbackActorLogic, type CallbackSnapshot } from "./callback.js";
-export { fromEventObservable, fromObservable, type ObservableActorLogic, type ObservableSnapshot } from "./observable.js";
-export { fromPromise, type PromiseActorLogic, type PromiseSnapshot } from "./promise.js";
-export { fromTransition, type TransitionActorLogic, type TransitionSnapshot } from "./transition.js";
+export { fromCallback, type CallbackActorLogic, type CallbackActorRef, type CallbackSnapshot } from "./callback.js";
+export { fromEventObservable, fromObservable, type ObservableActorLogic, type ObservableActorRef, type ObservableSnapshot } from "./observable.js";
+export { fromPromise, type PromiseActorLogic, type PromiseActorRef, type PromiseSnapshot } from "./promise.js";
+export { fromTransition, type TransitionActorLogic, type TransitionActorRef, type TransitionSnapshot } from "./transition.js";
 export declare function createEmptyActor(): ActorRef<Snapshot<undefined>, AnyEventObject, AnyEventObject>;

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

@@ -9,9 +9,42 @@ export type ObservableActorLogic<TContext, TInput extends NonReducibleUnknown, T
     type: string;
     [k: string]: unknown;
 }, TInput, AnyActorSystem, TEmitted>;
+/**
+ * Represents an actor created by `fromObservable` or `fromEventObservable`.
+ *
+ * The type of `self` within the actor's logic.
+ *
+ * @example
+ *
+ * ```ts
+ * import { fromObservable, createActor } from 'xstate';
+ * import { interval } from 'rxjs';
+ *
+ * // The type of the value observed by the actor's logic.
+ * type Context = number;
+ * // The actor's input.
+ * type Input = { period?: number };
+ *
+ * // Actor logic that observes a number incremented every `input.period`
+ * // milliseconds (default: 1_000).
+ * const logic = fromObservable<Context, Input>(({ input, self }) => {
+ *   self;
+ *   // ^? ObservableActorRef<Event, Input>
+ *
+ *   return interval(input.period ?? 1_000);
+ * });
+ *
+ * const actor = createActor(logic, { input: { period: 2_000 } });
+ * //    ^? ObservableActorRef<Event, Input>
+ * ```
+ *
+ * @see {@link fromObservable}
+ * @see {@link fromEventObservable}
+ */
 export type ObservableActorRef<TContext> = ActorRefFrom<ObservableActorLogic<TContext, any>>;
 /**
- * Observable actor logic is described by an observable stream of values. Actors created from observable logic (“observable actors”) can:
+ * Observable actor logic is described by an observable stream of values. Actors
+ * created from observable logic (“observable actors”) can:
  *
  * - Emit snapshots of the observable’s emitted value
  *
@@ -19,16 +52,10 @@ export type ObservableActorRef<TContext> = ActorRefFrom<ObservableActorLogic<TCo
  *
  * Sending events to observable actors will have no effect.
  *
- * @param observableCreator A function that creates an observable. It receives one argument, an object with the following properties:
- * - `input` - Data that was provided to the observable actor
- * - `self` - The parent actor
- * - `system` - The actor system to which the observable actor belongs
- *
- * It should return a {@link Subscribable}, which is compatible with an RxJS Observable, although RxJS is not required to create them.
- *
  * @example
+ *
  * ```ts
- * import { fromObservable, createActor } from 'xstate'
+ * import { fromObservable, createActor } from 'xstate';
  * import { interval } from 'rxjs';
  *
  * const logic = fromObservable((obj) => interval(1000));
@@ -47,6 +74,15 @@ export type ObservableActorRef<TContext> = ActorRefFrom<ObservableActorLogic<TCo
  * // ...
  * ```
  *
+ * @param observableCreator A function that creates an observable. It receives
+ *   one argument, an object with the following properties:
+ *
+ *   - `input` - Data that was provided to the observable actor
+ *   - `self` - The parent actor
+ *   - `system` - The actor system to which the observable actor belongs
+ *
+ *   It should return a {@link Subscribable}, which is compatible with an RxJS
+ *   Observable, although RxJS is not required to create them.
  * @see {@link https://rxjs.dev} for documentation on RxJS Observable and observable creators.
  * @see {@link Subscribable} interface in XState, which is based on and compatible with RxJS Observable.
  */
@@ -57,24 +93,20 @@ export declare function fromObservable<TContext, TInput extends NonReducibleUnkn
     emit: (emitted: TEmitted) => void;
 }) => Subscribable<TContext>): ObservableActorLogic<TContext, TInput, TEmitted>;
 /**
- * Creates event observable logic that listens to an observable that delivers event objects.
+ * Creates event observable logic that listens to an observable that delivers
+ * event objects.
  *
- * Event observable actor logic is described by an observable stream of {@link https://stately.ai/docs/transitions#event-objects | event objects}. Actors created from event observable logic (“event observable actors”) can:
+ * Event observable actor logic is described by an observable stream of
+ * {@link https://stately.ai/docs/transitions#event-objects | event objects}.
+ * Actors created from event observable logic (“event observable actors”) can:
  *
  * - Implicitly send events to its parent actor
  * - Emit snapshots of its emitted event objects
  *
  * Sending events to event observable actors will have no effect.
  *
- * @param lazyObservable A function that creates an observable that delivers event objects. It receives one argument, an object with the following properties:
- *
- * - `input` - Data that was provided to the event observable actor
- * - `self` - The parent actor
- * - `system` - The actor system to which the event observable actor belongs.
- *
- * It should return a {@link Subscribable}, which is compatible with an RxJS Observable, although RxJS is not required to create them.
- *
  * @example
+ *
  * ```ts
  * import {
  *   fromEventObservable,
@@ -85,20 +117,31 @@ export declare function fromObservable<TContext, TInput extends NonReducibleUnkn
  * } from 'xstate';
  * import { fromEvent } from 'rxjs';
  *
- * const mouseClickLogic = fromEventObservable(() =>
- *   fromEvent(document.body, 'click') as Subscribable<EventObject>
+ * const mouseClickLogic = fromEventObservable(
+ *   () => fromEvent(document.body, 'click') as Subscribable<EventObject>
  * );
  *
  * const canvasMachine = createMachine({
  *   invoke: {
  *     // Will send mouse `click` events to the canvas actor
- *     src: mouseClickLogic,
+ *     src: mouseClickLogic
  *   }
  * });
  *
  * const canvasActor = createActor(canvasMachine);
  * canvasActor.start();
  * ```
+ *
+ * @param lazyObservable A function that creates an observable that delivers
+ *   event objects. It receives one argument, an object with the following
+ *   properties:
+ *
+ *   - `input` - Data that was provided to the event observable actor
+ *   - `self` - The parent actor
+ *   - `system` - The actor system to which the event observable actor belongs.
+ *
+ *   It should return a {@link Subscribable}, which is compatible with an RxJS
+ *   Observable, although RxJS is not required to create them.
  */
 export declare function fromEventObservable<TEvent extends EventObject, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(lazyObservable: ({ input, system, self, emit }: {
     input: TInput;

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

@@ -8,19 +8,96 @@ export type PromiseActorLogic<TOutput, TInput = unknown, TEmitted extends EventO
     [k: string]: unknown;
 }, TInput, // input
 AnyActorSystem, TEmitted>;
+/**
+ * Represents an actor created by `fromPromise`.
+ *
+ * The type of `self` within the actor's logic.
+ *
+ * @example
+ *
+ * ```ts
+ * import { fromPromise, createActor } from 'xstate';
+ *
+ * // The actor's resolved output
+ * type Output = string;
+ * // The actor's input.
+ * type Input = { message: string };
+ *
+ * // Actor logic that fetches the url of an image of a cat saying `input.message`.
+ * const logic = fromPromise<Output, Input>(async ({ input, self }) => {
+ *   self;
+ *   // ^? PromiseActorRef<Output, Input>
+ *
+ *   const data = await fetch(
+ *     `https://cataas.com/cat/says/${input.message}`
+ *   );
+ *   const url = await data.json();
+ *   return url;
+ * });
+ *
+ * const actor = createActor(logic, { input: { message: 'hello world' } });
+ * //    ^? PromiseActorRef<Output, Input>
+ * ```
+ *
+ * @see {@link fromPromise}
+ */
 export type PromiseActorRef<TOutput> = ActorRefFrom<PromiseActorLogic<TOutput, unknown>>;
+/**
+ * An actor logic creator which returns promise logic as defined by an async
+ * process that resolves or rejects after some time.
+ *
+ * Actors created from promise actor logic (“promise actors”) can:
+ *
+ * - Emit the resolved value of the promise
+ * - Output the resolved value of the promise
+ *
+ * Sending events to promise actors will have no effect.
+ *
+ * @example
+ *
+ * ```ts
+ * const promiseLogic = fromPromise(async () => {
+ *   const result = await fetch('https://example.com/...').then((data) =>
+ *     data.json()
+ *   );
+ *
+ *   return result;
+ * });
+ *
+ * const promiseActor = createActor(promiseLogic);
+ * promiseActor.subscribe((snapshot) => {
+ *   console.log(snapshot);
+ * });
+ * promiseActor.start();
+ * // => {
+ * //   output: undefined,
+ * //   status: 'active'
+ * //   ...
+ * // }
+ *
+ * // After promise resolves
+ * // => {
+ * //   output: { ... },
+ * //   status: 'done',
+ * //   ...
+ * // }
+ * ```
+ *
+ * @param promiseCreator A function which returns a Promise, and accepts an
+ *   object with the following properties:
+ *
+ *   - `input` - Data that was provided to the promise actor
+ *   - `self` - The parent actor of the promise actor
+ *   - `system` - The actor system to which the promise actor belongs
+ *
+ * @see {@link https://stately.ai/docs/input | Input docs} for more information about how input is passed
+ */
 export declare function fromPromise<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject>(promiseCreator: ({ input, system, self, signal, emit }: {
-    /**
-     * Data that was provided to the promise actor
-     */
+    /** Data that was provided to the promise actor */
     input: TInput;
-    /**
-     * The actor system to which the promise actor belongs
-     */
+    /** The actor system to which the promise actor belongs */
     system: AnyActorSystem;
-    /**
-     * The parent actor of the promise actor
-     */
+    /** The parent actor of the promise actor */
     self: PromiseActorRef<TOutput>;
     signal: AbortSignal;
     emit: (emitted: TEmitted) => void;

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

@@ -4,44 +4,98 @@ export type TransitionSnapshot<TContext> = Snapshot<undefined> & {
     context: TContext;
 };
 export type TransitionActorLogic<TContext, TEvent extends EventObject, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject> = ActorLogic<TransitionSnapshot<TContext>, TEvent, TInput, AnyActorSystem, TEmitted>;
+/**
+ * Represents an actor created by `fromTransition`.
+ *
+ * The type of `self` within the actor's logic.
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   fromTransition,
+ *   createActor,
+ *   type AnyActorSystem
+ * } from 'xstate';
+ *
+ * //* The actor's stored context.
+ * type Context = {
+ *   // The current count.
+ *   count: number;
+ *   // The amount to increase `count` by.
+ *   step: number;
+ * };
+ * // The events the actor receives.
+ * type Event = { type: 'increment' };
+ * // The actor's input.
+ * type Input = { step?: number };
+ *
+ * // Actor logic that increments `count` by `step` when it receives an event of
+ * // type `increment`.
+ * const logic = fromTransition<Context, Event, AnyActorSystem, Input>(
+ *   (state, event, actorScope) => {
+ *     actorScope.self;
+ *     //         ^? TransitionActorRef<Context, Event>
+ *
+ *     if (event.type === 'increment') {
+ *       return {
+ *         ...state,
+ *         count: state.count + state.step
+ *       };
+ *     }
+ *     return state;
+ *   },
+ *   ({ input, self }) => {
+ *     self;
+ *     // ^? TransitionActorRef<Context, Event>
+ *
+ *     return {
+ *       count: 0,
+ *       step: input.step ?? 1
+ *     };
+ *   }
+ * );
+ *
+ * const actor = createActor(logic, { input: { step: 10 } });
+ * //    ^? TransitionActorRef<Context, Event>
+ * ```
+ *
+ * @see {@link fromTransition}
+ */
 export type TransitionActorRef<TContext, TEvent extends EventObject> = ActorRefFrom<TransitionActorLogic<TransitionSnapshot<TContext>, TEvent, unknown>>;
 /**
  * Returns actor logic given a transition function and its initial state.
  *
- * A “transition function” is a function that takes the current `state` and received `event` object as arguments, and returns the next state, similar to a reducer.
+ * A “transition function” is a function that takes the current `state` and
+ * received `event` object as arguments, and returns the next state, similar to
+ * a reducer.
  *
  * Actors created from transition logic (“transition actors”) can:
  *
  * - Receive events
  * - Emit snapshots of its state
  *
- * The transition function’s `state` is used as its transition actor’s `context`.
- *
- * Note that the "state" for a transition function is provided by the initial state argument, and is not the same as the State object of an actor or a state within a machine configuration.
+ * The transition function’s `state` is used as its transition actor’s
+ * `context`.
  *
- * @param transition The transition function used to describe the transition logic. It should return the next state given the current state and event. It receives the following arguments:
- * - `state` - the current state.
- * - `event` - the received event.
- * - `actorScope` - the actor scope object, with properties like `self` and `system`.
- * @param initialContext The initial state of the transition function, either an object representing the state, or a function which returns a state object. If a function, it will receive as its only argument an object with the following properties:
- * - `input` - the `input` provided to its parent transition actor.
- * - `self` - a reference to its parent transition actor.
- * @see {@link https://stately.ai/docs/input | Input docs} for more information about how input is passed
- * @returns Actor logic
+ * Note that the "state" for a transition function is provided by the initial
+ * state argument, and is not the same as the State object of an actor or a
+ * state within a machine configuration.
  *
  * @example
+ *
  * ```ts
  * const transitionLogic = fromTransition(
  *   (state, event) => {
  *     if (event.type === 'increment') {
  *       return {
  *         ...state,
- *         count: state.count + 1,
+ *         count: state.count + 1
  *       };
  *     }
  *     return state;
  *   },
- *   { count: 0 },
+ *   { count: 0 }
  * );
  *
  * const transitionActor = createActor(transitionLogic);
@@ -62,6 +116,26 @@ export type TransitionActorRef<TContext, TEvent extends EventObject> = ActorRefF
  * //   ...
  * // }
  * ```
+ *
+ * @param transition The transition function used to describe the transition
+ *   logic. It should return the next state given the current state and event.
+ *   It receives the following arguments:
+ *
+ *   - `state` - the current state.
+ *   - `event` - the received event.
+ *   - `actorScope` - the actor scope object, with properties like `self` and
+ *       `system`.
+ *
+ * @param initialContext The initial state of the transition function, either an
+ *   object representing the state, or a function which returns a state object.
+ *   If a function, it will receive as its only argument an object with the
+ *   following properties:
+ *
+ *   - `input` - the `input` provided to its parent transition actor.
+ *   - `self` - a reference to its parent transition actor.
+ *
+ * @returns Actor logic
+ * @see {@link https://stately.ai/docs/input | Input docs} for more information about how input is passed
  */
 export declare function fromTransition<TContext, TEvent extends EventObject, TSystem extends AnyActorSystem, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(transition: (snapshot: TContext, event: TEvent, actorScope: ActorScope<TransitionSnapshot<TContext>, TEvent, TSystem, TEmitted>) => TContext, initialContext: TContext | (({ input, self }: {
     input: TInput;

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

@@ -1,25 +1,26 @@
 import { EventObject } from "./types.js";
 /**
- * Asserts that the given event object is of the specified type or types.
- * Throws an error if the event object is not of the specified types.
-  @example
-
-  ```ts
-  // ...
-  entry: ({ event }) => {
-    assertEvent(event, 'doNothing');
-    // event is { type: 'doNothing' }
-  },
-  // ...
-  exit: ({ event }) => {
-    assertEvent(event, 'greet');
-    // event is { type: 'greet'; message: string }
-
-    assertEvent(event, ['greet', 'notify']);
-    // event is { type: 'greet'; message: string }
-    // or { type: 'notify'; message: string; level: 'info' | 'error' }
-  },
-  ```
+ * Asserts that the given event object is of the specified type or types. Throws
+ * an error if the event object is not of the specified types.
+ *
+ * @example
+ *
+ * ```ts
+ * // ...
+ * entry: ({ event }) => {
+ *   assertEvent(event, 'doNothing');
+ *   // event is { type: 'doNothing' }
+ * },
+ * // ...
+ * exit: ({ event }) => {
+ *   assertEvent(event, 'greet');
+ *   // event is { type: 'greet'; message: string }
+ *
+ *   assertEvent(event, ['greet', 'notify']);
+ *   // event is { type: 'greet'; message: string }
+ *   // or { type: 'notify'; message: string; level: 'info' | 'error' }
+ * },
+ * ```
  */
 export declare function assertEvent<TEvent extends EventObject, TAssertedType extends TEvent['type']>(event: TEvent, type: TAssertedType | TAssertedType[]): asserts event is TEvent & {
     type: TAssertedType;