xstate 5.0.0-beta.44 → 5.0.0-beta.46

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

@@ -2,17 +2,66 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var guards_dist_xstateGuards = require('../../dist/raise-fb6f017b.cjs.js');
+var guards_dist_xstateGuards = require('../../dist/raise-a1d3d7e9.cjs.js');
 require('../../dev/dist/xstate-dev.cjs.js');
 
 /**
- * Returns actor logic from a transition function and its initial state.
+ * Returns actor logic given a transition function and its initial state.
  *
- * A transition function is a function that takes the current state and an event and returns the next 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.
  *
- * @param transition The transition function that returns the next state given the current state and event.
- * @param initialContext The initial state of the transition function.
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * const transitionLogic = fromTransition(
+ *   (state, event) => {
+ *     if (event.type === 'increment') {
+ *       return {
+ *         ...state,
+ *         count: state.count + 1,
+ *       };
+ *     }
+ *     return state;
+ *   },
+ *   { count: 0 },
+ * );
+ *
+ * const transitionActor = createActor(transitionLogic);
+ * transitionActor.subscribe((snapshot) => {
+ *   console.log(snapshot);
+ * });
+ * transitionActor.start();
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 0 },
+ * //   ...
+ * // }
+ *
+ * transitionActor.send({ type: 'increment' });
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 1 },
+ * //   ...
+ * // }
+ * ```
  */
 function fromTransition(transition, initialContext) {
   return {
@@ -169,6 +218,46 @@ function fromCallback(invokeCallback) {
   return logic;
 }
 
+/**
+ * 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
+ *
+ * The observable’s emitted value is used as its observable actor’s `context`.
+ *
+ * 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 { interval } from 'rxjs';
+ *
+ * const logic = fromObservable((obj) => interval(1000));
+ *
+ * const actor = createActor(logic);
+ *
+ * actor.subscribe((snapshot) => {
+ *   console.log(snapshot.context);
+ * });
+ *
+ * actor.start();
+ * // At every second:
+ * // Logs 0
+ * // Logs 1
+ * // Logs 2
+ * // ...
+ * ```
+ *
+ * @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.
+ */
 function fromObservable(observableCreator) {
   const nextEventType = '$$xstate.next';
   const errorEventType = '$$xstate.error';
@@ -277,12 +366,48 @@ 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:
  *
- * @param lazyObservable A function that creates an observable
- * @returns Event observable logic
+ * - 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,
+ *   Subscribable,
+ *   EventObject,
+ *   createMachine,
+ *   createActor
+ * } from 'xstate';
+ * import { fromEvent } from 'rxjs';
+ *
+ * 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,
+ *   }
+ * });
+ *
+ * const canvasActor = createActor(canvasMachine);
+ * canvasActor.start();
+ * ```
  */
 
 function fromEventObservable(lazyObservable) {

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

@@ -2,17 +2,66 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var guards_dist_xstateGuards = require('../../dist/raise-ed700d14.development.cjs.js');
+var guards_dist_xstateGuards = require('../../dist/raise-a9e7e31c.development.cjs.js');
 require('../../dev/dist/xstate-dev.development.cjs.js');
 
 /**
- * Returns actor logic from a transition function and its initial state.
+ * Returns actor logic given a transition function and its initial state.
  *
- * A transition function is a function that takes the current state and an event and returns the next 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.
  *
- * @param transition The transition function that returns the next state given the current state and event.
- * @param initialContext The initial state of the transition function.
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * const transitionLogic = fromTransition(
+ *   (state, event) => {
+ *     if (event.type === 'increment') {
+ *       return {
+ *         ...state,
+ *         count: state.count + 1,
+ *       };
+ *     }
+ *     return state;
+ *   },
+ *   { count: 0 },
+ * );
+ *
+ * const transitionActor = createActor(transitionLogic);
+ * transitionActor.subscribe((snapshot) => {
+ *   console.log(snapshot);
+ * });
+ * transitionActor.start();
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 0 },
+ * //   ...
+ * // }
+ *
+ * transitionActor.send({ type: 'increment' });
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 1 },
+ * //   ...
+ * // }
+ * ```
  */
 function fromTransition(transition, initialContext) {
   return {
@@ -169,6 +218,46 @@ function fromCallback(invokeCallback) {
   return logic;
 }
 
+/**
+ * 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
+ *
+ * The observable’s emitted value is used as its observable actor’s `context`.
+ *
+ * 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 { interval } from 'rxjs';
+ *
+ * const logic = fromObservable((obj) => interval(1000));
+ *
+ * const actor = createActor(logic);
+ *
+ * actor.subscribe((snapshot) => {
+ *   console.log(snapshot.context);
+ * });
+ *
+ * actor.start();
+ * // At every second:
+ * // Logs 0
+ * // Logs 1
+ * // Logs 2
+ * // ...
+ * ```
+ *
+ * @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.
+ */
 function fromObservable(observableCreator) {
   const nextEventType = '$$xstate.next';
   const errorEventType = '$$xstate.error';
@@ -277,12 +366,48 @@ 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:
  *
- * @param lazyObservable A function that creates an observable
- * @returns Event observable logic
+ * - 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,
+ *   Subscribable,
+ *   EventObject,
+ *   createMachine,
+ *   createActor
+ * } from 'xstate';
+ * import { fromEvent } from 'rxjs';
+ *
+ * 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,
+ *   }
+ * });
+ *
+ * const canvasActor = createActor(canvasMachine);
+ * canvasActor.start();
+ * ```
  */
 
 function fromEventObservable(lazyObservable) {

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

@@ -1,14 +1,63 @@
-import { X as XSTATE_STOP, C as createActor } from '../../dist/raise-348cc74e.development.esm.js';
+import { X as XSTATE_STOP, C as createActor } from '../../dist/raise-fa23c2b9.development.esm.js';
 import '../../dev/dist/xstate-dev.development.esm.js';
 
 /**
- * Returns actor logic from a transition function and its initial state.
+ * Returns actor logic given a transition function and its initial state.
  *
- * A transition function is a function that takes the current state and an event and returns the next 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.
  *
- * @param transition The transition function that returns the next state given the current state and event.
- * @param initialContext The initial state of the transition function.
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * const transitionLogic = fromTransition(
+ *   (state, event) => {
+ *     if (event.type === 'increment') {
+ *       return {
+ *         ...state,
+ *         count: state.count + 1,
+ *       };
+ *     }
+ *     return state;
+ *   },
+ *   { count: 0 },
+ * );
+ *
+ * const transitionActor = createActor(transitionLogic);
+ * transitionActor.subscribe((snapshot) => {
+ *   console.log(snapshot);
+ * });
+ * transitionActor.start();
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 0 },
+ * //   ...
+ * // }
+ *
+ * transitionActor.send({ type: 'increment' });
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 1 },
+ * //   ...
+ * // }
+ * ```
  */
 function fromTransition(transition, initialContext) {
   return {
@@ -165,6 +214,46 @@ function fromCallback(invokeCallback) {
   return logic;
 }
 
+/**
+ * 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
+ *
+ * The observable’s emitted value is used as its observable actor’s `context`.
+ *
+ * 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 { interval } from 'rxjs';
+ *
+ * const logic = fromObservable((obj) => interval(1000));
+ *
+ * const actor = createActor(logic);
+ *
+ * actor.subscribe((snapshot) => {
+ *   console.log(snapshot.context);
+ * });
+ *
+ * actor.start();
+ * // At every second:
+ * // Logs 0
+ * // Logs 1
+ * // Logs 2
+ * // ...
+ * ```
+ *
+ * @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.
+ */
 function fromObservable(observableCreator) {
   const nextEventType = '$$xstate.next';
   const errorEventType = '$$xstate.error';
@@ -273,12 +362,48 @@ 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:
  *
- * @param lazyObservable A function that creates an observable
- * @returns Event observable logic
+ * - 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,
+ *   Subscribable,
+ *   EventObject,
+ *   createMachine,
+ *   createActor
+ * } from 'xstate';
+ * import { fromEvent } from 'rxjs';
+ *
+ * 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,
+ *   }
+ * });
+ *
+ * const canvasActor = createActor(canvasMachine);
+ * canvasActor.start();
+ * ```
  */
 
 function fromEventObservable(lazyObservable) {

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

@@ -1,14 +1,63 @@
-import { X as XSTATE_STOP, C as createActor } from '../../dist/raise-5854eaca.esm.js';
+import { X as XSTATE_STOP, C as createActor } from '../../dist/raise-1682abb7.esm.js';
 import '../../dev/dist/xstate-dev.esm.js';
 
 /**
- * Returns actor logic from a transition function and its initial state.
+ * Returns actor logic given a transition function and its initial state.
  *
- * A transition function is a function that takes the current state and an event and returns the next 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.
  *
- * @param transition The transition function that returns the next state given the current state and event.
- * @param initialContext The initial state of the transition function.
+ * 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.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * const transitionLogic = fromTransition(
+ *   (state, event) => {
+ *     if (event.type === 'increment') {
+ *       return {
+ *         ...state,
+ *         count: state.count + 1,
+ *       };
+ *     }
+ *     return state;
+ *   },
+ *   { count: 0 },
+ * );
+ *
+ * const transitionActor = createActor(transitionLogic);
+ * transitionActor.subscribe((snapshot) => {
+ *   console.log(snapshot);
+ * });
+ * transitionActor.start();
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 0 },
+ * //   ...
+ * // }
+ *
+ * transitionActor.send({ type: 'increment' });
+ * // => {
+ * //   status: 'active',
+ * //   context: { count: 1 },
+ * //   ...
+ * // }
+ * ```
  */
 function fromTransition(transition, initialContext) {
   return {
@@ -165,6 +214,46 @@ function fromCallback(invokeCallback) {
   return logic;
 }
 
+/**
+ * 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
+ *
+ * The observable’s emitted value is used as its observable actor’s `context`.
+ *
+ * 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 { interval } from 'rxjs';
+ *
+ * const logic = fromObservable((obj) => interval(1000));
+ *
+ * const actor = createActor(logic);
+ *
+ * actor.subscribe((snapshot) => {
+ *   console.log(snapshot.context);
+ * });
+ *
+ * actor.start();
+ * // At every second:
+ * // Logs 0
+ * // Logs 1
+ * // Logs 2
+ * // ...
+ * ```
+ *
+ * @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.
+ */
 function fromObservable(observableCreator) {
   const nextEventType = '$$xstate.next';
   const errorEventType = '$$xstate.error';
@@ -273,12 +362,48 @@ 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:
  *
- * @param lazyObservable A function that creates an observable
- * @returns Event observable logic
+ * - 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,
+ *   Subscribable,
+ *   EventObject,
+ *   createMachine,
+ *   createActor
+ * } from 'xstate';
+ * import { fromEvent } from 'rxjs';
+ *
+ * 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,
+ *   }
+ * });
+ *
+ * const canvasActor = createActor(canvasMachine);
+ * canvasActor.start();
+ * ```
  */
 
 function fromEventObservable(lazyObservable) {