diff --git a/.prettierrc b/.prettierrc index 8771bfcba4..9e413afc98 100644 --- a/.prettierrc +++ b/.prettierrc @@ -5,5 +5,7 @@ "semi": true, "singleQuote": true, "trailingComma": "none", - "bracketSpacing": true + "bracketSpacing": true, + "plugins": ["prettier-plugin-jsdoc"], + "tsdoc": true } diff --git a/examples/todomvc-react/src/react-app-env.d.ts b/examples/todomvc-react/src/react-app-env.d.ts index f717520653..dfe30fbe73 100644 --- a/examples/todomvc-react/src/react-app-env.d.ts +++ b/examples/todomvc-react/src/react-app-env.d.ts @@ -9,11 +9,11 @@ declare namespace NodeJS { /** * By default, there are two modes in Vite: * - * * `development` is used by vite and vite serve - * * `production` is used by vite build - * - * You can overwrite the default mode used for a command by passing the --mode option flag. + * - `development` is used by vite and vite serve + * - `production` is used by vite build * + * You can overwrite the default mode used for a command by passing the + * --mode option flag. */ readonly NODE_ENV: 'development' | 'production'; } diff --git a/jest.config.js b/jest.config.js index 07edeb4e3c..daef5f79a9 100644 --- a/jest.config.js +++ b/jest.config.js @@ -1,8 +1,6 @@ const { constants } = require('jest-config'); -/** - * @type {import('@jest/types').Config.InitialOptions} - */ +/** @type {import('@jest/types').Config.InitialOptions} */ module.exports = { prettierPath: null, setupFilesAfterEnv: ['@xstate-repo/jest-utils/setup'], diff --git a/package.json b/package.json index f604b98221..2a050fb9d4 100644 --- a/package.json +++ b/package.json @@ -76,6 +76,7 @@ "markdown-it-codesandbox-embed": "^0.1.0", "patch-package": "^6.5.1", "prettier": "^3.1.0", + "prettier-plugin-jsdoc": "^1.3.0", "spawn-command": "0.0.2-1", "synckit": "^0.8.5", "tslib": "^2.3.1", diff --git a/packages/core/src/State.ts b/packages/core/src/State.ts index 78156a13a8..8cb82844ce 100644 --- a/packages/core/src/State.ts +++ b/packages/core/src/State.ts @@ -55,9 +55,7 @@ interface MachineSnapshotBase< TMeta, _TUnusedButLeftForCompatReasons = never > { - /** - * The state machine that produced this state snapshot. - */ + /** The state machine that produced this state snapshot. */ machine: StateMachine< TContext, TEvent, @@ -73,61 +71,59 @@ interface MachineSnapshotBase< EventObject, // TEmitted any // TMeta >; - /** - * The tags of the active state nodes that represent the current state value. - */ + /** The tags of the active state nodes that represent the current state value. */ tags: Set; /** * The current state value. * * This represents the active state nodes in the state machine. - * - For atomic state nodes, it is a string. + * + * - For atomic state nodes, it is a string. * - For compound parent state nodes, it is an object where: + * * - The key is the parent state node's key * - The value is the current state value of the active child state node(s) - * + * * @example - ```ts - // single-level state node - snapshot.value; // => 'yellow' - - // nested state nodes - snapshot.value; // => { red: 'wait' } - ``` + * + * ```ts + * // single-level state node + * snapshot.value; // => 'yellow' + * + * // nested state nodes + * snapshot.value; // => { red: 'wait' } + * ``` */ value: TStateValue; - /** - * The current status of this snapshot. - */ + /** The current status of this snapshot. */ status: 'active' | 'done' | 'error' | 'stopped'; error: unknown; context: TContext; historyValue: Readonly>; - /** - * The enabled state nodes representative of the state value. - */ + /** The enabled state nodes representative of the state value. */ _nodes: Array>; - /** - * An object mapping actor names to spawned/invoked actors. - */ + /** An object mapping actor names to spawned/invoked actors. */ children: TChildren; /** - * Whether the current state value is a subset of the given partial state value. + * Whether the current state value is a subset of the given partial state + * value. + * * @param partialStateValue */ matches: (partialStateValue: ToTestStateValue) => boolean; /** * Whether the current state nodes has a state node with the specified `tag`. + * * @param tag */ hasTag: (tag: TTag) => boolean; /** - * Determines whether sending the `event` will cause a non-forbidden transition - * to be selected, even if the transitions have no actions nor + * Determines whether sending the `event` will cause a non-forbidden + * transition to be selected, even if the transitions have no actions nor * change the state value. * * @param event The event to test diff --git a/packages/core/src/StateMachine.ts b/packages/core/src/StateMachine.ts index 3d7fa7cb32..d01bc2e905 100644 --- a/packages/core/src/StateMachine.ts +++ b/packages/core/src/StateMachine.ts @@ -84,9 +84,7 @@ export class StateMachine< TEmitted > { - /** - * The machine's own version. - */ + /** The machine's own version. */ public version?: string; public schemas: unknown; @@ -107,9 +105,7 @@ export class StateMachine< public events: Array>; constructor( - /** - * The raw config used to create the machine. - */ + /** The raw config used to create the machine. */ public config: MachineConfig< TContext, TEvent, @@ -167,12 +163,11 @@ export class StateMachine< } /** - * Clones this state machine with the provided implementations - * and merges the `context` (if provided). - * - * @param implementations Options (`actions`, `guards`, `actors`, `delays`, `context`) - * to recursively merge with the existing options. + * Clones this state machine with the provided implementations and merges the + * `context` (if provided). * + * @param implementations Options (`actions`, `guards`, `actors`, `delays`, + * `context`) to recursively merge with the existing options. * @returns A new `StateMachine` instance with the provided implementations. */ public provide( @@ -263,8 +258,8 @@ export class StateMachine< } /** - * Determines the next snapshot given the current `snapshot` and received `event`. - * Calculates a full macrostep from all microsteps. + * Determines the next snapshot given the current `snapshot` and received + * `event`. Calculates a full macrostep from all microsteps. * * @param snapshot The current snapshot * @param event The received event @@ -294,8 +289,8 @@ export class StateMachine< } /** - * Determines the next state given the current `state` and `event`. - * Calculates a microstep. + * Determines the next state given the current `state` and `event`. Calculates + * a microstep. * * @param state The current state * @param event The received event @@ -342,8 +337,8 @@ export class StateMachine< } /** - * The initial state _before_ evaluating any microsteps. - * This "pre-initial" state is provided to initial actions executed in the initial state. + * The initial state _before_ evaluating any microsteps. This "pre-initial" + * state is provided to initial actions executed in the initial state. */ private getPreInitialState( actorScope: AnyActorScope, @@ -387,7 +382,8 @@ export class StateMachine< } /** - * Returns the initial `State` instance, with reference to `self` as an `ActorRef`. + * Returns the initial `State` instance, with reference to `self` as an + * `ActorRef`. */ public getInitialSnapshot( actorScope: ActorScope< diff --git a/packages/core/src/StateNode.ts b/packages/core/src/StateNode.ts index 2cc4dc676e..424ae235f9 100644 --- a/packages/core/src/StateNode.ts +++ b/packages/core/src/StateNode.ts @@ -70,53 +70,40 @@ export class StateNode< TEvent extends EventObject = EventObject > { /** - * The relative key of the state node, which represents its location in the overall state value. + * The relative key of the state node, which represents its location in the + * overall state value. */ public key: string; - /** - * The unique ID of the state node. - */ + /** The unique ID of the state node. */ public id: string; /** * The type of this state node: * - * - `'atomic'` - no child state nodes - * - `'compound'` - nested child state nodes (XOR) - * - `'parallel'` - orthogonal nested child state nodes (AND) - * - `'history'` - history state node - * - `'final'` - final state node + * - `'atomic'` - no child state nodes + * - `'compound'` - nested child state nodes (XOR) + * - `'parallel'` - orthogonal nested child state nodes (AND) + * - `'history'` - history state node + * - `'final'` - final state node */ public type: 'atomic' | 'compound' | 'parallel' | 'final' | 'history'; - /** - * The string path from the root machine node to this node. - */ + /** The string path from the root machine node to this node. */ public path: string[]; - /** - * The child state nodes. - */ + /** The child state nodes. */ public states: StateNodesConfig; /** * The type of history on this state node. Can be: * - * - `'shallow'` - recalls only top-level historical state value - * - `'deep'` - recalls historical state value at all levels + * - `'shallow'` - recalls only top-level historical state value + * - `'deep'` - recalls historical state value at all levels */ public history: false | 'shallow' | 'deep'; - /** - * The action(s) to be executed upon entering the state node. - */ + /** The action(s) to be executed upon entering the state node. */ public entry: UnknownAction[]; - /** - * The action(s) to be executed upon exiting the state node. - */ + /** The action(s) to be executed upon exiting the state node. */ public exit: UnknownAction[]; - /** - * The parent state node. - */ + /** The parent state node. */ public parent?: StateNode; - /** - * The root machine node. - */ + /** The root machine node. */ public machine: StateMachine< TContext, TEvent, @@ -133,18 +120,21 @@ export class StateNode< any // meta >; /** - * The meta data associated with this state node, which will be returned in State instances. + * The meta data associated with this state node, which will be returned in + * State instances. */ public meta?: any; /** - * The output data sent with the "xstate.done.state._id_" event if this is a final state node. + * The output data sent with the "xstate.done.state._id_" event if this is a + * final state node. */ public output?: | Mapper | NonReducibleUnknown; /** - * The order this state node appears. Corresponds to the implicit document order. + * The order this state node appears. Corresponds to the implicit document + * order. */ public order: number = -1; @@ -155,9 +145,7 @@ export class StateNode< public always?: Array>; constructor( - /** - * The raw config used to create the machine. - */ + /** The raw config used to create the machine. */ public config: StateNodeConfig< TContext, TEvent, @@ -243,9 +231,7 @@ export class StateNode< }); } - /** - * The well-structured state node definition. - */ + /** The well-structured state node definition. */ public get definition(): StateNodeDefinition { return { id: this.id, @@ -292,9 +278,7 @@ export class StateNode< return this.definition; } - /** - * The logic invoked as actors by this state node. - */ + /** The logic invoked as actors by this state node. */ public get invoke(): Array< InvokeDefinition< TContext, @@ -343,9 +327,7 @@ export class StateNode< ); } - /** - * The mapping of events to transitions. - */ + /** The mapping of events to transitions. */ public get on(): TransitionDefinitionMap { return memo(this, 'on', () => { const transitions = this.transitions; @@ -442,9 +424,7 @@ export class StateNode< return selectedTransition ? [selectedTransition] : undefined; } - /** - * All the event types accepted by this state node and its descendants. - */ + /** All the event types accepted by this state node and its descendants. */ public get events(): Array> { return memo(this, 'events', () => { const { states } = this; diff --git a/packages/core/src/actions/assign.ts b/packages/core/src/actions/assign.ts index 9332a3442b..8256bdf916 100644 --- a/packages/core/src/actions/assign.ts +++ b/packages/core/src/actions/assign.ts @@ -101,34 +101,36 @@ export interface AssignAction< /** * Updates the current context of the machine. * - * @param assignment An object that represents the partial context to update, or a - * function that returns an object that represents the partial context to update. - * * @example - ```ts - import { createMachine, assign } from 'xstate'; - - const countMachine = createMachine({ - context: { - count: 0, - message: '' - }, - on: { - inc: { - actions: assign({ - count: ({ context }) => context.count + 1 - }) - }, - updateMessage: { - actions: assign(({ context, event }) => { - return { - message: event.message.trim() - } - }) - } - } - }); - ``` + * + * ```ts + * import { createMachine, assign } from 'xstate'; + * + * const countMachine = createMachine({ + * context: { + * count: 0, + * message: '' + * }, + * on: { + * inc: { + * actions: assign({ + * count: ({ context }) => context.count + 1 + * }) + * }, + * updateMessage: { + * actions: assign(({ context, event }) => { + * return { + * message: event.message.trim() + * }; + * }) + * } + * } + * }); + * ``` + * + * @param assignment An object that represents the partial context to update, or + * a function that returns an object that represents the partial context to + * update. */ export function assign< TContext extends MachineContext, diff --git a/packages/core/src/actions/cancel.ts b/packages/core/src/actions/cancel.ts index 5a094b8d20..443bef7b9e 100644 --- a/packages/core/src/actions/cancel.ts +++ b/packages/core/src/actions/cancel.ts @@ -49,30 +49,36 @@ export interface CancelAction< } /** - * Cancels a delayed `sendTo(...)` action that is waiting to be executed. The canceled `sendTo(...)` action - * will not send its event or execute, unless the `delay` has already elapsed before `cancel(...)` is called. + * Cancels a delayed `sendTo(...)` action that is waiting to be executed. The + * canceled `sendTo(...)` action will not send its event or execute, unless the + * `delay` has already elapsed before `cancel(...)` is called. * - * @param sendId The `id` of the `sendTo(...)` action to cancel. - * * @example - ```ts - import { createMachine, sendTo, cancel } from 'xstate'; - - const machine = createMachine({ - // ... - on: { - sendEvent: { - actions: sendTo('some-actor', { type: 'someEvent' }, { - id: 'some-id', - delay: 1000 - }) - }, - cancelEvent: { - actions: cancel('some-id') - } - } - }); - ``` + * + * ```ts + * import { createMachine, sendTo, cancel } from 'xstate'; + * + * const machine = createMachine({ + * // ... + * on: { + * sendEvent: { + * actions: sendTo( + * 'some-actor', + * { type: 'someEvent' }, + * { + * id: 'some-id', + * delay: 1000 + * } + * ) + * }, + * cancelEvent: { + * actions: cancel('some-id') + * } + * } + * }); + * ``` + * + * @param sendId The `id` of the `sendTo(...)` action to cancel. */ export function cancel< TContext extends MachineContext, diff --git a/packages/core/src/actions/emit.ts b/packages/core/src/actions/emit.ts index 32efb9ed91..d3d343aad0 100644 --- a/packages/core/src/actions/emit.ts +++ b/packages/core/src/actions/emit.ts @@ -65,38 +65,40 @@ export interface EmitAction< } /** - * Emits an event to event handlers registered on the actor via `actor.on(event, handler)`. + * Emits an event to event handlers registered on the actor via `actor.on(event, + * handler)`. * * @example - ```ts - import { emit } from 'xstate'; - - const machine = createMachine({ - // ... - on: { - something: { - actions: emit({ - type: 'emitted', - some: 'data' - }) - } - } - // ... - }); - - const actor = createActor(machine).start(); - - actor.on('emitted', (event) => { - console.log(event); - }); - - actor.send({ type: 'something' }); - // logs: - // { - // type: 'emitted', - // some: 'data' - // } - ``` + * + * ```ts + * import { emit } from 'xstate'; + * + * const machine = createMachine({ + * // ... + * on: { + * something: { + * actions: emit({ + * type: 'emitted', + * some: 'data' + * }) + * } + * } + * // ... + * }); + * + * const actor = createActor(machine).start(); + * + * actor.on('emitted', (event) => { + * console.log(event); + * }); + * + * actor.send({ type: 'something' }); + * // logs: + * // { + * // type: 'emitted', + * // some: 'data' + * // } + * ``` */ export function emit< TContext extends MachineContext, @@ -105,9 +107,7 @@ export function emit< TEvent extends EventObject, TEmitted extends EventObject >( - /** - * The event to emit, or an expression that returns an event to emit. - */ + /** The event to emit, or an expression that returns an event to emit. */ eventOrExpr: | TEmitted | SendExpr diff --git a/packages/core/src/actions/enqueueActions.ts b/packages/core/src/actions/enqueueActions.ts index b90856a67c..7dc8b22ad7 100644 --- a/packages/core/src/actions/enqueueActions.ts +++ b/packages/core/src/actions/enqueueActions.ts @@ -239,24 +239,26 @@ type CollectActions< ) => void; /** - * Creates an action object that will execute actions that are queued by the `enqueue(action)` function. + * Creates an action object that will execute actions that are queued by the + * `enqueue(action)` function. * * @example - ```ts - import { createMachine, enqueueActions } from 'xstate'; - - const machine = createMachine({ - entry: enqueueActions(({ enqueue, check }) => { - enqueue.assign({ count: 0 }); - - if (check('someGuard')) { - enqueue.assign({ count: 1 }); - } - - enqueue('someAction'); - }) - }) - ``` + * + * ```ts + * import { createMachine, enqueueActions } from 'xstate'; + * + * const machine = createMachine({ + * entry: enqueueActions(({ enqueue, check }) => { + * enqueue.assign({ count: 0 }); + * + * if (check('someGuard')) { + * enqueue.assign({ count: 1 }); + * } + * + * enqueue('someAction'); + * }) + * }); + * ``` */ export function enqueueActions< TContext extends MachineContext, diff --git a/packages/core/src/actions/log.ts b/packages/core/src/actions/log.ts index b7c849d4c0..2af9492fb9 100644 --- a/packages/core/src/actions/log.ts +++ b/packages/core/src/actions/log.ts @@ -60,11 +60,12 @@ export interface LogAction< } /** + * @param expr The expression function to evaluate which will be logged. Takes + * in 2 arguments: + * + * - `ctx` - the current state context + * - `event` - the event that caused this action to be executed. * - * @param expr The expression function to evaluate which will be logged. - * Takes in 2 arguments: - * - `ctx` - the current state context - * - `event` - the event that caused this action to be executed. * @param label The label to give to the logged expression. */ export function log< diff --git a/packages/core/src/actions/send.ts b/packages/core/src/actions/send.ts index 03250afd4a..a5adc9e667 100644 --- a/packages/core/src/actions/send.ts +++ b/packages/core/src/actions/send.ts @@ -185,10 +185,12 @@ export interface SendToAction< * Sends an event to an actor. * * @param actor The `ActorRef` to send the event to. - * @param event The event to send, or an expression that evaluates to the event to send + * @param event The event to send, or an expression that evaluates to the event + * to send * @param options Send action options - * - `id` - The unique send event identifier (used with `cancel()`). - * - `delay` - The number of milliseconds to delay the sending of the event. + * + * - `id` - The unique send event identifier (used with `cancel()`). + * - `delay` - The number of milliseconds to delay the sending of the event. */ export function sendTo< TContext extends MachineContext, diff --git a/packages/core/src/actors/callback.ts b/packages/core/src/actors/callback.ts index 536b5d312b..1ec3ef577f 100644 --- a/packages/core/src/actors/callback.ts +++ b/packages/core/src/actors/callback.ts @@ -62,59 +62,46 @@ export type InvokeCallback< }: { /** * 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; - /** - * 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; 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'; @@ -141,6 +128,24 @@ export type InvokeCallback< * }; * }); * ``` + * + * @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 function fromCallback< TEvent extends EventObject, diff --git a/packages/core/src/actors/observable.ts b/packages/core/src/actors/observable.ts index 6a2c197d89..5fa0f5c2ac 100644 --- a/packages/core/src/actors/observable.ts +++ b/packages/core/src/actors/observable.ts @@ -40,7 +40,8 @@ export type ObservableActorRef = ActorRefFrom< >; /** - * 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 * @@ -48,16 +49,10 @@ export type ObservableActorRef = ActorRefFrom< * * 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)); @@ -76,6 +71,15 @@ export type ObservableActorRef = ActorRefFrom< * // ... * ``` * + * @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. */ @@ -187,24 +191,20 @@ export function fromObservable< } /** - * 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, @@ -215,20 +215,31 @@ export function fromObservable< * } from 'xstate'; * import { fromEvent } from 'rxjs'; * - * const mouseClickLogic = fromEventObservable(() => - * fromEvent(document.body, 'click') as Subscribable + * const mouseClickLogic = fromEventObservable( + * () => fromEvent(document.body, 'click') as Subscribable * ); * * 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 function fromEventObservable< TEvent extends EventObject, diff --git a/packages/core/src/actors/promise.ts b/packages/core/src/actors/promise.ts index 6e0ff0c8eb..e6f4f53fff 100644 --- a/packages/core/src/actors/promise.ts +++ b/packages/core/src/actors/promise.ts @@ -33,26 +33,23 @@ export type PromiseActorRef = ActorRefFrom< >; /** - * 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; * }); @@ -75,6 +72,15 @@ export type PromiseActorRef = ActorRefFrom< * // ... * // } * ``` + * + * @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(); @@ -91,17 +97,11 @@ export function fromPromise< 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; signal: AbortSignal; emit: (emitted: TEmitted) => void; diff --git a/packages/core/src/actors/transition.ts b/packages/core/src/actors/transition.ts index c29ce1ceeb..f14d15255c 100644 --- a/packages/core/src/actors/transition.ts +++ b/packages/core/src/actors/transition.ts @@ -35,40 +35,36 @@ export type TransitionActorRef< /** * 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); @@ -89,6 +85,26 @@ export type TransitionActorRef< * // ... * // } * ``` + * + * @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 function fromTransition< TContext, diff --git a/packages/core/src/assert.ts b/packages/core/src/assert.ts index 3b7c4ccefe..6d2bc7a0c0 100644 --- a/packages/core/src/assert.ts +++ b/packages/core/src/assert.ts @@ -2,26 +2,27 @@ import { EventObject } from './types.ts'; import { toArray } from './utils.ts'; /** - * 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 function assertEvent< TEvent extends EventObject, diff --git a/packages/core/src/createActor.ts b/packages/core/src/createActor.ts index f7d149359a..e537a3b039 100644 --- a/packages/core/src/createActor.ts +++ b/packages/core/src/createActor.ts @@ -68,25 +68,24 @@ const defaultOptions = { }; /** - * An Actor is a running process that can receive events, send events and change its behavior based on the events it receives, which can cause effects outside of the actor. When you run a state machine, it becomes an actor. + * An Actor is a running process that can receive events, send events and change + * its behavior based on the events it receives, which can cause effects outside + * of the actor. When you run a state machine, it becomes an actor. */ export class Actor implements ActorRef, EventFromLogic, EmittedFrom> { - /** - * The current internal state of the actor. - */ + /** The current internal state of the actor. */ private _snapshot!: SnapshotFrom; /** - * The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions. + * The clock that is responsible for setting and clearing timeouts, such as + * delayed events and transitions. */ public clock: Clock; public options: Readonly>; - /** - * The unique identifier for this actor relative to its parent. - */ + /** The unique identifier for this actor relative to its parent. */ public id: string; private mailbox: Mailbox> = new Mailbox( @@ -122,21 +121,18 @@ export class Actor private _systemId: string | undefined; - /** - * The globally unique process ID for this invocation. - */ + /** The globally unique process ID for this invocation. */ public sessionId: string; - /** - * The system to which this actor belongs. - */ + /** The system to which this actor belongs. */ public system: AnyActorSystem; private _doneEvent?: DoneActorEvent; public src: string | AnyActorLogic; /** - * Creates a new actor instance for the given logic with the provided options, if any. + * Creates a new actor instance for the given logic with the provided options, + * if any. * * @param logic The logic to create an actor from * @param options Actor options @@ -327,11 +323,15 @@ export class Actor * Subscribe an observer to an actor’s snapshot values. * * @remarks - * The observer will receive the actor’s snapshot value when it is emitted. The observer can be: + * The observer will receive the actor’s snapshot value when it is emitted. + * The observer can be: + * * - A plain function that receives the latest snapshot, or - * - An observer object whose `.next(snapshot)` method receives the latest snapshot + * - An observer object whose `.next(snapshot)` method receives the latest + * snapshot * * @example + * * ```ts * // Observer as a plain function * const subscription = actor.subscribe((snapshot) => { @@ -340,6 +340,7 @@ export class Actor * ``` * * @example + * * ```ts * // Observer as an object * const subscription = actor.subscribe({ @@ -351,13 +352,16 @@ export class Actor * }, * complete() { * // ... - * }, + * } * }); * ``` * - * The return value of `actor.subscribe(observer)` is a subscription object that has an `.unsubscribe()` method. You can call `subscription.unsubscribe()` to unsubscribe the observer: + * The return value of `actor.subscribe(observer)` is a subscription object + * that has an `.unsubscribe()` method. You can call + * `subscription.unsubscribe()` to unsubscribe the observer: * * @example + * * ```ts * const subscription = actor.subscribe((snapshot) => { * // ... @@ -367,9 +371,12 @@ export class Actor * subscription.unsubscribe(); * ``` * - * When the actor is stopped, all of its observers will automatically be unsubscribed. + * When the actor is stopped, all of its observers will automatically be + * unsubscribed. * - * @param observer - Either a plain function that receives the latest snapshot, or an observer object whose `.next(snapshot)` method receives the latest snapshot + * @param observer - Either a plain function that receives the latest + * snapshot, or an observer object whose `.next(snapshot)` method receives + * the latest snapshot */ public subscribe(observer: Observer>): Subscription; public subscribe( @@ -445,9 +452,7 @@ export class Actor }; } - /** - * Starts the Actor from the initial state - */ + /** Starts the Actor from the initial state */ public start(): this { if (this._processingStatus === ProcessingStatus.Running) { // Do not restart the service if it is already started @@ -580,9 +585,7 @@ export class Actor return this; } - /** - * Stops the Actor and unsubscribe all listeners. - */ + /** Stops the Actor and unsubscribe all listeners. */ public stop(): this { if (this._parent) { throw new Error('A non-root actor cannot be stopped directly.'); @@ -661,9 +664,7 @@ export class Actor return this; } - /** - * @internal - */ + /** @internal */ public _send(event: EventFromLogic) { if (this._processingStatus === ProcessingStatus.Stopped) { // do nothing @@ -716,10 +717,11 @@ export class Actor * @remarks * The internal state can be persisted from any actor, not only machines. * - * Note that the persisted state is not the same as the snapshot from {@link Actor.getSnapshot}. Persisted state represents the internal state of the actor, while snapshots represent the actor's last emitted value. + * Note that the persisted state is not the same as the snapshot from + * {@link Actor.getSnapshot}. Persisted state represents the internal state of + * the actor, while snapshots represent the actor's last emitted value. * * Can be restored with {@link ActorOptions.state} - * * @see https://stately.ai/docs/persistence */ public getPersistedSnapshot(): Snapshot; @@ -737,11 +739,11 @@ export class Actor * @remarks * The snapshot represent an actor's last emitted value. * - * When an actor receives an event, its internal state may change. - * An actor may emit a snapshot when a state transition occurs. - * - * Note that some actors, such as callback actors generated with `fromCallback`, will not emit snapshots. + * When an actor receives an event, its internal state may change. An actor + * may emit a snapshot when a state transition occurs. * + * Note that some actors, such as callback actors generated with + * `fromCallback`, will not emit snapshots. * @see {@link Actor.subscribe} to subscribe to an actor’s snapshot values. * @see {@link Actor.getPersistedSnapshot} to persist the internal state of an actor (which is more than just a snapshot). */ @@ -759,13 +761,16 @@ type RequiredOptions = undefined extends InputFrom ? never : 'input'; /** - * Creates a new actor instance for the given actor logic with the provided options, if any. + * Creates a new actor instance for the given actor logic with the provided + * options, if any. * * @remarks - * When you create an actor from actor logic via `createActor(logic)`, you implicitly create an actor system where the created actor is the root actor. - * Any actors spawned from this root actor and its descendants are part of that actor system. - * + * When you create an actor from actor logic via `createActor(logic)`, you + * implicitly create an actor system where the created actor is the root actor. + * Any actors spawned from this root actor and its descendants are part of that + * actor system. * @example + * * ```ts * import { createActor } from 'xstate'; * import { someActorLogic } from './someActorLogic.ts'; @@ -787,7 +792,10 @@ type RequiredOptions = * actor.stop(); * ``` * - * @param logic - The actor logic to create an actor from. For a state machine actor logic creator, see {@link createMachine}. Other actor logic creators include {@link fromCallback}, {@link fromEventObservable}, {@link fromObservable}, {@link fromPromise}, and {@link fromTransition}. + * @param logic - The actor logic to create an actor from. For a state machine + * actor logic creator, see {@link createMachine}. Other actor logic creators + * include {@link fromCallback}, {@link fromEventObservable}, + * {@link fromObservable}, {@link fromPromise}, and {@link fromTransition}. * @param options - Actor options */ export function createActor( @@ -805,13 +813,12 @@ export function createActor( } /** - * Creates a new Interpreter instance for the given machine with the provided options, if any. + * Creates a new Interpreter instance for the given machine with the provided + * options, if any. * * @deprecated Use `createActor` instead */ export const interpret = createActor; -/** - * @deprecated Use `Actor` instead. - */ +/** @deprecated Use `Actor` instead. */ export type Interpreter = typeof Actor; diff --git a/packages/core/src/createMachine.ts b/packages/core/src/createMachine.ts index f1f6cd2721..2a266e3ce9 100644 --- a/packages/core/src/createMachine.ts +++ b/packages/core/src/createMachine.ts @@ -67,40 +67,42 @@ type ToStateValue = * * The state machine represents the pure logic of a state machine actor. * - * @param config The state machine configuration. - * @param options DEPRECATED: use `setup({ ... })` or `machine.provide({ ... })` to provide machine implementations instead. - * * @example - ```ts - import { createMachine } from 'xstate'; - - const lightMachine = createMachine({ - id: 'light', - initial: 'green', - states: { - green: { - on: { - TIMER: { target: 'yellow' } - } - }, - yellow: { - on: { - TIMER: { target: 'red' } - } - }, - red: { - on: { - TIMER: { target: 'green' } - } - } - } - }); - - const lightActor = createActor(lightMachine); - lightActor.start(); - - lightActor.send({ type: 'TIMER' }); - ``` + * + * ```ts + * import { createMachine } from 'xstate'; + * + * const lightMachine = createMachine({ + * id: 'light', + * initial: 'green', + * states: { + * green: { + * on: { + * TIMER: { target: 'yellow' } + * } + * }, + * yellow: { + * on: { + * TIMER: { target: 'red' } + * } + * }, + * red: { + * on: { + * TIMER: { target: 'green' } + * } + * } + * } + * }); + * + * const lightActor = createActor(lightMachine); + * lightActor.start(); + * + * lightActor.send({ type: 'TIMER' }); + * ``` + * + * @param config The state machine configuration. + * @param options DEPRECATED: use `setup({ ... })` or `machine.provide({ ... })` + * to provide machine implementations instead. */ export function createMachine< TContext extends MachineContext, diff --git a/packages/core/src/eventUtils.ts b/packages/core/src/eventUtils.ts index 40506c7eff..0066cae865 100644 --- a/packages/core/src/eventUtils.ts +++ b/packages/core/src/eventUtils.ts @@ -2,8 +2,8 @@ import { XSTATE_INIT } from './constants.ts'; import { DoneActorEvent, DoneStateEvent, ErrorActorEvent } from './types.ts'; /** - * Returns an event that represents an implicit event that - * is sent after the specified `delay`. + * Returns an event that represents an implicit event that is sent after the + * specified `delay`. * * @param delayRef The delay in milliseconds * @param id The state node ID where this event is handled @@ -13,8 +13,8 @@ export function createAfterEvent(delayRef: number | string, id: string) { } /** - * Returns an event that represents that a final state node - * has been reached in the parent state node. + * Returns an event that represents that a final state node has been reached in + * the parent state node. * * @param id The final state node's parent state node `id` * @param output The data to pass into the event @@ -32,8 +32,8 @@ export function createDoneStateEvent( /** * Returns an event that represents that an invoked service has terminated. * - * An invoked service is terminated when it has reached a top-level final state node, - * but not when it is canceled. + * An invoked service is terminated when it has reached a top-level final state + * node, but not when it is canceled. * * @param invokeId The invoked service ID * @param output The data to pass into the event diff --git a/packages/core/src/getNextSnapshot.ts b/packages/core/src/getNextSnapshot.ts index 611fcbaff0..7f57aaab0d 100644 --- a/packages/core/src/getNextSnapshot.ts +++ b/packages/core/src/getNextSnapshot.ts @@ -44,33 +44,36 @@ export function getInitialSnapshot( } /** - * Determines the next snapshot for the given `actorLogic` based on - * the given `snapshot` and `event`. + * Determines the next snapshot for the given `actorLogic` based on the given + * `snapshot` and `event`. * - * If the `snapshot` is `undefined`, the initial snapshot of the - * `actorLogic` is used. + * If the `snapshot` is `undefined`, the initial snapshot of the `actorLogic` is + * used. * * @example - ```ts - import { getNextSnapshot } from 'xstate'; - import { trafficLightMachine } from './trafficLightMachine.ts'; - - const nextSnapshot = getNextSnapshot( - trafficLightMachine, // actor logic - undefined, // snapshot (or initial state if undefined) - { type: 'TIMER' }); // event object - - console.log(nextSnapshot.value); - // => 'yellow' - - const nextSnapshot2 = getNextSnapshot( - trafficLightMachine, // actor logic - nextSnapshot, // snapshot - { type: 'TIMER' }); // event object - - console.log(nextSnapshot2.value); - // =>'red' - ``` + * + * ```ts + * import { getNextSnapshot } from 'xstate'; + * import { trafficLightMachine } from './trafficLightMachine.ts'; + * + * const nextSnapshot = getNextSnapshot( + * trafficLightMachine, // actor logic + * undefined, // snapshot (or initial state if undefined) + * { type: 'TIMER' } + * ); // event object + * + * console.log(nextSnapshot.value); + * // => 'yellow' + * + * const nextSnapshot2 = getNextSnapshot( + * trafficLightMachine, // actor logic + * nextSnapshot, // snapshot + * { type: 'TIMER' } + * ); // event object + * + * console.log(nextSnapshot2.value); + * // =>'red' + * ``` */ export function getNextSnapshot( actorLogic: T, diff --git a/packages/core/src/guards.ts b/packages/core/src/guards.ts index 6d98fdd610..4e0ded4f64 100644 --- a/packages/core/src/guards.ts +++ b/packages/core/src/guards.ts @@ -139,30 +139,33 @@ function checkNot( } /** - * Higher-order guard that evaluates to `true` if the `guard` passed to it evaluates to `false`. + * Higher-order guard that evaluates to `true` if the `guard` passed to it + * evaluates to `false`. * * @category Guards * @example - ```ts - import { setup, not } from 'xstate'; - - const machine = setup({ - guards: { - someNamedGuard: () => false - } - }).createMachine({ - on: { - someEvent: { - guard: not('someNamedGuard'), - actions: () => { - // will be executed if guard in `not(...)` - // evaluates to `false` - } - } - } - }); - ``` - * @returns A guard + * + * ```ts + * import { setup, not } from 'xstate'; + * + * const machine = setup({ + * guards: { + * someNamedGuard: () => false + * } + * }).createMachine({ + * on: { + * someEvent: { + * guard: not('someNamedGuard'), + * actions: () => { + * // will be executed if guard in `not(...)` + * // evaluates to `false` + * } + * } + * } + * }); + * ``` + * + * @returns A guard */ export function not< TContext extends MachineContext, @@ -205,28 +208,27 @@ function checkAnd( * * @category Guards * @example - ```ts - import { setup, and } from 'xstate'; - - const machine = setup({ - guards: { - someNamedGuard: () => true - } - }).createMachine({ - on: { - someEvent: { - guard: and([ - ({ context }) => context.value > 0, - 'someNamedGuard' - ]), - actions: () => { - // will be executed if all guards in `and(...)` - // evaluate to true - } - } - } - }); - ``` + * + * ```ts + * import { setup, and } from 'xstate'; + * + * const machine = setup({ + * guards: { + * someNamedGuard: () => true + * } + * }).createMachine({ + * on: { + * someEvent: { + * guard: and([({ context }) => context.value > 0, 'someNamedGuard']), + * actions: () => { + * // will be executed if all guards in `and(...)` + * // evaluate to true + * } + * } + * } + * }); + * ``` + * * @returns A guard action object */ export function and< @@ -272,33 +274,32 @@ function checkOr( } /** - * Higher-order guard that evaluates to `true` if any of the `guards` passed to it - * evaluate to `true`. + * Higher-order guard that evaluates to `true` if any of the `guards` passed to + * it evaluate to `true`. * * @category Guards * @example - ```ts - import { setup, or } from 'xstate'; - - const machine = setup({ - guards: { - someNamedGuard: () => true - } - }).createMachine({ - on: { - someEvent: { - guard: or([ - ({ context }) => context.value > 0, - 'someNamedGuard' - ]), - actions: () => { - // will be executed if any of the guards in `or(...)` - // evaluate to true - } - } - } - }); - ``` + * + * ```ts + * import { setup, or } from 'xstate'; + * + * const machine = setup({ + * guards: { + * someNamedGuard: () => true + * } + * }).createMachine({ + * on: { + * someEvent: { + * guard: or([({ context }) => context.value > 0, 'someNamedGuard']), + * actions: () => { + * // will be executed if any of the guards in `or(...)` + * // evaluate to true + * } + * } + * } + * }); + * ``` + * * @returns A guard action object */ export function or< diff --git a/packages/core/src/inspection.ts b/packages/core/src/inspection.ts index 16936c8796..63011a1788 100644 --- a/packages/core/src/inspection.ts +++ b/packages/core/src/inspection.ts @@ -16,6 +16,7 @@ export interface BaseInspectionEventProperties { rootId: string; // the session ID of the root /** * The relevant actorRef for the inspection event. + * * - For snapshot events, this is the `actorRef` of the snapshot. * - For event events, this is the target `actorRef` (recipient of event). * - For actor events, this is the `actorRef` of the registered actor. diff --git a/packages/core/src/reportUnhandledError.ts b/packages/core/src/reportUnhandledError.ts index bde48916d7..2c005d0755 100644 --- a/packages/core/src/reportUnhandledError.ts +++ b/packages/core/src/reportUnhandledError.ts @@ -1,9 +1,10 @@ /** - * This function makes sure that unhandled errors are thrown in a separate macrotask. - * It allows those errors to be detected by global error handlers and reported to bug tracking services - * without interrupting our own stack of execution. + * This function makes sure that unhandled errors are thrown in a separate + * macrotask. It allows those errors to be detected by global error handlers and + * reported to bug tracking services without interrupting our own stack of + * execution. * - * @param err error to be thrown + * @param err Error to be thrown */ export function reportUnhandledError(err: unknown) { setTimeout(() => { diff --git a/packages/core/src/stateUtils.ts b/packages/core/src/stateUtils.ts index 0b3052c939..f02c89fdb4 100644 --- a/packages/core/src/stateUtils.ts +++ b/packages/core/src/stateUtils.ts @@ -269,9 +269,7 @@ export function getCandidates( return candidates; } -/** - * All delayed transitions from the config. - */ +/** All delayed transitions from the config. */ export function getDelayedTransitions( stateNode: AnyStateNode ): Array> { @@ -563,9 +561,7 @@ export function getInitialStateNodes(stateNode: AnyStateNode) { return set; } -/** - * Returns the child state node from its relative `stateKey`, or throws. - */ +/** Returns the child state node from its relative `stateKey`, or throws. */ export function getStateNode( stateNode: AnyStateNode, stateKey: string @@ -986,9 +982,7 @@ function areStateNodeCollectionsEqual( return true; } -/** - * https://www.w3.org/TR/scxml/#microstepProcedure - */ +/** https://www.w3.org/TR/scxml/#microstepProcedure */ export function microstep< TContext extends MachineContext, TEvent extends EventObject @@ -1828,7 +1822,8 @@ function selectEventlessTransitions( } /** - * Resolves a partial state value with its full representation in the state node's machine. + * Resolves a partial state value with its full representation in the state + * node's machine. * * @param stateValue The partial state value to resolve. */ diff --git a/packages/core/src/system.ts b/packages/core/src/system.ts index b96d584861..2b96123563 100644 --- a/packages/core/src/system.ts +++ b/packages/core/src/system.ts @@ -48,21 +48,13 @@ function createScheduledEventId( } export interface ActorSystem { - /** - * @internal - */ + /** @internal */ _bookId: () => string; - /** - * @internal - */ + /** @internal */ _register: (sessionId: string, actorRef: AnyActorRef) => string; - /** - * @internal - */ + /** @internal */ _unregister: (actorRef: AnyActorRef) => void; - /** - * @internal - */ + /** @internal */ _set: (key: K, actorRef: T['actors'][K]) => void; get: (key: K) => T['actors'][K] | undefined; @@ -71,15 +63,11 @@ export interface ActorSystem { | Observer | ((inspectionEvent: InspectionEvent) => void) ) => Subscription; - /** - * @internal - */ + /** @internal */ _sendInspectionEvent: ( event: HomomorphicOmit ) => void; - /** - * @internal - */ + /** @internal */ _relay: ( source: AnyActorRef | undefined, target: AnyActorRef, @@ -89,9 +77,7 @@ export interface ActorSystem { getSnapshot: () => { _scheduledEvents: Record; }; - /** - * @internal - */ + /** @internal */ _snapshot: { _scheduledEvents: Record; }; diff --git a/packages/core/src/toPromise.ts b/packages/core/src/toPromise.ts index cf8f1c27f8..50cae3cf0c 100644 --- a/packages/core/src/toPromise.ts +++ b/packages/core/src/toPromise.ts @@ -4,6 +4,7 @@ import { AnyActorRef, OutputFrom } from './types.ts'; * Returns a promise that resolves to the `output` of the actor when it is done. * * @example + * * ```ts * const machine = createMachine({ * // ... diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index 34049782fa..796ef6be8b 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -26,18 +26,20 @@ export type GetParameterizedParams = T extends any ? ('params' extends keyof T ? T['params'] : undefined) : never; /** - * * @remarks - * - * `T | unknown` reduces to `unknown` and that can be problematic when it comes to contextual typing. - * It especially is a problem when the union has a function member, like here: + * `T | unknown` reduces to `unknown` and that can be problematic when it comes + * to contextual typing. It especially is a problem when the union has a + * function member, like here: * * ```ts - * declare function test(cbOrVal: ((arg: number) => unknown) | unknown): void; - * test((arg) => {}) // oops, implicit any + * declare function test( + * cbOrVal: ((arg: number) => unknown) | unknown + * ): void; + * test((arg) => {}); // oops, implicit any * ``` * - * This type can be used to avoid this problem. This union represents the same value space as `unknown`. + * This type can be used to avoid this problem. This union represents the same + * value space as `unknown`. */ export type NonReducibleUnknown = {} | null | undefined; export type AnyFunction = (...args: any[]) => any; @@ -69,9 +71,7 @@ export type Cast = A extends B ? A : B; // @TODO: Replace with native `NoInfer` when TS issue gets fixed: // https://github.com/microsoft/TypeScript/pull/57673 export type DoNotInfer = [T][T extends any ? 0 : any]; -/** - * @deprecated Use the built-in `NoInfer` type instead - */ +/** @deprecated Use the built-in `NoInfer` type instead */ export type NoInfer = DoNotInfer; export type LowInfer = T & {}; @@ -80,13 +80,9 @@ export type MetaObject = Record; export type Lazy = () => T; export type MaybeLazy = T | Lazy; -/** - * The full definition of an event, with a string `type`. - */ +/** The full definition of an event, with a string `type`. */ export type EventObject = { - /** - * The type of event that is sent. - */ + /** The type of event that is sent. */ type: string; }; @@ -291,13 +287,13 @@ export interface StateValueMap { } /** - * The string or object representing the state value relative to the parent state node. + * The string or object representing the state value relative to the parent + * state node. * * @remarks - * * - For a child atomic state node, this is a string, e.g., `"pending"`. - * - * - For complex state nodes, this is an object, e.g., `{ success: "someChildState" }`. + * - For complex state nodes, this is an object, e.g., `{ success: + * "someChildState" }`. */ export type StateValue = string | StateValueMap; @@ -378,16 +374,15 @@ export interface InvokeDefinition< id: string; systemId: string | undefined; - /** - * The source of the actor logic to be invoked - */ + /** The source of the actor logic to be invoked */ src: AnyActorLogic | string; input?: | Mapper | NonReducibleUnknown; /** - * The transition to take upon the invoked child machine reaching its final top-level state. + * The transition to take upon the invoked child machine reaching its final + * top-level state. */ onDone?: | string @@ -405,7 +400,8 @@ export interface InvokeDefinition< > >; /** - * The transition to take upon the invoked child machine sending an error event. + * The transition to take upon the invoked child machine sending an error + * event. */ onError?: | string @@ -614,14 +610,12 @@ type DistributeActors< | Compute< { systemId?: string; - /** - * The source of the machine to be invoked, or the machine itself. - */ + /** 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`). + * 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']; @@ -637,7 +631,8 @@ type DistributeActors< > | InputFrom; /** - * The transition to take upon the invoked child machine reaching its final top-level state. + * The transition to take upon the invoked child machine reaching + * its final top-level state. */ onDone?: | string @@ -655,7 +650,8 @@ type DistributeActors< > >; /** - * The transition to take upon the invoked child machine sending an error event. + * The transition to take upon the invoked child machine sending an + * error event. */ onError?: | string @@ -775,16 +771,15 @@ export type InvokeConfig< id?: string; systemId?: string; - /** - * The source of the machine to be invoked, or the machine itself. - */ + /** The source of the machine to be invoked, or the machine itself. */ src: AnyActorLogic | string; // TODO: fix types input?: | Mapper | NonReducibleUnknown; /** - * The transition to take upon the invoked child machine reaching its final top-level state. + * The transition to take upon the invoked child machine reaching its + * final top-level state. */ onDone?: | string @@ -802,7 +797,8 @@ export type InvokeConfig< > >; /** - * The transition to take upon the invoked child machine sending an error event. + * The transition to take upon the invoked child machine sending an error + * event. */ onError?: | string @@ -860,9 +856,7 @@ export interface StateNodeConfig< TEmitted extends EventObject, TMeta extends MetaObject > { - /** - * The initial state transition. - */ + /** The initial state transition. */ initial?: | InitialTransitionConfig | string @@ -870,21 +864,21 @@ export interface StateNodeConfig< /** * The type of this state node: * - * - `'atomic'` - no child state nodes - * - `'compound'` - nested child state nodes (XOR) - * - `'parallel'` - orthogonal nested child state nodes (AND) - * - `'history'` - history state node - * - `'final'` - final state node + * - `'atomic'` - no child state nodes + * - `'compound'` - nested child state nodes (XOR) + * - `'parallel'` - orthogonal nested child state nodes (AND) + * - `'history'` - history state node + * - `'final'` - final state node */ type?: 'atomic' | 'compound' | 'parallel' | 'final' | 'history'; /** - * Indicates whether the state node is a history state node, and what - * type of history: - * shallow, deep, true (shallow), false (none), undefined (none) + * Indicates whether the state node is a history state node, and what type of + * history: shallow, deep, true (shallow), false (none), undefined (none) */ history?: 'shallow' | 'deep' | boolean | undefined; /** - * The mapping of state node keys to their state node configurations (recursive). + * The mapping of state node keys to their state node configurations + * (recursive). */ states?: | StatesConfig< @@ -901,7 +895,8 @@ export interface StateNodeConfig< > | undefined; /** - * The services to invoke upon entering this state node. These services will be stopped upon exiting this state node. + * The services to invoke upon entering this state node. These services will + * be stopped upon exiting this state node. */ invoke?: SingleOrArray< InvokeConfig< @@ -915,9 +910,7 @@ export interface StateNodeConfig< TMeta > >; - /** - * The mapping of event types to their potential transition(s). - */ + /** The mapping of event types to their potential transition(s). */ on?: TransitionsConfig< TContext, TEvent, @@ -928,9 +921,7 @@ export interface StateNodeConfig< TEmitted, TMeta >; - /** - * The action(s) to be executed upon entering the state node. - */ + /** The action(s) to be executed upon entering the state node. */ entry?: Actions< TContext, TEvent, @@ -942,9 +933,7 @@ export interface StateNodeConfig< TDelay, TEmitted >; - /** - * The action(s) to be executed upon exiting the state node. - */ + /** The action(s) to be executed upon exiting the state node. */ exit?: Actions< TContext, TEvent, @@ -957,9 +946,11 @@ export interface StateNodeConfig< TEmitted >; /** - * The potential transition(s) to be taken upon reaching a final child state node. + * The potential transition(s) to be taken upon reaching a final child state + * node. * - * This is equivalent to defining a `[done(id)]` transition on this state node's `on` property. + * This is equivalent to defining a `[done(id)]` transition on this state + * node's `on` property. */ onDone?: | string @@ -978,13 +969,15 @@ export interface StateNodeConfig< > | undefined; /** - * The mapping (or array) of delays (in milliseconds) to their potential transition(s). - * The delayed transitions are taken after the specified delay in an interpreter. + * The mapping (or array) of delays (in milliseconds) to their potential + * transition(s). The delayed transitions are taken after the specified delay + * in an interpreter. */ after?: DelayedTransitions; /** - * An eventless transition that is always taken when this state node is active. + * An eventless transition that is always taken when this state node is + * active. */ always?: TransitionConfigOrTarget< TContext, @@ -999,38 +992,38 @@ export interface StateNodeConfig< >; parent?: StateNode; /** - * The meta data associated with this state node, which will be returned in State instances. + * The meta data associated with this state node, which will be returned in + * State instances. */ meta?: TMeta; /** - * The output data sent with the "xstate.done.state._id_" event if this is a final state node. + * The output data sent with the "xstate.done.state._id_" event if this is a + * final state node. * - * The output data will be evaluated with the current `context` and placed on the `.data` property - * of the event. + * The output data will be evaluated with the current `context` and placed on + * the `.data` property of the event. */ output?: Mapper | NonReducibleUnknown; /** - * The unique ID of the state node, which can be referenced as a transition target via the - * `#id` syntax. + * The unique ID of the state node, which can be referenced as a transition + * target via the `#id` syntax. */ id?: string | undefined; /** - * The order this state node appears. Corresponds to the implicit document order. + * The order this state node appears. Corresponds to the implicit document + * order. */ order?: number; /** - * The tags for this state node, which are accumulated into the `state.tags` property. + * The tags for this state node, which are accumulated into the `state.tags` + * property. */ tags?: SingleOrArray; - /** - * A text description of the state node - */ + /** A text description of the state node */ description?: string; - /** - * A default target for a history state - */ + /** A default target for a history state */ target?: string; } @@ -1112,7 +1105,7 @@ export type AnyMachineSnapshot = MachineSnapshot< any >; -/** @deprecated use `AnyMachineSnapshot` instead */ +/** @deprecated Use `AnyMachineSnapshot` instead */ export type AnyState = AnyMachineSnapshot; export type AnyStateMachine = StateMachine< @@ -1229,9 +1222,7 @@ export type DelayConfig< > = number | DelayExpr; // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something -/** - * @hidden - */ +/** @ignore */ export interface MachineImplementationsSimplified< TContext extends MachineContext, TEvent extends EventObject, @@ -1363,12 +1354,8 @@ export type MachineConfig< >, 'output' > & { - /** - * The initial context (extended state) - */ - /** - * The machine's own version. - */ + /** The initial context (extended state) */ + /** The machine's own version. */ version?: string; // TODO: make it conditionally required output?: Mapper | TOutput; @@ -1721,9 +1708,7 @@ export interface StateConfig< > { context: TContext; historyValue?: HistoryValue; - /** - * @internal - */ + /** @internal */ _nodes: Array>; children: Record; status: 'active' | 'done' | 'error' | 'stopped'; @@ -1748,10 +1733,12 @@ export interface StateConfig< export interface ActorOptions { /** - * The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions. + * The clock that is responsible for setting and clearing timeouts, such as + * delayed events and transitions. * * @remarks - * You can create your own “clock”. The clock interface is an object with two functions/methods: + * You can create your own “clock”. The clock interface is an object with two + * functions/methods: * * - `setTimeout` - same arguments as `window.setTimeout(fn, timeout)` * - `clearTimeout` - same arguments as `window.clearTimeout(id)` @@ -1759,74 +1746,65 @@ export interface ActorOptions { * By default, the native `setTimeout` and `clearTimeout` functions are used. * * For testing, XState provides `SimulatedClock`. - * * @see {@link Clock} * @see {@link SimulatedClock} */ clock?: Clock; /** - * Specifies the logger to be used for `log(...)` actions. Defaults to the native `console.log(...)` method. + * Specifies the logger to be used for `log(...)` actions. Defaults to the + * native `console.log(...)` method. */ logger?: (...args: any[]) => void; parent?: AnyActorRef; - /** - * @internal - */ + /** @internal */ syncSnapshot?: boolean; - /** - * The custom `id` for referencing this service. - */ + /** The custom `id` for referencing this service. */ id?: string; - /** - * @deprecated Use `inspect` instead. - */ + /** @deprecated Use `inspect` instead. */ devTools?: never; - /** - * The system ID to register this actor under. - */ + /** The system ID to register this actor under. */ systemId?: string; - /** - * The input data to pass to the actor. - */ + /** The input data to pass to the actor. */ input?: InputFrom; /** * Initializes actor logic from a specific persisted internal state. * * @remarks - * - * If the state is compatible with the actor logic, when the actor is started it will be at that persisted state. - * Actions from machine actors will not be re-executed, because they are assumed to have been already executed. - * However, invocations will be restarted, and spawned actors will be restored recursively. + * If the state is compatible with the actor logic, when the actor is started + * it will be at that persisted state. Actions from machine actors will not be + * re-executed, because they are assumed to have been already executed. + * However, invocations will be restarted, and spawned actors will be restored + * recursively. * * Can be generated with {@link Actor.getPersistedSnapshot}. - * * @see https://stately.ai/docs/persistence */ snapshot?: Snapshot; - /** - * @deprecated Use `snapshot` instead. - */ + /** @deprecated Use `snapshot` instead. */ state?: Snapshot; - /** - * The source actor logic. - */ + /** The source actor logic. */ src?: string | AnyActorLogic; /** - * A callback function or observer object which can be used to inspect actor system updates. + * A callback function or observer object which can be used to inspect actor + * system updates. * * @remarks - * If a callback function is provided, it can accept an inspection event argument. The types of inspection events that can be observed include: + * If a callback function is provided, it can accept an inspection event + * argument. The types of inspection events that can be observed include: * * - `@xstate.actor` - An actor ref has been created in the system - * - `@xstate.event` - An event was sent from a source actor ref to a target actor ref in the system - * - `@xstate.snapshot` - An actor ref emitted a snapshot due to a received event + * - `@xstate.event` - An event was sent from a source actor ref to a target + * actor ref in the system + * - `@xstate.snapshot` - An actor ref emitted a snapshot due to a received + * event * * @example + * * ```ts * import { createMachine } from 'xstate'; * @@ -1859,9 +1837,11 @@ export interface ActorOptions { * }); * ``` * - * Alternately, an observer object (`{ next?, error?, complete? }`) can be provided: + * Alternately, an observer object (`{ next?, error?, complete? }`) can be + * provided: * * @example + * * ```ts * const actor = createActor(machine, { * inspect: { @@ -1897,9 +1877,7 @@ export interface ActorOptions { export type AnyActor = Actor; -/** - * @deprecated Use `AnyActor` instead. - */ +/** @deprecated Use `AnyActor` instead. */ export type AnyInterpreter = AnyActor; // Based on RxJS types @@ -1967,9 +1945,7 @@ export interface ActorRef< TEmitted extends EventObject = EventObject > extends Subscribable, InteropObservable { - /** - * The unique identifier for this actor relative to its parent. - */ + /** The unique identifier for this actor relative to its parent. */ id: string; sessionId: string; /** @internal */ @@ -2066,9 +2042,7 @@ export type ActorRefFrom = ReturnTypeOrValue extends infer R export type DevToolsAdapter = (service: AnyActor) => void; -/** - * @deprecated Use `Actor` instead. - */ +/** @deprecated Use `Actor` instead. */ export type InterpreterFrom< T extends AnyStateMachine | ((...args: any[]) => AnyStateMachine) > = ReturnTypeOrValue extends StateMachine< @@ -2199,8 +2173,9 @@ export interface ActorLogic< /** 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. + * Transition function that processes the current state and an incoming + * message to produce a new state. + * * @param snapshot - The current state. * @param message - The incoming message. * @param actorScope - The actor scope. @@ -2213,6 +2188,7 @@ export interface ActorLogic< ) => 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. @@ -2222,8 +2198,10 @@ export interface ActorLogic< 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 `getPersistedSnapshot`. + * Called when Actor is created to restore the internal state of the actor + * given a persisted state. The persisted state can be created by + * `getPersistedSnapshot`. + * * @param persistedState - The persisted state to restore from. * @param actorScope - The actor scope. * @returns The restored state. @@ -2234,6 +2212,7 @@ export interface ActorLogic< ) => TSnapshot; /** * Called when the actor is started. + * * @param snapshot - The starting state. * @param actorScope - The actor scope. */ @@ -2242,8 +2221,9 @@ export interface ActorLogic< actorScope: ActorScope ) => void; /** - * Obtains the internal state of the actor in a representation which can be be persisted. - * The persisted state can be restored by `restoreSnapshot`. + * Obtains the internal state of the actor in a representation which can be be + * persisted. The persisted state can be restored by `restoreSnapshot`. + * * @param snapshot - The current state. * @returns The a representation of the internal state to be persisted. */ @@ -2470,9 +2450,7 @@ export interface StateMachineTypes { emitted: EventObject; } -/** - * @deprecated - */ +/** @deprecated */ export interface ResolvedStateMachineTypes< TContext extends MachineContext, TEvent extends EventObject, diff --git a/packages/core/src/waitFor.ts b/packages/core/src/waitFor.ts index 68b083e9f6..d125788d71 100644 --- a/packages/core/src/waitFor.ts +++ b/packages/core/src/waitFor.ts @@ -3,8 +3,8 @@ import { ActorRef, AnyActorRef, SnapshotFrom, Subscription } from './types.ts'; interface WaitForOptions { /** - * How long to wait before rejecting, if no emitted - * state satisfies the predicate. + * How long to wait before rejecting, if no emitted state satisfies the + * predicate. * * @defaultValue Infinity */ @@ -16,14 +16,14 @@ const defaultWaitForOptions: WaitForOptions = { }; /** - * Subscribes to an actor ref and waits for its emitted value to satisfy - * a predicate, and then resolves with that value. - * Will throw if the desired state is not reached after an optional timeout. - * (defaults to Infinity). + * Subscribes to an actor ref and waits for its emitted value to satisfy a + * predicate, and then resolves with that value. Will throw if the desired state + * is not reached after an optional timeout. (defaults to Infinity). * * @example + * * ```js - * const state = await waitFor(someService, state => { + * const state = await waitFor(someService, (state) => { * return state.hasTag('loaded'); * }); * @@ -33,8 +33,8 @@ const defaultWaitForOptions: WaitForOptions = { * @param actorRef The actor ref to subscribe to * @param predicate Determines if a value matches the condition to wait for * @param options - * @returns A promise that eventually resolves to the emitted value - * that matches the condition + * @returns A promise that eventually resolves to the emitted value that matches + * the condition */ export function waitFor( actorRef: TActorRef, diff --git a/packages/xstate-graph/src/TestModel.ts b/packages/xstate-graph/src/TestModel.ts index 84eea6f2bd..46a5ac089f 100644 --- a/packages/xstate-graph/src/TestModel.ts +++ b/packages/xstate-graph/src/TestModel.ts @@ -57,8 +57,8 @@ type GetPathOptions< TInput > = Partial> & { /** - * Whether to allow deduplicate paths so that paths that are contained by longer paths - * are included. + * Whether to allow deduplicate paths so that paths that are contained by + * longer paths are included. * * @default false */ @@ -66,11 +66,11 @@ type GetPathOptions< }; /** - * Creates a test model that represents an abstract model of a - * system under test (SUT). + * Creates a test model that represents an abstract model of a system under test + * (SUT). * - * The test model is used to generate test paths, which are used to - * verify that states in the model are reachable in the SUT. + * The test model is used to generate test paths, which are used to verify that + * states in the model are reachable in the SUT. */ export class TestModel< TSnapshot extends Snapshot, @@ -205,8 +205,8 @@ export class TestModel< } /** - * An array of adjacencies, which are objects that represent each `state` with the `nextState` - * given the `event`. + * An array of adjacencies, which are objects that represent each `state` with + * the `nextState` given the `event`. */ public getAdjacencyMap(): AdjacencyMap { const adjMap = getAdjacencyMap(this.testLogic, this.options); @@ -388,18 +388,18 @@ function serializeMachineTransition( } /** - * Creates a test model that represents an abstract model of a - * system under test (SUT). + * Creates a test model that represents an abstract model of a system under test + * (SUT). * - * The test model is used to generate test paths, which are used to - * verify that states in the `machine` are reachable in the SUT. + * The test model is used to generate test paths, which are used to verify that + * states in the `machine` are reachable in the SUT. * * @example * * ```js * const toggleModel = createModel(toggleMachine).withEvents({ * TOGGLE: { - * exec: async page => { + * exec: async (page) => { * await page.click('input'); * } * } @@ -408,8 +408,9 @@ function serializeMachineTransition( * * @param machine The state machine used to represent the abstract model. * @param options Options for the created test model: - * - `events`: an object mapping string event types (e.g., `SUBMIT`) - * to an event test config (e.g., `{exec: () => {...}, cases: [...]}`) + * + * - `events`: an object mapping string event types (e.g., `SUBMIT`) to an event + * test config (e.g., `{exec: () => {...}, cases: [...]}`) */ export function createTestModel( machine: TMachine, diff --git a/packages/xstate-graph/src/deduplicatePaths.ts b/packages/xstate-graph/src/deduplicatePaths.ts index c5d7c5de13..20caf9a018 100644 --- a/packages/xstate-graph/src/deduplicatePaths.ts +++ b/packages/xstate-graph/src/deduplicatePaths.ts @@ -3,8 +3,8 @@ import { EventObject, Snapshot } from 'xstate'; import { simpleStringify } from './utils.ts'; /** - * Deduplicates your paths so that A -> B - * is not executed separately to A -> B -> C + * Deduplicates your paths so that A -> B is not executed separately to A -> B + * -> C */ export const deduplicatePaths = < TSnapshot extends Snapshot, @@ -13,9 +13,7 @@ export const deduplicatePaths = < paths: StatePath[], serializeEvent: (event: TEvent) => string = simpleStringify ): StatePath[] => { - /** - * Put all paths on the same level so we can dedup them - */ + /** Put all paths on the same level so we can dedup them */ const allPathsWithEventSequence: Array<{ path: StatePath; eventSequence: string[]; @@ -35,9 +33,7 @@ export const deduplicatePaths = < const superpathsWithEventSequence: typeof allPathsWithEventSequence = []; - /** - * Filter out the paths that are subpaths of superpaths - */ + /** Filter out the paths that are subpaths of superpaths */ pathLoop: for (const pathWithEventSequence of allPathsWithEventSequence) { // Check each existing superpath to see if the path is a subpath of it superpathLoop: for (const superpathWithEventSequence of superpathsWithEventSequence) { diff --git a/packages/xstate-graph/src/graph.ts b/packages/xstate-graph/src/graph.ts index 6561657fd5..b42f70562c 100644 --- a/packages/xstate-graph/src/graph.ts +++ b/packages/xstate-graph/src/graph.ts @@ -26,6 +26,7 @@ import { createMockActorScope } from './actorScope.ts'; /** * Returns all state nodes of the given `node`. + * * @param stateNode State node to recursively get child state nodes from */ export function getStateNodes( diff --git a/packages/xstate-graph/src/types.ts b/packages/xstate-graph/src/types.ts index 2604f5b89e..c5ace726a6 100644 --- a/packages/xstate-graph/src/types.ts +++ b/packages/xstate-graph/src/types.ts @@ -53,9 +53,7 @@ export type DirectedGraphNode = JSONSerializable< id: string; stateNode: StateNode; children: DirectedGraphNode[]; - /** - * The edges representing all transitions from this `stateNode`. - */ + /** The edges representing all transitions from this `stateNode`. */ edges: DirectedGraphEdge[]; }, { @@ -78,13 +76,9 @@ export interface StatePlan< TSnapshot extends Snapshot, TEvent extends EventObject > { - /** - * The target state. - */ + /** The target state. */ state: TSnapshot; - /** - * The paths that reach the target state. - */ + /** The paths that reach the target state. */ paths: Array>; } @@ -92,17 +86,14 @@ export interface StatePath< TSnapshot extends Snapshot, TEvent extends EventObject > { - /** - * The ending state of the path. - */ + /** The ending state of the path. */ state: TSnapshot; /** - * The ordered array of state-event pairs (steps) which reach the ending `state`. + * The ordered array of state-event pairs (steps) which reach the ending + * `state`. */ steps: Steps; - /** - * The combined weight of all steps in the path. - */ + /** The combined weight of all steps in the path. */ weight: number; } @@ -117,13 +108,9 @@ export interface Step< TSnapshot extends Snapshot, TEvent extends EventObject > { - /** - * The event that resulted in the current state - */ + /** The event that resulted in the current state */ event: TEvent; - /** - * The current state after taking the event. - */ + /** The current state after taking the event. */ state: TSnapshot; } @@ -196,17 +183,14 @@ export interface TraversalConfig< > extends SerializationConfig { events: readonly TEvent[] | ((state: TSnapshot) => readonly TEvent[]); /** - * The maximum number of traversals to perform when calculating - * the state transition adjacency map. + * The maximum number of traversals to perform when calculating the state + * transition adjacency map. * * @default `Infinity` */ limit: number; fromState: TSnapshot | undefined; - /** - * When true, traversal of the adjacency map will stop - * for that current state. - */ + /** When true, traversal of the adjacency map will stop for that current state. */ stopWhen: ((state: TSnapshot) => boolean) | undefined; toState: ((state: TSnapshot) => boolean) | undefined; } @@ -321,8 +305,8 @@ export interface TestPath< > extends StatePath { description: string; /** - * Tests and executes each step in `steps` sequentially, and then - * tests the postcondition that the `state` is reached. + * Tests and executes each step in `steps` sequentially, and then tests the + * postcondition that the `state` is reached. */ test: (params: TestParam) => Promise; } @@ -333,8 +317,8 @@ export interface TestPathResult { export type StatePredicate = (state: TState) => boolean; /** - * Executes an effect using the `testContext` and `event` - * that triggers the represented `event`. + * Executes an effect using the `testContext` and `event` that triggers the + * represented `event`. */ export type EventExecutor< TSnapshot extends Snapshot, diff --git a/packages/xstate-inspect/src/types.ts b/packages/xstate-inspect/src/types.ts index 42d3829fc9..d96cdcd766 100644 --- a/packages/xstate-inspect/src/types.ts +++ b/packages/xstate-inspect/src/types.ts @@ -35,22 +35,16 @@ export interface Inspector { ) => { unsubscribe: () => void; }; - /** - * Disconnects the inspector. - */ + /** Disconnects the inspector. */ disconnect: () => void; } -/** - * Events that the receiver sends to the inspector - */ +/** Events that the receiver sends to the inspector */ export type ReceiverCommand = | { type: 'xstate.event'; event: string; service: string } | { type: 'xstate.inspecting' }; -/** - * Events that the receiver receives from the inspector - */ +/** Events that the receiver receives from the inspector */ export type ReceiverEvent = | { type: 'service.register'; diff --git a/packages/xstate-react/src/createActorContext.ts b/packages/xstate-react/src/createActorContext.ts index f5728d4743..e5e8a02b2e 100644 --- a/packages/xstate-react/src/createActorContext.ts +++ b/packages/xstate-react/src/createActorContext.ts @@ -15,9 +15,7 @@ export function createActorContext( Provider: (props: { children: React.ReactNode; options?: ActorOptions; - /** - * @deprecated Use `logic` instead. - */ + /** @deprecated Use `logic` instead. */ machine?: never; logic?: TLogic; }) => React.ReactElement; @@ -34,9 +32,7 @@ export function createActorContext( }: { children: React.ReactNode; logic: TLogic; - /** - * @deprecated Use `logic` instead. - */ + /** @deprecated Use `logic` instead. */ machine?: never; options?: ActorOptions; }) { diff --git a/packages/xstate-react/src/useMachine.ts b/packages/xstate-react/src/useMachine.ts index 58dc109e6c..b27be21a50 100644 --- a/packages/xstate-react/src/useMachine.ts +++ b/packages/xstate-react/src/useMachine.ts @@ -1,9 +1,7 @@ import { Actor, ActorOptions, AnyStateMachine, StateFrom } from 'xstate'; import { useActor } from './useActor.ts'; -/** - * @alias useActor - */ +/** @alias useActor */ export function useMachine( machine: TMachine, options: ActorOptions = {} diff --git a/packages/xstate-solid/src/createImmutable.ts b/packages/xstate-solid/src/createImmutable.ts index c838475b63..7764371bac 100644 --- a/packages/xstate-solid/src/createImmutable.ts +++ b/packages/xstate-solid/src/createImmutable.ts @@ -91,8 +91,8 @@ const updateStore = ( }; /** - * Based on Ryan Carniato's createImmutable prototype - * Clones the initial value and diffs updates + * Based on Ryan Carniato's createImmutable prototype Clones the initial value + * and diffs updates */ export function createImmutable( init: T diff --git a/packages/xstate-solid/src/deepClone.ts b/packages/xstate-solid/src/deepClone.ts index 40d92125dd..1eeaa76a2d 100644 --- a/packages/xstate-solid/src/deepClone.ts +++ b/packages/xstate-solid/src/deepClone.ts @@ -10,11 +10,12 @@ export function isWrappable(obj: any): obj is object { } /** - * Accepts any value and creates a deep clone if it is an object - * This function only deeply clones objects, any classes with be copied + * Accepts any value and creates a deep clone if it is an object This function + * only deeply clones objects, any classes with be copied + * * @param value The variable to deeply clone * @param valueRefs A WeakMap that stores a reference from the original - * object/array to the cloned object/array + * object/array to the cloned object/array */ const clone = ( value: T, diff --git a/packages/xstate-store/src/fromStore.ts b/packages/xstate-store/src/fromStore.ts index 15e2fb8b9c..cee8a02ebd 100644 --- a/packages/xstate-store/src/fromStore.ts +++ b/packages/xstate-store/src/fromStore.ts @@ -7,10 +7,13 @@ import { } from './types'; /** - * An actor logic creator which creates store [actor logic](https://stately.ai/docs/actors#actor-logic) for use with XState. + * An actor logic creator which creates store [actor + * logic](https://stately.ai/docs/actors#actor-logic) for use with XState. * - * @param initialContext The initial context for the store, either a function that returns context based on input, or the context itself - * @param transitions The transitions object defining how the context updates due to events + * @param initialContext The initial context for the store, either a function + * that returns context based on input, or the context itself + * @param transitions The transitions object defining how the context updates + * due to events * @returns An actor logic creator function that creates store actor logic */ export function fromStore< diff --git a/packages/xstate-store/src/react.ts b/packages/xstate-store/src/react.ts index 8d4ff1e5ae..7fe45a0cbc 100644 --- a/packages/xstate-store/src/react.ts +++ b/packages/xstate-store/src/react.ts @@ -11,21 +11,24 @@ function defaultCompare(a: T, b: T) { } /** - * A React hook that subscribes to the `store` and selects a value from the store's snapshot, - * with an optional compare function. - * + * A React hook that subscribes to the `store` and selects a value from the + * store's snapshot, with an optional compare function. + * * @example - ```ts - function Component() { - const count = useSelector(store, (s) => s.count); - - return
{count}
; - } - ``` - * + * + * ```ts + * function Component() { + * const count = useSelector(store, (s) => s.count); + * + * return
{count}
; + * } + * ``` + * * @param store The store, created from `createStore(…)` - * @param selector A function which takes in the `snapshot` and returns a selected value - * @param compare An optional function which compares the selected value to the previous value + * @param selector A function which takes in the `snapshot` and returns a + * selected value + * @param compare An optional function which compares the selected value to the + * previous value * @returns The selected value */ export function useSelector | undefined, T>( diff --git a/packages/xstate-store/src/store.ts b/packages/xstate-store/src/store.ts index 6ecbbd4c97..338723fd9e 100644 --- a/packages/xstate-store/src/store.ts +++ b/packages/xstate-store/src/store.ts @@ -109,33 +109,34 @@ function createStoreCore< } /** - * Creates a **store** that has its own internal state and can be sent events that - * update its internal state based on transitions. + * Creates a **store** that has its own internal state and can be sent events + * that update its internal state based on transitions. * * @example - ```ts - const store = createStore({ - // Initial context - { count: 0 }, - // Transitions - { - on: { - inc: (context, event: { by: number }) => { - return { - count: context.count + event.by - } - } - } - } - }); - - store.subscribe((snapshot) => { - console.log(snapshot); - }); - - store.send({ type: 'inc', by: 5 }); - // Logs { context: { count: 5 }, status: 'active', ... } - ``` + * + * ```ts + * const store = createStore({ + * // Initial context + * { count: 0 }, + * // Transitions + * { + * on: { + * inc: (context, event: { by: number }) => { + * return { + * count: context.count + event.by + * } + * } + * } + * } + * }); + * + * store.subscribe((snapshot) => { + * console.log(snapshot); + * }); + * + * store.send({ type: 'inc', by: 5 }); + * // Logs { context: { count: 5 }, status: 'active', ... } + * ``` */ export function createStore< TContext extends StoreContext, @@ -155,33 +156,34 @@ export function createStore< } /** - * Creates a `Store` with a provided producer (such as Immer's `producer(…)` - * A store has its own internal state and can receive events. + * Creates a `Store` with a provided producer (such as Immer's `producer(…)` A + * store has its own internal state and can receive events. * * @example - ```ts - import { produce } from 'immer'; - - const store = createStoreWithProducer(produce, { - // Initial context - { count: 0 }, - // Transitions - { - on: { - inc: (context, event: { by: number }) => { - context.count += event.by; - } - } - } - }); - - store.subscribe((snapshot) => { - console.log(snapshot); - }); - - store.send({ type: 'inc', by: 5 }); - // Logs { context: { count: 5 }, status: 'active', ... } - ``` + * + * ```ts + * import { produce } from 'immer'; + * + * const store = createStoreWithProducer(produce, { + * // Initial context + * { count: 0 }, + * // Transitions + * { + * on: { + * inc: (context, event: { by: number }) => { + * context.count += event.by; + * } + * } + * } + * }); + * + * store.subscribe((snapshot) => { + * console.log(snapshot); + * }); + * + * store.send({ type: 'inc', by: 5 }); + * // Logs { context: { count: 5 }, status: 'active', ... } + * ``` */ export function createStoreWithProducer< TContext extends StoreContext, @@ -208,7 +210,9 @@ declare global { } /** - * Creates a store function, which is a function that accepts the current snapshot and an event and returns a new snapshot. + * Creates a store function, which is a function that accepts the current + * snapshot and an event and returns a new snapshot. + * * @param transitions * @param updater * @returns diff --git a/packages/xstate-store/src/types.ts b/packages/xstate-store/src/types.ts index 631d9a5154..aa2ded7e35 100644 --- a/packages/xstate-store/src/types.ts +++ b/packages/xstate-store/src/types.ts @@ -53,9 +53,10 @@ export type StoreSnapshot = Snapshot & { /** * An actor-like object that: - * - has its own state - * - can receive events - * - is observable + * + * - Has its own state + * - Can receive events + * - Is observable */ export interface Store extends Subscribable>, @@ -102,13 +103,9 @@ export interface Subscribable extends InteropSubscribable { // Same as MachineContext (for now) export type StoreContext = Record; -/** - * The full definition of an event, with a string `type`. - */ +/** The full definition of an event, with a string `type`. */ export type EventObject = { - /** - * The type of event that is sent. - */ + /** The type of event that is sent. */ type: string; }; type Values = T[keyof T]; diff --git a/packages/xstate-vue/src/useMachine.ts b/packages/xstate-vue/src/useMachine.ts index f07135c53e..f207a0d7d7 100644 --- a/packages/xstate-vue/src/useMachine.ts +++ b/packages/xstate-vue/src/useMachine.ts @@ -8,9 +8,7 @@ import { } from 'xstate'; import { useActor } from './useActor.ts'; -/** - * @alias useActor - */ +/** @alias useActor */ export function useMachine( machine: TMachine, options: ActorOptions = {} diff --git a/yarn.lock b/yarn.lock index ad9c8efefd..9eaf4fbc6d 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2029,6 +2029,13 @@ dependencies: "@types/node" "*" +"@types/debug@^4.0.0": + version "4.1.12" + resolved "https://registry.yarnpkg.com/@types/debug/-/debug-4.1.12.tgz#a155f21690871953410df4b6b6f53187f0500917" + integrity sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ== + dependencies: + "@types/ms" "*" + "@types/estree@*": version "0.0.45" resolved "https://registry.yarnpkg.com/@types/estree/-/estree-0.0.45.tgz#e9387572998e5ecdac221950dab3e8c3b16af884" @@ -2113,6 +2120,13 @@ "@types/tough-cookie" "*" parse5 "^7.0.0" +"@types/mdast@^4.0.0": + version "4.0.4" + resolved "https://registry.yarnpkg.com/@types/mdast/-/mdast-4.0.4.tgz#7ccf72edd2f1aa7dd3437e180c64373585804dd6" + integrity sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA== + dependencies: + "@types/unist" "*" + "@types/minimatch@*": version "3.0.3" resolved "https://registry.yarnpkg.com/@types/minimatch/-/minimatch-3.0.3.tgz#3dca0e3f33b200fc7d1139c0cd96c1268cadfd9d" @@ -2123,6 +2137,11 @@ resolved "https://registry.yarnpkg.com/@types/minimist/-/minimist-1.2.1.tgz#283f669ff76d7b8260df8ab7a4262cc83d988256" integrity sha512-fZQQafSREFyuZcdWFAExYjBiCL7AUCdgsk80iO0q4yihYYdcIiH28CcuPTGFgLOCC8RlW49GSQxdHwZP+I7CNg== +"@types/ms@*": + version "0.7.34" + resolved "https://registry.yarnpkg.com/@types/ms/-/ms-0.7.34.tgz#10964ba0dee6ac4cd462e2795b6bebd407303433" + integrity sha512-nG96G3Wp6acyAgJqGasjODb+acrI7KltPiRxzHPXnP3NgI28bpQDRv53olbqGXbfcgF5aiiHmO3xpwEpS5Ld9g== + "@types/node@*": version "14.14.17" resolved "https://registry.yarnpkg.com/@types/node/-/node-14.14.17.tgz#29fab92f3986c0e379968ad3c2043683d8020dbb" @@ -2228,6 +2247,11 @@ resolved "https://registry.yarnpkg.com/@types/tough-cookie/-/tough-cookie-4.0.0.tgz#fef1904e4668b6e5ecee60c52cc6a078ffa6697d" integrity sha512-I99sngh224D0M7XgW1s120zxCt3VYQ3IQsuw3P3jbq5GG4yc79+ZjyKznyOGIQrflfylLgcfekeZW/vk0yng6A== +"@types/unist@*", "@types/unist@^3.0.0": + version "3.0.2" + resolved "https://registry.yarnpkg.com/@types/unist/-/unist-3.0.2.tgz#6dd61e43ef60b34086287f83683a5c1b2dc53d20" + integrity sha512-dqId9J8K/vGi5Zr7oo212BGii5m3q5Hxlkwy3WpYuKPklmBEvsbMYYyLxAQpSffdLl/gdW0XUpKWFvYmyoWCoQ== + "@types/use-sync-external-store@^0.0.3": version "0.0.3" resolved "https://registry.yarnpkg.com/@types/use-sync-external-store/-/use-sync-external-store-0.0.3.tgz#b6725d5f4af24ace33b36fafd295136e75509f43" @@ -2858,6 +2882,11 @@ binary-extensions@^2.0.0: resolved "https://registry.yarnpkg.com/binary-extensions/-/binary-extensions-2.2.0.tgz#75f502eeaf9ffde42fc98829645be4ea76bd9e2d" integrity sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA== +binary-searching@^2.0.5: + version "2.0.5" + resolved "https://registry.yarnpkg.com/binary-searching/-/binary-searching-2.0.5.tgz#ab6d08d51cd1b58878ae208ab61988f885b22dd3" + integrity sha512-v4N2l3RxL+m4zDxyxz3Ne2aTmiPn8ZUpKFpdPtO+ItW1NcTCXA7JeHG5GMBSvoKSkQZ9ycS+EouDVxYB9ufKWA== + bluebird@^3.7.2: version "3.7.2" resolved "https://registry.yarnpkg.com/bluebird/-/bluebird-3.7.2.tgz#9f229c15be272454ffa973ace0dbee79a1b0c36f" @@ -3118,6 +3147,11 @@ char-regex@^2.0.0: resolved "https://registry.yarnpkg.com/char-regex/-/char-regex-2.0.1.tgz#6dafdb25f9d3349914079f010ba8d0e6ff9cd01e" integrity sha512-oSvEeo6ZUD7NepqAat3RqoucZ5SeqLJgOvVIwkafu6IP3V0pO38s/ypdVUmDDK6qIIHNlYHJAKX9E7R7HoKElw== +character-entities@^2.0.0: + version "2.0.2" + resolved "https://registry.yarnpkg.com/character-entities/-/character-entities-2.0.2.tgz#2d09c2e72cd9523076ccb21157dff66ad43fcc22" + integrity sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ== + chardet@^0.7.0: version "0.7.0" resolved "https://registry.yarnpkg.com/chardet/-/chardet-0.7.0.tgz#90094849f0937f2eedc2425d0d28a9e5f0cbad9e" @@ -3290,6 +3324,11 @@ commander@^2.12.1, commander@^2.14.1, commander@^2.18.0, commander@^2.20.0, comm resolved "https://registry.yarnpkg.com/commander/-/commander-2.20.3.tgz#fd485e84c03eb4881c20722ba48035e8531aeb33" integrity sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ== +comment-parser@^1.4.0: + version "1.4.1" + resolved "https://registry.yarnpkg.com/comment-parser/-/comment-parser-1.4.1.tgz#bdafead37961ac079be11eb7ec65c4d021eaf9cc" + integrity sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg== + commondir@^1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/commondir/-/commondir-1.0.1.tgz#ddd800da0c66127393cca5950ea968a3aaf1253b" @@ -3561,6 +3600,13 @@ debug@^3.1.0: dependencies: ms "^2.1.1" +debug@^4.0.0: + version "4.3.5" + resolved "https://registry.yarnpkg.com/debug/-/debug-4.3.5.tgz#e83444eceb9fedd4a1da56d671ae2446a01a6e1e" + integrity sha512-pt0bNEmneDIvdL1Xsd9oDQ/wrQRkXDT4AUWlNZNPKvW5x/jyO9VFXkJUP07vQ2upmw5PlaITaPKc31jK13V+jg== + dependencies: + ms "2.1.2" + decamelize-keys@^1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/decamelize-keys/-/decamelize-keys-1.1.0.tgz#d171a87933252807eb3cb61dc1c1445d078df2d9" @@ -3579,6 +3625,13 @@ decimal.js@^10.4.2: resolved "https://registry.yarnpkg.com/decimal.js/-/decimal.js-10.4.3.tgz#1044092884d245d1b7f65725fa4ad4c6f781cc23" integrity sha512-VBBaLc1MgL5XpzgIP7ny5Z6Nx3UrRkIViUkPUdtl9aya5amy3De1gsUUSB1g3+3sExYNjCAsAznmukyxCb1GRA== +decode-named-character-reference@^1.0.0: + version "1.0.2" + resolved "https://registry.yarnpkg.com/decode-named-character-reference/-/decode-named-character-reference-1.0.2.tgz#daabac9690874c394c81e4162a0304b35d824f0e" + integrity sha512-O8x12RzrUF8xyVcY0KJowWsmaJxQbmy0/EtnNtHRpsOcT7dFk5W598coHqBVpmWo1oQQfsCqfCmkZN5DJrZVdg== + dependencies: + character-entities "^2.0.0" + decode-uri-component@^0.2.0: version "0.2.0" resolved "https://registry.yarnpkg.com/decode-uri-component/-/decode-uri-component-0.2.0.tgz#eb3913333458775cb84cd1a1fae062106bb87545" @@ -3740,6 +3793,11 @@ delayed-stream@~1.0.0: resolved "https://registry.yarnpkg.com/delayed-stream/-/delayed-stream-1.0.0.tgz#df3ae199acadfb7d440aaae0b29e2272b24ec619" integrity sha1-3zrhmayt+31ECqrgsp4icrJOxhk= +dequal@^2.0.0: + version "2.0.3" + resolved "https://registry.yarnpkg.com/dequal/-/dequal-2.0.3.tgz#2644214f1997d39ed0ee0ece72335490a7ac67be" + integrity sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA== + detect-file@^1.0.0: version "1.0.0" resolved "https://registry.yarnpkg.com/detect-file/-/detect-file-1.0.0.tgz#f0d66d03672a825cb1b73bdb3fe62310c8e552b7" @@ -3755,6 +3813,13 @@ detect-newline@^3.0.0: resolved "https://registry.yarnpkg.com/detect-newline/-/detect-newline-3.1.0.tgz#576f5dfc63ae1a192ff192d8ad3af6308991b651" integrity sha512-TLz+x/vEXm/Y7P7wn1EJFNLxYpUD4TgMosxY6fAVJUnJMbupHBOncxyWUG9OpTaH9EBD7uFI5LfEgmMOc54DsA== +devlop@^1.0.0: + version "1.1.0" + resolved "https://registry.yarnpkg.com/devlop/-/devlop-1.1.0.tgz#4db7c2ca4dc6e0e834c30be70c94bbc976dc7018" + integrity sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA== + dependencies: + dequal "^2.0.0" + diff-sequences@^29.3.1: version "29.3.1" resolved "https://registry.yarnpkg.com/diff-sequences/-/diff-sequences-29.3.1.tgz#104b5b95fe725932421a9c6e5b4bef84c3f2249e" @@ -6861,6 +6926,31 @@ matcher@^1.0.0: dependencies: escape-string-regexp "^1.0.4" +mdast-util-from-markdown@^2.0.0: + version "2.0.1" + resolved "https://registry.yarnpkg.com/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.1.tgz#32a6e8f512b416e1f51eb817fc64bd867ebcd9cc" + integrity sha512-aJEUyzZ6TzlsX2s5B4Of7lN7EQtAxvtradMMglCQDyaTFgse6CmtmdJ15ElnVRlCg1vpNyVtbem0PWzlNieZsA== + dependencies: + "@types/mdast" "^4.0.0" + "@types/unist" "^3.0.0" + decode-named-character-reference "^1.0.0" + devlop "^1.0.0" + mdast-util-to-string "^4.0.0" + micromark "^4.0.0" + micromark-util-decode-numeric-character-reference "^2.0.0" + micromark-util-decode-string "^2.0.0" + micromark-util-normalize-identifier "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + unist-util-stringify-position "^4.0.0" + +mdast-util-to-string@^4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz#7a5121475556a04e7eddeb67b264aae79d312814" + integrity sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg== + dependencies: + "@types/mdast" "^4.0.0" + mdn-data@2.0.30: version "2.0.30" resolved "https://registry.yarnpkg.com/mdn-data/-/mdn-data-2.0.30.tgz#ce4df6f80af6cfbe218ecd5c552ba13c4dfa08cc" @@ -6930,6 +7020,200 @@ methods@~1.1.1: resolved "https://registry.yarnpkg.com/methods/-/methods-1.1.2.tgz#5529a4d67654134edcc5266656835b0f851afcee" integrity sha1-VSmk1nZUE07cxSZmVoNbD4Ua/O4= +micromark-core-commonmark@^2.0.0: + version "2.0.1" + resolved "https://registry.yarnpkg.com/micromark-core-commonmark/-/micromark-core-commonmark-2.0.1.tgz#9a45510557d068605c6e9a80f282b2bb8581e43d" + integrity sha512-CUQyKr1e///ZODyD1U3xit6zXwy1a8q2a1S1HKtIlmgvurrEpaw/Y9y6KSIbF8P59cn/NjzHyO+Q2fAyYLQrAA== + dependencies: + decode-named-character-reference "^1.0.0" + devlop "^1.0.0" + micromark-factory-destination "^2.0.0" + micromark-factory-label "^2.0.0" + micromark-factory-space "^2.0.0" + micromark-factory-title "^2.0.0" + micromark-factory-whitespace "^2.0.0" + micromark-util-character "^2.0.0" + micromark-util-chunked "^2.0.0" + micromark-util-classify-character "^2.0.0" + micromark-util-html-tag-name "^2.0.0" + micromark-util-normalize-identifier "^2.0.0" + micromark-util-resolve-all "^2.0.0" + micromark-util-subtokenize "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-factory-destination@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-factory-destination/-/micromark-factory-destination-2.0.0.tgz#857c94debd2c873cba34e0445ab26b74f6a6ec07" + integrity sha512-j9DGrQLm/Uhl2tCzcbLhy5kXsgkHUrjJHg4fFAeoMRwJmJerT9aw4FEhIbZStWN8A3qMwOp1uzHr4UL8AInxtA== + dependencies: + micromark-util-character "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-factory-label@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-factory-label/-/micromark-factory-label-2.0.0.tgz#17c5c2e66ce39ad6f4fc4cbf40d972f9096f726a" + integrity sha512-RR3i96ohZGde//4WSe/dJsxOX6vxIg9TimLAS3i4EhBAFx8Sm5SmqVfR8E87DPSR31nEAjZfbt91OMZWcNgdZw== + dependencies: + devlop "^1.0.0" + micromark-util-character "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-factory-space@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-factory-space/-/micromark-factory-space-2.0.0.tgz#5e7afd5929c23b96566d0e1ae018ae4fcf81d030" + integrity sha512-TKr+LIDX2pkBJXFLzpyPyljzYK3MtmllMUMODTQJIUfDGncESaqB90db9IAUcz4AZAJFdd8U9zOp9ty1458rxg== + dependencies: + micromark-util-character "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-factory-title@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-factory-title/-/micromark-factory-title-2.0.0.tgz#726140fc77892af524705d689e1cf06c8a83ea95" + integrity sha512-jY8CSxmpWLOxS+t8W+FG3Xigc0RDQA9bKMY/EwILvsesiRniiVMejYTE4wumNc2f4UbAa4WsHqe3J1QS1sli+A== + dependencies: + micromark-factory-space "^2.0.0" + micromark-util-character "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-factory-whitespace@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.0.tgz#9e92eb0f5468083381f923d9653632b3cfb5f763" + integrity sha512-28kbwaBjc5yAI1XadbdPYHX/eDnqaUFVikLwrO7FDnKG7lpgxnvk/XGRhX/PN0mOZ+dBSZ+LgunHS+6tYQAzhA== + dependencies: + micromark-factory-space "^2.0.0" + micromark-util-character "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-util-character@^2.0.0: + version "2.1.0" + resolved "https://registry.yarnpkg.com/micromark-util-character/-/micromark-util-character-2.1.0.tgz#31320ace16b4644316f6bf057531689c71e2aee1" + integrity sha512-KvOVV+X1yLBfs9dCBSopq/+G1PcgT3lAK07mC4BzXi5E7ahzMAF8oIupDDJ6mievI6F+lAATkbQQlQixJfT3aQ== + dependencies: + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-util-chunked@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-chunked/-/micromark-util-chunked-2.0.0.tgz#e51f4db85fb203a79dbfef23fd41b2f03dc2ef89" + integrity sha512-anK8SWmNphkXdaKgz5hJvGa7l00qmcaUQoMYsBwDlSKFKjc6gjGXPDw3FNL3Nbwq5L8gE+RCbGqTw49FK5Qyvg== + dependencies: + micromark-util-symbol "^2.0.0" + +micromark-util-classify-character@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-classify-character/-/micromark-util-classify-character-2.0.0.tgz#8c7537c20d0750b12df31f86e976d1d951165f34" + integrity sha512-S0ze2R9GH+fu41FA7pbSqNWObo/kzwf8rN/+IGlW/4tC6oACOs8B++bh+i9bVyNnwCcuksbFwsBme5OCKXCwIw== + dependencies: + micromark-util-character "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-util-combine-extensions@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.0.tgz#75d6ab65c58b7403616db8d6b31315013bfb7ee5" + integrity sha512-vZZio48k7ON0fVS3CUgFatWHoKbbLTK/rT7pzpJ4Bjp5JjkZeasRfrS9wsBdDJK2cJLHMckXZdzPSSr1B8a4oQ== + dependencies: + micromark-util-chunked "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-util-decode-numeric-character-reference@^2.0.0: + version "2.0.1" + resolved "https://registry.yarnpkg.com/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.1.tgz#2698bbb38f2a9ba6310e359f99fcb2b35a0d2bd5" + integrity sha512-bmkNc7z8Wn6kgjZmVHOX3SowGmVdhYS7yBpMnuMnPzDq/6xwVA604DuOXMZTO1lvq01g+Adfa0pE2UKGlxL1XQ== + dependencies: + micromark-util-symbol "^2.0.0" + +micromark-util-decode-string@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-decode-string/-/micromark-util-decode-string-2.0.0.tgz#7dfa3a63c45aecaa17824e656bcdb01f9737154a" + integrity sha512-r4Sc6leeUTn3P6gk20aFMj2ntPwn6qpDZqWvYmAG6NgvFTIlj4WtrAudLi65qYoaGdXYViXYw2pkmn7QnIFasA== + dependencies: + decode-named-character-reference "^1.0.0" + micromark-util-character "^2.0.0" + micromark-util-decode-numeric-character-reference "^2.0.0" + micromark-util-symbol "^2.0.0" + +micromark-util-encode@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-encode/-/micromark-util-encode-2.0.0.tgz#0921ac7953dc3f1fd281e3d1932decfdb9382ab1" + integrity sha512-pS+ROfCXAGLWCOc8egcBvT0kf27GoWMqtdarNfDcjb6YLuV5cM3ioG45Ys2qOVqeqSbjaKg72vU+Wby3eddPsA== + +micromark-util-html-tag-name@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.0.tgz#ae34b01cbe063363847670284c6255bb12138ec4" + integrity sha512-xNn4Pqkj2puRhKdKTm8t1YHC/BAjx6CEwRFXntTaRf/x16aqka6ouVoutm+QdkISTlT7e2zU7U4ZdlDLJd2Mcw== + +micromark-util-normalize-identifier@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.0.tgz#91f9a4e65fe66cc80c53b35b0254ad67aa431d8b" + integrity sha512-2xhYT0sfo85FMrUPtHcPo2rrp1lwbDEEzpx7jiH2xXJLqBuy4H0GgXk5ToU8IEwoROtXuL8ND0ttVa4rNqYK3w== + dependencies: + micromark-util-symbol "^2.0.0" + +micromark-util-resolve-all@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.0.tgz#189656e7e1a53d0c86a38a652b284a252389f364" + integrity sha512-6KU6qO7DZ7GJkaCgwBNtplXCvGkJToU86ybBAUdavvgsCiG8lSSvYxr9MhwmQ+udpzywHsl4RpGJsYWG1pDOcA== + dependencies: + micromark-util-types "^2.0.0" + +micromark-util-sanitize-uri@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.0.tgz#ec8fbf0258e9e6d8f13d9e4770f9be64342673de" + integrity sha512-WhYv5UEcZrbAtlsnPuChHUAsu/iBPOVaEVsntLBIdpibO0ddy8OzavZz3iL2xVvBZOpolujSliP65Kq0/7KIYw== + dependencies: + micromark-util-character "^2.0.0" + micromark-util-encode "^2.0.0" + micromark-util-symbol "^2.0.0" + +micromark-util-subtokenize@^2.0.0: + version "2.0.1" + resolved "https://registry.yarnpkg.com/micromark-util-subtokenize/-/micromark-util-subtokenize-2.0.1.tgz#76129c49ac65da6e479c09d0ec4b5f29ec6eace5" + integrity sha512-jZNtiFl/1aY73yS3UGQkutD0UbhTt68qnRpw2Pifmz5wV9h8gOVsN70v+Lq/f1rKaU/W8pxRe8y8Q9FX1AOe1Q== + dependencies: + devlop "^1.0.0" + micromark-util-chunked "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + +micromark-util-symbol@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-symbol/-/micromark-util-symbol-2.0.0.tgz#12225c8f95edf8b17254e47080ce0862d5db8044" + integrity sha512-8JZt9ElZ5kyTnO94muPxIGS8oyElRJaiJO8EzV6ZSyGQ1Is8xwl4Q45qU5UOg+bGH4AikWziz0iN4sFLWs8PGw== + +micromark-util-types@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/micromark-util-types/-/micromark-util-types-2.0.0.tgz#63b4b7ffeb35d3ecf50d1ca20e68fc7caa36d95e" + integrity sha512-oNh6S2WMHWRZrmutsRmDDfkzKtxF+bc2VxLC9dvtrDIRFln627VsFP6fLMgTryGDljgLPjkrzQSDcPrjPyDJ5w== + +micromark@^4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/micromark/-/micromark-4.0.0.tgz#84746a249ebd904d9658cfabc1e8e5f32cbc6249" + integrity sha512-o/sd0nMof8kYff+TqcDx3VSrgBTcZpSvYcAHIfHhv5VAuNmisCxjhx6YmxS8PFEpb9z5WKWKPdzf0jM23ro3RQ== + dependencies: + "@types/debug" "^4.0.0" + debug "^4.0.0" + decode-named-character-reference "^1.0.0" + devlop "^1.0.0" + micromark-core-commonmark "^2.0.0" + micromark-factory-space "^2.0.0" + micromark-util-character "^2.0.0" + micromark-util-chunked "^2.0.0" + micromark-util-combine-extensions "^2.0.0" + micromark-util-decode-numeric-character-reference "^2.0.0" + micromark-util-encode "^2.0.0" + micromark-util-normalize-identifier "^2.0.0" + micromark-util-resolve-all "^2.0.0" + micromark-util-sanitize-uri "^2.0.0" + micromark-util-subtokenize "^2.0.0" + micromark-util-symbol "^2.0.0" + micromark-util-types "^2.0.0" + micromatch@^3.0.4, micromatch@^3.1.10, micromatch@^3.1.8: version "3.1.10" resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-3.1.10.tgz#70859bc95c9840952f359a068a3fc49f9ecfac23" @@ -7868,6 +8152,15 @@ prepend-http@^2.0.0: resolved "https://registry.yarnpkg.com/prepend-http/-/prepend-http-2.0.0.tgz#e92434bfa5ea8c19f41cdfd401d741a3c819d897" integrity sha1-6SQ0v6XqjBn0HN/UAddBo8gZ2Jc= +prettier-plugin-jsdoc@^1.3.0: + version "1.3.0" + resolved "https://registry.yarnpkg.com/prettier-plugin-jsdoc/-/prettier-plugin-jsdoc-1.3.0.tgz#98e9cbecc5b8725801cc8a4233a16748500e867b" + integrity sha512-cQm8xIa0fN9ieJFMXACQd6JPycl+8ouOijAqUqu44EF/s4fXL3Wi9sKXuEaodsEWgCN42Xby/bNhqgM1iWx4uw== + dependencies: + binary-searching "^2.0.5" + comment-parser "^1.4.0" + mdast-util-from-markdown "^2.0.0" + prettier@^2.7.1: version "2.8.3" resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.8.3.tgz#ab697b1d3dd46fb4626fbe2f543afe0cc98d8632" @@ -9549,6 +9842,13 @@ uniq@^1.0.1: resolved "https://registry.yarnpkg.com/uniq/-/uniq-1.0.1.tgz#b31c5ae8254844a3a8281541ce2b04b865a734ff" integrity sha1-sxxa6CVIRKOoKBVBzisEuGWnNP8= +unist-util-stringify-position@^4.0.0: + version "4.0.0" + resolved "https://registry.yarnpkg.com/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz#449c6e21a880e0855bf5aabadeb3a740314abac2" + integrity sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ== + dependencies: + "@types/unist" "^3.0.0" + universalify@^0.1.0: version "0.1.2" resolved "https://registry.yarnpkg.com/universalify/-/universalify-0.1.2.tgz#b646f69be3942dabcecc9d6639c80dc105efaa66"