xstate
Version:
Finite State Machines and Statecharts for the Modern Web.
218 lines (217 loc) • 8.27 kB
TypeScript
import { symbolObservable } from "./symbolObservable.js";
import { AnyActorSystem, Clock } from "./system.js";
import type { AnyActorLogic, AnyActorRef, ConditionalRequired, EmittedFrom, EventFromLogic, InputFrom, IsNotNever, Snapshot, SnapshotFrom } from "./types.js";
import { ActorOptions, ActorRef, EventObject, InteropSubscribable, Observer, Subscription } from "./types.js";
export declare const $$ACTOR_TYPE = 1;
export type SnapshotListener<TLogic extends AnyActorLogic> = (snapshot: SnapshotFrom<TLogic>) => void;
export type EventListener<TEvent extends EventObject = EventObject> = (event: TEvent) => void;
export type Listener = () => void;
export type ErrorListener = (error: any) => void;
export declare enum ProcessingStatus {
NotStarted = 0,
Running = 1,
Stopped = 2
}
/**
* 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 declare class Actor<TLogic extends AnyActorLogic> implements ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>> {
logic: TLogic;
/**
* The current internal state of the actor.
*/
private _snapshot;
/**
* The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.
*/
clock: Clock;
options: Readonly<ActorOptions<TLogic>>;
/**
* The unique identifier for this actor relative to its parent.
*/
id: string;
private mailbox;
private observers;
private eventListeners;
private logger;
_parent?: AnyActorRef;
ref: ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>>;
private _actorScope;
private _systemId;
/**
* The globally unique process ID for this invocation.
*/
sessionId: string;
/**
* The system to which this actor belongs.
*/
system: AnyActorSystem;
private _doneEvent?;
src: string | AnyActorLogic;
/**
* 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
*/
constructor(logic: TLogic, options?: ActorOptions<TLogic>);
private _initState;
private _deferred;
private update;
/**
* 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:
* - A plain function that receives the latest snapshot, or
* - An observer object whose `.next(snapshot)` method receives the latest snapshot
*
* @example
* ```ts
* // Observer as a plain function
* const subscription = actor.subscribe((snapshot) => {
* console.log(snapshot);
* });
* ```
*
* @example
* ```ts
* // Observer as an object
* const subscription = actor.subscribe({
* next(snapshot) {
* console.log(snapshot);
* },
* error(err) {
* // ...
* },
* 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:
*
* @example
* ```ts
* const subscription = actor.subscribe((snapshot) => {
* // ...
* });
*
* // Unsubscribe the observer
* subscription.unsubscribe();
* ```
*
* 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
*/
subscribe(observer: Observer<SnapshotFrom<TLogic>>): Subscription;
subscribe(nextListener?: (snapshot: SnapshotFrom<TLogic>) => void, errorListener?: (error: any) => void, completeListener?: () => void): Subscription;
on<TType extends EmittedFrom<TLogic>['type']>(type: TType, handler: (emitted: EmittedFrom<TLogic> & {
type: TType;
}) => void): Subscription;
/**
* Starts the Actor from the initial state
*/
start(): this;
private _process;
private _stop;
/**
* Stops the Actor and unsubscribe all listeners.
*/
stop(): this;
private _complete;
private _reportError;
private _error;
private _stopProcedure;
/**
* Sends an event to the running Actor to trigger a transition.
*
* @param event The event to send
*/
send(event: EventFromLogic<TLogic>): void;
private attachDevTools;
toJSON(): {
xstate$$type: number;
id: string;
};
/**
* Obtain the internal state of the actor, which can be persisted.
*
* @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.
*
* Can be restored with {@link ActorOptions.state}
*
* @see https://stately.ai/docs/persistence
*/
getPersistedSnapshot(): Snapshot<unknown>;
[symbolObservable](): InteropSubscribable<SnapshotFrom<TLogic>>;
/**
* Read an actor’s snapshot synchronously.
*
* @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.
*
* @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).
*/
getSnapshot(): SnapshotFrom<TLogic>;
}
type RequiredOptions<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? never : 'input';
/**
* 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.
*
* @example
* ```ts
* import { createActor } from 'xstate';
* import { someActorLogic } from './someActorLogic.ts';
*
* // Creating the actor, which implicitly creates an actor system with itself as the root actor
* const actor = createActor(someActorLogic);
*
* actor.subscribe((snapshot) => {
* console.log(snapshot);
* });
*
* // Actors must be started by calling `actor.start()`, which will also start the actor system.
* actor.start();
*
* // Actors can receive events
* actor.send({ type: 'someEvent' });
*
* // You can stop root actors by calling `actor.stop()`, which will also stop the actor system and all actors in that system.
* 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 options - Actor options
*/
export declare function createActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: ConditionalRequired<[
options?: ActorOptions<TLogic> & {
[K in RequiredOptions<TLogic>]: unknown;
}
], IsNotNever<RequiredOptions<TLogic>>>): Actor<TLogic>;
/**
* Creates a new Interpreter instance for the given machine with the provided options, if any.
*
* @deprecated Use `createActor` instead
*/
export declare const interpret: typeof createActor;
/**
* @deprecated Use `Actor` instead.
*/
export type Interpreter = typeof Actor;
export {};