@storesjs/stores 0.8.0

package/dist/types.d.ts

@@ -0,0 +1,332 @@
+import { Mutate, StateCreator as ZustandStateCreator, StoreApi } from 'zustand';
+import { PersistOptions } from 'zustand/middleware';
+import { UseBoundStoreWithEqualityFn } from 'zustand/traditional';
+import { StorageValue } from './storage/storageTypes';
+import { SyncConfig } from './sync/types';
+type SubscribeWithSelector = ['zustand/subscribeWithSelector', never];
+type HydrationPromise<PersistReturn> = PersistReturn extends Promise<void> ? {
+    /** Invoke to get a promise that resolves once hydration completes. */
+    hydrationPromise: () => Promise<void>;
+} : {
+    hydrationPromise?: undefined;
+};
+export type StorePersist<Store, PersistedState, PersistReturn> = Store extends {
+    getState: () => infer S;
+    setState: {
+        (...args: infer SetPartialArgs): infer _;
+        (...args: infer SetFullArgs): infer _;
+    };
+} ? {
+    setState(...args: SetPartialArgs): PersistReturn;
+    setState(...args: SetFullArgs): PersistReturn;
+    persist: {
+        clearStorage: () => void;
+        getOptions: () => Partial<PersistOptions<S, PersistedState>>;
+        hasHydrated: () => boolean;
+        onHydrate: (listener: (state: S) => void) => () => void;
+        onFinishHydration: (listener: (state: S) => void) => () => void;
+        rehydrate: () => Promise<void> | void;
+        setOptions: (options: Partial<PersistOptions<S, PersistedState, PersistReturn>>) => void;
+    } & HydrationPromise<PersistReturn>;
+} : never;
+export type StateCreator<S, U = S> = ZustandStateCreator<S, [SubscribeWithSelector], [SubscribeWithSelector], U>;
+export type BaseStore<S, ExtraSubscribeOptions extends boolean = false> = UseBoundStoreWithEqualityFn<Mutate<StoreApi<S>, [SubscribeWithSelector]>> & {
+    subscribe: SubscribeOverloads<S, ExtraSubscribeOptions>;
+};
+export type PersistedStore<S, PersistedState = Partial<S>, ExtraSubscribeOptions extends boolean = false, PersistReturn = unknown> = {
+    (): S;
+    <U>(selector: (state: S) => U, equalityFn?: (a: U, b: U) => boolean): U;
+} & Omit<BaseStore<S, ExtraSubscribeOptions>, 'setState' | 'persist'> & StorePersist<BaseStore<S, ExtraSubscribeOptions>, PersistedState, PersistReturn>;
+export type Store<S, PersistedState extends Partial<S> = never, ExtraSubscribeOptions extends boolean = false, PersistReturn = unknown> = [
+    PersistedState
+] extends [never] ? BaseStore<S, ExtraSubscribeOptions> : PersistedStore<S, PersistedState, ExtraSubscribeOptions, PersistReturn>;
+export type OptionallyPersistedStore<S, PersistedState, PersistReturn = void> = WithAsyncSet<Store<S>, S, PersistedState, PersistReturn> & UseStoreCallSignatures<S> & {
+    persist?: PersistedStore<S, PersistedState, false, PersistReturn>['persist'];
+};
+export type NoInfer<T> = [T][T extends unknown ? 0 : never];
+export type Timeout = ReturnType<typeof setTimeout>;
+export type Listener<S> = (state: S, prevState: S) => void;
+export type Selector<S, Selected> = (state: S) => Selected;
+export type EqualityFn<T = unknown> = (a: T, b: T) => boolean;
+export type UseStoreCallSignatures<S> = {
+    (): S;
+    <Selected>(selector: Selector<S, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
+};
+export type InferStoreState<Store extends StoreApi<unknown>> = Store extends {
+    getState: () => infer T;
+} ? T : never;
+/**
+ * Extracts the return type of setState from a store.
+ * Returns `void` for non-persisted or sync-persisted stores.
+ * Returns `Promise<void>` for async-persisted stores.
+ */
+export type InferSetStateReturn<Store> = Store extends {
+    setState(...args: SetStateArgs<infer S>): infer R;
+} ? R : void;
+/**
+ * Extracts the PersistedState type from a store's persist property.
+ * Returns `Partial<State>` if the store doesn't have persistence.
+ */
+export type InferPersistedState<Store, State> = Store extends {
+    persist: {
+        getOptions: () => infer Options;
+    };
+} ? Options extends {
+    name?: string;
+} ? Partial<State> : Partial<State> : Partial<State>;
+export type SetPartial<S> = Partial<S> | ((state: S) => Partial<S>);
+export type SetFull<S> = S | ((state: S) => S);
+export type SetStateReplaceArgs<S, ExtraArgs extends unknown[] = []> = [update: SetFull<S>, replace: true, ...extraArgs: ExtraArgs];
+export type SetStatePartialArgs<S, ExtraArgs extends unknown[] = []> = [update: SetPartial<S>, replace?: false, ...extraArgs: ExtraArgs];
+export type SetStateArgs<S, ExtraArgs extends unknown[] = []> = SetStatePartialArgs<S, ExtraArgs> | SetStateReplaceArgs<S, ExtraArgs>;
+export type SetState<S, ExtraArgs extends unknown[] = [], PersistReturn extends Promise<void> | void = void> = (...args: SetStateArgs<S, ExtraArgs>) => PersistReturn;
+export type SetStateOverloads<S, PersistReturn extends Promise<void> | void = void> = {
+    (update: SetPartial<S>, replace?: false): PersistReturn;
+    (update: SetFull<S>, replace: true): PersistReturn;
+};
+export type WithAsyncSet<Store extends StoreApi<unknown>, S, PersistedState, PersistReturn> = Omit<Store, 'persist' | 'setState'> & {
+    persist?: PersistedStore<S, PersistedState, false, PersistReturn>['persist'];
+    setState(update: SetPartial<InferStoreState<Store>>, replace?: false): PersistReturn;
+    setState(update: SetFull<InferStoreState<Store>>, replace: true): PersistReturn;
+};
+export type SubscribeOptions<Selected> = {
+    equalityFn?: EqualityFn<Selected>;
+    fireImmediately?: boolean;
+    isDerivedStore?: boolean;
+};
+export type ListenerArgs<S> = [listener: Listener<S>];
+export type SelectorArgs<S, Selected> = [
+    selector: Selector<S, Selected>,
+    listener: Listener<Selected>,
+    options?: SubscribeOptions<Selected>
+];
+export type SubscribeOverloads<S, ExtraOptions extends boolean = false> = {
+    (listener: Listener<S>): UnsubscribeFn<ExtraOptions>;
+    <Selected>(selector: Selector<S, Selected>, listener: Listener<Selected>, options?: SubscribeOptions<Selected>): UnsubscribeFn<ExtraOptions>;
+};
+export type SubscribeArgs<S, Selected = unknown> = ListenerArgs<S> | SelectorArgs<S, Selected>;
+export type UnsubscribeFn<Options extends boolean = false> = Options extends true ? (skipAbortFetch?: boolean) => void : () => void;
+export type SubscribeFn<S, Selected = S> = (...args: SubscribeArgs<S, Selected>) => UnsubscribeFn;
+export type DerivedStore<S> = WithFlushUpdates<ReadOnlyDerivedStore<BaseStore<S>>>;
+export type WithFlushUpdates<Store extends StoreApi<unknown>> = Store & {
+    /**
+     * Destroy the derived store and its subscriptions.
+     */
+    destroy: () => void;
+    /**
+     * Flush all pending updates — only applicable to **debounced** derived stores.
+     */
+    flushUpdates: () => void;
+};
+export type WithGetSnapshot<Store extends StoreApi<unknown>> = Store & {
+    /**
+     * Provided to `useSyncExternalStoreWithSelector` to ensure it activates the derived
+     * store when it gets the initial state before subscribing to the store.
+     */
+    getSnapshot: () => InferStoreState<Store>;
+};
+type ReadOnlyDerivedStore<Store extends BaseStore<unknown>> = Omit<Store, 'getInitialState' | 'setState'> & UseStoreCallSignatures<InferStoreState<Store>> & {
+    /**
+     * @deprecated **Not applicable to derived stores.** Will throw an error.
+     */
+    getInitialState: Store['getInitialState'];
+    /**
+     * @deprecated **Not applicable to derived stores.** Will throw an error.
+     */
+    setState: Store['setState'];
+};
+/**
+ * Configuration for creating derived stores. You can pass either:
+ *  - A **function** (used as `equalityFn`), or
+ *  - An **object** with the fields below
+ */
+export type DeriveOptions<DerivedState = unknown> = EqualityFn<DerivedState> | {
+    /**
+     * Delay before triggering a re-derive when dependencies change.
+     * Accepts a number (ms) or debounce options:
+     *
+     * `{ delay: number, leading?: boolean, trailing?: boolean, maxWait?: number }`
+     * @default 0
+     */
+    debounce?: number | DebounceOptions;
+    /**
+     * If `true`, the store will log debug messages to the console.
+     *
+     * If `'verbose'`, the store will log the subscriptions it creates each time the derive
+     * function is run, rather than only the first time.
+     * @default false
+     */
+    debugMode?: boolean | 'verbose';
+    /**
+     * A custom comparison function for detecting state changes.
+     * @default `Object.is`
+     */
+    equalityFn?: EqualityFn<DerivedState>;
+    /**
+     * If `true`, the derived store will never destroy itself. Useful in cases where your
+     * derived store serves as a permanent cache subscribed to intermittently or not at all.
+     * Manual calls to `destroy` *will* destroy the store even when `keepAlive` is `true`.
+     *
+     * *Use this option carefully.*
+     * @default false
+     */
+    keepAlive?: boolean;
+    /**
+     * Locks the dependency graph after the first derivation. Subscriptions to
+     * underlying stores are established once and reused on subsequent runs, rather
+     * than being torn down and rebuilt (the default behavior).
+     *
+     * This avoids the overhead of regenerating selectors and prevents unnecessary
+     * subscription churn. However, it means only the *initially tracked* dependencies
+     * will trigger updates — even if your derive function conditionally reads different
+     * stores in later runs.
+     *
+     * **Requirement**: All `$` calls in your derive function must be consistent and
+     * top level. Conditional dependency tracking will not work correctly.
+     *
+     * Safe to enable for most derived stores where dependencies are static.
+     *
+     * @default false
+     */
+    lockDependencies?: boolean;
+};
+export type Deserializer<SerializedState, PersistedState> = (serializedState: SerializedState) => StorageValue<PersistedState>;
+export type Serializer<SerializedState> = <PersistedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+/**
+ * Synchronous storage interface.
+ * Used for localStorage and MMKV implementations.
+ */
+export interface SyncStorageInterface<SerializedState = unknown> {
+    readonly async?: false;
+    /**
+     * Adapter-level deserializer used when a store does not supply its own.
+     * Acts as the default before falling back to the framework implementation.
+     */
+    readonly deserializer?: <PersistedState>(serializedState: SerializedState) => StorageValue<PersistedState>;
+    /**
+     * Adapter-level serializer used when a store does not supply its own.
+     * Acts as the default before falling back to the framework implementation.
+     */
+    readonly serializer?: <PersistedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+    clearAll(): void;
+    contains(key: string): boolean;
+    delete(key: string): void;
+    get(key: string): SerializedState | undefined;
+    getAllKeys(): string[];
+    set(key: string, value: SerializedState): void;
+}
+/**
+ * Asynchronous storage interface.
+ * Used for Chrome storage and other async storage implementations.
+ */
+export type AsyncStorageInterface<SerializedState = unknown> = {
+    readonly async: true;
+    /**
+     * Adapter-level deserializer used when a store does not supply its own.
+     * Acts as the default before falling back to the framework implementation.
+     */
+    readonly deserializer?: <PersistedState>(serializedState: SerializedState) => StorageValue<PersistedState>;
+    /**
+     * Adapter-level serializer used when a store does not supply its own.
+     * Acts as the default before falling back to the framework implementation.
+     */
+    readonly serializer?: <PersistedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+    clearAll(): Promise<void>;
+    contains(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    get(key: string): Promise<SerializedState | undefined>;
+    getAllKeys(): Promise<string[]>;
+    set(key: string, value: SerializedState): Promise<void>;
+};
+/**
+ * Configuration options for creating a persistable store.
+ */
+export type PersistConfig<S, PersistedState = Partial<S>, PersistReturn = void> = {
+    /**
+     * A function to convert the serialized value back into the state object.
+     * If not provided, the storage adapter's `deserializer` is used before falling back to the default implementation.
+     */
+    deserializer?: <SerializedState>(serializedState: SerializedState) => StorageValue<PersistedState>;
+    /**
+     * A function to merge persisted state with current state during hydration.
+     * By default, zustand does a shallow merge, but this allows custom logic for deep merging nested objects.
+     */
+    merge?: PersistOptions<S, PersistedState>['merge'];
+    /**
+     * A function to perform persisted state migration.
+     * This function will be called when persisted state versions mismatch with the one specified here.
+     */
+    migrate?: PersistOptions<S, PersistedState>['migrate'];
+    /**
+     * A function returning another (optional) function.
+     * The main function will be called before the state rehydration.
+     * The returned function will be called after the state rehydration or when an error occurred.
+     */
+    onRehydrateStorage?: PersistOptions<S, PersistedState>['onRehydrateStorage'];
+    /**
+     * A function that determines which parts of the state should be persisted.
+     * By default, the entire state is persisted.
+     */
+    partialize?: (state: S) => PersistedState;
+    /**
+     * The throttle rate for the persist operation in milliseconds.
+     * @default iOS: time.seconds(3) | Android: time.seconds(5)
+     */
+    persistThrottleMs?: PersistReturn extends Promise<unknown> ? undefined : number;
+    /**
+     * A function to serialize the state and version for storage.
+     * If not provided, the storage adapter's `serializer` is used before falling back to the default implementation.
+     */
+    serializer?: <SerializedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+    /**
+     * Custom storage implementation. If async, `setState` will return a Promise that resolves
+     * when the state is persisted. If sync, `setState` will return void.
+     */
+    storage?: PersistReturn extends Promise<unknown> ? AsyncStorageInterface : SyncStorageInterface;
+    /**
+     * The unique key for the persisted store.
+     */
+    storageKey: string;
+    /**
+     * The version of the store's schema.
+     * Useful for handling schema changes across app versions.
+     * @default 0
+     */
+    version?: number;
+};
+export type EnforceStorageKey<Options> = {
+    storageKey: string;
+} extends Options ? Options : never;
+export type BaseStoreOptions<S, PersistedState = Partial<S>, PersistReturn = void> = (PersistConfig<S, PersistedState, PersistReturn> & {
+    sync?: S extends Record<string, unknown> ? SyncOption<S> : undefined;
+}) | ({
+    sync: S extends Record<string, unknown> ? SyncWithoutStorageOption<NoInfer<S>> : undefined;
+} & UndefinedPersistKeys<S, PersistedState, PersistReturn>);
+/**
+ * The `sync` option can be:
+ * - `SyncConfig` object
+ * - `string` (shorthand for `{ key: string }`)
+ * - `true` (inherits key from `storageKey` — only valid with persistence)
+ */
+export type SyncOption<S extends Record<string, unknown>> = SyncConfig<S> | string | true;
+type SyncWithoutStorageOption<S extends Record<string, unknown>> = string | (Omit<SyncConfig<S>, 'injectStorageMetadata' | 'key'> & {
+    injectStorageMetadata?: never;
+    key: SyncWithoutStorageKey<SyncConfig<S>>;
+    readonly __syncStateBrand?: (state: S) => S;
+});
+type SyncWithoutStorageKey<Config> = Config extends {
+    key?: infer Key;
+} ? Extract<Key, string> extends never ? string : Extract<Key, string> : string;
+type UndefinedPersistKeys<S, PersistedState, PersistReturn> = {
+    [K in keyof PersistConfig<S, PersistedState, PersistReturn>]?: undefined;
+};
+/**
+ * Expanded options for custom debounce behavior.
+ */
+export type DebounceOptions = {
+    delay: number;
+    leading?: boolean;
+    maxWait?: number;
+    trailing?: boolean;
+};
+export {};

package/dist/utils/core.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the first argument provided to it.
+ * @param value - Any value.
+ * @returns `value`.
+ */
+export declare const identity: (value: any) => any;

package/dist/utils/createAsyncMicrotaskScheduler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Creates an async microtask-batched scheduler for a given async function.
+ *
+ * When the returned scheduler is called multiple times synchronously, only a single
+ * microtask execution occurs. All callers receive the same Promise that resolves
+ * after the batched execution completes. The function will be invoked with the
+ * arguments from the most recent call.
+ *
+ * This is useful for batching rapid successive async operations (e.g., async storage
+ * writes, network requests) to reduce unnecessary work while ensuring:
+ * - The latest values are used
+ * - All callers can await the completion of the batched operation
+ *
+ * @template Args - The argument types of the async function to schedule
+ * @param fn - The async function to schedule for microtask execution
+ * @returns A scheduler function that returns a Promise resolving after execution
+ *
+ * @example
+ * ```ts
+ * const batchedSave = createAsyncMicrotaskScheduler(async (data: string) => {
+ *   await storage.write(data);
+ *   console.log('Saved:', data);
+ * });
+ *
+ * await Promise.all([
+ *   batchedSave('first'),
+ *   batchedSave('second'),
+ *   batchedSave('third'),
+ * ]);
+ * // Writes "third" to storage once, all three Promises resolve together
+ * // Logs "Saved: third"
+ * ```
+ */
+export declare function createAsyncMicrotaskScheduler<Args extends unknown[]>(fn: (...args: Args) => Promise<void>): (...args: Args) => Promise<void>;

package/dist/utils/createMicrotaskScheduler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Creates a microtask-batched scheduler for a given function.
+ *
+ * When the returned scheduler is called multiple times synchronously, only a single
+ * microtask execution occurs. The function will be invoked with the arguments from
+ * the most recent call.
+ *
+ * This is useful for batching rapid successive calls (e.g., state updates, change
+ * handlers) to reduce unnecessary work while ensuring the latest values are used.
+ *
+ * @template TArgs - The argument types of the function to schedule
+ * @param fn - The function to schedule for microtask execution
+ * @returns A scheduler function with the same signature as the input function
+ *
+ * @example
+ * ```ts
+ * const batchedUpdate = createMicrotaskScheduler((value: number) => {
+ *   console.log('Updated:', value);
+ * });
+ *
+ * batchedUpdate(1);
+ * batchedUpdate(2);
+ * batchedUpdate(3);
+ * // Logs "Updated: 3" once in the next microtask
+ * ```
+ */
+export declare function createMicrotaskScheduler<Args extends unknown[]>(fn: (...args: Args) => void): (...args: Args) => void;

package/dist/utils/createStoreActions.d.ts

@@ -0,0 +1,24 @@
+import { StoreApi } from 'zustand';
+import { InferStoreState } from '../types';
+import { NoOverlap, ObjectMethods } from '../types/objects';
+import { FunctionKeys } from '../types/functions';
+export type StoreActions<Store extends StoreApi<unknown>> = Pick<InferStoreState<Store>, FunctionKeys<InferStoreState<Store>>>;
+/**
+ * Given a store instance, produces a new object containing only its actions.
+ *
+ * Intended for export alongside the associated store.
+ *
+ * @param store - The store to create actions for.
+ * @param bundledMethods - Optional extra methods to bundle into the actions object.
+ *
+ * @example
+ * export const useCounterStore = createRainbowStore(set => ({
+ *   count: 0,
+ *   increment: () => set(state => ({ count: state.count + 1 })),
+ * }));
+ *
+ * export const exampleActions = createStoreActions(useExampleStore);
+ * exampleActions.increment();
+ */
+export declare function createStoreActions<Store extends StoreApi<unknown>>(store: Store): StoreActions<Store>;
+export declare function createStoreActions<Store extends StoreApi<unknown>, Bundled extends ObjectMethods>(store: Store, bundledMethods: NoOverlap<InferStoreState<Store>, Bundled>): StoreActions<Store> & Bundled;

package/dist/utils/debounce.d.ts

@@ -0,0 +1,21 @@
+export type DebounceOptions = {
+    leading?: boolean;
+    maxWait?: number;
+    trailing?: boolean;
+};
+export type DebouncedFunction<F extends (...args: Parameters<F>) => ReturnType<F>> = {
+    (...args: Parameters<F>): ReturnType<F> | undefined;
+    cancel: () => void;
+    flush: () => ReturnType<F> | undefined;
+};
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait` milliseconds
+ * have elapsed since the last time the debounced function was invoked.
+ * Copied and adapted from lodash@4.17.21.
+ *
+ * @param func The function to debounce.
+ * @param wait The number of milliseconds to delay.
+ * @param options The options object.
+ * @returns Returns the new debounced function.
+ */
+export declare function debounce<F extends (...args: Parameters<F>) => ReturnType<F>>(func: F, wait?: number, options?: DebounceOptions): DebouncedFunction<F>;

package/dist/utils/equality.d.ts

@@ -0,0 +1,37 @@
+/**
+ * **Worklet compatible**
+ *
+ * Performs a deep equality check between two values.
+ *
+ * This function recursively compares two values, checking if they are equal. For objects,
+ * it validates that both have the same keys and that each corresponding value is deeply equal.
+ * For non-objects, it uses strict equality.
+ *
+ * @param obj1 - The first value to compare.
+ * @param obj2 - The second value to compare.
+ * @returns `true` if the values are deeply equal; otherwise, `false`.
+ */
+export declare function deepEqual<U>(obj1: U, obj2: U): boolean;
+/**
+ * **Worklet compatible**
+ *
+ * Performs a shallow equality check between two values.
+ *
+ * For non-objects, uses strict equality (===). For objects, checks that both have identical
+ * keys and compares their values using `Object.is` without recursing into nested objects.
+ *
+ * Ideal for preventing re-renders due to top-level object recreation.
+ *
+ * @param obj1 - The first value to compare.
+ * @param obj2 - The second value to compare.
+ * @returns `true` if the values are shallowly equal; otherwise, `false`.
+ */
+export declare function shallowEqual<U>(obj1: U, obj2: U): boolean;
+/**
+ * Performs a deep equality check between two values, supporting objects, arrays, maps, sets, dates, regexps, array buffers, and more.
+ * Copied from dequal@2.0.3 and fully typed for TypeScript.
+ * @param foo - The first value to compare.
+ * @param bar - The second value to compare.
+ * @returns `true` if the values are deeply equal; otherwise, `false`.
+ */
+export declare function dequal(foo: unknown, bar: unknown): boolean;

package/dist/utils/factoryUtils.d.ts

@@ -0,0 +1,21 @@
+import { InferStoreState, OptionallyPersistedStore, SubscribeArgs, UnsubscribeFn } from '../types';
+/**
+ * #### `⚙️ createStoreFactoryUtils ⚙️`
+ *
+ * Produces strongly-typed helpers for store factory setups. Assumes:
+ * - A factory-capable "router" store exists whose properties map to a single underlying active store (via `getStore`).
+ * - The factory setup enforces a single active store instance.
+ * - `getStore` is a function that returns the concrete store instance.
+ *
+ * @param getStore – A function that returns the concrete store instance.
+ *
+ * @returns
+ * - `persist`: A persist object that attaches to the active store. Attach this to the factory-capable store.
+ * - `portableSubscribe`: A function for subscribing to store changes. Use as the factory-capable store's `subscribe` method.
+ * - `rebindSubscriptions`: Rebinds subscriptions on store change. Call this when the factory-capable store's underlying store is updated.
+ */
+export declare function createStoreFactoryUtils<Store extends OptionallyPersistedStore<InferStoreState<Store>, PersistedState>, PersistedState>(getStore: () => Store): {
+    persist: Store['persist'];
+    portableSubscribe: (...args: SubscribeArgs<InferStoreState<Store>>) => UnsubscribeFn;
+    rebindSubscriptions: (oldStore: Store, newStore: Store) => void;
+};

package/dist/utils/hydrationCoordinator.d.ts

@@ -0,0 +1,12 @@
+export type HydrationCoordinator = {
+    readonly complete: () => void;
+    readonly fail: (error: Error) => void;
+    readonly isHydrated: () => boolean;
+    readonly promise: Promise<void>;
+};
+/**
+ * Creates a coordinator for tracking async storage hydration lifecycle.
+ * Provides a promise that resolves once hydration completes and methods
+ * to signal completion or failure.
+ */
+export declare function createHydrationCoordinator(): HydrationCoordinator;

package/dist/utils/persistUtils.d.ts

@@ -0,0 +1,8 @@
+import { StorageValue } from '../storage/storageTypes';
+/**
+ * Default partialize function if none is provided. It omits top-level store
+ * methods and keeps all other state.
+ */
+export declare function omitStoreMethods<S, PersistedState extends Partial<S>>(state: S): PersistedState;
+export declare function defaultSerializeState<PersistedState>(storageValue: StorageValue<PersistedState>, shouldUseReplacer: boolean): string;
+export declare function defaultDeserializeState<PersistedState>(serializedState: string, shouldUseReviver: boolean): StorageValue<PersistedState>;

package/dist/utils/promiseUtils.d.ts

@@ -0,0 +1 @@
+export declare function isPromiseLike<T>(value: T | Promise<T> | void): value is Promise<T>;

package/dist/utils/serialization.d.ts

@@ -0,0 +1,13 @@
+type SerializedMap = {
+    __type: 'Map';
+    entries: [unknown, unknown][];
+};
+export declare function isSerializedMap(value: unknown): value is SerializedMap;
+type SerializedSet = {
+    __type: 'Set';
+    values: unknown[];
+};
+export declare function isSerializedSet(value: unknown): value is SerializedSet;
+export declare function replacer(_: string, value: unknown): unknown;
+export declare function reviver(_: string, value: unknown): unknown;
+export {};

package/dist/utils/storeUtils.d.ts

@@ -0,0 +1,56 @@
+import { StoreApi } from 'zustand';
+import { BaseStore, DerivedStore, PersistedStore, SetStateArgs, WithGetSnapshot } from '../types';
+import { QueryStore, QueryStoreState } from 'src/queryStore/types';
+export declare enum StoreTags {
+    QueryStore = "_queryStore",
+    VirtualStore = "_virtualStore"
+}
+export declare function assignStoreTag<S>(store: BaseStore<S>, tag: StoreTags): BaseStore<S>;
+/**
+ * Helper that applies a `setState` update to the provided state.
+ * Handles the `setState` discriminated union types internally.
+ */
+export declare function applyStateUpdate<S>(state: S, ...setArgs: SetStateArgs<S>): S;
+/**
+ * Calls the appropriate reset or destroy method on the store, if available.
+ * Handles both `DerivedStore` and `QueryStore`.
+ */
+export declare function destroyStore(store: BaseStore<unknown> | StoreApi<unknown> | QueryStore<unknown, Record<string, unknown>, unknown>, options?: {
+    clearQueryCache?: boolean;
+}): void;
+export declare function destroyStores(stores: Partial<Record<string, BaseStore<unknown> | StoreApi<unknown>>> | (BaseStore<unknown> | StoreApi<unknown> | undefined)[], options?: {
+    clearQueryCache?: boolean;
+    skipDestroy?: (store: BaseStore<unknown> | StoreApi<unknown>) => boolean;
+}): void;
+/**
+ * Returns the name of the store, either from the `persist` options or the store itself.
+ */
+export declare function getStoreName(store: BaseStore<unknown>): string;
+/**
+ * Checks if a store has a `destroy` method.
+ */
+export declare function hasDestroy<S>(store: StoreApi<S>): store is StoreApi<S> & {
+    destroy: () => void;
+};
+/**
+ * Checks if a store is a `DerivedStore` and reveals its internal `getSnapshot` method.
+ */
+export declare function hasGetSnapshot<S>(store: BaseStore<S> | StoreApi<S>): store is WithGetSnapshot<DerivedStore<S>>;
+/**
+ * Checks if a store is a `QueryStore`.
+ */
+export declare function isQueryStore<S>(store: StoreApi<S> | BaseStore<S> | QueryStore<S, Record<string, unknown>, S>): store is BaseStore<QueryStoreState<S, Record<string, unknown>, S>>;
+/**
+ * Checks if a store is a `DerivedStore`.
+ */
+export declare function isDerivedStore<S>(store: BaseStore<S> | StoreApi<S>): store is DerivedStore<S>;
+/**
+ * Checks if a store is persisted.
+ */
+export declare function isPersistedStore<S>(store: BaseStore<S>): store is PersistedStore<S>;
+/**
+ * Checks if a store is a virtual store.
+ */
+export declare function isVirtualStore<S>(store: BaseStore<S> | StoreApi<S>): store is BaseStore<S> & {
+    [StoreTags.VirtualStore]: true;
+};

package/dist/utils/stringUtils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a pluralized (by default: `word` + `'s'`) string based on the count.
+ *
+ * `word` should be provided in singular form.
+ */
+export declare function pluralize(word: string, count: number, pluralSuffix?: string): string;

package/dist/utils/time.d.ts

@@ -0,0 +1,46 @@
+type TimeInMs = number;
+type TimeUtils = {
+    /** Returns the input value unchanged, in milliseconds */
+    ms: (ms: number) => TimeInMs;
+    /** Converts seconds to milliseconds */
+    seconds: (seconds: number) => TimeInMs;
+    /** Converts minutes to milliseconds */
+    minutes: (minutes: number) => TimeInMs;
+    /** Converts hours to milliseconds */
+    hours: (hours: number) => TimeInMs;
+    /** Converts days to milliseconds */
+    days: (days: number) => TimeInMs;
+    /** Converts weeks to milliseconds */
+    weeks: (weeks: number) => TimeInMs;
+    /** Represents infinite time */
+    infinity: typeof Infinity;
+    /** Represents zero time */
+    zero: 0;
+};
+/**
+ * Worklet-compatible utility object for defining time values.
+ *
+ * All methods convert the input unit to milliseconds.
+ *
+ * @example
+ * time.seconds(5) // 5 seconds
+ * time.minutes(2) // 2 minutes
+ * time.hours(1) // 1 hour
+ * time.days(5) // 5 days
+ * time.weeks(2) // 2 weeks
+ * ––
+ * time.infinity // Infinity
+ * time.zero // 0
+ */
+export declare const time: TimeUtils;
+/**
+ * Waits for microtasks to complete.
+ * Uses setTimeout(0) to allow microtasks scheduled via queueMicrotask to execute.
+ *
+ * Useful in tests when waiting for async operations scheduled via microtasks.
+ *
+ * @example
+ * await waitForMicrotask();
+ */
+export declare function waitForMicrotask(): Promise<void>;
+export {};