react-smart-state/dist/cjs/index.d.ts

Next generation local and global state management

import { ISingleObject, LocalStateManagment, NestedKeyOf, PrimitiveTypes, ReturnState, WidenLiteral } from "./types";
export * from "./methods";
export * from "./types";
export * from "./objects";
/**
 * StateBuilder is a fluent API to build local or global reactive state
 * using the Create proxy system with support for recursive structures,
 * selective key ignoring, and optional binding with event dispatch control.
 */
declare class StateBuilder<T extends object> {
    private item;
    private initilized?;
    private ignoreKeys;
    private hardIgnoreKeys;
    private bindKeys;
    private localBindKeys;
    private timeoutSpeed?;
    private onStateInit?;
    private arrayParser?;
    /**
     * @param item - The object to wrap in a reactive state, or a function returning it
     */
    constructor(item: T | (() => T));
    /**
     * create proxies for arrays items.
     * that are not included in ignore objects.
     * this is disabled by default for better performance.
     */
    parseArray(): this;
    /**
     * Sets the debounce speed (in milliseconds) for event dispatch.
     * Set to `undefined` to disable throttling, or leave `-1` for default behavior.
     * @param speed - Optional timeout in milliseconds.
     */
    timeout(speed?: number): this;
    /**
     * Registers an asynchronous initialization function that will be called
     * when the state is first created or initialized.
     *
     * Useful for performing setup logic such as loading data, setting defaults, or
     * triggering side effects after the state is ready.
     *
     * @param func - An async function that receives the initial state and performs setup.
     * @returns The current instance (for chaining).
     */
    onInit(func: (state: T) => Promise<void>): this;
    /**
     * Prevents state updates for specific nested keys.
     * Any state update attempt on the specified keys will be ignored.
     * still keys added to .hook will override this settings
     *
     * @param keys - Array of nested key paths (e.g. 'user.name', 'settings.theme')
     * @returns The current instance (for chaining)
     */
    ignoreUpdatesFor(...keys: NestedKeyOf<T>[]): this;
    /**
     * Ignores specified nested keys from being proxied/reactive.
     * Useful for skipping large, static, or recursive subtrees to improve performance.
     * @param ignoreKeys - Keys to ignore from proxying
     */
    ignore(...ignoreKeys: NestedKeyOf<T>[]): this;
    /**
     * Rebinds specific nested keys that were previously ignored.
     * Enables listening to changes on those keys manually.
     * @param bindKeys - Keys within ignored objects to still bind to
     */
    bind(...bindKeys: NestedKeyOf<T>[]): this;
    /**
     * Like `bind()`, but events are scoped locally (do not trigger global listeners).
     * Useful for isolating state changes in local components.
     * @param bindKeys - Keys to bind with local-only change listeners
     */
    localBind(...bindKeys: NestedKeyOf<T>[]): this;
    /**
     * Builds and returns a local reactive state object that can be used in components.
     * Initializes the state only once, applies bindings, and sets hook context.
     */
    build(): ReturnState<T> & LocalStateManagment<T> & T;
    /**
     * Builds and returns a global reactive state object.
     * This does not hook into React, so it’s suitable for shared/global stores.
     */
    globalBuild(): ReturnState<T> & T;
}
declare const StateManagment: <T extends object>(item: T | (() => T)) => StateBuilder<T>;
export declare const PrimitiveValue: <T extends PrimitiveTypes>(initialValue?: T) => readonly [WidenLiteral<T, any>, (newValue: WidenLiteral<T, PrimitiveTypes> | ((prev: WidenLiteral<T, PrimitiveTypes>) => WidenLiteral<T, PrimitiveTypes>)) => void];
export declare const PrimitiveObject: <T extends PrimitiveTypes>(initialValue?: T) => ISingleObject<T>;
export default StateManagment;