import { DependencyList, EffectCallback, Dispatch, SetStateAction, Reducer, ReducerState, ReducerAction } from 'react'; import { c as ExtractTail } from './react-tools.Ozx07lAu.js'; /** * The map of mutator functions accepted by [createPubSubStore](https://react-tools.ndria.dev/hooks/state/createPubSubStore). * Each mutator receives the current store as its first argument, followed * by any number of additional custom arguments. * * @template T - The store object type. */ type PubSubMutatorsFn = Record void>; /** * The derived mutators object exposed on the store instance. Each key mirrors * a key of the original `mutatorsFn` map, but the first `store` argument is * stripped — callers only pass the additional custom arguments. * * @template E - The original mutators function map type. */ type PubSubMutators> = Record>) => void>; /** * Parameters accepted by [createPubSubStore](https://react-tools.ndria.dev/hooks/state/createPubSubStore). * * @template T - The store object type. Must be a plain object. * @template E - The mutators function map type. Each value must be a function * whose first argument is the current store `T`. */ type CreatePubSubStoreProps> = { /** * The initial state of the store. Shallow-copied on creation. If `persist` * is set and a previously serialised value exists in storage, the persisted * value takes precedence over this object. */ obj: T; /** * An optional map of named mutator functions used to update the store in a * structured way. Each mutator receives the **current store by reference** * as its first argument and may mutate it directly — the store is then * published to all subscribers automatically. The `store` argument is * stripped from the exposed {@link PubSubMutators} so callers only pass * the remaining arguments. */ mutatorsFn?: E; /** * When provided, the store is persisted to the specified Web Storage API * and rehydrated on the next page load: * - **`"localStorage"`** — Persists across browser sessions until explicitly * cleared. * - **`"sessionStorage"`** — Persists only for the duration of the current * browser session. * When omitted, the store lives only in memory. */ persist?: "localStorage" | "sessionStorage"; }; /** * Return value of [createPubSubStore](https://react-tools.ndria.dev/hooks/state/createPubSubStore). * * @template T - The store object type. * @template E - The mutators function map type. */ type CreatePubSubStoreResult> = { /** * Returns the current store value synchronously, outside of any React * component. Useful for reading state in event handlers, utilities, or * non-React code without subscribing to updates. */ getStore: () => T; /** * Imperatively mutates the store outside of any React component. Receives * the current store by reference via `cb` — mutate it directly and the * updated value is published to all subscribers and persisted to storage * if `persist` was configured. */ mutateStore: (cb: (globStore: T) => void) => void; /** * The derived mutator functions generated from `mutatorsFn`. Each key * mirrors the original map but with the leading `store` argument removed, * so callers only supply the additional custom arguments. Can be called * outside of React components. See {@link PubSubMutators}. */ mutators: PubSubMutators; /** * A React hook that subscribes a component to the store and returns a * reactive tuple. Supports two overloads: * * - **Without `subscribe`** — The component receives and re-renders on * changes to the full store object `T`. * - **With `subscribe`** — A selector function `(store: T) => C` is used * to derive a slice `C` from the store. The component only re-renders * when the selected slice changes (deep equality), avoiding unnecessary * re-renders for unrelated store updates. * * Returns a four-element tuple: * * | Index | Type | Description | * | ----- | ---- | ----------- | * | `0` | `T` \| `C` | The current store value or selected slice. Reactive — triggers a re-render on change. | * | `1` | `(store: T \| C \| ((curr: T) => T) \| ((curr: C) => C)) => void` | A setter that accepts a new value or an updater function. Updates the store (or the selected slice) and notifies all subscribers. | * | `2` | `() => T` \| `() => C` | A stable getter that returns the current value synchronously without causing a re-render. | * | `3` | {@link PubSubMutators}`` | The same derived mutators object as {@link CreatePubSubStoreResult.mutators}, available inside the component. | */ usePubSubStore: { (subscribe?: undefined): [ T, (store: T | ((currStore: T) => T)) => void, () => T, PubSubMutators ]; (subscribe?: (store: T) => C): [ C, (store: C | ((currStore: C) => C)) => void, () => C, PubSubMutators ]; }; }; /** * Parameters accepted by [useArray](https://react-tools.ndria.dev/hooks/state/useArray). * * @template T - The type of the elements contained in the array. */ type UseArrayProps = { /** * The initial array state. Accepts either a direct array value or a lazy * initializer function invoked only on the first render, avoiding unnecessary * re-creation of the initial value on subsequent renders. When omitted, * the array is initialised as empty. */ initialState?: Array | (() => Array); }; /** * Return value of [useArray](https://react-tools.ndria.dev/hooks/state/useArray). * A reactive `Array` whose mutating methods automatically synchronise the * underlying React state. All standard read-only methods (`map`, `filter`, * `find`, `reduce`, etc.) are inherited unchanged from `Array`. The * following mutating methods are overridden to trigger a re-render: * * | Method | Behaviour | * | ------------- | ------------------------------------------------------------------------- | * | `copyWithin` | Copies a sequence of elements within the array and updates state. | * | `fill` | Fills a range of indices with a static value and updates state. | * | `pop` | Removes and returns the last element, updating state. | * | `push` | Appends one or more elements and returns the new length, updating state. | * | `reverse` | Reverses the array in place and updates state. | * | `shift` | Removes and returns the first element, updating state. | * | `sort` | Sorts the array (optionally with a comparator) and updates state. | * | `splice` | Adds/removes elements at a given index and returns removed items. | * | `unshift` | Prepends one or more elements and returns the new length, updating state. | * * @template T - The type of the elements contained in the array. */ type UseArrayResult = Array & { /** Copies a sequence of elements within the array and triggers a re-render. */ copyWithin(target: number, start: number, end?: number): T[]; /** Fills a range of indices with `value` and triggers a re-render. */ fill(value: T, start?: number, end?: number): T[]; /** Removes and returns the last element, triggering a re-render. */ pop(): T | undefined; /** * Appends one or more elements to the end of the array, triggering a re-render. * Returns the new array length. */ push(...items: T[]): number; /** Reverses the array in place and triggers a re-render. */ reverse(): T[]; /** Removes and returns the first element, triggering a re-render. */ shift(): T | undefined; /** * Sorts the array in place, optionally using `compareFn`, and triggers a * re-render. */ sort(compareFn?: (a: T, b: T) => number): T[]; /** * Adds and/or removes elements starting at `start`. Returns the array of * removed elements and triggers a re-render. */ splice(start: number, deleteCount: number, ...items: T[]): T[]; /** * Prepends one or more elements to the beginning of the array, triggering a * re-render. Returns the new array length. */ unshift(...items: T[]): number; }; /** * Parameters accepted by [useDerivedState](https://react-tools.ndria.dev/hooks/state/useDerivedState). * * @template T - The type of the state value. */ type UseDerivedStateProps = { /** * The initial state value. Accepts either a direct value or a lazy initializer * function invoked only on the first render. */ initialState: T | (() => T); /** * A React dependency array (same semantics as `useEffect`). When any dependency * changes, `compute` is invoked to derive and apply a new state value. */ deps: DependencyList; /** * An optional effect callback invoked whenever `deps` change, following the * same semantics as `useEffect`. Use it to derive the next state value and * call the returned setter to update it. When omitted, the state is not * automatically recomputed on dependency changes. */ compute?: EffectCallback; }; /** * Return value of [useDerivedState](https://react-tools.ndria.dev/hooks/state/useDerivedState). * * @template T - The type of the state value. */ type UseDerivedStateResult = [ /** * The current state value, reactive — triggers a re-render when updated. */ T, /** * A stable setter function (same semantics as the setter returned by * `useState`). Accepts either a new value or an updater function receiving * the current state and returning the next state. */ Dispatch> ]; /** * Options accepted by [useLocalStorageState](https://react-tools.ndria.dev/hooks/state/useLocalStorageState) and [useSessionStorageState](https://react-tools.ndria.dev/hooks/state/useSessionStorageState). * Controls serialization and the access mode exposed by the hook. * * @template T - The type of the stored value. */ type StorageStateOptions = { /** * Custom serializer used to convert the value to a string before writing to * storage. Defaults to `JSON.stringify` when omitted. */ serializer?: (item: T) => string; /** * Custom deserializer used to convert the stored string back to a value when * reading from storage. Defaults to `JSON.parse` when omitted. */ deserializer?: (item: string) => T; /** * Controls which parts of the storage interface are exposed by the hook. * The return tuple shape varies per mode — see the table below. * * | `mode` | Return type | * | -------------- | ---------------------------------------------------------------- | * | `undefined` | `[T, Dispatch>, () => T, () => void]` | * | `"read/write"` | `[T, Dispatch>, () => T, () => void]` | * | `"read"` | `[T, () => T, () => void]` | * | `"write"` | `[Dispatch>, () => T, () => void]` | */ mode?: "read" | "write" | "read/write"; }; /** * Parameters accepted by all overloads of [useLocalStorageState](https://react-tools.ndria.dev/hooks/state/useLocalStorageState). * * @template T - The type of the value stored in `localStorage`. */ type UseLocalStorageStateProps = { /** * The `localStorage` key under which the value is persisted. Must be unique * across the application to avoid collisions with other stored entries. */ key: string; /** * The initial state value, used when no entry exists in `localStorage` for * the given `key`. Accepts either a direct value or a lazy initializer * function invoked only on the first render. */ initialState?: T | (() => T); /** * Optional configuration for serialization and access mode. * See {@link StorageStateOptions}. */ opts?: StorageStateOptions; }; /** * Return value of [useLocalStorageState](https://react-tools.ndria.dev/hooks/state/useLocalStorageState) and [useSessionStorageState](https://react-tools.ndria.dev/hooks/state/useSessionStorageState) * when `mode` is `undefined` or `"read/write"`. * * @template T - The type of the stored value. */ type StorageStateReadWriteResult = [ /** The current reactive state value, synchronised with storage. */ T, /** * A setter that updates both the React state and the corresponding storage * entry. Accepts either a new value or an updater function receiving the * current value and returning the next. */ Dispatch>, /** * A stable getter that returns the current value synchronously without * causing a re-render. */ () => T, /** * Removes the entry from storage and resets the state to `initialState`. */ () => void ]; /** * Return value of [useLocalStorageState](https://react-tools.ndria.dev/hooks/state/useLocalStorageState) and [useSessionStorageState](https://react-tools.ndria.dev/hooks/state/useSessionStorageState) * when `mode` is `"read"`. * * @template T - The type of the stored value. */ type StorageStateReadResult = [ /** The current reactive state value, synchronised with storage. */ T, /** * A stable getter that returns the current value synchronously without * causing a re-render. */ () => T, /** * Removes the entry from storage and resets the state to `initialState`. */ () => void ]; /** * Return value of [useLocalStorageState](https://react-tools.ndria.dev/hooks/state/useLocalStorageState) and [useSessionStorageState](https://react-tools.ndria.dev/hooks/state/useSessionStorageState) * when `mode` is `"write"`. * * @template T - The type of the stored value. */ type StorageStateWriteResult = [ /** * A setter that updates both the React state and the corresponding storage * entry. Accepts either a new value or an updater function receiving the * current value and returning the next. */ Dispatch>, /** * A stable getter that returns the current value synchronously without * causing a re-render. */ () => T, /** * Removes the entry from storage and resets the state to `initialState`. */ () => void ]; /** * Parameters accepted by all overloads of [useSessionStorageState](https://react-tools.ndria.dev/hooks/state/useSessionStorageState). * * @template T - The type of the value stored in `sessionStorage`. */ type UseSessionStorageStateProps = UseLocalStorageStateProps; /** * Parameters accepted by [useMap](https://react-tools.ndria.dev/hooks/state/useMap). * * @template K - The type of the map keys. * @template V - The type of the map values. */ type UseMapProps = { /** * The initial entries of the map. Accepts any `Iterable` of `[key, value]` * pairs (e.g. an array of tuples, another `Map`, or a generator) or a lazy * initializer function returning such an iterable, invoked only on the first * render. When omitted, the map is initialised as empty. */ initialState?: Iterable | (() => Iterable); }; /** * Return value of [useMap](https://react-tools.ndria.dev/hooks/state/useMap). * A reactive `Map` whose mutating methods automatically synchronise the * underlying React state. All standard read-only methods (`get`, `has`, * `keys`, `values`, `entries`, `forEach`, etc.) are inherited unchanged from * `Map`. The following mutating methods are overridden to trigger a * re-render: * * | Method | Behaviour | * | -------- | ---------------------------------------------------------------------------- | * | `set` | Adds or updates the entry for `key`, triggers a re-render, returns the map. | * | `clear` | Removes all entries and triggers a re-render. | * | `delete` | Removes the entry for `key` and triggers a re-render. Returns `true` if the key existed, `false` otherwise. | * * @template K - The type of the map keys. * @template V - The type of the map values. */ type UseMapResult = Map & { /** * Adds or updates the entry for `key` with `value`, triggers a re-render, * and returns the updated map. */ set(key: K, value: V): Map; /** Removes all entries from the map and triggers a re-render. */ clear(): void; /** * Removes the entry for `key` and triggers a re-render. Returns `true` if * the key existed in the map before deletion, `false` otherwise. */ delete(key: K): boolean; }; /** * Parameters accepted by [usePrevious](https://react-tools.ndria.dev/hooks/state/usePrevious). * * @template T - The type of the value being tracked. */ type UsePreviousProps = { /** * The value to track. On each render, the hook stores the current value so * it can be returned as the "previous" value on the next render. */ variable: T; }; /** * Return value of [usePrevious](https://react-tools.ndria.dev/hooks/state/usePrevious). * * @template T - The type of the tracked value. */ type UsePreviousResult = [ /** * The value from the previous render. `undefined` on the first render, before * any previous value has been recorded. */ T | undefined, /** * A function that enables or disables tracking. When called with `false`, * the hook stops recording new previous values — the last recorded value * is frozen until tracking is re-enabled with `true`. */ (enable: boolean) => void ]; /** * Parameters accepted by [useProxyState](https://react-tools.ndria.dev/hooks/state/useProxyState). * * @template T - The state object type. Must be a plain object (record). */ type UseProxyStateProps> = { /** * The initial state object. Accepts either a direct value or a lazy * initializer function invoked only on the first render. */ initialState: T | (() => T); /** * When `true`, nested objects within the state are also wrapped in a `Proxy`, * making deep mutations reactive. When `false` *(default)*, only top-level * property assignments trigger a re-render. */ proxyInDepth?: boolean; }; /** * Return value of [useProxyState](https://react-tools.ndria.dev/hooks/state/useProxyState). * * A `Proxy`-wrapped version of the state object `T`. Assigning any property * directly on the returned object (e.g. `state.count = 5`) triggers a re-render * automatically — no setter function is needed. * * @template T - The state object type. */ type UseProxyStateResult> = T; /** * Parameters accepted by [useReducerGetReset](https://react-tools.ndria.dev/hooks/state/useReducerGetReset). * * @template R - The reducer type, extending `Reducer`. */ type UseReducerGetResetProps> = { /** * The reducer function `(state, action) => state` that computes the next * state given the current state and a dispatched action. */ reducer: R; /** * The initial reducer state value, passed directly to `useReducer`. */ initialState: ReducerState; /** * An optional initializer function that receives `initialState` and returns * the actual initial state. Useful for lazily computing the initial value * or extracting it from a larger object. */ initializer?: (init: ReducerState) => ReducerState; }; /** * Return value of [useReducerGetReset](https://react-tools.ndria.dev/hooks/state/useReducerGetReset). * * @template R - The reducer type. */ type UseReducerGetResetResult> = [ /** The current reducer state, reactive — triggers a re-render when updated. */ ReducerState, /** The stable dispatch function used to send actions to the reducer. */ Dispatch>, /** * A stable getter that returns the current reducer state synchronously * without causing a re-render. Useful for reading state inside callbacks * without adding it as a dependency. */ () => ReducerState, /** * Resets the reducer state back to the original `initialState` (after * applying `initializer` if provided), dispatching a reset internally * and triggering a re-render. */ () => void ]; /** * The history controls object returned as part of {@link UseReducerHistoryResult} * and {@link UseReducerHistoryGetterResult}. * * @template R - The reducer type. */ type ReducerHistoryControls> = { /** * A read-only array of all recorded state snapshots, from oldest to most recent. * The entry at `presentPointer` is the currently active state. */ history: readonly ReducerState[]; /** * The index within `history` that corresponds to the current state. Moves * backward on `undo` and forward on `redo` or a new dispatch. */ presentPointer: number; /** * Enables or disables history recording. When called with `false`, dispatched * actions still update the state but are not added to `history`. Re-enable * with `true` to resume recording. */ trackUpdate: (enable: boolean) => void; /** * `true` when there is at least one state snapshot before `presentPointer` * that can be restored via `undo`. */ canUndo: boolean; /** * `true` when there is at least one state snapshot after `presentPointer` * that can be restored via `redo`. */ canRedo: boolean; /** * Moves `presentPointer` one step backward in `history` and restores the * corresponding state. No-op when `canUndo` is `false`. */ undo: () => void; /** * Moves `presentPointer` one step forward in `history` and restores the * corresponding state. No-op when `canRedo` is `false`. */ redo: () => void; /** * Jumps directly to the state at the given `index` in `history`, updating * `presentPointer` and restoring that snapshot. */ go: (index: number) => void; /** * Clears the entire history array. When `value` is provided, the cleared * history is replaced with a single entry computed by dispatching `value` * against the current state; otherwise the history is reset to the current * state only. */ clear: (value?: ReducerAction) => void; }; /** * Parameters accepted by [useReducerHistory](https://react-tools.ndria.dev/hooks/state/useReducerHistory) and [useReducerHistoryGetter](https://react-tools.ndria.dev/hooks/state/useReducerHistoryGetter). * * @template R - The reducer type, extending `Reducer`. */ type UseReducerHistoryProps> = { /** * The reducer function `(state, action) => state` that computes the next * state given the current state and a dispatched action. */ reducer: R; /** * The initial reducer state value, passed directly to `useReducer`. */ initialState: ReducerState; /** * An optional initializer function that receives `initialState` and returns * the actual initial state. Useful for lazily computing the initial value * or extracting it from a larger object. */ initializer?: (init: ReducerState) => ReducerState; /** * Maximum number of state snapshots retained in `history`: * - **`"no-limit"`** *(default)* — All snapshots are retained indefinitely. * - **`number`** — Once the limit is reached, the oldest snapshot is evicted * to make room for the new one (FIFO). */ capacity?: number | "no-limit"; }; /** * Return value of [useReducerHistory](https://react-tools.ndria.dev/hooks/state/useReducerHistory). * * @template R - The reducer type. */ type UseReducerHistoryResult> = [ /** The current reducer state, reactive — triggers a re-render when updated. */ ReducerState, /** The stable dispatch function used to send actions to the reducer. */ Dispatch>, /** The history controls object. See {@link ReducerHistoryControls}. */ ReducerHistoryControls ]; /** * Return value of [useReducerHistoryGetter](https://react-tools.ndria.dev/hooks/state/useReducerHistoryGetter). * * @template R - The reducer type. */ type UseReducerHistoryGetterResult> = [ /** The current reducer state, reactive — triggers a re-render when updated. */ ReducerState, /** The stable dispatch function used to send actions to the reducer. */ Dispatch>, /** * A stable getter that returns the current reducer state synchronously * without causing a re-render. Useful for reading state inside callbacks * without adding it as a dependency. */ () => ReducerState, /** The history controls object. See {@link ReducerHistoryControls}. */ ReducerHistoryControls ]; /** * Parameters accepted by [useSet](https://react-tools.ndria.dev/hooks/state/useSet). * * @template T - The type of the elements contained in the set. */ type UseSetProps = { /** * The initial set state. Accepts any `Iterable` (e.g. an array, another * `Set`, or a generator) or a lazy initializer function returning such an * iterable, invoked only on the first render. When omitted, the set is * initialised as empty. */ initialState?: Iterable | (() => Iterable); }; /** * Return value of [useSet](https://react-tools.ndria.dev/hooks/state/useSet). * A reactive `Set` whose mutating methods automatically synchronise the * underlying React state. All standard read-only methods (`has`, `keys`, * `values`, `entries`, `forEach`, etc.) are inherited unchanged from * `Set`. The following mutating methods are overridden to trigger a * re-render: * * | Method | Behaviour | * | -------- | ---------------------------------------------------------------------------------- | * | `add` | Adds `value` to the set, triggers a re-render, and returns the updated set. | * | `clear` | Removes all values and triggers a re-render. | * | `delete` | Removes `value` and triggers a re-render. Returns `true` if the value existed, `false` otherwise. | * * @template T - The type of the elements contained in the set. */ type UseSetResult = Set & { /** * Adds `value` to the set, triggers a re-render, and returns the updated set. */ add(value: T): Set; /** Removes all values from the set and triggers a re-render. */ clear(): void; /** * Removes `value` from the set and triggers a re-render. Returns `true` if * the value existed in the set before deletion, `false` otherwise. */ delete(value: T): boolean; }; /** * The history controls object returned as part of {@link UseStateHistoryResult} * and {@link UseStateHistoryGetterResult}. * * @template T - The type of the state value. */ type StateHistoryControls = { /** * A read-only array of all recorded state snapshots, from oldest to most * recent. The entry at `presentPointer` is the currently active state. */ history: readonly T[]; /** * The index within `history` that corresponds to the current state. Moves * backward on `undo` and forward on `redo` or a new state update. */ presentPointer: number; /** * Enables or disables history recording. When called with `false`, state * updates still trigger re-renders but are not added to `history`. Re-enable * with `true` to resume recording. */ trackUpdate: (enable: boolean) => void; /** * `true` when there is at least one state snapshot before `presentPointer` * that can be restored via `undo`. */ canUndo: boolean; /** * `true` when there is at least one state snapshot after `presentPointer` * that can be restored via `redo`. */ canRedo: boolean; /** * Moves `presentPointer` one step backward in `history` and restores the * corresponding state. No-op when `canUndo` is `false`. */ undo: () => void; /** * Moves `presentPointer` one step forward in `history` and restores the * corresponding state. No-op when `canRedo` is `false`. */ redo: () => void; /** * Jumps directly to the state at the given `index` in `history`, updating * `presentPointer` and restoring that snapshot. */ go: (index: number) => void; /** * Clears the entire history array. When `value` is provided, the cleared * history is replaced with a single entry equal to `value`; otherwise the * history is reset to the current state only. */ clear: (value?: T) => void; }; /** * Parameters accepted by [useStateHistory](https://react-tools.ndria.dev/hooks/state/useStateHistory) and [useStateHistoryGetter](https://react-tools.ndria.dev/hooks/state/useStateHistoryGetter). * * @template T - The type of the state value. */ type UseStateHistoryProps = { /** * The initial state value. Accepts either a direct value or a lazy initializer * function invoked only on the first render. */ initialState: T | (() => T); /** * Maximum number of state snapshots retained in `history`: * - **`"no-limit"`** *(default)* — All snapshots are retained indefinitely. * - **`number`** — Once the limit is reached, the oldest snapshot is evicted * to make room for the new one (FIFO). */ capacity?: number | "no-limit"; }; /** * Return value of [useStateHistory](https://react-tools.ndria.dev/hooks/state/useStateHistory). * * @template T - The type of the state value. */ type UseStateHistoryResult = [ /** The current state value, reactive — triggers a re-render when updated. */ T, /** * A stable setter (same semantics as the setter returned by `useState`). * Accepts either a new value or an updater function receiving the current * state and returning the next. */ Dispatch>, /** The history controls object. See {@link StateHistoryControls}. */ StateHistoryControls ]; /** * Return value of [useStateHistoryGetter](https://react-tools.ndria.dev/hooks/state/useStateHistoryGetter). * * @template T - The type of the state value. */ type UseStateHistoryGetterResult = [ /** The current state value, reactive — triggers a re-render when updated. */ T, /** * A stable setter (same semantics as the setter returned by `useState`). * Accepts either a new value or an updater function receiving the current * state and returning the next. */ Dispatch>, /** * A stable getter that returns the current state value synchronously without * causing a re-render. Useful for reading state inside callbacks without * adding it as a dependency. */ () => T, /** The history controls object. See {@link StateHistoryControls}. */ StateHistoryControls ]; /** * Parameters accepted by [useSyncExternalStore](https://react-tools.ndria.dev/hooks/state/useSyncExternalStore). * * @template Snapshot - The type of the snapshot value returned by `getSnapshot`. */ type UseSyncExternalStoreProps = { /** * A function that subscribes to the external store. Receives an `onStoreChange` * callback that must be called whenever the store changes. Must return a cleanup * function that unsubscribes when called. React may call this multiple times * with different callbacks — always use the latest one. */ subscribe: (onStoreChange: () => void) => () => void; /** * A function that returns the current snapshot of the store. Must be a pure * function that returns the same value when the store has not changed, allowing * React to bail out of re-renders via referential equality. Called on every * render and after every store change notification. */ getSnapshot: () => Snapshot; }; /** * Return value of [useSyncExternalStore](https://react-tools.ndria.dev/hooks/state/useSyncExternalStore). * * The current snapshot of the external store, reactive — the component re-renders * whenever `subscribe` notifies React of a change and `getSnapshot` returns a * different value. * * @template Snapshot - The type of the snapshot value. */ type UseSyncExternalStoreResult = Snapshot; /** * Validator function accepted by [useStateValidator](https://react-tools.ndria.dev/hooks/state/useStateValidator). * * The function is called on every state update and must return the (possibly * mutated) `validation` argument so React can detect changes. * * @template T Type of the validated state. * * ### Overloads * - **Object state** — both `this` context and the first argument receive the full object; * the `validation` argument is shaped as `{ [key in keyof T]: ValidationEntry }`. * - **Primitive state** — the first argument is the primitive value; * the `validation` argument is a single `ValidationEntry`. */ interface StateValidator { (this: T, state: T, validation: T extends object ? { [k in keyof T]: { invalid: boolean; message?: string; }; } : { invalid: boolean; message?: string; }): typeof validation; (state: T, validation: T extends object ? { [k in keyof T]: { invalid: boolean; message?: string; }; } : { invalid: boolean; message?: string; }): typeof validation; } /** * Parameters accepted by [useStateValidator](https://react-tools.ndria.dev/hooks/state/useStateValidator). * * @template T - The type of the state value being validated. */ type UseStateValidatorProps = { /** * The initial state value. Accepts either a direct value or a lazy initializer * function invoked only on the first render. */ initialState: T | (() => T); /** * A validator function or configuration object that defines the validation * rules applied to the state. See {@link StateValidator}. */ validator: StateValidator; }; /** * Return value of [useStateValidator](https://react-tools.ndria.dev/hooks/state/useStateValidator). * * @template T - The type of the state value being validated. */ type UseStateValidatorResult = [ /** The current state value, reactive — triggers a re-render when updated. */ T, /** * A stable setter (same semantics as the setter returned by `useState`). * Accepts either a new value or an updater function receiving the current * state and returning the next. Triggers re-validation after each update. */ Dispatch>, /** * The current validation result, updated synchronously after each state change. * Shape depends on `T`: * - When `T` is an **object** — a mirrored object where each key maps to * `{ invalid: boolean, message?: string }`, allowing per-field validation * feedback. * - When `T` is a **primitive** — a single `{ invalid: boolean, message?: string }` * object describing the overall validity of the value. */ T extends object ? { [k in keyof T]: { invalid: boolean; message?: string; }; } : { invalid: boolean; message?: string; } ]; /** * **`usePrevious`**: It's track the previous value of a variable, with possibility to enable/disable tracking. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/usePrevious) * @template T - The type of the value being tracked. * @param {UsePreviousProps["variable"]} variable - {@link UsePreviousProps} * @returns {UsePreviousResult} result - {@link UsePreviousResult} */ declare const usePrevious: (variable: UsePreviousProps["variable"]) => UsePreviousResult; /** * **`useStateGetReset`**: Custom useState with get and reset state functions. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useStateGetReset) * @template T - The type of the state value. * @param {UseStateGetResetProps["initialState"]} [initialState] - {@link UseStateGetResetProps} * @returns {UseStateGetResetResult} result - {@link UseStateGetResetResult} */ declare function useStateGetReset(): [T | undefined, Dispatch>, () => T | undefined, () => void]; declare function useStateGetReset(initialState?: T | (() => T)): [T, Dispatch>, () => T, () => void]; /** * **`useStateHistory`**: custom useState that tracks and allows to use previous values. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useStateHistory) * @template T - The type of the state value. * @param {UseStateHistoryProps["initialState"]} initialState - {@link UseStateHistoryProps} * @param {UseStateHistoryProps["capacity"]} capacity - {@link UseStateHistoryProps} * @returns {UseStateHistoryResult} result - {@link UseStateHistoryResult} */ declare const useStateHistory: (initialState: UseStateHistoryProps["initialState"], capacity?: UseStateHistoryProps["capacity"]) => UseStateHistoryResult; /** * **`useStateHistoryGetter`**: custom useState with getter state function and that tracks and allows to use previous values. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useStateHistoryGetter) * @template T - The type of the state value. * @param {UseStateHistoryProps["initialState"]} initialState - {@link UseStateHistoryProps} * @param {UseStateHistoryProps["capacity"]} capacity - {@link UseStateHistoryProps} * @returns {UseStateHistoryGetterResult} result - {@link UseStateHistoryGetterResult} */ declare const useStateHistoryGetter: (initialState: UseStateHistoryProps["initialState"], capacity?: UseStateHistoryProps["capacity"]) => UseStateHistoryGetterResult; /** * **`useReducerGetReset`**: Custom useReducer with get and reset state functions. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useReducerGetReset) * @template R - The reducer type, extending `Reducer`. * @param {UseReducerGetResetProps["reducer"]} reducer - {@link UseReducerGetResetProps} * @param {UseReducerGetResetProps["initialState"]} initialState - {@link UseReducerGetResetProps} * @param {UseReducerGetResetProps["initializer"]} [initializer] - {@link UseReducerGetResetProps} * @returns {UseReducerGetResetResult} result - {@link UseReducerGetResetResult} */ declare const useReducerGetReset: >(reducer: UseReducerGetResetProps["reducer"], initialState: UseReducerGetResetProps["initialState"], initializer?: UseReducerGetResetProps["initializer"]) => UseReducerGetResetResult; /** * **`useReducerHistory`**: Custom useReducer that tracks and allows to use previous values. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useReducerHistory) * @template R - The reducer type. * @param {UseReducerHistoryProps["obj"]} reducer - {@link UseReducerHistoryProps} * @param {UseReducerHistoryProps["mutatorsFn"]} initialState - {@link UseReducerHistoryProps} * @param {UseReducerHistoryProps["persist"]} [initializer] - {@link UseReducerHistoryProps} * @param {UseReducerHistoryProps["persist"]} [capacity] - {@link UseReducerHistoryProps} * @returns {UseReducerHistoryResult} result - {@link UseReducerHistoryResult} */ declare const useReducerHistory: >(reducer: UseReducerHistoryProps["reducer"], initialState: UseReducerHistoryProps["initialState"], initializer?: UseReducerHistoryProps["initializer"], capacity?: UseReducerHistoryProps["capacity"]) => UseReducerHistoryResult; /** * **`useReducerHistoryGetter`**: Custom useReducer with getter state function and that tracks and allows to use previous values. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useReducerHistoryGetter) * @template R - The reducer type. * @param {UseReducerHistoryProps["reducer"]} reducer - {@link UseReducerHistoryProps} * @param {UseReducerHistoryProps["initialState"]} initialState - {@link UseReducerHistoryProps} * @param {UseReducerHistoryProps["initializer"]} [initializer] - {@link UseReducerHistoryProps} * @param {UseReducerHistoryProps["capacity"]} [capacity] - {@link UseReducerHistoryProps} * @returns {UseReducerHistoryGetterResult} result - {@link UseReducerHistoryGetterResult} */ declare const useReducerHistoryGetter: >(reducer: UseReducerHistoryProps["reducer"], initialState: UseReducerHistoryProps["initialState"], initializer?: UseReducerHistoryProps["initializer"], capacity?: UseReducerHistoryProps["capacity"]) => UseReducerHistoryGetterResult; /** * ___useLocalStorageState___: Custom _useState_ hook implementation using _LocalStorage_, with immutable _getter state_ function and to _remove_ key from localStorage. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useLocalStorageState) * @template T - The type of the stored value. * @param {UseLocalStorageStateProps} props - {@link UseLocalStorageStateProps} * @returns {StorageStateReadWriteResult | StorageStateReadResult | StorageStateWriteResult} result - {@link StorageStateReadWriteResult} */ declare function useLocalStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: undefined; }; }): StorageStateReadWriteResult; declare function useLocalStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: "read"; }; }): StorageStateReadResult; declare function useLocalStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: "write"; }; }): StorageStateWriteResult; declare function useLocalStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: "read/write"; }; }): StorageStateReadWriteResult; /** * ___useSessionStorageState___: Custom _useState_ hook implementation using _sessionStorage_, with immutable _getter state_ function and to _remove_ key from sessionStorage. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useSessionStorageState) * @template T - The type of the stored value. * @param {CreatePubSubStoreProps["obj"]} props - {@link CreatePubSubStoreProps} * @param {CreatePubSubStoreProps["mutatorsFn"]} [mutatorsFn] - {@link CreatePubSubStoreProps} * @param {CreatePubSubStoreProps["persist"]} [persist] - {@link CreatePubSubStoreProps} * @returns {CreatePubSubStoreResult} result - {@link CreatePubSubStoreResult} */ declare function useSessionStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: undefined; }; }): StorageStateReadWriteResult; declare function useSessionStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: "read"; }; }): StorageStateReadResult; declare function useSessionStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: "write"; }; }): StorageStateWriteResult; declare function useSessionStorageState({ key, initialState, opts }: { key: string; initialState?: T | (() => T); opts?: { serializer?: (item: T) => string; deserializer?: (item: string) => T; mode?: "read/write"; }; }): StorageStateReadWriteResult; /** * __`useMap`__: Hook to use _Map data structure_ to handle component state with all Map methods. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useMap) * @template K - The type of the map keys. * @template V - The type of the map values. * @param {UseMapProps["initialState"]} [initialState] - {@link UseMapProps} * @returns {UseMapResult} result - {@link UseMapResult} */ declare const useMap: (initialState?: UseMapProps["initialState"]) => UseMapResult; /** * __`useSet`__: Hook to use _Set data structure_ to handle component state with all Set methods. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useSet) * @template T - The type of the elements contained in the set. * @param {UseSetProps["initialState"]} [initialState] - {@link UseSetProps} * @returns {UseSetResult} result - {@link UseSetResult} */ declare const useSet: (initialState?: UseSetProps["initialState"]) => UseSetResult; /** * __`useArray`__: Hook to use _Array data structure_ to handle component state with all Array methods. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useArray) * @template T - The type of the elements contained in the array. * @param {UseArrayProps["initialState"]} [initialState] - {@link UseArrayProps} * @returns {UseArrayResult} result - {@link UseArrayResult} */ declare const useArray: (initialState?: UseArrayProps["initialState"]) => UseArrayResult; /** * __`useProxyState`__: Hook to handle component state that allows you to use an object for your state and mutating it in a way more idiomatic for JS. * * __*N.B.*__: not destructure state, otherwise break changes updated. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useProxyState) * @template T - The state object type. Must be a plain object (record). * @param {UseProxyStateProps["initialState"]} initialState - {@link UseProxyStateProps} * @param {UseProxyStateProps["proxyInDepth"]} [proxyInDepth] - {@link UseProxyStateProps} * @returns {UseProxyStateResult} result - {@link UseProxyStateResult} */ declare const useProxyState: >(initialState: UseProxyStateProps["initialState"], proxyInDepth?: UseProxyStateProps["proxyInDepth"]) => UseProxyStateResult; /** * __`useSyncExternalStore`__: _useSyncExternalStore_ hook polyfilled for React versions below 18 ___only client side___. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useSyncExternalStore) * @template Snapshot - The type of the snapshot value returned by `getSnapshot`. * @param {UseSyncExternalStoreProps["subscribe"]} subscribe - {@link UseSyncExternalStoreProps} * @param {UseSyncExternalStoreProps["getSnapshot"]} getSnapshot - {@link UseSyncExternalStoreProps} * @returns {UseSyncExternalStoreResult} result - {@link UseSyncExternalStoreResult} */ declare function useSyncExternalStorePolyfill(subscribe: UseSyncExternalStoreProps["subscribe"], getSnapshot: UseSyncExternalStoreProps["getSnapshot"]): UseSyncExternalStoreResult; declare const useSyncExternalStore: typeof useSyncExternalStorePolyfill; /** * **`useDerivedState`**: Hook useful when the internal state of a component depends on one or more props. It receives an _initial state_ and a _dependency array_ that works the same way as that of a _useEffect_, _useMemo_, and _useCallback_. Every time the dependencies change, the __derived state__ is resetted to _initial state_. A third optional parameter can be passed, to execute a _compute_ function after the dependencies are updated, without having a _useEffect_ within the component. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useDerivedState) * @template T - The type of the state value. * @param {UseDerivedStateProps["initialState"]} initialState - {@link UseDerivedStateProps} * @param {UseDerivedStateProps["deps"]} deps - {@link UseDerivedStateProps} * @param {UseDerivedStateProps["compute"]} [compute] - {@link UseDerivedStateProps} * @returns {UseDerivedStateResult} result - {@link UseDerivedStateResult} */ declare const useDerivedState: (initialState: UseDerivedStateProps["initialState"], deps: UseDerivedStateProps["deps"], compute?: UseDerivedStateProps["compute"]) => UseDerivedStateResult; /** * **`useStateValidator`**: custom _useState_ hook that validates state on every update. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/useStateValidator) * @template T Type of the validated state. * @param {CreatePubSubStoreProps["initialState"]} initialState - {@link CreatePubSubStoreProps} * @param {CreatePubSubStoreProps["validator"]} validator - {@link CreatePubSubStoreProps} * @returns {CreatePubSubStoreResult} result - {@link CreatePubSubStoreResult} */ declare const useStateValidator: (initialState: UseStateValidatorProps["initialState"], validator: UseStateValidatorProps["validator"]) => UseStateValidatorResult; /** * **`createPubSubStore`**: A state management hook implemented on Publish-Subscribe pattern. It allows components to subscribe to state changes and receive updates whenever the state is modified, providing a scalable and decoupled state management solution. * * __*N.B.*__: to work properly, objects like Set, Map, Date or more generally objects without _Symbol.iterator_ must be treated as immutable. * @see [📖 Documentation](https://react-tools.ndria.dev/hooks/state/createPubSubStore) * @template T - The store object type. Must be a plain object. * @template E - The mutators function map type. Each value must be a function * @param {CreatePubSubStoreProps["obj"]} obj - {@link CreatePubSubStoreProps} * @param {CreatePubSubStoreProps["mutatorsFn"]} [mutatorsFn] - {@link CreatePubSubStoreProps} * @param {CreatePubSubStoreProps["persist"]} [persist] - {@link CreatePubSubStoreProps} * @returns {CreatePubSubStoreResult} result - {@link CreatePubSubStoreResult} */ declare const createPubSubStore: void>>(obj: CreatePubSubStoreProps["obj"], mutatorsFn?: CreatePubSubStoreProps["mutatorsFn"], persist?: CreatePubSubStoreProps["persist"]) => CreatePubSubStoreResult; export { useDerivedState as a, useLocalStorageState as b, createPubSubStore as c, useMap as d, usePrevious as e, useProxyState as f, useReducerGetReset as g, useReducerHistory as h, useReducerHistoryGetter as i, useSessionStorageState as j, useSet as k, useStateGetReset as l, useStateHistory as m, useStateHistoryGetter as n, useStateValidator as o, useSyncExternalStore as p, useArray as u }; export type { UseSyncExternalStoreResult as $, UseDerivedStateResult as A, UseLocalStorageStateProps as B, CreatePubSubStoreProps as C, UseMapProps as D, UseMapResult as E, UsePreviousProps as F, UsePreviousResult as G, UseProxyStateProps as H, UseProxyStateResult as I, UseReducerGetResetProps as J, UseReducerGetResetResult as K, UseReducerHistoryGetterResult as L, UseReducerHistoryProps as M, UseReducerHistoryResult as N, UseSessionStorageStateProps as O, PubSubMutators as P, UseSetProps as Q, ReducerHistoryControls as R, StateHistoryControls as S, UseSetResult as T, UseArrayProps as U, UseStateHistoryGetterResult as V, UseStateHistoryProps as W, UseStateHistoryResult as X, UseStateValidatorProps as Y, UseStateValidatorResult as Z, UseSyncExternalStoreProps as _, CreatePubSubStoreResult as q, PubSubMutatorsFn as r, StateValidator as s, StorageStateOptions as t, StorageStateReadResult as v, StorageStateReadWriteResult as w, StorageStateWriteResult as x, UseArrayResult as y, UseDerivedStateProps as z };