react-containerized-state/dist/index.d.cts

Fast and minimal state container which can be used and shared across React or non-React components.

import { Container, ComputeValue, EqualityCheckFunction } from 'containerized-state';
export * from 'containerized-state';

type SubscribeProps<T, P> = {
    /**
     * The state container to subscribe to.
     */
    container: Container<T>;
    /**
     * A render function that receives the computed value as an argument.
     */
    children: (renderProps: P) => React.ReactNode;
    /**
     * A function that computes a derived value from the container's state.
     */
    compute?: ComputeValue<T, P>;
    /**
     * An optional function to compare previous and next computed values to
     * prevent unnecessary re-renders.
     */
    isEqual?: EqualityCheckFunction<P>;
};
/**
 * A render props component that subscribes to a state container and provides
 * a computed value to its children.
 *
 * It uses the `useComputedValue` hook internally to handle the subscription
 * and re-rendering logic. This component is useful for encapsulating state
 * access and providing a clean, declarative API for consuming state in a
 * React component tree.
 *
 * @template T The type of the value in the state container.
 * @template P The type of the computed value.
 *
 * @example
 * // In a component:
 * const myContainer = new Container({ name: "Alice", age: 30 });
 *
 * <Subscribe
 * container={myContainer}
 * compute={(state) => `Hello, ${state.name}! You are ${state.age} years old.`}
 * >
 * {(greeting) => <div>{greeting}</div>}
 * </Subscribe>
 */
declare const Subscribe: <T, P = T>(props: SubscribeProps<T, P>) => React.JSX.Element;

/**
 * Custom hook that subscribes to a container and computes a derived value.
 *
 * @param container The container to subscribe to and retrieve the value from.
 * @param compute The function to compute the derived value from the container's value.
 * @param [isEqual] Optional function to compare the previous and next computed values.
 *
 * @example
 * // Example usage:
 * const container = new Container({ count: 0, step: 1 });
 * const computeDouble = (state) => state.count * 2;
 * const doubleCount = useComputedValue(container, computeDouble);
 */
declare const useComputedValue: <T, P>(container: Container<T>, compute: ComputeValue<T, P>, isEqual?: EqualityCheckFunction<P>) => P;

type Updater<T> = (state: React.SetStateAction<T>) => void | Promise<void>;
/**
 * Custom hook that provides an updater function to set the value of a container.
 *
 * @param container - The container to update.
 *
 * @example
 * // Example usage:
 * const container = new Container(0);
 * const updateValue = useUpdate(container);
 * updateValue(42); // Sets the container value to 42
 * updateValue(prev => prev + 1); // Updates the container value using a function
 */
declare const useUpdate: <T>(container: Container<T>) => Updater<T>;

/**
 * Custom hook that subscribes to a container and retrieves its current value.
 *
 * @param container - The container to subscribe to and retrieve the value from.
 *
 * @example
 * // Example usage:
 * const container = new Container(0);
 * const currentValue = useValue(container);
 */
declare const useValue: <T>(container: Container<T>) => T;

export { Subscribe, type SubscribeProps, type Updater, useComputedValue, useUpdate, useValue };