xstate/dist/declarations/src/actors/callback.d.ts

Finite State Machines and Statecharts for the Modern Web.

import { AnyActorSystem } from "../system.js";
import { ActorLogic, ActorRefFrom, AnyEventObject, EventObject, NonReducibleUnknown, Snapshot } from "../types.js";
export type CallbackSnapshot<TInput> = Snapshot<undefined> & {
    input: TInput;
};
export type CallbackActorLogic<TEvent extends EventObject, TInput = NonReducibleUnknown> = ActorLogic<CallbackSnapshot<TInput>, TEvent, TInput, AnyActorSystem, EventObject>;
export type CallbackActorRef<TEvent extends EventObject, TInput = NonReducibleUnknown> = ActorRefFrom<CallbackActorLogic<TEvent, TInput>>;
export type Receiver<TEvent extends EventObject> = (listener: {
    bivarianceHack(event: TEvent): void;
}['bivarianceHack']) => void;
export type InvokeCallback<TEvent extends EventObject = AnyEventObject, TSentEvent extends EventObject = AnyEventObject, TInput = NonReducibleUnknown> = ({ input, system, self, sendBack, receive }: {
    /**
     * 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
     */
    system: AnyActorSystem;
    /**
     * The parent actor of the callback actor
     */
    self: CallbackActorRef<TEvent>;
    /**
     * 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
     */
    receive: Receiver<TEvent>;
}) => (() => void) | void;
/**
 * 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.
 *
 * 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';
 *
 *   const handler = (event) => {
 *     if (lockStatus === 'locked') {
 *       return;
 *     }
 *     sendBack(event);
 *   };
 *
 *   receive((event) => {
 *     if (event.type === 'lock') {
 *       lockStatus = 'locked';
 *     } else if (event.type === 'unlock') {
 *       lockStatus = 'unlocked';
 *     }
 *   });
 *
 *   document.body.addEventListener('click', handler);
 *
 *   return () => {
 *     document.body.removeEventListener('click', handler);
 *   };
 * });
 * ```
 */
export declare function fromCallback<TEvent extends EventObject, TInput = NonReducibleUnknown>(invokeCallback: InvokeCallback<TEvent, AnyEventObject, TInput>): CallbackActorLogic<TEvent, TInput>;