dreamstate/lib.d.ts

Store management library based on react context and observers

import { ReactNode, Context, FunctionComponent } from 'react';

/**
 * Properties for the Dreamstate context manager provider.
 * Defines the props used for initializing and configuring the provider.
 */
interface IProviderProps<T> {
    initialState?: T;
    children?: ReactNode;
}

/**
 * A callable function type with no parameters.
 * Represents any function that does not take any arguments and returns nothing.
 */
type TCallable = () => void;
/**
 * An object type that can contain any properties with any values.
 */
type TAnyObject = Record<string, TAnyValue>;
/**
 * An object type that cannot be accessed because data is unknown.
 */
type TEmptyObject = Record<string, unknown>;
/**
 * Represents any value.
 */
type TAnyValue = any;

/**
 * Meta symbols for private internals in context managers.
 */
declare const SIGNAL_METADATA_SYMBOL: unique symbol;
declare const QUERY_METADATA_SYMBOL: unique symbol;
declare const SIGNALING_HANDLER_SYMBOL: unique symbol;
declare const SCOPE_SYMBOL: unique symbol;

/**
 * Internal registry object that stores mutable references, accounting for all Dreamstate scope data.
 * This interface defines the structure of the registry used to manage context, signals, and queries
 * within the Dreamstate scope. It contains various maps and sets that allow efficient tracking
 * and interaction with context managers, their states, observers, subscribers, signal listeners,
 * and query providers.
 */
interface IRegistry {
    /**
     * Registry of currently provided context manager instances.
     * Stores instances of context managers for access and management.
     */
    CONTEXT_INSTANCES_REGISTRY: TManagerInstanceMap;
    /**
     * Registry of current scope manager states.
     * Used for accessing and synchronizing the states across context managers and their providers.
     */
    CONTEXT_STATES_REGISTRY: TManagerMap<TAnyObject>;
    /**
     * Provider references counting.
     * Tracks the reference count for each context manager instance.
     * If the count is greater than 0, the context manager should be active in the current scope.
     * If the reference count is 0, the context manager instance should be disposed.
     */
    CONTEXT_SERVICES_REFERENCES: TManagerMap<number>;
    /**
     * ContextManager observers registry for providers of related context.
     * Used by Dreamstate observer components to track and notify observers of context changes.
     */
    CONTEXT_OBSERVERS_REGISTRY: TManagerMap<Set<TUpdateObserver>>;
    /**
     * ContextManager subscribers registry for data updates.
     * Used by Pub-Sub subscribers to directly consume data updates from context managers.
     */
    CONTEXT_SUBSCRIBERS_REGISTRY: TManagerMap<Set<TUpdateSubscriber<TAnyValue>>>;
    /**
     * Registry of signal handlers.
     * Stores signal listeners that are registered to handle signals emitted within the scope.
     */
    SIGNAL_LISTENERS_REGISTRY: Set<TSignalListener<TAnyValue>>;
    /**
     * Registry of query request handlers.
     * Stores query providers for various query types that can return data for specific requests.
     */
    QUERY_PROVIDERS_REGISTRY: Map<TQueryType, Array<TQueryListener<TAnyValue, TAnyValue>>>;
}

/**
 * Internals of the scope context, meant for internal use only.
 *
 * This interface defines the internal properties and methods for managing data flow, signals,
 * and queries within the scope. It is not intended for external access and should only be used
 * by the `dreamstate` library for its internal operations.
 */
interface IScopeContextInternals {
    /**
     * Mutable registry that contains all references and scope data.
     */
    REGISTRY: IRegistry;
    /**
     * Registers a `ManagerClass` in the current scope and creates an instance for context provision.
     *
     * @template T - Type of initial state injected into the manager.
     * @template C - Type of initial context injected into the manager.
     * @param {IContextManagerConstructor} ManagerClass - The manager class that should be registered in the scope.
     * @param {T | null} [initialState] - Optional initial state parameter that will be injected into the manager's
     *   constructor upon creation.
     * @param {Partial<C>} [initialContext] - Optional initial context parameter that will be injected into the
     *   manager and mixed with the context.
     * @returns {boolean} `true` if the service was successfully registered, `false` otherwise.
     */
    registerManager<T extends TAnyObject, C extends TAnyObject>(ManagerClass: TAnyContextManagerConstructor, initialState?: T | null, initialContext?: Partial<C>): boolean;
    /**
     * Unregisters a `ManagerClass` from the current scope.
     * Cleans up memory and removes all internal references associated with the manager.
     *
     * @param {TAnyContextManagerConstructor} ManagerClass - The manager class that should be unregistered from the scope.
     * @returns {boolean} `true` if the service was successfully unregistered, `false` otherwise.
     */
    unRegisterManager(ManagerClass: TAnyContextManagerConstructor): boolean;
    /**
     * Adds an observer to a specified service.
     * The observer will be notified when the manager's context is updated.
     *
     * @template T - Type of the manager's context.
     * @param {TAnyContextManagerConstructor} ManagerClass - The manager class reference for which the observer
     *   should be added.
     * @param {TUpdateObserver} serviceObserver - The observer that should be notified on manager updates.
     * @param {number} [referencesCount] - Optional count of manager references for injection.
     *   By default, checks the registry.
     */
    addServiceObserver(ManagerClass: TAnyContextManagerConstructor, serviceObserver: TUpdateObserver, referencesCount?: number): void;
    /**
     * Removes an observer from a specified service.
     * The observer will no longer be notified of updates from the manager's context.
     *
     * @template T - Type of the manager's context.
     * @param {TAnyContextManagerConstructor} ManagerClass - The manager class reference for which
     *   the observer should be removed.
     * @param {TUpdateObserver} serviceObserver - The observer that should be removed from the registry.
     * @param {number} [referencesCount] - Optional count of manager references for injection.
     *   By default, checks the registry.
     */
    removeServiceObserver(ManagerClass: TAnyContextManagerConstructor, serviceObserver: TUpdateObserver, referencesCount?: number): void;
    /**
     * Notifies all observers that are subscribed to a manager's context updates.
     * This will update all providers based on the current context of the provided manager instance.
     *
     * @template T - Type of the manager's context.
     * @param {ContextManager<T>} manager - The manager instance whose context should trigger updates
     *   to subscribed providers.
     */
    notifyObservers<T extends TAnyObject>(manager: ContextManager<T>): void;
    /**
     * Subscribes to manager context updates.
     * The provided callback will be triggered whenever the manager's context is updated.
     *
     * @template T - Type of the manager's context.
     * @template D - Type of the context manager constructor.
     * @param {IContextManagerConstructor} ManagerClass - The manager class reference for which to subscribe.
     * @param {TUpdateSubscriber<T>} subscriber - The callback function that will be triggered on context updates.
     * @returns {TCallable} A function that can be used to unsubscribe from context updates.
     */
    subscribeToManager<T extends TAnyObject, D extends IContextManagerConstructor<TAnyValue, T>>(ManagerClass: D, subscriber: TUpdateSubscriber<T>): TCallable;
    /**
     * Unsubscribes from manager context updates.
     *
     * @template T - Type of the manager's context.
     * @template D - Type of the context manager constructor.
     * @param {IContextManagerConstructor} ManagerClass - The manager class reference for which to unsubscribe.
     * @param {TUpdateSubscriber<T>} subscriber - The callback function that should be removed
     *   from context updates subscription.
     */
    unsubscribeFromManager<T extends TAnyObject, D extends IContextManagerConstructor<TAnyValue, T>>(ManagerClass: D, subscriber: TUpdateSubscriber<T>): void;
}
/**
 * Represents the current scope context.
 * Provides public methods to interact with the current scope, including managing context, signals, and queries.
 */
interface IScopeContext {
    /**
     * Library internals.
     * Not intended for normal use, except during unit testing.
     */
    INTERNAL: IScopeContextInternals;
    /**
     * Retrieves the current context snapshot for the given manager class.
     *
     * @template T - Type of the context.
     * @template D - Type of the context manager constructor.
     * @param manager - The manager class whose context is to be retrieved.
     * @returns The current context snapshot for the specified manager.
     */
    getContextOf<T extends TAnyObject, D extends IContextManagerConstructor<T>>(manager: D): T;
    /**
     * Retrieves the current context manager instance if it was provisioned.
     *
     * @template T - Type of the context manager class.
     * @param manager - The manager class whose instance is to be retrieved.
     * @returns The current context manager instance for the specified manager class.
     */
    getInstanceOf<T extends IContextManagerConstructor>(manager: T): InstanceType<T>;
    /**
     * Emits a signal for all subscribers in the current Dreamstate scope.
     *
     * @template D - Type of the signal data.
     * @param base - The base signal object that triggers the event.
     *   It includes a `type` field  and an optional `data` field.
     * @param emitter - Optional signal emitter reference.
     * @returns A signal event instance that wraps the emitted signal.
     */
    emitSignal<D = undefined>(base: IBaseSignal<D>, emitter?: TAnyContextManagerConstructor | null): ISignalEvent<D>;
    /**
     * Subscribes to signals within the current scope.
     * The listener will be invoked on every signal event.
     *
     * @template D - Type of the signal data.
     * @param listener - The callback function to be invoked on signal events.
     * @returns A callable function that unsubscribes the listener.
     */
    subscribeToSignals<D = undefined>(listener: TSignalListener<D>): TCallable;
    /**
     * Unsubscribes a listener from signals in the current scope.
     * The provided listener will no longer be invoked on signal events.
     *
     * @template D - Type of the signal data.
     * @param listener - The callback function to remove from signal subscriptions.
     */
    unsubscribeFromSignals<D = undefined>(listener: TSignalListener<D>): void;
    /**
     * Registers a query provider callback to answer query data calls.
     *
     * @template T - Type of the query.
     * @param queryType - The type of query for data provisioning.
     * @param listener - The callback that listens to queries and returns evaluation data.
     * @returns A callable function that unregisters the query provider.
     */
    registerQueryProvider<T extends TQueryType>(queryType: T, listener: TQueryListener<T, TAnyValue>): TCallable;
    /**
     * Unregisters a query provider callback.
     * The callback will no longer handle query data calls.
     *
     * @template T - Type of the query.
     * @param queryType - The type of query for which the provider is unregistered.
     * @param listener - The callback to be unregistered.
     */
    unRegisterQueryProvider<T extends TQueryType>(queryType: T, listener: TQueryListener<T, TAnyValue>): void;
    /**
     * Queries data synchronously from the current scope.
     * The handler for the specified query type is executed, and its result is wrapped as a query response.
     *
     * @template D - Type of the data provided in the query request.
     * @template T - Type of the query.
     * @template Q - Type of the query request.
     * @param query - The query request containing the query type and optional data.
     * @returns The query response or null if no handler is found.
     */
    queryDataSync<D, T extends TQueryType, Q extends IOptionalQueryRequest<D, T>>(query: Q): TQueryResponse<TAnyValue>;
    /**
     * Queries data asynchronously from the current scope.
     * The handler for the specified query type is executed, and its result is wrapped as a query response.
     *
     * @template D - Type of the data provided in the query request.
     * @template T - Type of the query.
     * @template Q - Type of the query request.
     * @param query - The query request containing the query type and optional data.
     * @returns A promise that resolves with the query response or null if no handler is found.
     */
    queryDataAsync<D, T extends TQueryType, Q extends IOptionalQueryRequest<D, T>>(query: Q): Promise<TQueryResponse<TAnyValue>>;
}

/**
 * Abstract context manager class.
 * This class wraps data and logic, separating them from the React tree. It allows you to create
 * global or local storages with lifecycles, which can be cleaned up and ejected when no longer needed.
 *
 * This class serves as a foundation for managing scoped data and logic in a React application using
 * the Dreamstate library.
 *
 * To provide specific `ContextManager` classes in the React tree, use the `createProvider` method.
 * To consume specific `ContextManager` data, use the `useManager` method.
 * For more details on shallow checks of context updates, see the `createNested`, `createActions`,
 * and other related methods.
 *
 * Every instance of this class is automatically managed and created by Dreamstate scope if needed.
 * - Instances can emit signals and query data within the scope where they were created.
 * - Instances can register methods as scope signal listeners or query data providers.
 * - Each instance is responsible for a specific data part (similar to reducers in Redux).
 *
 * Examples of `ContextManager` subclasses: AuthManager, GraphicsManager, ChatManager, LocalMediaManager, etc.
 *
 * **Important Notes**:
 * - Async methods called after the manager class is unregistered will trigger warnings during development,
 *   but they will not affect the actual scope after ejection.
 *
 *  @template T - The type of the context state managed by this class.
 *  @template S - The type of additional data or metadata that can be attached to the manager.
 */
declare abstract class ContextManager<T extends TAnyObject = TEmptyObject, S extends TAnyObject = TAnyObject> {
    /**
     * React context default value getter.
     * This method provides placeholder values to context consumers when the corresponding manager is not provided.
     *
     * @returns {TAnyObject | null}
     * - Returns the default value for context consumers when the manager is not provided.
     * - Defaults to `null` if no specific getter is defined.
     */
    static getDefaultContext(): TAnyObject | null;
    /**
     * React context getter.
     * This method allows access to the related React.Context, which can be useful for manual rendering
     * or testing scenarios.
     *
     * The context is lazily initialized, even for static resolving, before any other elements of the
     * ContextManager are used.
     *
     * @returns {Context<TAnyValue>} The React context associated with this ContextManager.
     */
    static get REACT_CONTEXT(): Context<TAnyValue>;
    /**
     * Manager instance scope reference.
     * Used internally to emit signals/queries or subscribe to data within the current scope.
     */
    [SCOPE_SYMBOL]: IScopeContext;
    /**
     * Signaling handler that operates on scope signals and calls the required method
     * registered in metadata to handle the signal event.
     */
    [SIGNALING_HANDLER_SYMBOL]: TSignalListener;
    /**
     * Manager instance signals metadata reference.
     * Used internally to emit signals, providing instance-based metadata description for the signals.
     */
    [SIGNAL_METADATA_SYMBOL]: TSignalSubscriptionMetadata;
    /**
     * Manager instance query metadata reference.
     * Used internally to emit queries, providing instance-based metadata description for the queries.
     */
    [QUERY_METADATA_SYMBOL]: TQuerySubscriptionMetadata;
    /**
     * Flag indicating whether the current manager is still active or has been disposed.
     * Once a manager is disposed, it cannot be reused or continue functioning.
     * Scope-related methods (signals, queries) will be inaccessible, and using them will throw exceptions.
     */
    IS_DISPOSED: boolean;
    /**
     * Manager instance context.
     * This field will be synchronized with React providers when the 'setContext' method is called.
     * It should hold an object value.
     *
     * While manual mutations of nested value fields are allowed, they are not recommended.
     * After calling 'setContext', the context will be shallowly compared with the existing context
     * before it is synced with the React tree.
     * Meta fields created by Dreamstate utilities (such as createActions, createNested, etc.) may
     * have a different comparison mechanism instead of the standard shallow check.
     *
     * For more information about the shallow check process, refer to 'createNested', 'createActions',
     * and similar methods.
     */
    context: T;
    /**
     * Generic context manager constructor.
     * The initial state can be used as an initialization value or SSR-provided data.
     * Treating the initial state as an optional value allows for more generic and reusable code,
     * as the manager can be provided in different places with different initial states.
     *
     * @template S - The type of initial state object.
     * @param {S} initialState - Optional initial state received from the Dreamstate Provider component properties.
     */
    constructor(initialState?: S);
    /**
     * Lifecycle method called when the first provider is injected into the React tree.
     * This follows a similar philosophy to 'componentWillMount' in class-based components.
     *
     * This method is useful for initializing data and setting up subscriptions.
     */
    onProvisionStarted(): void;
    /**
     * Lifecycle method called when the last provider is removed from the React tree.
     * This follows a similar philosophy to 'componentWillUnmount' in class-based components.
     *
     * This method is useful for disposing of data when the context is being ejected
     * or when Hot Module Replacement (HMR) occurs.
     */
    onProvisionEnded(): void;
    /**
     * Get the current manager scope.
     * This method allows access to the current execution scope and provides methods
     * for retrieving manager instances within it.
     *
     * @returns {IScopeContext} The current manager scope.
     */
    getScope(): IScopeContext;
    /**
     * Forces an update and re-render of subscribed components.
     * This is useful when you need to ensure that the components remain in sync with the current context.
     *
     * Side effect: After a successful update, all subscribed components will be re-rendered
     * according to their subscription.
     *
     * Note: This will only force an update of the provider; components using `useManager` selectors
     * will not be forced to render.
     *
     * Note: A new shallow copy of `this.context` is created after each call.
     *
     * Note: If the manager is out of scope, the method will simply replace `this.context`.
     */
    forceUpdate(): void;
    /**
     * Updates the current context from a partially supplied state or a functional selector.
     * The update is applied to the React provider tree only if the `shouldObserversUpdate` check passes
     * and if any changes have occurred in the store.
     * This follows the same philosophy as `setState` in React class components.
     *
     * Side effect: After a successful update, all subscribed components will be updated accordingly
     * to their subscription.
     *
     * Note: A partial context object or a callback that returns a partial context is required.
     *
     * Note: This will only update the provider; components using `useManager` selectors will not be
     * forced to render.
     *
     * Note: If the manager is out of scope, it will simply rewrite the `this.context` object without
     * any side effects.
     *
     * @param {object | Function} next - A part of the context to be updated or a context transformer function.
     *   If a function is provided, it will be executed immediately with the `currentContext` as its parameter.
     */
    setContext(next: Partial<T> | TPartialTransformer<T>): void;
    /**
     * Emits a signal to other managers and subscribers within the current scope.
     * Valid signal types include `string`, `number`, and `symbol`.
     *
     * @template D - The type of the data associated with the signal.
     * @param {IBaseSignal<D>} baseSignal - The base signal object containing a signal type and
     *   optional data.
     * @param {*} baseSignal.data - Optional data associated with the signal.
     * @returns {ISignalEvent<D>} The signal event object that encapsulates the emitted signal.
     *
     * @throws {Error} Throws an error if the manager is out of scope.
     */
    emitSignal<D = undefined>(baseSignal: IBaseSignal<D>): ISignalEvent<D>;
    /**
     * Sends a context query to retrieve data from query handler methods.
     * This asynchronous method is particularly useful for async providers, although
     * synchronous providers are handled as well.
     *
     * If a valid query handler is found in the current scope, it returns a promise that resolves
     * with a query response object; otherwise, it resolves with `null`.
     *
     * @template D - The type of the query data.
     * @template T - The type of the query.
     * @template Q - The query request type, extending IOptionalQueryRequest<D, T>.
     * @param {Q} queryRequest - The query request object containing the query type and optional data.
     * @param {TQueryType} queryRequest.type - The type of the query.
     * @param {*} [queryRequest.data] - Optional data used as parameters for data retrieval.
     * @returns {Promise<TQueryResponse<TAnyValue> | null>} A promise that resolves with the query response if a valid
     *   handler is found, or `null` if no handler exists in the current scope.
     */
    queryDataAsync<D, T extends TQueryType, Q extends IOptionalQueryRequest<D, T>>(queryRequest: Q): Promise<TQueryResponse<TAnyValue>>;
    /**
     * Sends a context query to retrieve data from query handler methods synchronously.
     * This method is ideal for synchronous operations; asynchronous handlers will return a promise
     * in the data field.
     *
     * If a valid query handler is found in the current scope, the method returns a query response object.
     * Otherwise, it returns `null`.
     *
     * @template D - The type of the query data.
     * @template T - The type of the query.
     * @template Q - The type of the query request, extending IOptionalQueryRequest<D, T>.
     * @param {Q} queryRequest - The query request object containing:
     *   - `type`: The type of the query.
     *   - `data` (optional): Additional data or parameters for data retrieval.
     * @returns {TQueryResponse<TAnyValue> | null} The query response object if a valid handler is found,
     *   or `null` if no handler exists in the current scope.
     */
    queryDataSync<D, T extends TQueryType, Q extends IOptionalQueryRequest<D, T>>(queryRequest: Q): TQueryResponse<TAnyValue>;
}

/**
 * Represents allowed signal types.
 * A signal type can be a symbol, string, or number.
 */
type TSignalType = symbol | string | number;
/**
 * A base signal containing a type and optional data fields.
 * Defines the structure of a basic signal, including its type and optional data.
 */
interface IBaseSignal<D = undefined> extends TAnyObject {
    /**
     * The type of the current signal.
     */
    readonly type: TSignalType;
    /**
     * The data associated with the current signal, optional.
     */
    readonly data?: D;
}
/**
 * A signal that contains only the type field.
 * Represents a signal with a type but no associated data.
 */
interface ISignalWithoutData extends TAnyObject {
    /**
     * The type of the current signal.
     */
    readonly type: TSignalType;
}
/**
 * A signal that contains both the type and data fields.
 * Represents a signal with both a type and associated data.
 */
interface ISignalWithData<D = undefined> extends TAnyObject {
    /**
     * The type of the current signal.
     */
    readonly type: TSignalType;
    /**
     * The data associated with the current signal.
     */
    readonly data: D;
}
/**
 * A signal event emitted within a scope.
 * Extends IBaseSignal with additional properties, including the emitter and timestamp.
 */
interface ISignalEvent<D = undefined> extends IBaseSignal<D> {
    /**
     * The data of the current signal event.
     * This field is strictly typed based on the signal data.
     */
    readonly data: D;
    /**
     * The emitter of the signal.
     * Can be a context manager constructor or null if no emitter is specified.
     */
    readonly emitter: TAnyContextManagerConstructor | null;
    /**
     * The timestamp when the signal event was emitted.
     */
    readonly timestamp: number;
    /**
     * Flag indicating whether the signal has been canceled.
     */
    canceled?: boolean;
    /**
     * Method to stop the signal from being handled by subsequent listeners.
     */
    cancel(): void;
}
/**
 * A generic signal listener method.
 * Listens for and handles emitted signal events.
 */
type TSignalListener<D = undefined> = (signal: ISignalEvent<D>) => void;
/**
 * Class metadata containing information about signal handlers.
 * Represents an array of signal types and their corresponding subscriptions.
 */
type TSignalSubscriptionMetadata = Array<[string | symbol, TSignalType | Array<TSignalType>]>;
/**
 * A derived signal type based on the provided data.
 * Resolves to either ISignalWithoutData or ISignalWithData depending on the presence of data.
 */
type TDerivedSignal<D = undefined> = D extends undefined ? ISignalWithoutData : ISignalWithData<D>;

/**
 * Context manager class reference.
 * Defines a constructor signature for a context manager, including its associated context.
 */
interface IContextManagerConstructor<T extends TAnyObject = TAnyObject, S extends TAnyObject = TAnyValue, C extends ContextManager<T> = ContextManager<T>> {
    getDefaultContext(): TAnyObject | null;
    REACT_CONTEXT: Context<T>;
    prototype: C;
    new (initialState?: S): C;
}
/**
 * A reference to any context manager class.
 * Represents a context manager class with any state and context type.
 */
type TAnyContextManagerConstructor = IContextManagerConstructor<TAnyValue, TAnyValue>;
/**
 * A partial transformer for the context manager's 'context' field.
 * Transforms the context value into a partial version of the context.
 */
type TPartialTransformer<T> = (value: T) => Partial<T>;
/**
 * Observers that are bound to provider elements.
 * These observers are triggered to react to changes in the context.
 */
type TUpdateObserver = () => void;
/**
 * Subscribers that consume context data when it is available.
 * These subscribers receive context updates and handle the data.
 */
type TUpdateSubscriber<T extends TAnyObject> = (context: T) => void;
/**
 * A mutable map that stores manager class references.
 * Maps context manager classes to instances of their associated manager.
 */
type TManagerMap<T> = Map<TAnyContextManagerConstructor, T>;
/**
 * A mapping of manager instances and their corresponding service class references.
 * Maps context manager constructors to their created instances.
 */
type TManagerInstanceMap = TManagerMap<InstanceType<TAnyContextManagerConstructor>>;

/**
 * Represents allowed query types.
 * A query type can be a symbol, string, number, or any custom type that extends string.
 */
type TQueryType<T extends string = string> = symbol | string | number | T;
/**
 * A base query request that includes an optional data field.
 * Represents a query with a key type and optional associated data.
 */
interface IOptionalQueryRequest<D = TAnyValue, T extends TQueryType = TQueryType> {
    /**
     * The query key type used for search matching.
     */
    readonly type: T;
    /**
     * The data parameters requested by the query, optional.
     */
    readonly data?: D;
}
/**
 * A base query request with a required data field.
 * Represents a query with a key type and required data.
 */
interface IQueryRequest<D = undefined, T extends TQueryType = TQueryType> {
    /**
     * The query key type used for search matching.
     */
    readonly type: T;
    /**
     * The data parameters requested by the query, required.
     */
    readonly data: D;
}
/**
 * A query request type that contains base information.
 * A type alias for IQueryRequest, defining a query with required data and key type.
 */
type TQueryRequest<D = undefined, T extends TQueryType = TQueryType> = IQueryRequest<D, T>;
/**
 * Metadata for a query subscription.
 * An array of tuples containing a string or symbol and a query type.
 */
type TQuerySubscriptionMetadata = Array<[string | symbol, TQueryType]>;
/**
 * A query listener that provides data for specific query types.
 * It takes a query request and returns the response data or null if no data is available.
 */
type TQueryListener<T extends TQueryType = TQueryType, D = undefined, R = TAnyValue> = (query: IQueryRequest<D, T> | IOptionalQueryRequest<D, T>) => R | null;
/**
 * A query response that represents the answer to a query request.
 * Contains the query key, data, timestamp, and the answerer that provided the response.
 */
interface IQueryResponse<D = undefined, T extends TQueryType = TQueryType> {
    /**
     * The query key type used for search matching.
     */
    readonly type: T;
    /**
     * The data returned in response to the query request.
     */
    readonly data: D;
    /**
     * The timestamp when the query response was emitted.
     */
    readonly timestamp: number;
    /**
     * The answerer of the query, which can be a context manager constructor or a function returning data.
     */
    readonly answerer: TAnyContextManagerConstructor | (() => TAnyValue);
}
/**
 * A query response type.
 * A type alias for IQueryResponse, representing response without data.
 */
type TQueryResponse<D = undefined> = IQueryResponse<D>;
/**
 * An optional query response type.
 * A query response that can either contain data or be null if no response is available.
 */
type TOptionalQueryResponse<D = undefined> = IQueryResponse<D> | null;

interface ICreateProviderProps {
    /**
     * A flag that determines whether to observe the context changes in one large React node
     *   or as smaller scoped nodes for better performance.
     */
    isCombined?: boolean;
}
/**
 * Method for creation of a component that provides React contexts and observes context changes.
 *
 * This function generates a React provider component that listens to changes in context state,
 * using the provided context managers and their corresponding configurations. The created provider
 * component can be used to wrap parts of the React component tree, making data from the context managers
 * available to all components within the tree via hooks like `useManager` and `useContext`.
 *
 * @param {Array<IContextManagerConstructor>} sources - An array of context manager class references
 *   that should be provided as context in the React tree when the returned provider component renders.
 * @param {ICreateProviderProps} config - Configuration options for the store provider.
 * @param {boolean} config.isCombined - A flag that determines whether to observe the context changes
 *   in one large React node or as smaller scoped nodes for better performance.
 * @returns {FunctionComponent} A React function component that acts as a provider for the specified
 *   context manager classes, making their data accessible to the React tree.
 *
 * @throws {TypeError} If the `sources` parameter is not an array.
 * @throws {TypeError} If any object in the `sources` array is not a class that extends `ContextManager`.
 */
declare function createProvider<T extends TAnyObject = TAnyObject>(sources: Array<IContextManagerConstructor>, config?: ICreateProviderProps): FunctionComponent<IProviderProps<T>>;

export { ContextManager as C, createProvider as o };
export type { IRegistry as I, TAnyObject as T, TAnyValue as a, TQueryType as b, TSignalType as c, IScopeContext as d, IContextManagerConstructor as e, IProviderProps as f, ISignalEvent as g, TDerivedSignal as h, TManagerInstanceMap as i, TManagerMap as j, TOptionalQueryResponse as k, TPartialTransformer as l, TQueryRequest as m, TQueryResponse as n, ICreateProviderProps as p, TAnyContextManagerConstructor as q };