react-signify/dist/index.d.ts

A JS library for predictable and maintainable global state management

import * as react from 'react';

type TCacheType = 'LocalStorage' | 'SessionStorage';
type TCacheConfig = {
    type?: TCacheType;
    key: string;
};

type TSignifyConfig = {
    cache?: TCacheConfig;
    syncKey?: string;
};
type TSetterCallback<T> = (pre: {
    value: T;
}) => void;
type TWrapProps<T> = {
    children(value: T): React.JSX.Element;
};
type TConvertValueCb<T, P> = (v: T) => P;
type TUseValueCb<T> = (value: T) => void;
type TConditionUpdate<T> = (pre: T, cur: T) => boolean;
type TConditionRendering<T> = (value: T) => boolean;
type TOmitHtml<T, P> = T extends string | number ? P : Omit<P, 'html'>;

/**
 * Signify class for managing a reactive state in a React environment.
 *
 * This class encapsulates the state management logic, providing features such
 * as synchronization with external systems, conditional updates and rendering,
 * and various utilities to interact with the state.
 *
 * @template T - Type of the state value.
 */
declare class Signify<T = unknown> {
    #private;
    /**
     * Constructor to initialize the Signify instance with an initial value and optional configuration.
     *
     * @param initialValue - The initial value of the state.
     * @param config - Optional configuration settings for state management.
     */
    constructor(initialValue: T, config?: TSignifyConfig);
    /**
     * Getter for obtaining the current value of the state.
     */
    get value(): T;
    /**
     * Setter function to update the state. Can take a new value or a callback function which use to update value directly.
     *
     * @param v - New value or a callback to compute the new value based on current state.
     */
    readonly set: (v: T | TSetterCallback<T>, isForceUpdate?: boolean) => void;
    /**
     * Stops rendering updates for this instance.
     */
    readonly stop: () => void;
    /**
     * Resumes rendering updates for this instance.
     */
    readonly resume: () => void;
    /**
     * Resets the state back to its initial value.
     */
    readonly reset: () => void;
    /**
     * Sets a condition for updating the state. The callback receives previous and new values and returns a boolean indicating whether to update.
     *
     * @param cb - Callback function for determining update conditions.
     */
    readonly conditionUpdating: (cb: TConditionUpdate<T>) => TConditionUpdate<T>;
    /**
     * Sets a condition for rendering. The callback receives the current value and returns a boolean indicating whether to render.
     *
     * @param cb - Callback function for determining render conditions.
     */
    readonly conditionRendering: (cb: TConditionRendering<T>) => TConditionRendering<T>;
    /**
     * Function to use the current value in components. This provides reactivity to component updates based on state changes.
     */
    readonly use: <P = undefined>(pickValue?: TConvertValueCb<T, P> | undefined) => P extends undefined ? T : P;
    /**
     * Function to watch changes on state and notify listeners accordingly.
     */
    readonly watch: (callback: TUseValueCb<T>, deps?: react.DependencyList) => void;
    /**
     * Function to subscribe to state changes and notify listeners accordingly.
     */
    readonly subscribe: (callback: TUseValueCb<T>) => {
        unsubscribe: () => boolean;
    };
    /**
     * Generates HTML output from the use function to render dynamic content based on current state.
     */
    readonly html: react.DetailedReactHTMLElement<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>;
    /**
     * A wrapper component that allows for rendering based on current state while managing reactivity efficiently.
     */
    readonly Wrap: ({ children }: TWrapProps<T>) => react.JSX.Element;
    /**
     * A hard wrapper component that provides additional control over rendering and avoids unnecessary re-renders in parent components.
     */
    readonly HardWrap: ({ children }: TWrapProps<T>) => react.JSX.Element;
    /**
     * Creates a sliced version of the state by applying a function to derive a part of the current value.
     *
     * @param pick - Function that extracts a portion of the current value.
     */
    readonly slice: <P>(pick: (v: T) => P) => TOmitHtml<P, {
        value: P;
        use: <P_1 = undefined>(pickValue?: TConvertValueCb<P, P_1> | undefined) => P_1 extends undefined ? P : P_1;
        watch: (callback: TUseValueCb<P>, deps?: react.DependencyList) => void;
        html: react.DetailedReactHTMLElement<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>;
        Wrap: ({ children }: TWrapProps<P>) => react.JSX.Element;
        HardWrap: ({ children }: TWrapProps<P>) => react.JSX.Element;
        stop: () => boolean;
        resume: () => void;
        conditionRendering: (cb: TConditionRendering<P>) => TConditionRendering<P>;
        subscribe: (callback: TUseValueCb<P>) => {
            unsubscribe: () => boolean;
        };
    }>;
}
/**
 * ReactSignify
 * -
 * @link https://reactsignify.dev
 * @description
 * Factory function to create a new Signify instance with an initial value and optional configuration settings.
 *
 * @template T - Type of the initial state value.
 * @param initialValue - The initial value to start with in Signify instance.
 * @param config - Optional configuration settings for Signify instance behavior.
 *
 * @returns A new instance of Signify configured with provided initial settings.
 */
declare const signify: <T>(initialValue: T, config?: TSignifyConfig) => TOmitHtml<T, Signify<T>>;

export { signify };
export type { TCacheConfig as TCacheInfo, TSignifyConfig };