dreamstate/test-utils.d.ts

Store management library based on react context and observers

import { FunctionComponent, Provider, Context } from 'react';
import { T as TAnyObject, e as IContextManagerConstructor, p as ICreateProviderProps, d as IScopeContext, f as IProviderProps, q as TAnyContextManagerConstructor, I as IRegistry, i as TManagerInstanceMap } from './lib.js';

/**
 * Creates a mock context provider that constructs instances without firing provision events.
 * This is useful for testing or mocking tree provision where required.
 *
 * @template T - The type of the provided context value, defaults to `TAnyObject`.
 * @param {IContextManagerConstructor[]} sources - An array of context manager constructors that should be
 *   provided within the React tree when the returned component renders.
 * @param {ICreateProviderProps} config - Configuration for the store provider.
 * @param {boolean} config.isCombined - Determines whether to use a single large React node for observing
 *   changes or multiple smaller scoped nodes.
 * @param {IScopeContext} scope - The scope where providers should be injected. Uses a mocked scope by default.
 * @returns {FunctionComponent<IProviderProps<T>>} A mocked React provider component that provides the source
 *   classes within the mocked scope.
 */
declare function mockContextProvider<T extends TAnyObject = TAnyObject>(sources: Array<IContextManagerConstructor>, config?: ICreateProviderProps, scope?: IScopeContext): FunctionComponent<IProviderProps<T>>;

/**
 * Creates a mock scope provider with an initial clean state.
 * This can be used to mock the entire scope context in a React tree.
 *
 * Must be used together with the `mockScope` method to ensure that the `value` property
 * of `ScopeContext.Provider` is correctly set.
 *
 * @returns {Provider<IScopeContext>} A `ScopeContext.Provider` component for React rendering.
 */
declare function mockScopeProvider(): Provider<IScopeContext>;

/**
 * Retrieves the current instance of a context manager from the given scope.
 * Returns `null` if the manager is not found in the current scope.
 *
 * @template T - The type of the context manager constructor.
 * @param {T} ManagerClass - The constructor reference of the context manager to retrieve.
 * @param {IScopeContext} scope - The scope in which to search for the manager instance.
 * @returns {InstanceType<T> | null} The instance of the specified manager class if found, otherwise `null`.
 */
declare function getCurrent<T extends TAnyContextManagerConstructor>(ManagerClass: T, scope: IScopeContext): InstanceType<T> | null;

/**
 * Mocks the initial context of a manager during service registration.
 * This method ensures type safety by packaging the manager and its initial context in a structured way.
 *
 * @template D - The type of the context manager constructor.
 * @param {D} ManagerClass - The manager class to which the initial context should be applied.
 * @param {Partial<D["prototype"]["context"]>} context - A partial initial context to be used during provision.
 * @returns {[D, Partial<D["prototype"]["context"]>]} A tuple containing the manager class and the provided
 *   initial context.
 */
declare function mockManagerInitialContext<D extends TAnyContextManagerConstructor>(ManagerClass: D, context: Partial<D["prototype"]["context"]>): [D, Partial<D["prototype"]["context"]>];

/**
 * Creates a mocked internal registry for scope testing.
 * This registry contains managers and listeners for testing purposes.
 *
 * @returns {IRegistry} The internal registry of managers and listeners.
 */
declare function mockRegistry(): IRegistry;

interface IMockScopeConfig {
    isLifecycleDisabled?: boolean;
    applyInitialContexts?: Array<[TAnyContextManagerConstructor, TAnyObject]>;
}
/**
 * Creates a mock scope with a clean initial state.
 * This can be used to mock the entire scope context for advanced testing.
 *
 * The `mockManagerInitialContext` function can be used to provision mocked contexts within this scope.
 *
 * @param {IMockScopeConfig} [mockConfig] - Configuration object for scope mocking.
 * @param {IRegistry} [registry] - An optional custom registry to be used as the scope storage.
 * @returns {IScopeContext} A mocked scope context.
 */
declare function mockScope(mockConfig?: IMockScopeConfig, registry?: IRegistry): IScopeContext;

/**
 * Mocks a context manager for isolated testing.
 *
 * @template T - The type of the manager's state.
 * @template S - The type of the initial state injected into the manager.
 * @template M - The type of the context manager constructor.
 * @param {M} ManagerClass - The constructor reference of the context manager to be created.
 * @param {S | null} initialState - An optional initial state to inject into the manager's constructor.
 * @param {IScopeContext} [scope] - An optional scope context where the manager
 *   should be mocked. If not provided, a new scope is created.
 * @returns {InstanceType<M>} The instance of the mocked manager.
 */
declare function mockManager<T extends TAnyObject, S extends TAnyObject, M extends IContextManagerConstructor<T, S>>(ManagerClass: M, initialState?: S | null, scope?: IScopeContext): InstanceType<M>;

/**
 * Mocks multiple context managers and a scope for isolated testing.
 *
 * This is useful when multiple managers need to be paired together for specific test cases.
 *
 * @template T - The type of the manager's state.
 * @template S - The type of the initial state injected into each manager.
 * @template M - The type of a single context manager constructor.
 * @param {M[]} managerClasses - An array of context manager constructor references to be created.
 * @param {S | null} initialState - An optional initial state to inject into each manager's constructor.
 * @param {IScopeContext} [scope] - The scope where managers should be mocked. A mocked scope is
 *   used by default.
 * @returns {TManagerInstanceMap} A mapping of manager instances along with the mocked scope context.
 */
declare function mockManagers<T extends TAnyObject, S extends TAnyObject, M extends IContextManagerConstructor<T, S>>(managerClasses: Array<M>, initialState?: S | null, scope?: IScopeContext): TManagerInstanceMap;

/**
 * Retrieves the React context consumer for the specified context manager.
 *
 * @template T - The type of the context manager constructor.
 * @param {T} ManagerClass - The constructor reference of the context manager.
 * @returns {Context<T["prototype"]["context"]>["Consumer"]} The React context consumer for the specified manager class.
 */
declare function getReactConsumer<T extends TAnyContextManagerConstructor>(ManagerClass: T): Context<T["prototype"]["context"]>["Consumer"];

/**
 * Retrieves the React context provider for the specified context manager.
 *
 * @template T - The type of the context manager constructor.
 * @param {T} ManagerClass - The constructor reference of the context manager.
 * @returns {Context<T["prototype"]["context"]>["Provider"]} The React context provider for the specified manager class.
 */
declare function getReactProvider<T extends TAnyContextManagerConstructor>(ManagerClass: T): Context<T["prototype"]["context"]>["Provider"];

/**
 * Waits for all queued events or a specified amount of time.
 * This function is essentially a promisified `setTimeout`.
 *
 * @param {number} [ms] - The time in milliseconds to wait. Defaults to 0 if not specified.
 * @returns {Promise<void>} A promise that resolves after the specified time has elapsed.
 */
declare function nextAsyncQueue(ms?: number): Promise<void>;

export { getCurrent, getReactConsumer, getReactProvider, mockContextProvider, mockManager, mockManagerInitialContext, mockManagers, mockRegistry, mockScope, mockScopeProvider, nextAsyncQueue };
export type { IMockScopeConfig };