fluidstate/primitives/reactive-remotes.d.ts

Library for fine-grained reactivity state management

import { ReactiveInstance, ReactiveRemoteOptions } from "./reactive-primitive-types";
/**
 * Creates and returns a new `ReactiveInstance` object.
 *
 * A `ReactiveInstance` encapsulates a set of reactive primitive functions
 * (`createAtom`, `createComputedAtom`, `createReaction`, etc.) operating
 * on the currently provided reactive layer.
 *
 * This function is typically used by a system (e.g., a UI library or a game engine module)
 * to obtain its own handle to the reactive capabilities. This handle can then be
 * passed to another system to establish a "remote" reactive relationship,
 * allowing for controlled interaction and data synchronization between them.
 *
 * @returns A `ReactiveInstance` object.
 */
export declare const getReactiveInstance: () => ReactiveInstance;
/**
 * Adds an external `ReactiveInstance` as a "remote" to the current reactive system.
 *
 * This establishes a relationship where the local system can be aware of the remote
 * system. If a `scheduler` is provided in the options, reactions originating from
 * (or related to) the remote instance that depend on local data can be scheduled
 * according to the local system's defined timing.
 *
 * This is crucial for scenarios where one reactive system (e.g., a game engine)
 * needs to integrate with another (e.g., a user's application state)
 * while maintaining control over update cycles.
 *
 * @param reactiveInstance - The external `ReactiveInstance` to be added.
 * @param options - Optional configuration for the remote connection,
 *   primarily for providing a custom `scheduler`.
 * @returns The `reactiveInstance` that was added.
 * @throws Error if the `reactiveInstance` has already been added or when
 *   trying to add instance as its own remote.
 */
export declare const addReactiveRemote: (reactiveInstance: ReactiveInstance, options?: ReactiveRemoteOptions) => ReactiveInstance;
/**
 * Removes a `ReactiveInstance` that was previously added as a remote.
 *
 * This function cleans up the remote connection by:
 * 1. Stopping any reactions that were specifically associated with this remote instance
 *    (e.g., reactions created by the local system to observe the remote system's data,
 *    or reactions whose scheduling was managed due to this remote connection).
 * 2. Removing the `reactiveInstance` from the internal tracking collections.
 *
 * @param reactiveInstance - The `ReactiveInstance` to remove.
 * @throws Error if the `reactiveInstance` was not found in the set of active remotes.
 */
export declare const removeReactiveRemote: (reactiveInstance: ReactiveInstance) => void;