xstate 5.32.0 → 6.0.0-alpha.1

package/dist/declarations/src/actors/observable.d.ts

@@ -1,8 +1,18 @@
+import { StandardSchemaV1 } from "../schema.types.js";
 import { AnyActorSystem } from "../system.js";
-import { ActorLogic, ActorRefFromLogic, EventObject, NonReducibleUnknown, Snapshot, Subscribable, Subscription } from "../types.js";
+import { ActorLogic, ActorFromLogic, ActorRefFromLogic, EventObject, NonReducibleUnknown, Snapshot, Subscribable, Subscription } from "../types.js";
 export type ObservableSnapshot<TContext, TInput extends NonReducibleUnknown> = Snapshot<undefined> & {
     context: TContext | undefined;
     input: TInput | undefined;
+    effects?: Record<string, {
+        status: 'active';
+    } | {
+        status: 'done';
+        output?: unknown;
+    } | {
+        status: 'error';
+        error: unknown;
+    }>;
     _subscription: Subscription | undefined;
 };
 export type ObservableActorLogic<TContext, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject> = ActorLogic<ObservableSnapshot<TContext, TInput>, {
@@ -10,14 +20,15 @@ export type ObservableActorLogic<TContext, TInput extends NonReducibleUnknown, T
     [k: string]: unknown;
 }, TInput, AnyActorSystem, TEmitted>;
 /**
- * Represents an actor created by `fromObservable` or `fromEventObservable`.
+ * Represents an actor created by `createObservableLogic` or
+ * `createEventObservableLogic`.
  *
  * The type of `self` within the actor's logic.
  *
  * @example
  *
  * ```ts
- * import { fromObservable, createActor } from 'xstate';
+ * import { createObservableLogic, createActor } from 'xstate';
  * import { interval } from 'rxjs';
  *
  * // The type of the value observed by the actor's logic.
@@ -27,21 +38,48 @@ export type ObservableActorLogic<TContext, TInput extends NonReducibleUnknown, T
  *
  * // Actor logic that observes a number incremented every `input.period`
  * // milliseconds (default: 1_000).
- * const logic = fromObservable<Context, Input>(({ input, self }) => {
- *   self;
- *   // ^? ObservableActorRef<Event, Input>
+ * const logic = createObservableLogic<Context, Input>(
+ *   ({ input, self }) => {
+ *     self;
+ *     // ^? ObservableActor<Event, Input>
  *
- *   return interval(input.period ?? 1_000);
- * });
+ *     return interval(input.period ?? 1_000);
+ *   }
+ * );
  *
  * const actor = createActor(logic, { input: { period: 2_000 } });
- * //    ^? ObservableActorRef<Event, Input>
+ * //    ^? ObservableActor<Event, Input>
  * ```
  *
- * @see {@link fromObservable}
- * @see {@link fromEventObservable}
+ * @see {@link createObservableLogic}
+ * @see {@link createEventObservableLogic}
  */
 export type ObservableActorRef<TContext> = ActorRefFromLogic<ObservableActorLogic<TContext, any>>;
+type ObservableActor<TContext, TInput extends NonReducibleUnknown = any, TEmitted extends EventObject = EventObject> = ActorFromLogic<ObservableActorLogic<TContext, TInput, TEmitted>>;
+export type ObservableLogicFunction<TContext, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject> = ({ input, system, self, emit }: {
+    input: TInput;
+    system: AnyActorSystem;
+    self: ObservableActor<TContext, TInput, TEmitted>;
+    emit: (emitted: TEmitted) => void;
+}) => Subscribable<TContext>;
+export interface ObservableLogicConfig<TContext, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject, TInputSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    schemas?: {
+        input?: TInputSchema;
+    };
+    run: ObservableLogicFunction<TContext, TInput, TEmitted>;
+}
+export type EventObservableLogicFunction<TEvent extends EventObject, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject> = ({ input, system, self, emit }: {
+    input: TInput;
+    system: AnyActorSystem;
+    self: ObservableActor<TEvent, TInput, TEmitted>;
+    emit: (emitted: TEmitted) => void;
+}) => Subscribable<TEvent>;
+export interface EventObservableLogicConfig<TEvent extends EventObject, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject, TInputSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    schemas?: {
+        input?: TInputSchema;
+    };
+    run: EventObservableLogicFunction<TEvent, TInput, TEmitted>;
+}
 /**
  * Observable actor logic is described by an observable stream of values. Actors
  * created from observable logic (“observable actors”) can:
@@ -55,10 +93,10 @@ export type ObservableActorRef<TContext> = ActorRefFromLogic<ObservableActorLogi
  * @example
  *
  * ```ts
- * import { fromObservable, createActor } from 'xstate';
+ * import { createObservableLogic, createActor } from 'xstate';
  * import { interval } from 'rxjs';
  *
- * const logic = fromObservable((obj) => interval(1000));
+ * const logic = createObservableLogic((obj) => interval(1000));
  *
  * const actor = createActor(logic);
  *
@@ -86,12 +124,15 @@ export type ObservableActorRef<TContext> = ActorRefFromLogic<ObservableActorLogi
  * @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.
  */
-export declare function fromObservable<TContext, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(observableCreator: ({ input, system, self }: {
-    input: TInput;
-    system: AnyActorSystem;
-    self: ObservableActorRef<TContext>;
-    emit: (emitted: TEmitted) => void;
-}) => Subscribable<TContext>): ObservableActorLogic<TContext, TInput, TEmitted>;
+export declare function createObservableLogic<TContext, const TInputSchema extends StandardSchemaV1, TEmitted extends EventObject = EventObject>(config: ObservableLogicConfig<TContext, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, TInputSchema> & {
+    schemas: {
+        input: TInputSchema;
+    };
+}): ObservableActorLogic<TContext, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted>;
+export declare function createObservableLogic<TContext, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(config: ObservableLogicConfig<TContext, TInput, TEmitted> & {
+    schemas?: undefined;
+}): ObservableActorLogic<TContext, TInput, TEmitted>;
+export declare function createObservableLogic<TContext, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(observableCreator: ObservableLogicFunction<TContext, TInput, TEmitted>): ObservableActorLogic<TContext, TInput, TEmitted>;
 /**
  * Creates event observable logic that listens to an observable that delivers
  * event objects.
@@ -109,7 +150,7 @@ export declare function fromObservable<TContext, TInput extends NonReducibleUnkn
  *
  * ```ts
  * import {
- *   fromEventObservable,
+ *   createEventObservableLogic,
  *   Subscribable,
  *   EventObject,
  *   createMachine,
@@ -117,7 +158,7 @@ export declare function fromObservable<TContext, TInput extends NonReducibleUnkn
  * } from 'xstate';
  * import { fromEvent } from 'rxjs';
  *
- * const mouseClickLogic = fromEventObservable(
+ * const mouseClickLogic = createEventObservableLogic(
  *   () => fromEvent(document.body, 'click') as Subscribable<EventObject>
  * );
  *
@@ -143,9 +184,13 @@ export declare function fromObservable<TContext, TInput extends NonReducibleUnkn
  *   It should return a {@link Subscribable}, which is compatible with an RxJS
  *   Observable, although RxJS is not required to create them.
  */
-export declare function fromEventObservable<TEvent extends EventObject, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(lazyObservable: ({ input, system, self, emit }: {
-    input: TInput;
-    system: AnyActorSystem;
-    self: ObservableActorRef<TEvent>;
-    emit: (emitted: TEmitted) => void;
-}) => Subscribable<TEvent>): ObservableActorLogic<TEvent, TInput, TEmitted>;
+export declare function createEventObservableLogic<TEvent extends EventObject, const TInputSchema extends StandardSchemaV1, TEmitted extends EventObject = EventObject>(config: EventObservableLogicConfig<TEvent, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, TInputSchema> & {
+    schemas: {
+        input: TInputSchema;
+    };
+}): ObservableActorLogic<TEvent, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted>;
+export declare function createEventObservableLogic<TEvent extends EventObject, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(config: EventObservableLogicConfig<TEvent, TInput, TEmitted> & {
+    schemas?: undefined;
+}): ObservableActorLogic<TEvent, TInput, TEmitted>;
+export declare function createEventObservableLogic<TEvent extends EventObject, TInput extends NonReducibleUnknown, TEmitted extends EventObject = EventObject>(lazyObservable: EventObservableLogicFunction<TEvent, TInput, TEmitted>): ObservableActorLogic<TEvent, TInput, TEmitted>;
+export {};

package/dist/declarations/src/actors/promise.d.ts

@@ -1,22 +1,74 @@
+import { StandardSchemaV1 } from "../schema.types.js";
 import { AnyActorSystem } from "../system.js";
-import { ActorLogic, ActorRefFromLogic, EventObject, NonReducibleUnknown, Snapshot } from "../types.js";
-export type PromiseSnapshot<TOutput, TInput> = Snapshot<TOutput> & {
+import { ActorLogic, ActorFromLogic, ActorRefFromLogic, EventObject, NonReducibleUnknown, Snapshot } from "../types.js";
+export type AsyncSnapshot<TOutput, TInput> = Snapshot<TOutput> & {
     input: TInput | undefined;
+    effects?: Record<string, {
+        status: 'active';
+    } | {
+        status: 'done';
+        output?: unknown;
+    } | {
+        status: 'error';
+        error: unknown;
+    }>;
 };
-export type PromiseActorLogic<TOutput, TInput = unknown, TEmitted extends EventObject = EventObject> = ActorLogic<PromiseSnapshot<TOutput, TInput>, {
+export type AsyncActorLogic<TOutput, TInput = unknown, TEmitted extends EventObject = EventObject> = ActorLogic<AsyncSnapshot<TOutput, TInput>, {
     type: string;
     [k: string]: unknown;
-}, TInput, // input
-AnyActorSystem, TEmitted>;
+}, TInput, AnyActorSystem, TEmitted>;
+export type AsyncActorRef<TOutput> = ActorRefFromLogic<AsyncActorLogic<TOutput, unknown>>;
+type AsyncActor<TOutput, TInput = unknown, TEmitted extends EventObject = EventObject> = ActorFromLogic<AsyncActorLogic<TOutput, TInput, TEmitted>>;
+export interface LogicArgs<TOutput, TInput> {
+    /** Data that was provided to the async actor. */
+    input: TInput;
+    /** The actor system to which the async actor belongs. */
+    system: AnyActorSystem;
+    /** The async actor. */
+    self: AsyncActor<TOutput, TInput>;
+    /** Aborted when the async actor is stopped or times out. */
+    signal: AbortSignal;
+}
+export interface LogicEnqueue<TEmitted extends EventObject> {
+    /** Emits an event that can be observed with `actor.on(...)`. */
+    emit: (emitted: TEmitted) => void;
+    /**
+     * Executes async work as a durable effect keyed by `key`.
+     *
+     * @experimental The durability semantics (step journaling, replay, and
+     *   resumption across persistence) are not finalized and may change.
+     */
+    step: <TStepOutput>(key: string, exec: () => TStepOutput | PromiseLike<TStepOutput>) => Promise<TStepOutput>;
+}
+export type LogicFunction<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject> = (args: LogicArgs<TOutput, TInput>, enq: LogicEnqueue<TEmitted>) => PromiseLike<TOutput>;
+export interface LogicConfig<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject, TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    /**
+     * Stable identifier for this async logic. This identifies the logic, not a
+     * particular actor instance.
+     */
+    id?: string;
+    /** Schemas for inferring async logic types. */
+    schemas?: {
+        input?: TInputSchema;
+        output?: TOutputSchema;
+    };
+    /** Maximum time this async logic may run before it is aborted and errors. */
+    timeout?: number | string;
+    /** The async work to execute when the actor starts. */
+    run: LogicFunction<TOutput, TInput, TEmitted>;
+}
+export declare class TimeoutError extends Error {
+    constructor(timeout: number | string);
+}
 /**
- * Represents an actor created by `fromPromise`.
+ * Represents an actor created by `createAsyncLogic`.
  *
  * The type of `self` within the actor's logic.
  *
  * @example
  *
  * ```ts
- * import { fromPromise, createActor } from 'xstate';
+ * import { createAsyncLogic, createActor } from 'xstate';
  *
  * // The actor's resolved output
  * type Output = string;
@@ -24,51 +76,59 @@ AnyActorSystem, TEmitted>;
  * type Input = { message: string };
  *
  * // Actor logic that fetches the url of an image of a cat saying `input.message`.
- * const logic = fromPromise<Output, Input>(async ({ input, self }) => {
- *   self;
- *   // ^? PromiseActorRef<Output, Input>
- *
- *   const data = await fetch(
- *     `https://cataas.com/cat/says/${input.message}`
- *   );
- *   const url = await data.json();
- *   return url;
+ * const logic = createAsyncLogic<Output, Input>({
+ *   run: async ({ input, self }, enq) => {
+ *     self;
+ *     // ^? AsyncActor<Output, Input>
+ *     enq.emit({ type: 'request.start' });
+ *
+ *     const data = await fetch(
+ *       `https://cataas.com/cat/says/${input.message}`
+ *     );
+ *     const url = await data.json();
+ *     return url;
+ *   }
  * });
  *
  * const actor = createActor(logic, { input: { message: 'hello world' } });
- * //    ^? PromiseActorRef<Output, Input>
+ * //    ^? AsyncActor<Output, Input>
  * ```
  *
- * @see {@link fromPromise}
+ * @see {@link createAsyncLogic}
  */
-export type PromiseActorRef<TOutput> = ActorRefFromLogic<PromiseActorLogic<TOutput, unknown>>;
 /**
- * An actor logic creator which returns promise logic as defined by an async
+ * An actor logic creator which returns async logic as defined by an async
  * process that resolves or rejects after some time.
  *
- * Actors created from promise actor logic (“promise actors”) can:
+ * Actors created from async actor logic can:
  *
- * - Emit the resolved value of the promise
- * - Output the resolved value of the promise
+ * - Output the resolved value of the async process
+ * - Error with the rejected value of the async process
+ * - Abort when stopped or timed out
  *
- * Sending events to promise actors will have no effect.
+ * Sending events to async actors will have no effect.
  *
  * @example
  *
  * ```ts
- * const promiseLogic = fromPromise(async () => {
- *   const result = await fetch('https://example.com/...').then((data) =>
- *     data.json()
- *   );
- *
- *   return result;
+ * const asyncLogic = createAsyncLogic({
+ *   id: 'fetch-user',
+ *   timeout: '30s',
+ *   run: async ({ signal }, enq) => {
+ *     enq.emit({ type: 'request.start' });
+ *     const result = await fetch('https://example.com/...', {
+ *       signal
+ *     }).then((data) => data.json());
+ *
+ *     return result;
+ *   }
  * });
  *
- * const promiseActor = createActor(promiseLogic);
- * promiseActor.subscribe((snapshot) => {
+ * const asyncActor = createActor(asyncLogic);
+ * asyncActor.subscribe((snapshot) => {
  *   console.log(snapshot);
  * });
- * promiseActor.start();
+ * asyncActor.start();
  * // => {
  * //   output: undefined,
  * //   status: 'active'
@@ -83,22 +143,47 @@ export type PromiseActorRef<TOutput> = ActorRefFromLogic<PromiseActorLogic<TOutp
  * // }
  * ```
  *
- * @param promiseCreator A function which returns a Promise, and accepts an
- *   object with the following properties:
+ * @param asyncLogic A config object with a `run` function which returns a
+ *   Promise, and accepts an object with the following properties:
+ *
+ *   - `input` - Data that was provided to the async actor
+ *   - `self` - The async actor ref
+ *   - `system` - The actor system to which the async actor belongs
+ *   - `signal` - An abort signal for cancellation
  *
- *   - `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
+ *   `run` also receives an `enq` object with the following properties:
+ *
+ *   - `emit` - Emits an event that can be observed with `actor.on(...)`
  *
  * @see {@link https://stately.ai/docs/input | Input docs} for more information about how input is passed
  */
-export declare function fromPromise<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject>(promiseCreator: ({ input, system, self, signal, emit }: {
-    /** Data that was provided to the promise actor */
-    input: TInput;
-    /** The actor system to which the promise actor belongs */
-    system: AnyActorSystem;
-    /** The parent actor of the promise actor */
-    self: PromiseActorRef<TOutput>;
-    signal: AbortSignal;
-    emit: (emitted: TEmitted) => void;
-}) => PromiseLike<TOutput>): PromiseActorLogic<TOutput, TInput, TEmitted>;
+export declare function createAsyncLogic<const TInputSchema extends StandardSchemaV1, const TOutputSchema extends StandardSchemaV1, TEmitted extends EventObject = EventObject>(asyncLogic: LogicConfig<StandardSchemaV1.InferOutput<TOutputSchema>, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, TInputSchema, TOutputSchema> & {
+    schemas: {
+        input: TInputSchema;
+        output: TOutputSchema;
+    };
+}): AsyncActorLogic<StandardSchemaV1.InferOutput<TOutputSchema>, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted> & {
+    id?: string;
+};
+export declare function createAsyncLogic<TOutput, const TInputSchema extends StandardSchemaV1, TEmitted extends EventObject = EventObject>(asyncLogic: LogicConfig<TOutput, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted, TInputSchema> & {
+    schemas: {
+        input: TInputSchema;
+        output?: never;
+    };
+}): AsyncActorLogic<TOutput, StandardSchemaV1.InferOutput<TInputSchema>, TEmitted> & {
+    id?: string;
+};
+export declare function createAsyncLogic<const TOutputSchema extends StandardSchemaV1, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject>(asyncLogic: LogicConfig<StandardSchemaV1.InferOutput<TOutputSchema>, TInput, TEmitted, StandardSchemaV1, TOutputSchema> & {
+    schemas: {
+        input?: never;
+        output: TOutputSchema;
+    };
+}): AsyncActorLogic<StandardSchemaV1.InferOutput<TOutputSchema>, TInput, TEmitted> & {
+    id?: string;
+};
+export declare function createAsyncLogic<TOutput, TInput = NonReducibleUnknown, TEmitted extends EventObject = EventObject>(asyncLogic: Omit<LogicConfig<TOutput, TInput, TEmitted>, 'schemas'> & {
+    schemas?: undefined;
+}): AsyncActorLogic<TOutput, TInput, TEmitted> & {
+    id?: string;
+};
+export {};

package/dist/declarations/src/actors/subscription.d.ts

@@ -0,0 +1,22 @@
+import { AnyActorSystem } from "../system.js";
+import { ActorLogic, ActorRefFromLogic, AnyActorRef, EventObject, Snapshot } from "../types.js";
+export type SubscriptionSnapshot = Snapshot<undefined> & {
+    input: SubscriptionInput<any, any, any, any>;
+};
+export interface SubscriptionMappers<TSnapshot extends Snapshot<unknown>, TOutput, TMappedEvent extends EventObject> {
+    snapshot?: (snapshot: TSnapshot) => TMappedEvent;
+    done?: (output: TOutput) => TMappedEvent;
+    error?: (error: unknown) => TMappedEvent;
+}
+export interface SubscriptionInput<TSnapshot extends Snapshot<unknown>, TOutput, TMappedEvent extends EventObject, TMappers extends SubscriptionMappers<TSnapshot, TOutput, TMappedEvent>> {
+    actor: AnyActorRef;
+    mappers: TMappers;
+}
+export type SubscriptionActorLogic<TSnapshot extends Snapshot<unknown> = Snapshot<unknown>, TOutput = unknown, TMappedEvent extends EventObject = EventObject> = ActorLogic<SubscriptionSnapshot, EventObject, SubscriptionInput<TSnapshot, TOutput, TMappedEvent, SubscriptionMappers<TSnapshot, TOutput, TMappedEvent>>, AnyActorSystem, EventObject>;
+export type SubscriptionActorRef<TSnapshot extends Snapshot<unknown> = Snapshot<unknown>, TOutput = unknown, TMappedEvent extends EventObject = EventObject> = ActorRefFromLogic<SubscriptionActorLogic<TSnapshot, TOutput, TMappedEvent>>;
+/**
+ * Creates actor logic for subscribing to lifecycle events (done/error/snapshot)
+ * from another actor. Used internally by `enq.subscribeTo()`.
+ */
+export declare function createSubscriptionLogic<TSnapshot extends Snapshot<unknown> = Snapshot<unknown>, TOutput = unknown, TMappedEvent extends EventObject = EventObject>(): SubscriptionActorLogic<TSnapshot, TOutput, TMappedEvent>;
+export declare const subscriptionLogic: SubscriptionActorLogic<Snapshot<unknown>, unknown, EventObject>;

package/dist/declarations/src/atom.d.ts

@@ -0,0 +1,81 @@
+type Observer<T> = {
+    next?: (value: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+};
+interface Subscription {
+    unsubscribe(): void;
+}
+interface Readable<T> extends Subscribable<T> {
+    get: () => T;
+}
+interface Subscribable<T> {
+    subscribe(observer: Observer<T>): Subscription;
+    subscribe(next: (value: T) => void, error?: (error: any) => void, complete?: () => void): Subscription;
+}
+export interface BaseAtom<T> extends Subscribable<T>, Readable<T> {
+}
+export interface Atom<T> extends BaseAtom<T> {
+    set: (valueOrFn: T | ((prev: T) => T)) => void;
+}
+export interface ReducerAtom<TState, TEvent> extends BaseAtom<TState> {
+    send: (event: TEvent) => void;
+}
+export interface AtomOptions<T> {
+    compare?: (a: T, b: T) => boolean;
+}
+export interface AtomConfig<TValue, TInput> {
+    createAtom: undefined extends TInput ? (input?: TInput) => Atom<TValue> : (input: TInput) => Atom<TValue>;
+}
+export type AnyAtomConfig = AtomConfig<any, any>;
+export type ValueFromAtomConfig<TConfig extends AnyAtomConfig> = TConfig extends AtomConfig<infer TValue, any> ? TValue : never;
+export type InputFromAtomConfig<TConfig extends AnyAtomConfig> = TConfig extends AtomConfig<any, infer TInput> ? TInput : never;
+export type AnyAtom = BaseAtom<any>;
+export interface ReadonlyAtom<T> extends BaseAtom<T> {
+}
+/**
+ * Returns `true` if the value is an atom (writable, computed, async, or
+ * reducer). Lets actor-consuming APIs (e.g. `enq.subscribeTo`) accept atoms
+ * directly.
+ */
+export declare function isAtom(value: unknown): value is AnyAtom;
+/** The current state of an async atom. */
+export type AsyncAtomState<Data, Error = unknown> = {
+    status: 'pending';
+} | {
+    status: 'done';
+    data: Data;
+} | {
+    status: 'error';
+    error: Error;
+};
+/** Options passed to an async atom getter. */
+export interface AsyncAtomOptions {
+    /** Signal aborted when the async atom recomputes before this run settles. */
+    signal: AbortSignal;
+}
+/**
+ * Creates a read-only atom whose value is loaded from an async getter.
+ *
+ * The getter receives an `AbortSignal`; when the async atom recomputes, the
+ * previous signal is aborted and stale resolutions are ignored.
+ */
+export declare function createAsyncAtom<T>(getValue: (options: AsyncAtomOptions) => Promise<T>, options?: AtomOptions<AsyncAtomState<T>>): ReadonlyAtom<AsyncAtomState<T>>;
+/**
+ * Creates an atom.
+ *
+ * Pass a value for a writable atom or a getter for a computed read-only atom.
+ */
+export declare function createAtom<T>(getValue: (prev?: T) => T, options?: AtomOptions<T>): ReadonlyAtom<T>;
+export declare function createAtom<T>(initialValue: T, options?: AtomOptions<T>): Atom<T>;
+/**
+ * Creates an inert atom config that can be instantiated later.
+ *
+ * Useful for framework hooks that need to create a stable local atom from
+ * component input.
+ */
+export declare function createAtomConfig<T, TInput>(getInitialValue: (input: TInput) => T, options?: AtomOptions<T>): AtomConfig<T, TInput>;
+export declare function createAtomConfig<T>(initialValue: T, options?: AtomOptions<T>): AtomConfig<T, undefined>;
+/** Creates an atom whose updates are handled by a reducer function. */
+export declare function createReducerAtom<TState, TEvent>(initialValue: TState, reducer: (state: TState, event: TEvent) => TState, options?: AtomOptions<TState>): ReducerAtom<TState, TEvent>;
+export {};

package/dist/declarations/src/createActor.d.ts

@@ -1,8 +1,7 @@
 import { symbolObservable } from "./symbolObservable.js";
 import { AnyActorSystem, Clock } from "./system.js";
-export declare let executingCustomAction: boolean;
-import type { AnyActorLogic, AnyActorRef, ConditionalRequired, EmittedFrom, EventFromLogic, InputFrom, IsNotNever, Readable, Snapshot, SnapshotFrom } from "./types.js";
-import { ActorOptions, ActorRef, InteropSubscribable, Observer, Subscription } from "./types.js";
+import type { AnyActor, AnyActorLogic, EmittedFrom, EventFromLogic, SendableEventFromLogic, InputFrom, Snapshot, SnapshotFrom, Readable } from "./types.js";
+import { ActorOptions, ActorInstance, ActorRef, InteropSubscribable, Observer, Subscription } from "./types.js";
 export declare const $$ACTOR_TYPE = 1;
 export declare enum ProcessingStatus {
     NotStarted = 0,
@@ -13,8 +12,13 @@ export declare enum ProcessingStatus {
  * 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 the concrete runtime instance with lifecycle methods and
+ * system-owned internals. It also satisfies the narrower `ActorRef` contract,
+ * so consumer APIs should accept `ActorRef` when they only need to send events
+ * or read snapshots.
  */
-export declare class Actor<TLogic extends AnyActorLogic> implements ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>> {
+export declare class Actor<TLogic extends AnyActorLogic> implements ActorInstance<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>, SendableEventFromLogic<TLogic>> {
     logic: TLogic;
     /** The current internal state of the actor. */
     private _snapshot;
@@ -26,19 +30,26 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorRef<Sna
     options: Readonly<ActorOptions<TLogic>>;
     /** The unique identifier for this actor relative to its parent. */
     id: string;
+    private readonly _boundProcess;
     private mailbox;
     private observers;
     private eventListeners;
     private logger;
-    _parent?: AnyActorRef;
-    ref: ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>>;
+    _parent?: AnyActor;
+    ref: ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>, SendableEventFromLogic<TLogic>>;
     private _actorScope;
     systemId: string | undefined;
     /** The globally unique process ID for this invocation. */
     sessionId: string;
     /** The system to which this actor belongs. */
     system: AnyActorSystem;
-    private _doneEvent?;
+    trigger: {
+        [K in SendableEventFromLogic<TLogic>['type']]: {} extends Omit<Extract<SendableEventFromLogic<TLogic>, {
+            type: K;
+        }>, 'type'> ? () => void : (payload: Omit<Extract<SendableEventFromLogic<TLogic>, {
+            type: K;
+        }>, 'type'>) => void;
+    };
     src: string | AnyActorLogic;
     /**
      * Creates a new actor instance for the given logic with the provided options,
@@ -48,8 +59,10 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorRef<Sna
      * @param options Actor options
      */
     constructor(logic: TLogic, options?: ActorOptions<TLogic>);
-    private _initState;
     private _deferred;
+    private _pendingEffects?;
+    private _setErrorSnapshot;
+    private _next;
     private update;
     /**
      * Subscribe an observer to an actor’s snapshot values.
@@ -119,11 +132,9 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorRef<Sna
     /** 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;
     /**
@@ -131,8 +142,7 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorRef<Sna
      *
      * @param event The event to send
      */
-    send(event: EventFromLogic<TLogic>): void;
-    private attachDevTools;
+    send(event: SendableEventFromLogic<TLogic>): void;
     toJSON(): {
         xstate$$type: number;
         id: string;
@@ -162,11 +172,13 @@ export declare class Actor<TLogic extends AnyActorLogic> implements ActorRef<Sna
      * may emit a snapshot when a state transition occurs.
      *
      * Note that some actors, such as callback actors generated with
-     * `fromCallback`, will not emit snapshots.
+     * `createCallbackLogic`, 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>;
+    /** Read the actor's current snapshot as an atom value. */
+    get(): SnapshotFrom<TLogic>;
 }
 export type RequiredActorOptionsKeys<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? never : 'input';
 /**
@@ -203,25 +215,11 @@ export type RequiredActorOptionsKeys<TLogic extends AnyActorLogic> = undefined e
  *
  * @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}.
+ *   include {@link createCallbackLogic}, {@link createEventObservableLogic},
+ *   {@link createObservableLogic}, {@link createLogic}, and
+ *   {@link createAsyncLogic}.
  * @param options - Actor options
  */
-export declare function createActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: ConditionalRequired<[
-    options?: ActorOptions<TLogic> & {
-        [K in RequiredActorOptionsKeys<TLogic>]: unknown;
-    }
-], IsNotNever<RequiredActorOptionsKeys<TLogic>>>): Actor<TLogic>;
-/**
- * Creates a new Interpreter instance for the given machine with the provided
- * options, if any.
- *
- * @deprecated Use `createActor` instead
- * @alias
- */
-export declare const interpret: typeof createActor;
-/**
- * @deprecated Use `Actor` instead.
- * @alias
- */
-export type Interpreter = typeof Actor;
+export declare function createActor<TLogic extends AnyActorLogic>(logic: TLogic, options?: ActorOptions<TLogic> & {
+    [K in RequiredActorOptionsKeys<TLogic>]: unknown;
+}): Actor<TLogic>;