react-hooks-global-states/GlobalStore.d.ts

A package to easily handle global state across your React components using hooks.

import type { ActionCollectionConfig, GlobalStoreCallbacks, ActionCollectionResult, MetadataSetter, SubscribeCallbackConfig, SubscribeCallback, SelectorCallback, SubscriberParameters, StateHook, BaseMetadata, StateChanges, StoreTools, ObservableFragment, UnsubscribeCallback, AnyFunction, ReadonlyHook, ReadonlyStateApi, CleanupFunction } from './types';
/**
 * The GlobalStore class is the main class of the library and it is used to create a GlobalStore instances
 * */
export declare class GlobalStore<State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata> | undefined | unknown, PublicStateMutator = keyof ActionsConfig extends never | undefined ? React.Dispatch<React.SetStateAction<State>> : ActionCollectionResult<State, Metadata, NonNullable<ActionsConfig>>> {
    protected cleanupFunctions: CleanupFunction[];
    protected _name: string;
    actionsConfig: ActionsConfig | null;
    callbacks: GlobalStoreCallbacks<State, PublicStateMutator, Metadata> | null;
    metadata: Metadata;
    /**
     * @description If the actionsConfig is defined, this will be a map of actions that can be used to modify or interact with the state
     * */
    actions: PublicStateMutator extends AnyFunction ? null : PublicStateMutator;
    storeTools: StoreTools<State, PublicStateMutator, Metadata>;
    /**
     * @description The main hook that will be used to interact with the global state
     */
    use: StateHook<State, PublicStateMutator, Metadata>;
    /**
     * @deprecated
     * @description Set of subscribers that are listening to state changes
     * Useful for debugging purposes... You'll probably not need to use this in your application
     */
    subscribers: Set<SubscriberParameters>;
    state: State;
    protected stateCallback?: () => State;
    protected metadataCallback?: () => Metadata;
    constructor(state: State | (() => State));
    constructor(state: State | (() => State), args: {
        metadata?: Metadata | (() => Metadata);
        callbacks?: GlobalStoreCallbacks<State, PublicStateMutator, Metadata>;
        actions?: ActionsConfig;
        name?: string;
    });
    /**
     * This method is meant to be overridden by the extended classes
     */
    protected onInit?: () => void | CleanupFunction;
    /**
     * This method is meant to be overridden by the extended classes
     */
    protected onStateChanged?: (args: StateChanges<State>) => void;
    /**
     * @description
     * Initializes the global store, setting up the main hook and actions map if applicable,
     */
    protected initialize(): Promise<void>;
    /**
     * set the state for a single subscriber
     * validate if the state should be updated by comparing the previous state and the new state
     */
    protected executeSetStateForSubscriber(subscription: SubscriberParameters, args: {
        forceUpdate: boolean | undefined;
        newState: State;
        currentState: State;
        identifier: string | undefined;
    }): {
        didUpdate: boolean;
    };
    /**
     * set the state and update all the subscribers
     * @param {State} newState - The new state to set
     * @param {object} options - The options for setting the state
     * @param {boolean} [options.forceUpdate] - Whether to force the update even if the state is the same
     * @param {string} [options.identifier] - An optional identifier for the state change
     * */
    setActualStateWithoutValidations(newState: State, { forceUpdate, identifier }: {
        forceUpdate?: boolean;
        identifier?: string;
    }): void;
    /**
     * Set the value of the metadata property, this is no reactive and will not trigger a re-render
     * @param {MetadataSetter<Metadata>} setter - The setter function or the value to set
     * */
    setMetadata(setter: Parameters<MetadataSetter<Metadata>>[0]): void;
    /**
     * Returns the metadata [non-reactive additional information associated with the global state]
     */
    getMetadata(): Metadata;
    /**
     * Get the current value of the state
     */
    getState(): State;
    /**
     * Subscribe an individual callback to state changes
     */
    subscribe<TDerivate>(...[param1, param2, param3]: [
        SubscribeCallback<State> | SelectorCallback<State, TDerivate>,
        (SubscribeCallbackConfig<State> | SubscribeCallback<TDerivate>)?,
        SubscribeCallbackConfig<State | TDerivate>?
    ]): UnsubscribeCallback;
    /**
     * Adds a subscription object to the subscribers set and returns the unsubscribe function
     */
    protected subscribeCallback(subscription: SubscriberParameters): () => void;
    partialUpdateSubscription(subscription: SubscriberParameters, values: Partial<SubscriberParameters>): void;
    /**
     * Returns a custom hook that allows to handle a global state
     * @returns {[State, StateMutator, Metadata]} - The state, the state setter or the actions map, the metadata
     * */
    getMainHook(): StateHook<State, PublicStateMutator, Metadata>;
    protected reselectIfDependenciesChanged({ subscription, newDependencies, currentDependencies, }: {
        subscription: SubscriberParameters;
        newDependencies: unknown[] | undefined;
        currentDependencies: unknown[] | undefined;
    }): void;
    createSelectorHook: typeof createSelectorHook;
    createObservable: typeof createObservable;
    /**
     * Returns the state setter or the actions map
     * @returns {StateMutator} - The state setter or the actions map
     * */
    protected getStateOrchestrator(): PublicStateMutator;
    /**
     * This is the only setState function that should be exposed outside the class
     * This is responsible for defining whenever or not the state change should be allowed or prevented
     * the function also execute the functions:
     * - onStateChanged (if defined) - this function is executed after the state change
     * - computePreventStateChange (if defined) - this function is executed before the state change and it should return a boolean value that will be used to determine if the state change should be prevented or not
     */
    setState(setter: Parameters<React.Dispatch<React.SetStateAction<State>>>[0], { forceUpdate, identifier, }?: {
        forceUpdate?: boolean;
        identifier?: string;
    }): void;
    /**
     * This creates storeTools and actions map if applicable
     * */
    getStoreActionsMap(): {
        actions: PublicStateMutator extends AnyFunction ? null : PublicStateMutator;
        storeTools: StoreTools<State, PublicStateMutator, Metadata>;
    };
    protected removeSubscriptions(): void;
    protected executeCleanupTasks(): void;
    dispose(): void;
    reset(): void;
    reset(state: State, metadata: Metadata): void;
    __devtools_getLifeCycleStoreToolsWrapper?: (logsPrefix: string) => StoreTools<State, PublicStateMutator, Metadata>;
    __devtools_initialize_getStoreActionsMapWrapped?: () => {
        actions: PublicStateMutator extends AnyFunction ? null : PublicStateMutator;
        storeTools: StoreTools<State, PublicStateMutator, Metadata>;
    };
}
export declare function createObservable<RootState, PublicStateMutator, Metadata extends BaseMetadata, Selected>(this: Pick<ReadonlyStateApi<RootState, PublicStateMutator, Metadata>, 'getState' | 'subscribe'>, selector: (state: RootState) => Selected, options?: {
    isEqual?: (current: Selected, next: Selected) => boolean;
    isEqualRoot?: (current: RootState, next: RootState) => boolean;
    name?: string;
}): ObservableFragment<Selected, PublicStateMutator, Metadata>;
/**
 * @description
 * Creates a derived hook bound to a selected fragment of the root state.
 * The derived hook re-renders only when the selected value changes and
 * exposes the same API as the parent state hook.
 */
export declare function createSelectorHook<RootState, PublicStateMutator, Metadata extends BaseMetadata, Selected>(this: Pick<ReadonlyStateApi<RootState, PublicStateMutator, Metadata>, 'getState' | 'subscribe'>, selector: (state: RootState) => Selected, options?: {
    isEqual?: (current: Selected, next: Selected) => boolean;
    isEqualRoot?: (current: RootState, next: RootState) => boolean;
    name?: string;
}): ReadonlyHook<Selected, PublicStateMutator, Metadata>;
export default GlobalStore;