xstate 5.14.0 → 5.15.0

package/actors/dist/xstate-actors.esm.js

@@ -1,43 +1,98 @@
-import { X as XSTATE_STOP, A as createActor } from '../../dist/raise-4e39e875.esm.js';
+import { X as XSTATE_STOP, A as createActor } from '../../dist/raise-2cfe6b8f.esm.js';
 import '../../dev/dist/xstate-dev.esm.js';
 
+/**
+ * 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}
+ */
+
 /**
  * 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`.
+ * 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.
- *
- * @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);
@@ -58,6 +113,26 @@ import '../../dev/dist/xstate-dev.esm.js';
  * //   ...
  * // }
  * ```
+ *
+ * @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
  */
 function fromTransition(transition, initialContext) {
   return {
@@ -84,36 +159,64 @@ function fromTransition(transition, initialContext) {
 }
 
 const instanceStates = /* #__PURE__ */new WeakMap();
+
+/**
+ * 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}
+ */
+
 /**
- * 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';
@@ -140,6 +243,24 @@ const instanceStates = /* #__PURE__ */new WeakMap();
  *   };
  * });
  * ```
+ *
+ * @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
  */
 function fromCallback(invokeCallback) {
   const logic = {
@@ -205,8 +326,43 @@ function fromCallback(invokeCallback) {
 const XSTATE_OBSERVABLE_NEXT = 'xstate.observable.next';
 const XSTATE_OBSERVABLE_ERROR = 'xstate.observable.error';
 const XSTATE_OBSERVABLE_COMPLETE = 'xstate.observable.complete';
+
+/**
+ * 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}
+ */
+
 /**
- * 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
  *
@@ -214,16 +370,10 @@ const XSTATE_OBSERVABLE_COMPLETE = 'xstate.observable.complete';
  *
  * 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));
@@ -242,6 +392,15 @@ const XSTATE_OBSERVABLE_COMPLETE = 'xstate.observable.complete';
  * // ...
  * ```
  *
+ * @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.
  */
@@ -346,24 +505,20 @@ function fromObservable(observableCreator) {
 }
 
 /**
- * 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,
@@ -374,20 +529,31 @@ function fromObservable(observableCreator) {
  * } 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.
  */
 function fromEventObservable(lazyObservable) {
   // TODO: event types
@@ -482,27 +648,61 @@ function fromEventObservable(lazyObservable) {
 
 const XSTATE_PROMISE_RESOLVE = 'xstate.promise.resolve';
 const XSTATE_PROMISE_REJECT = 'xstate.promise.reject';
+
+/**
+ * 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}
+ */
+
+const controllerMap = new WeakMap();
+
 /**
- * An actor logic creator which returns promise logic as defined by an async process that resolves or rejects after some time.
+ * 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.
  *
- * @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
- *
  * @example
+ *
  * ```ts
  * const promiseLogic = fromPromise(async () => {
- *   const result = await fetch('https://example.com/...')
- *     .then((data) => data.json());
+ *   const result = await fetch('https://example.com/...').then((data) =>
+ *     data.json()
+ *   );
  *
  *   return result;
  * });
@@ -525,9 +725,16 @@ const XSTATE_PROMISE_REJECT = 'xstate.promise.reject';
  * //   ...
  * // }
  * ```
+ *
+ * @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
  */
-
-const controllerMap = new WeakMap();
 function fromPromise(promiseCreator) {
   const logic = {
     config: promiseCreator,