@storesjs/stores 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christian Baroni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+import { StoresLogger } from './logger';
+import { SyncEngine } from './sync/types';
+import { AsyncStorageInterface, SyncStorageInterface } from './types';
+export type StoresConfig = {
+    logger: StoresLogger;
+    storage: AsyncStorageInterface | SyncStorageInterface;
+    syncEngine: SyncEngine;
+};
+type ConfigWithoutLogger = Omit<StoresConfig, 'logger'>;
+export declare function configureStores(update: Partial<StoresConfig>): void;
+export declare function getStoresConfig(): ConfigWithoutLogger;
+export declare function markStoreCreated(): void;
+export {};

package/dist/createBaseStore.d.ts

@@ -0,0 +1,35 @@
+import { BaseStoreOptions, OptionallyPersistedStore, Store, StateCreator } from './types';
+/**
+ * Creates a base store without persistence.
+ * @param createState - The state creator function for the base store.
+ * @returns A Zustand store with the specified state.
+ */
+export declare function createBaseStore<S>(createState: StateCreator<S>): Store<S>;
+/**
+ * Creates a base store with persistence.
+ * @param createState - The state creator function for the base store.
+ * @param options - The configuration options for persistence and sync.
+ * @returns A Zustand store with the specified state and persistence.
+ */
+export declare function createBaseStore<S, PersistedState extends Partial<S> = Partial<S>, PersistReturn extends void = void>(createState: StateCreator<S>, options: BaseStoreOptions<S, PersistedState, PersistReturn>): Store<S, PersistedState, false, PersistReturn>;
+/**
+ * Creates a base store with async persistence.
+ * @param createState - The state creator function for the base store.
+ * @param options - The configuration options for persistence and sync.
+ * @returns A Zustand store with the specified state and persistence.
+ */
+export declare function createBaseStore<S, PersistedState extends Partial<S> = Partial<S>, PersistReturn extends Promise<void> = Promise<void>>(createState: StateCreator<S>, options: BaseStoreOptions<S, PersistedState, PersistReturn>): Store<S, PersistedState, false, PersistReturn>;
+/**
+ * Creates a base store with optional persistence.
+ * @param createState - The state creator function for the base store.
+ * @param options - The configuration options for persistence and sync.
+ * @returns A Zustand store with the specified state and optional persistence.
+ */
+export declare function createBaseStore<S, PersistedState extends Partial<S> = Partial<S>, PersistReturn extends void = void>(createState: StateCreator<S>, options?: BaseStoreOptions<S, PersistedState, PersistReturn>): OptionallyPersistedStore<S, PersistedState, PersistReturn>;
+/**
+ * Creates a base store with optional async persistence.
+ * @param createState - The state creator function for the base store.
+ * @param options - The configuration options for persistence and sync.
+ * @returns A Zustand store with the specified state and optional persistence.
+ */
+export declare function createBaseStore<S, PersistedState extends Partial<S> = Partial<S>, PersistReturn extends Promise<void> = Promise<void>>(createState: StateCreator<S>, options?: BaseStoreOptions<S, PersistedState, PersistReturn>): OptionallyPersistedStore<S, PersistedState, PersistReturn>;

package/dist/createDerivedStore.d.ts

@@ -0,0 +1,70 @@
+import { DeriveOptions, DerivedStore, EqualityFn, Store, Selector, InferStoreState } from './types';
+/**
+ * ### `createDerivedStore`
+ *
+ * Creates a **read-only** store derived from one or more underlying Zustand stores.
+ *
+ * ---
+ * The `deriveFunction` is called whenever its dependencies change, producing a new derived state.
+ * Dependencies are automatically tracked through a special `$` helper, which supports:
+ *
+ * 1) **Selector-based** usage:
+ *    ```ts
+ *    $ => {
+ *      const user = $(useUserStore, s => s.user, shallowEqual);
+ *      const theme = $(useSettingsStore, s => s.appearance.theme);
+ *      return { user, theme, isAdmin: user?.roles.includes('admin') };
+ *    }
+ *    ```
+ *
+ * 2) **Proxy-based** usage (auto-built selectors for nested properties):
+ *    ```ts
+ *    $ => {
+ *      const { user } = $(useUserStore); // Subscribe to `user`
+ *      const theme = $(useSettingsStore).appearance.theme; // Subscribe to `theme`
+ *      return { isAdmin: user?.roles.includes('admin'), theme, user };
+ *    }
+ *    ```
+ *
+ * ---
+ * Derived stores automatically unsubscribe from all dependencies when no consumers remain, and
+ * resubscribe when new consumers appear. The returned function doubles as:
+ *
+ * - A **React hook** (`const state = useDerivedStore(selector, equalityFn?)`)
+ * - A **store object** with `getState()`, `subscribe()`, and `destroy()`
+ *
+ * ---
+ * You can optionally pass a second parameter (either an equality function or a config object)
+ * to enable debouncing, customize the equality function, or set `lockDependencies: true`.
+ *
+ * (When dependencies are locked, subscriptions created via `$` are established once and are
+ * not rebuilt on subsequent re-derives, which can be a performance win for certain workloads.)
+ *
+ * ---
+ * @example
+ * ```ts
+ * // Create a derived store
+ * const useSearchResults = createDerivedStore($ => {
+ *   const query = $(useSearchStore).query.trim().toLowerCase();
+ *   const items = $(useItemsStore).items;
+ *   return findResults(query, items);
+ * }, shallowEqual);
+ *
+ * function SearchResults() {
+ *   // Consume the derived state
+ *   const results = useSearchResults(); // Or (selector, equalityFn?)
+ *   return <ResultsList items={results} />;
+ * }
+ * ```
+ *
+ * ---
+ * @param deriveFunction - Function that reads from other stores via `$` to produce derived state.
+ * @param optionsOrEqualityFn - Either an equality function or a config object (see `DeriveOptions`).
+ *
+ * @returns A read-only derived store (usable as a hook or standard store object).
+ */
+export declare function createDerivedStore<Derived>(deriveFunction: ($: DeriveGetter) => Derived, optionsOrEqualityFn?: DeriveOptions<Derived>): DerivedStore<Derived>;
+export type DeriveGetter = {
+    <S extends Store<unknown>>(store: S): InferStoreState<S>;
+    <S extends Store<unknown>, Selected>(store: S, selector: Selector<InferStoreState<S>, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
+};

package/dist/createQueryStore.d.ts

@@ -0,0 +1,131 @@
+import { QueryStoreConfig, QueryStoreState } from './queryStore/types';
+import { BaseStoreOptions, OptionallyPersistedStore, PersistedStore, StateCreator, Store } from './types';
+/**
+ * Creates a persisted, query-enabled store with data fetching capabilities (sync storage).
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends void = void>(config: QueryStoreConfig<TQueryFnData, TParams, TData>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>): PersistedStore<QueryStoreState<TData, TParams>, PersistedState, false, PersistReturn>;
+/**
+ * Creates a persisted, query-enabled store with data fetching capabilities (async storage).
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends Promise<void> = Promise<void>>(config: QueryStoreConfig<TQueryFnData, TParams, TData>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>): PersistedStore<QueryStoreState<TData, TParams>, PersistedState, false, PersistReturn>;
+/**
+ * Creates a persisted, query-enabled store with data fetching capabilities (sync storage).
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template CustomState - User-defined custom store state
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, CustomState = unknown, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams, CustomState>> = Partial<QueryStoreState<TData, TParams, CustomState>>, PersistReturn extends void = void>(config: QueryStoreConfig<TQueryFnData, TParams, TData, CustomState>, stateCreator: StateCreator<QueryStoreState<TData, TParams, CustomState>, CustomState>, options: BaseStoreOptions<QueryStoreState<TData, TParams, CustomState>, PersistedState, PersistReturn>): PersistedStore<QueryStoreState<TData, TParams, CustomState>, PersistedState, false, PersistReturn>;
+/**
+ * Creates a persisted, query-enabled store with data fetching capabilities (async storage).
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template CustomState - User-defined custom store state
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, CustomState = unknown, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams, CustomState>> = Partial<QueryStoreState<TData, TParams, CustomState>>, PersistReturn extends Promise<void> = Promise<void>>(config: QueryStoreConfig<TQueryFnData, TParams, TData, CustomState>, stateCreator: StateCreator<QueryStoreState<TData, TParams, CustomState>, CustomState>, options: BaseStoreOptions<QueryStoreState<TData, TParams, CustomState>, PersistedState, PersistReturn>): PersistedStore<QueryStoreState<TData, TParams, CustomState>, PersistedState, false, PersistReturn>;
+/**
+ * Creates a query-enabled store with data fetching capabilities.
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template CustomState - User-defined custom store state
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, CustomState = unknown, TData = TQueryFnData>(config: QueryStoreConfig<TQueryFnData, TParams, TData, CustomState>, stateCreator: StateCreator<QueryStoreState<TData, TParams, CustomState>, CustomState>, options?: BaseStoreOptions<QueryStoreState<TData, TParams, CustomState>>): Store<QueryStoreState<TData, TParams, CustomState>>;
+/**
+ * Creates a query-enabled store with data fetching capabilities.
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData>(config: QueryStoreConfig<TQueryFnData, TParams, TData>, options?: BaseStoreOptions<QueryStoreState<TData, TParams>>): Store<QueryStoreState<TData, TParams>>;
+/**
+ * Creates a conditionally persisted, query-enabled store with data-fetching capabilities
+ * and custom state (sync storage).
+ *
+ * `options.persist` may be `undefined` – the returned store exposes `persist?`.
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template CustomState - User-defined custom store state
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, CustomState = unknown, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams, CustomState>> = Partial<QueryStoreState<TData, TParams, CustomState>>, PersistReturn extends void = void>(config: QueryStoreConfig<TQueryFnData, TParams, TData, CustomState>, stateCreator: StateCreator<QueryStoreState<TData, TParams, CustomState>, CustomState>, options?: BaseStoreOptions<QueryStoreState<TData, TParams, CustomState>, PersistedState, PersistReturn>): OptionallyPersistedStore<QueryStoreState<TData, TParams, CustomState>, PersistedState, PersistReturn>;
+/**
+ * Creates a conditionally persisted, query-enabled store with data-fetching capabilities
+ * and custom state (async storage).
+ *
+ * `options.persist` may be `undefined` – the returned store exposes `persist?`.
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template CustomState - User-defined custom store state
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, CustomState = unknown, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams, CustomState>> = Partial<QueryStoreState<TData, TParams, CustomState>>, PersistReturn extends Promise<void> = Promise<void>>(config: QueryStoreConfig<TQueryFnData, TParams, TData, CustomState>, stateCreator: StateCreator<QueryStoreState<TData, TParams, CustomState>, CustomState>, options?: BaseStoreOptions<QueryStoreState<TData, TParams, CustomState>, PersistedState, PersistReturn>): OptionallyPersistedStore<QueryStoreState<TData, TParams, CustomState>, PersistedState, PersistReturn>;
+/**
+ * Creates a conditionally persisted, query-enabled store with data fetching capabilities (sync storage).
+ *
+ * `options.persist` may be `undefined` – the returned store exposes `persist?`.
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends void = void>(config: QueryStoreConfig<TQueryFnData, TParams, TData, QueryStoreState<TData, TParams>>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn> | undefined): OptionallyPersistedStore<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>;
+/**
+ * Creates a conditionally persisted, query-enabled store with data fetching capabilities (async storage).
+ *
+ * `options.persist` may be `undefined` – the returned store exposes `persist?`.
+ *
+ * @template TQueryFnData - The raw data type returned by the fetcher
+ * @template TParams - Parameters passed to the fetcher function
+ * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
+ * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
+ */
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends Promise<void> = Promise<void>>(config: QueryStoreConfig<TQueryFnData, TParams, TData, QueryStoreState<TData, TParams>>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn> | undefined): OptionallyPersistedStore<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>;
+/**
+ * The default query store `retryDelay` function.
+ *
+ * Exponential backoff starting at `baseDelay` (5s default), doubling each retry, capped at `maxDelay` (5m default).
+ *
+ * ```ts
+ * retryCount => Math.min(baseDelay * Math.pow(2, retryCount), maxDelay)
+ * ```
+ */
+export declare function defaultRetryDelay(retryCount: number, options?: {
+    baseDelay?: number;
+    maxDelay?: number;
+}): number;
+/**
+ * @deprecated Use `getQueryKey` instead, unless using for non-parsable query keys.
+ */
+export declare function getLegacyQueryKey<TParams extends Record<string, unknown>>(params: TParams): string;
+/**
+ * Generates a deterministic query store `queryKey` from the given parameters,
+ * consistent with internally generated keys.
+ */
+export declare function getQueryKey<TParams extends Record<string, unknown>>(params: TParams): string;
+/**
+ * Parses a query store `queryKey` into the corresponding parameters.
+ */
+export declare function parseQueryKey<TParams extends Record<string, unknown>>(queryKey: string): TParams;

package/dist/createVirtualStore.d.ts

@@ -0,0 +1,39 @@
+import { DeriveGetter } from './createDerivedStore';
+import { BaseStore, InferPersistedState, InferSetStateReturn, InferStoreState, OptionallyPersistedStore } from './types';
+type MethodOverrides<Store extends BaseStore<State>, State = InferStoreState<Store>> = Partial<Pick<Store, 'getState' | 'setState'>>;
+type VirtualStoreOptions = {
+    debugMode?: boolean;
+    /**
+     * Whether to lock dependencies (see: {@link DeriveOptions}) for the virtual store.
+     * @default true
+     */
+    lockDependencies?: boolean;
+};
+/**
+ * ### `createVirtualStore`
+ *
+ * Returns a stable store interface backed by different store instances over time.
+ * When dependencies change, the derive function runs and creates a new store, then
+ * all subscriptions rebind automatically. Only depend on state that should trigger
+ * new store creation.
+ *
+ * ---
+ * 💡 **Note:** `lockDependencies` (see: {@link DeriveOptions}) is enabled by default.
+ * Ensure that any `$` dependencies in your `createStore` function are called
+ * consistently. If they are not, set `lockDependencies` to `false`.
+ *
+ * ---
+ * @param createStore - Derive function that returns a store instance
+ * @param overrides - Optional method overrides (e.g., `getState(id?: string)`)
+ *
+ * @example
+ * ```ts
+ * const useUserAssetsStore = createVirtualStore($ => {
+ *   const address = $(useWalletsStore).accountAddress;
+ *   return createUserAssetsStore(address);
+ * });
+ * ```
+ */
+export declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>>(createStore: ($: DeriveGetter) => Store, options?: VirtualStoreOptions): OptionallyPersistedStore<InferStoreState<Store>, InferPersistedState<Store, InferStoreState<Store>>, InferSetStateReturn<Store>>;
+export declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>, Overrides extends MethodOverrides<Store>>(createStore: ($: DeriveGetter) => Store, overrides: (getStore: () => Store) => Overrides, options?: VirtualStoreOptions): OptionallyPersistedStore<InferStoreState<Store>, InferPersistedState<Store, InferStoreState<Store>>, InferSetStateReturn<Store>> & Overrides;
+export {};

package/dist/derivedStore/deriveProxy.d.ts

@@ -0,0 +1,24 @@
+import { BaseStore, Selector } from '../types';
+type TrackedInvocation = {
+    args: unknown[] | undefined;
+    method: string;
+};
+type TrackPathFn = (store: BaseStore<unknown>, path: string[], isLeaf: boolean, invocation?: TrackedInvocation) => void;
+type SubscriptionBuilder = (store: BaseStore<unknown>, selector: Selector<unknown, unknown>) => void;
+/**
+ * Gets or creates a lightweight tracking proxy that records path access and store
+ * method invocations via proxy traps. Used to auto-generate selectors that point
+ * to either the accessed path or the value returned by an invoked store method.
+ */
+export declare function getOrCreateProxy<S>(store: BaseStore<S>, rootProxyCache: WeakMap<BaseStore<unknown>, unknown>, trackPath: TrackPathFn): S;
+export type PathFinder = {
+    buildProxySubscriptions(createSubscription: SubscriptionBuilder, shouldLog: boolean): void;
+    trackPath: TrackPathFn;
+};
+/**
+ * A factory that returns a proxy path-tracking object with two methods:
+ *  - `buildProxySubscriptions()`: builds subscriptions to the final paths
+ *  - `trackPath()`: records usage of a store path
+ */
+export declare function createPathFinder(): PathFinder;
+export {};

package/dist/derivedStore/globalDeriveScheduler.d.ts

@@ -0,0 +1,22 @@
+type Rank = number;
+type StoreId = string;
+type Task = () => void;
+export declare function isCascadeActive(): boolean;
+/**
+ * Rank of the currently running derive batch, or null if not in a batch.
+ */
+export declare function getCurrentDeriveRank(): Rank | null;
+/**
+ * Arms the cascade and schedules a single microtask flush.
+ */
+export declare function activateCascade(): void;
+/**
+ * Enlist one per-store component flush (idempotent per store).
+ */
+export declare function joinCascade(storeId: StoreId, task: Task): void;
+/**
+ * Enqueue (or upgrade) a derive task with the given rank.
+ * If the task is already present, we keep the maximum rank (run later).
+ */
+export declare function enqueueDerive(task: Task, rank: Rank): void;
+export {};

package/dist/env.d.ts

@@ -0,0 +1,7 @@
+export declare const IS_REACT_NATIVE = false;
+export declare const IS_BROWSER: boolean;
+export declare const IS_IOS = false;
+export declare const IS_ANDROID = false;
+export declare const IS_DEV: boolean;
+export declare const IS_TEST: boolean;
+export declare const unstable_batchedUpdates: <T>(callback: () => T) => T;

package/dist/env.native.d.ts

@@ -0,0 +1,8 @@
+import { unstable_batchedUpdates } from 'react-native';
+export declare const IS_REACT_NATIVE = true;
+export declare const IS_BROWSER = false;
+export declare const IS_IOS: boolean;
+export declare const IS_ANDROID: boolean;
+export declare const IS_DEV: boolean;
+export declare const IS_TEST: boolean;
+export { unstable_batchedUpdates };

package/dist/env.web.d.ts

@@ -0,0 +1,7 @@
+export declare const IS_REACT_NATIVE = false;
+export declare const IS_BROWSER: boolean;
+export declare const IS_IOS = false;
+export declare const IS_ANDROID = false;
+export declare const IS_DEV: boolean;
+export declare const IS_TEST: boolean;
+export declare const unstable_batchedUpdates: <T>(callback: () => T) => T;

package/dist/hooks/compareHooks.d.ts

@@ -0,0 +1,49 @@
+import { DependencyList, EffectCallback } from 'react';
+type EqualityFn = <T>(a: T, b: T) => boolean;
+/**
+ * A version of React's `useMemo` that uses deep comparison (or a custom comparator) for its dependencies.
+ *
+ * @param factory - Function that computes the memoized value.
+ * @param deps - Dependency list to compare.
+ * @param equalityFn - Custom function to compare dependencies. Defaults to deep equality.
+ * @returns The memoized value.
+ */
+export declare function useDeepMemo<T>(factory: () => T, deps: DependencyList, equalityFn?: EqualityFn): T;
+/**
+ * A version of React's `useEffect` that uses deep comparison (or a custom comparator) for its dependencies.
+ *
+ * @param effect - The effect callback.
+ * @param deps - Dependency list to compare.
+ * @param equalityFn - Custom function to compare dependencies. Defaults to deep equality.
+ */
+export declare function useDeepEffect(effect: EffectCallback, deps: DependencyList, equalityFn?: EqualityFn): void;
+/**
+ * A version of React's `useCallback` that uses deep comparison (or a custom comparator) for its dependencies.
+ *
+ * @param callback - The callback function to memoize.
+ * @param deps - Dependency list to compare.
+ * @param equalityFn - Custom function to compare dependencies. Defaults to deep equality.
+ * @returns A memoized callback.
+ */
+export declare function useDeepCallback<T extends (...args: Parameters<T>) => ReturnType<T>>(callback: T, deps: DependencyList, equalityFn?: EqualityFn): T;
+/**
+ * A version of React's `useLayoutEffect` that uses deep comparison (or a custom comparator) for its dependencies.
+ *
+ * @param effect - The effect callback.
+ * @param deps - Dependency list to compare.
+ * @param equalityFn - Custom function to compare dependencies. Defaults to deep equality.
+ */
+export declare function useDeepLayoutEffect(effect: EffectCallback, deps: DependencyList, equalityFn?: EqualityFn): void;
+/**
+ * A JS-side equivalent of Reanimated's `useAnimatedReaction` hook.
+ *
+ * Runs a "prepare" function to compute a value, and then runs a "react" function
+ * whenever the prepared value changes, providing both the current and previous prepared values.
+ *
+ * @param prepare - Function that computes the value to watch.
+ * @param react - Function that reacts to changes in the prepared value, receiving (current, previous).
+ * @param dependencies - Dependency array. Required for correct operation in React.
+ * @param equalityFn - Custom function to compare dependencies. Defaults to `Object.is`.
+ */
+export declare function useCompareEffect<PreparedResult>(prepare: () => PreparedResult, react: (current: PreparedResult, previous: PreparedResult | null) => void, dependencies: DependencyList, equalityFn?: EqualityFn): void;
+export {};

package/dist/hooks/useLazyRef.d.ts

@@ -0,0 +1,12 @@
+import { RefObject } from 'react';
+/**
+ * ### `useLazyRef`
+ *
+ * A version of `useRef` that allows for lazy initialization.
+ *
+ * ---
+ * @param initializer A function that returns the initial value for the ref.
+ *
+ * @returns A stable, pre-initialized `RefObject<T>`.
+ */
+export declare function useLazyRef<T>(initializer: () => T): RefObject<T>;

package/dist/hooks/useListen.d.ts

@@ -0,0 +1,97 @@
+import { RefObject } from 'react';
+import { BaseStore, EqualityFn, InferStoreState, Selector } from '../types';
+/**
+ * Handle returned by `useListen`.
+ *
+ * The hook cleans itself up, so you normally ignore this handle.
+ * Keep it only when you need to pause or resume the listener manually
+ * (e.g. suspend heavy work while a long-lived component is off screen).
+ */
+export type ListenHandle = {
+    /** `true` while the listener is attached. */
+    isActive: boolean;
+    /** Re-attach the listener. */
+    resubscribe: (options?: ResubscribeOptions) => void;
+    /** Detach the listener. Safe to call more than once. */
+    unsubscribe: () => void;
+};
+/**
+ * Options for resubscribing a listener.
+ */
+export type ResubscribeOptions = {
+    /**
+     * Whether to fire the callback immediately when resubscribing.
+     * @default false
+     */
+    fireImmediately?: boolean;
+    /**
+     * Whether to force a resubscription even if the listener is already active.
+     * @default false
+     */
+    forceResubscribe?: boolean;
+};
+/**
+ * Options for the `useListen` hook.
+ */
+export type UseListenOptions<Selected> = {
+    /**
+     * Whether to log debug messages to the console.
+     * @default false
+     */
+    debugMode?: boolean;
+    /**
+     * Whether to enable the listener.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Dictates whether `react` should be called on state slice changes.
+     * Compares the previous and current selected values.
+     * @default Object.is
+     */
+    equalityFn?: EqualityFn<Selected>;
+    /**
+     * Whether to fire the callback immediately on mount. Note that if `true`,
+     * the `react` callback will be called on mount regardless of whether the
+     * selected value has changed.
+     * @default false
+     */
+    fireImmediately?: boolean;
+};
+/**
+ * ### `useListen`
+ *
+ * Subscribes to a slice of a Zustand store and runs a callback whenever that slice changes,
+ * **without triggering re-renders**.
+ *
+ * Useful for forwarding updates to non-React state (e.g. Reanimated shared values), scoped side
+ * effects, or deciding yourself if or when a render should happen.
+ *
+ * The hook attaches the listener and cleans it up automatically. Use the returned `ListenHandle`
+ * only when you need to pause or resume the listener manually.
+ *
+ * ---
+ * 💡 **Note:** With the exception of `enabled`, changes in `options` are **not reactive**.
+ * They take effect only if a resubscription occurs.
+ *
+ * ---
+ * @param store - Zustand store to listen to. Should be a stable reference.
+ * @param selector - Selects the slice of the store state to listen to.
+ * @param react - Triggered when the selected slice changes. Receives `(current, previous, unsubscribe)`.
+ * @param optionsOrEqualityFn - Optional `equalityFn`, `fireImmediately` settings, forwarded to `store.subscribe`.
+ *
+ * ---
+ * @example
+ * ```ts
+ * useListen(
+ *   useCandlestickStore,
+ *   state => state.getData(),
+ *   (candles, previous, unsubscribe) => {
+ *     if (candles?.unsupported) return unsubscribe();
+ *     updateTokenPrice(token, getPriceUpdate(candles, previous));
+ *     runOnUI(() => chartManager.value?.setCandles(candles))();
+ *   }
+ * );
+ * ```
+ */
+export declare function useListen<Store extends BaseStore<S>, Selected, S = InferStoreState<Store>>(store: Store, selector: Selector<S, Selected>, react: (current: Selected, previous: Selected, unsubscribe: () => void) => void, optionsOrEqualityFn?: UseListenOptions<Selected> | UseListenOptions<Selected>['equalityFn']): RefObject<Readonly<ListenHandle>>;

package/dist/hooks/useStableValue.d.ts

@@ -0,0 +1,15 @@
+/**
+ * **Initializes a value once**, guaranteeing stability across renders.
+ *
+ * @param initializer A function that produces the value. It is invoked **only
+ * on the first render** for a given component instance.
+ *
+ * @returns A stable `T` guaranteed to be the value initially returned by the
+ * provided `initializer`.
+ *
+ * @example
+ * ```ts
+ * const initialState = useStableValue(() => getInitialState());
+ * ```
+ */
+export declare function useStableValue<T>(init: () => T): T;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { configureStores } from './config';
+export { createBaseStore } from './createBaseStore';
+export * from './createDerivedStore';
+export * from './createQueryStore';
+export * from './createVirtualStore';
+export { replacer, reviver } from './utils/serialization';
+export { applyStateUpdate, destroyStore, destroyStores, getStoreName, isDerivedStore, isPersistedStore, isQueryStore, isVirtualStore, } from './utils/storeUtils';
+export * from './hooks/useListen';
+export * from './hooks/useStableValue';
+export * from './sync/types';
+export * from './queryStore/types';
+export * from './storage/storageTypes';
+export * from './types';
+export * from './utils/createStoreActions';
+export { deepEqual, shallowEqual } from './utils/equality';
+export { time } from './utils/time';

package/dist/logger.d.ts

@@ -0,0 +1,16 @@
+export declare class StoresError extends Error {
+    cause: Error;
+    constructor(message: string, error?: unknown);
+}
+export interface StoresLogger {
+    debug: (message: string, context?: Record<string, unknown>) => void;
+    error: {
+        <T extends Error>(error: T, context?: Record<string, unknown>): void;
+        <T extends string>(error: T, context?: Record<string, unknown>): void;
+    };
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+}
+export declare let logger: StoresLogger;
+export declare function ensureError(error: unknown): Error;
+export declare function setLogger(customLogger: StoresLogger): void;

package/dist/middleware/createHydrationGate.d.ts

@@ -0,0 +1,19 @@
+import { StateCreator } from '../types';
+import { SyncContext } from 'src/sync/syncEnhancer';
+type WrappedOnRehydrateStorage<S> = (userCallback: ((state: S) => ((finalState?: S, error?: unknown) => void) | void) | undefined, syncContext: SyncContext | undefined) => (state: S) => (finalState?: S, error?: unknown) => void;
+/**
+ * Creates hydration-gating middleware that queues state updates until rehydration completes.
+ *
+ * **Before hydration**: Queues all `set()` calls and flushes them sequentially after rehydration.
+ *
+ * **After hydration**: Passes `set()` calls through synchronously without batching.
+ *
+ * This ensures persistence sees a fully rehydrated base state before applying queued updates,
+ * while keeping in-memory state changes synchronous post-hydration.
+ */
+export declare function createHydrationGate<S>(stateCreator: StateCreator<S>): {
+    hydrationPromise: () => Promise<void>;
+    stateCreator: StateCreator<S>;
+    wrapOnRehydrateStorage: WrappedOnRehydrateStorage<S>;
+};
+export {};

package/dist/middleware/createSubscriptionManager.d.ts

@@ -0,0 +1,10 @@
+export type SubscriptionLifecycleHandlers = {
+    readonly onSubscribe?: (isFirstSubscription: boolean) => void;
+    readonly onLastUnsubscribe?: () => void;
+};
+export type SubscriptionManager = {
+    readonly getSubscriptionCount: () => number;
+    readonly setHandlers: (handlers: SubscriptionLifecycleHandlers | null) => void;
+    readonly subscribe: () => () => void;
+};
+export declare function createSubscriptionManager(): SubscriptionManager;