xstate 5.13.2 → 5.15.0

package/actors/dist/xstate-actors.development.cjs.js

@@ -2,46 +2,101 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var guards_dist_xstateGuards = require('../../dist/raise-bf7a8462.development.cjs.js');
+var guards_dist_xstateGuards = require('../../dist/raise-bad6a97b.development.cjs.js');
 require('../../dev/dist/xstate-dev.development.cjs.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);
@@ -62,6 +117,26 @@ require('../../dev/dist/xstate-dev.development.cjs.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 {
@@ -88,36 +163,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';
@@ -144,6 +247,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 = {
@@ -151,7 +272,8 @@ function fromCallback(invokeCallback) {
     start: (state, actorScope) => {
       const {
         self,
-        system
+        system,
+        emit
       } = actorScope;
       const callbackState = {
         receivers: undefined,
@@ -173,7 +295,8 @@ function fromCallback(invokeCallback) {
         receive: listener => {
           callbackState.receivers ??= new Set();
           callbackState.receivers.add(listener);
-        }
+        },
+        emit
       });
     },
     transition: (state, event, actorScope) => {
@@ -207,8 +330,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
  *
@@ -216,16 +374,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));
@@ -244,6 +396,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.
  */
@@ -251,12 +412,7 @@ function fromObservable(observableCreator) {
   // TODO: add event types
   const logic = {
     config: observableCreator,
-    transition: (snapshot, event, {
-      self,
-      id,
-      defer,
-      system
-    }) => {
+    transition: (snapshot, event) => {
       if (snapshot.status !== 'active') {
         return snapshot;
       }
@@ -308,7 +464,8 @@ function fromObservable(observableCreator) {
     },
     start: (state, {
       self,
-      system
+      system,
+      emit
     }) => {
       if (state.status === 'done') {
         // Do not restart a completed observable
@@ -317,7 +474,8 @@ function fromObservable(observableCreator) {
       state._subscription = observableCreator({
         input: state.input,
         system,
-        self
+        self,
+        emit
       }).subscribe({
         next: value => {
           system._relay(self, self, {
@@ -351,24 +509,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,
@@ -379,20 +533,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
@@ -442,7 +607,8 @@ function fromEventObservable(lazyObservable) {
     },
     start: (state, {
       self,
-      system
+      system,
+      emit
     }) => {
       if (state.status === 'done') {
         // Do not restart a completed observable
@@ -451,7 +617,8 @@ function fromEventObservable(lazyObservable) {
       state._subscription = lazyObservable({
         input: state.input,
         system,
-        self
+        self,
+        emit
       }).subscribe({
         next: value => {
           if (self._parent) {
@@ -485,27 +652,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;
  * });
@@ -528,9 +729,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,
@@ -571,7 +779,8 @@ function fromPromise(promiseCreator) {
     },
     start: (state, {
       self,
-      system
+      system,
+      emit
     }) => {
       // TODO: determine how to allow customizing this so that promises
       // can be restarted if necessary
@@ -584,7 +793,8 @@ function fromPromise(promiseCreator) {
         input: state.input,
         system,
         self,
-        signal: controller.signal
+        signal: controller.signal,
+        emit
       }));
       resolvedPromise.then(response => {
         if (self.getSnapshot().status !== 'active') {