@storesjs/stores 0.10.0 → 0.12.0

package/dist/vanilla/index.vanilla.d.ts

@@ -1 +1,1469 @@
-export * from './index.shared';
+//#region src/storage/storageTypes.d.ts
+type StorageValue<S, HideSyncMetadata extends boolean = false> = HideSyncMetadata extends true ? {
+  state: S;
+  version?: number;
+} : {
+  state: S;
+  syncMetadata?: {
+    origin?: string;
+    timestamp?: number;
+    fields?: Record<string, number>;
+  };
+  version?: number;
+};
+//#endregion
+//#region src/types/functions.d.ts
+/**
+* Relaxes function parameter variance to allow subtype
+* assignment otherwise blocked by strict contravariance.
+*/
+type BivariantMethod<T extends Record<string, UnknownFunction>> = T[keyof T];
+/**
+* Extract the keys of `T` whose values are functions.
+*/
+type FunctionKeys<T> = { [K in keyof T]-?: T[K] extends UnknownFunction ? K : never }[keyof T];
+/**
+* A record of string keys to unknown functions.
+*/
+type FunctionRecord = Record<string, UnknownFunction>;
+/**
+* Return `T` if it is **not** a function, otherwise `never`.
+*/
+type NonFunction<T> = T extends ((...args: infer _) => unknown) ? never : T;
+/**
+* Unknown generic function type.
+*/
+type UnknownFunction = (...args: never[]) => unknown;
+//#endregion
+//#region src/types/setState.d.ts
+type SetPartial<S> = S | Partial<S> | BivariantMethod<{
+  updater(state: S): S | Partial<S>;
+}>;
+type SetFull<S> = S | BivariantMethod<{
+  updater(state: S): S;
+}>;
+type SetStateReplaceArgs<S, ExtraArgs extends unknown[] = []> = [update: SetFull<S>, replace: true, ...extraArgs: ExtraArgs];
+type SetStatePartialArgs<S, ExtraArgs extends unknown[] = []> = [update: SetPartial<S>, replace?: false, ...extraArgs: ExtraArgs];
+type SetStateArgs<S, ExtraArgs extends unknown[] = []> = SetStatePartialArgs<S, ExtraArgs> | SetStateReplaceArgs<S, ExtraArgs>;
+/**
+* Rest-argument form of `setState`, used when forwarding calls.
+*/
+type SetState<S, ExtraArgs extends unknown[] = [], PersistReturn extends Promise<void> | void = void> = (...args: SetStateArgs<S, ExtraArgs>) => PersistReturn;
+/**
+* Store `setState` method overloads for partial updates and full replacement.
+*/
+type SetStateOverloads<S, PersistReturn extends Promise<void> | void = void> = BivariantMethod<{
+  setState(update: SetPartial<S>, replace?: false): PersistReturn;
+  setState(update: SetFull<S>, replace: true): PersistReturn;
+}>;
+//#endregion
+//#region src/types/subscribe.d.ts
+type Listener<S> = (state: S, prevState: S) => void;
+type Selector<S, Selected> = (state: S) => Selected;
+type EqualityFn<T = unknown> = (a: T, b: T) => boolean;
+/**
+* Minimum store API required for subscription.
+*/
+type SubscribableStore = {
+  subscribe(selector: Selector<unknown, unknown>, listener: () => void, options?: SubscribeOptions<unknown>): UnsubscribeFn;
+};
+type SubscribeOptions<Selected> = {
+  equalityFn?: EqualityFn<Selected>;
+  fireImmediately?: boolean;
+};
+type ListenerArgs<S> = [listener: Listener<S>];
+type SelectorArgs<S, Selected> = [selector: Selector<S, Selected>, listener: Listener<Selected>, options?: SubscribeOptions<Selected>];
+type SubscribeArgs<S, Selected = unknown> = ListenerArgs<S> | SelectorArgs<S, Selected>;
+type UnsubscribeFn = () => void;
+type SubscribeFn<S, Selected = S> = (...args: SubscribeArgs<S, Selected>) => UnsubscribeFn;
+type SubscribeOverloads<S> = {
+  (listener: Listener<S>): UnsubscribeFn;
+  <Selected>(selector: Selector<S, Selected>, listener: Listener<Selected>, options?: SubscribeOptions<Selected>): UnsubscribeFn;
+};
+//#endregion
+//#region src/store/types.d.ts
+/**
+* Store object contract shared by creators, middleware, and internal store utilities.
+*/
+type StoreApi<S> = {
+  getInitialState: () => S;
+  getState: () => S;
+  setState: SetStateOverloads<S>;
+  subscribe: SubscribeOverloads<S>;
+};
+/**
+* Callback that builds store state from the set/get/store API supplied during construction.
+*/
+type StateCreator$1<S, Mutators extends StoreMutators = [], StoreMutatorOutput extends StoreMutators = [], U = S> = ((setState: Get<Mutate<StoreApi<S>, Mutators>, "setState", never>, getState: Get<Mutate<StoreApi<S>, Mutators>, "getState", never>, store: Mutate<StoreApi<S>, Mutators>) => U) & {
+  $$storeMutators?: StoreMutatorOutput;
+};
+/**
+* Synchronous storage adapter consumed by the persistence wrapper.
+*/
+type SyncPersistStorage<State, PersistedState = Partial<State>> = {
+  getItem: (name: string) => StorageValue<PersistedState> | null;
+  removeItem: (name: string) => void;
+  setItem: (name: string, state: State, version: number | undefined) => void;
+};
+/**
+* Asynchronous storage adapter consumed by the persistence wrapper.
+*/
+type AsyncPersistStorage<State, PersistedState = Partial<State>> = {
+  getItem: (name: string) => Promise<StorageValue<PersistedState> | null>;
+  removeItem: (name: string) => Promise<void>;
+  setItem: (name: string, state: State, version: number | undefined) => Promise<void>;
+};
+/**
+* Accepted storage adapter types for sync or async persistence.
+*/
+type PersistStorage<State, PersistedState = Partial<State>> = AsyncPersistStorage<State, PersistedState> | SyncPersistStorage<State, PersistedState>;
+/**
+* Persistence options consumed by the persistence wrapper.
+*/
+type PersistOptions<S, PersistedState = Partial<S>> = {
+  merge?: (persistedState: PersistedState | undefined, currentState: S) => S;
+  migrate?: (persistedState: PersistedState, version: number) => PersistedState | Promise<PersistedState>;
+  name: string;
+  onRehydrateStorage?: (state: S) => ((state?: S, error?: unknown) => void) | void;
+  skipHydration?: boolean;
+  storage: PersistStorage<S, PersistedState>;
+  version: number;
+};
+/**
+* Methods attached by the persistence wrapper before async hydration state is added.
+*/
+type PersistMethods<S, PersistedState> = {
+  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>>) => void;
+};
+/**
+* Store shape after the persistence wrapper adds persistence methods, write-through `setState`,
+* and async hydration state when applicable.
+*/
+type WithPersist<Store, PersistedState, PersistReturn extends void | Promise<void>> = Store extends StoreApi<infer S> ? Write<Store, {
+  persist: PersistMethods<S, PersistedState> & HydrationPromise<PersistReturn>;
+  setState: SetStateOverloads<S, PersistReturn>;
+}> : Store;
+type HydrationPromise<PersistReturn> = PersistReturn extends Promise<void> ? {
+  /** Invoke to get a promise that resolves once hydration completes. */hydrationPromise: () => Promise<void>;
+} : {
+  hydrationPromise?: undefined;
+};
+type Get<T, K, Fallback> = K extends keyof T ? T[K] : Fallback;
+type Write<T, U> = Omit<T, keyof U> & U;
+type PersistMutator<Store, Args> = Args extends [infer PersistedState, infer PersistReturn extends void | Promise<void>] ? WithPersist<Store, PersistedState, PersistReturn> : Store;
+type StoreMutatorIdentifier = keyof StoreMutatorMap<unknown, unknown>;
+/**
+* Mapping from store mutator identifiers to the store API shape they add.
+*/
+interface StoreMutatorMap<Store, Args> {
+  "stores/persist": PersistMutator<Store, Args>;
+}
+/**
+* Ordered list of store mutators applied to a state creator.
+*/
+type StoreMutators = [StoreMutatorIdentifier, unknown][];
+/**
+* Applies a list of store mutators to a store API type.
+*/
+type Mutate<Store, Mutators> = number extends Mutators["length" & keyof Mutators] ? Store : Mutators extends [] ? Store : Mutators extends [[infer Identifier, infer Args], ...infer Rest] ? Identifier extends StoreMutatorIdentifier ? Rest extends StoreMutators ? Mutate<StoreMutatorMap<Store, Args>[Identifier], Rest> : StoreMutatorMap<Store, Args>[Identifier] : Store : Store;
+//#endregion
+//#region src/sync/types.d.ts
+/**
+* Metadata for a field's last write.
+*/
+type FieldMetadata = readonly [timestamp: number, sessionId: string];
+type SyncStateKey<T extends Record<string, unknown>> = Extract<{ [K in keyof T]-?: T[K] extends UnknownFunction ? never : K }[keyof T], string>;
+type SyncValues<T extends Record<string, unknown>> = Partial<T> & { [K in SyncStateKey<T>]?: T[K] };
+type SyncUpdate<T extends Record<string, unknown>> = {
+  replace: boolean;
+  sessionId: string;
+  timestamp: number;
+  values: SyncValues<T>;
+};
+/**
+* Passed to `SyncEngine.register()` to connect a store to the sync system.
+*/
+type SyncRegistration<T extends Record<string, unknown>> = {
+  /** Callback invoked by the engine to apply incoming remote updates to the store. */apply: (update: SyncUpdate<T>) => void; /** The state keys to sync. Non-function properties only. */
+  fields: ReadonlyArray<SyncStateKey<T>>; /** Returns the store's current state. Used by engines that need to read state (e.g., for diffing). */
+  getState: () => T; /** Unique identifier for this store. Must match across clients to sync the same data. */
+  key: string;
+};
+/**
+* Returned by `SyncEngine.register()`. Controls the lifecycle of a synced store.
+*/
+interface SyncHandle<T extends Record<string, unknown>> {
+  /**
+  * Permanently removes this store from the sync engine. After calling, the handle
+  * is invalid and the store will no longer send or receive updates. To temporarily
+  * pause sync, use `onFirstSubscribe`/`onLastUnsubscribe` lifecycle hooks instead.
+  */
+  destroy: () => void;
+  /** Returns `true` once the store has received its initial state from the engine. */
+  hydrated?: () => boolean;
+  /**
+  * Called when the store's subscriber count goes from 0 to 1. The registration
+  * remains active. Use for lazy resource acquisition (e.g., opening a WebSocket).
+  */
+  onFirstSubscribe?: () => void;
+  /** Registers a one-time callback to run when hydration completes. */
+  onHydrated?: (callback: () => void) => void;
+  /**
+  * Called when the store's subscriber count drops to 0. The registration remains
+  * active and `onFirstSubscribe` will fire again on the next subscription.
+  * Use for resource cleanup (e.g., closing idle connections).
+  */
+  onLastUnsubscribe?: () => void;
+  /**
+  * Broadcasts a state update to other clients. Set to `null` for engines where
+  * publishing is implicit (e.g., `chrome.storage` where the write itself triggers sync).
+  */
+  publish: ((update: SyncUpdate<T>) => void) | null;
+}
+/**
+* Interface for multi-client state synchronization. Stores register to send and receive updates.
+*/
+interface SyncEngine {
+  /**
+  * When `true`, embeds sync metadata (`{ origin, timestamp, fields }`) into persisted
+  * storage values. Required for engines that use storage writes as their transport.
+  * Only effective when the store is also persisted.
+  * @default false
+  */
+  readonly injectStorageMetadata?: boolean;
+  /** Registers a store for synchronization. Returns a handle to control the sync lifecycle. */
+  register: {
+    <T extends Record<string, unknown>>(registration: SyncRegistration<T>): SyncHandle<T>;
+    (registration: SyncRegistration<Record<string, unknown>>): SyncHandle<Record<string, unknown>>;
+  };
+  /** Unique identifier for this client session. Used for conflict resolution and filtering self-updates. */
+  readonly sessionId: string;
+}
+type SyncMergeFn<T, TState = unknown> = (incoming: T, current: T, currentState: TState, incomingValues: Partial<TState>) => T;
+type SyncConfig<T extends Record<string, unknown>> = {
+  /**
+  * The sync engine implementation to use.
+  *
+  * Defaults to cross-tab sync in browser environments. No-op in other environments unless a
+  * custom engine is provided.
+  */
+  engine?: SyncEngine; /** The state keys to sync. If unspecified, all non-function store properties are synced. */
+  fields?: ReadonlyArray<SyncStateKey<T>>;
+  /**
+  * When true, injects sync metadata (`{ origin, timestamp, fields }`) into the persisted
+  * storage payload. Only takes effect when used with a persisted store.
+  *
+  * Useful for sync engines that use storage events as their transport (e.g., `chrome.storage`).
+  *
+  * Can also be set on the `engine` object. This option takes precedence if both are provided.
+  * @default false
+  */
+  injectStorageMetadata?: boolean; /** The key used to identify the store to the sync engine. Required if `storageKey` is absent. */
+  key?: string; /** Optional merge function to use for each synced state key. Use with caution. */
+  merge?: { [K in SyncStateKey<T>]?: SyncMergeFn<T[K], T> };
+};
+/**
+* Internal type for `SyncConfig` with `key` always present.
+*/
+type NormalizedSyncConfig<T extends Record<string, unknown>> = SyncConfig<T> & {
+  key: string;
+};
+//#endregion
+//#region src/types/useStoreCallSignatures.react.d.ts
+type UseStoreCallSignatures<State> = {
+  (): State;
+  <Selected>(selector: Selector<State, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
+};
+//#endregion
+//#region src/types.d.ts
+type StoreMutatorsWithSelector<Mutators extends StoreMutators = StoreMutators> = Mutators;
+type StateCreator<S, U = S> = StateCreator$1<S, [], [], U>;
+type UseBoundStoreWithEqualityFn<Store extends {
+  getState: () => unknown;
+}, State = InferStoreState<Store>> = UseStoreCallSignatures<State> & Store;
+type BaseStore<S> = UseBoundStoreWithEqualityFn<StoreApi<S>> & {
+  subscribe: SubscribeOverloads<S>;
+};
+type PersistedStore<S, PersistedState = Partial<S>, PersistReturn extends void | Promise<void> = void | Promise<void>> = UseStoreCallSignatures<S> & WithPersist<BaseStore<S>, PersistedState, PersistReturn>;
+type Store<S, PersistedState extends Partial<S> = never, PersistReturn extends void | Promise<void> = void | Promise<void>> = [PersistedState] extends [never] ? BaseStore<S> : PersistedStore<S, PersistedState, PersistReturn>;
+/**
+* Store returned by creators that accept optional persistence options.
+* `persist` exists only when persistence is configured.
+*/
+type OptionallyPersistedStore<S, PersistedState, PersistReturn extends void | Promise<void> = void> = UseStoreCallSignatures<S> & Omit<BaseStore<S>, "setState"> & {
+  persist?: PersistedStore<S, PersistedState, PersistReturn>["persist"];
+  setState(update: SetPartial<S>, replace?: false): PersistReturn;
+  setState(update: SetFull<S>, replace: true): PersistReturn;
+};
+type NoInfer<T> = [T][T extends unknown ? 0 : never];
+type Timeout = ReturnType<typeof setTimeout>;
+type InferStoreState<Store> = Store extends {
+  getState: () => infer T;
+} ? T : never;
+/**
+* Action methods returned by `createStoreActions(store)`.
+*/
+type StoreActions<Store extends StoreApi<unknown>> = Pick<InferStoreState<Store>, FunctionKeys<InferStoreState<Store>>>;
+/**
+* Extracts a store's `setState` return type.
+*  - `void` for non-persisted or synchronous persisted stores.
+*  - `Promise<void>` for async persisted stores.
+*/
+type InferSetStateReturn<Store> = Store extends {
+  setState(...args: SetStateArgs<infer S>): infer R;
+} ? R : void;
+/**
+* Extracts a store's `PersistedState` type.
+* Returns `never` if the store doesn't use persistence.
+*/
+type InferPersistedState<PersistedStore> = PersistedStore extends Store<infer _, infer PersistedState> ? PersistedState : never;
+/**
+* Reads store state and records dependencies for tracked computations.
+*  - `$(store, selector, equalityFn?)` depends on the selected state
+*  - `$(store)` depends on accessed state paths
+*/
+type DeriveGetter = {
+  <SourceStore extends StoreApi<InferStoreState<SourceStore>>>(store: SourceStore): InferStoreState<SourceStore>;
+  <SourceStore extends StoreApi<InferStoreState<SourceStore>>, Selected>(store: SourceStore, selector: Selector<InferStoreState<SourceStore>, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
+};
+type DerivedStore<S> = WithFlushUpdates<ReadOnlyDerivedStore<BaseStore<S>>>;
+type WithFlushUpdates<Store extends StoreApi<unknown>> = Store & {
+  /**
+  * Destroy the derived store and its subscriptions.
+  *
+  * Derived stores automatically clean up internal resources and subscriptions
+  * when no subscribers exist. So calling `destroy()` is usually unnecessary,
+  * unless `keepAlive: true` is specified and explicit teardown is desired.
+  */
+  destroy: () => void;
+  /**
+  * Flush all pending updates — only applicable to **debounced** derived stores.
+  */
+  flushUpdates: () => void;
+};
+type WithGetSnapshot<Store extends StoreApi<unknown>> = Store & {
+  /**
+  * Reads the current snapshot while activating lazy derived stores before subscription.
+  */
+  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
+*/
+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;
+};
+type Deserializer<SerializedState, PersistedState> = (serializedState: SerializedState) => StorageValue<PersistedState>;
+type Serializer<SerializedState> = <PersistedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+/**
+* Synchronous storage interface.
+* Used for localStorage and MMKV implementations.
+*/
+type 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.
+  */
+  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.
+  */
+  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.
+*/
+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.
+  */
+  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.
+  */
+  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.
+*/
+type PersistConfig<S, PersistedState extends Partial<S> = 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: unknown) => StorageValue<PersistedState>;
+  /**
+  * A function to merge persisted state with current state during hydration.
+  * By default, persisted state is shallow-merged into the current state.
+  */
+  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: Readonly<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?: (storageValue: StorageValue<PersistedState>) => string;
+  /**
+  * 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;
+};
+type EnforceStorageKey<Options> = {
+  storageKey: string;
+} extends Options ? Options : never;
+type BaseStoreOptions<S, PersistedState extends Partial<S> = 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)
+*/
+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>>;
+});
+type SyncWithoutStorageKey<Config> = Config extends {
+  key?: infer Key;
+} ? Extract<Key, string> extends never ? string : Extract<Key, string> : string;
+type UndefinedPersistKeys<S, PersistedState extends Partial<S>, PersistReturn> = { [K in keyof PersistConfig<S, PersistedState, PersistReturn>]?: undefined };
+/**
+* Expanded options for custom debounce behavior.
+*/
+type DebounceOptions = {
+  delay: number;
+  leading?: boolean;
+  maxWait?: number;
+  trailing?: boolean;
+};
+//#endregion
+//#region src/createBaseStore.d.ts
+/**
+* Creates a base store without persistence.
+* @param createState - The state creator function for the base store.
+* @returns A store with the specified state.
+*/
+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 store with the specified state and persistence.
+*/
+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, 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 store with the specified state and persistence.
+*/
+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, 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 store with the specified state and optional persistence.
+*/
+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 store with the specified state and optional persistence.
+*/
+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>;
+//#endregion
+//#region src/createDerivedStore.d.ts
+/**
+* ### `createDerivedStore`
+*
+* Creates a **read-only** store derived from one or more source 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 store exposes:
+*
+* - A **store object** with `getState()`, `subscribe()`, and `destroy()`
+* - In the React build, a **React hook** (`const state = derivedStore(selector, equalityFn?)`)
+*
+* ---
+* 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 searchResultsStore = createDerivedStore($ => {
+*   const query = $(searchStore).query.trim().toLowerCase();
+*   const items = $(itemsStore).items;
+*   return findResults(query, items);
+* }, shallowEqual);
+*
+* const results = searchResultsStore.getState();
+* ```
+*
+* ---
+* @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. In the React build, it is also callable as a hook.
+*/
+declare function createDerivedStore<Derived>(deriveFunction: ($: DeriveGetter) => Derived, optionsOrEqualityFn?: DeriveOptions<Derived>): DerivedStore<Derived>;
+//#endregion
+//#region src/queryStore/queryParam.d.ts
+declare const QUERY_PARAM_CONFIG: unique symbol;
+/**
+* Selects how a query parameter participates in the query key.
+*/
+type QueryParamKey<T> = false | ((value: T) => unknown);
+/**
+* A query value derived from stores via `$`.
+*/
+type ReactiveParam<T, State> = ($: DeriveGetter, store: StoreApi<State>) => T;
+/**
+* Query parameter wrapper for values whose fetcher value and key value differ.
+*/
+type QueryParamConfig<T, State> = {
+  readonly [QUERY_PARAM_CONFIG]: true;
+  readonly key: QueryParamKey<T>;
+  readonly value: NonFunction<T> | ReactiveParam<T, State>;
+};
+/**
+* A direct, reactive, or key-configured query parameter.
+*/
+type QueryParam<T, State> = NonFunction<T> | ReactiveParam<T, State> | QueryParamConfig<T, State>;
+/**
+* Wraps a query parameter when its full fetcher value should be excluded
+* from the query key or represented by a smaller key value.
+*/
+declare function queryParam<T, State>(value: NonFunction<T> | ReactiveParam<T, State>, options: {
+  key: QueryParamKey<T>;
+}): QueryParamConfig<T, State>;
+//#endregion
+//#region src/queryStore/types.d.ts
+/**
+* Helper type that represents the store returned by `createQueryStore()`.
+*/
+type QueryStore<TData, TParams extends Record<string, unknown>, CustomState = unknown> = Store<QueryStoreState<TData, TParams, CustomState>>;
+/**
+* Configuration options for creating a query-enabled store.
+*/
+type QueryStoreConfig<TQueryFnData, TParams extends Record<string, unknown>, TData = TQueryFnData, CustomState = unknown, S extends QueryStoreState<TData, TParams, CustomState> = QueryStoreState<TData, TParams, CustomState>> = ([TQueryFnData] extends [TData] ? {
+  /**
+  * A function to transform the raw fetched data** (`TQueryFnData`) into another
+  * form (`TData`). If not provided, the raw data returned by `fetcher` is used.
+  */
+  transform?: (data: TQueryFnData, params: TParams) => TData;
+} : {
+  /**
+  * A function to transform the raw fetched data** (`TQueryFnData`) into another
+  * form (`TData`). If not provided, the raw data returned by `fetcher` is used.
+  */
+  transform: (data: TQueryFnData, params: TParams) => TData;
+}) & {
+  /**
+  * **A function responsible for fetching data from a remote source.**
+  * Receives parameters of type TParams and optionally an abort controller.
+  * Returns either a promise or a raw data value of type TQueryFnData.
+  *
+  * ---
+  * `abortController` is by default available, unless either:
+  *  - `abortInterruptedFetches` is set to `false` in the store's config
+  *  - The fetch was manually triggered with `skipStoreUpdates: true`
+  */
+  fetcher: (params: TParams, abortController: AbortController | null) => TQueryFnData | Promise<TQueryFnData>;
+  /**
+  * Called after each failure handled by the query store.
+  * `willRetry` indicates whether another attempt was scheduled.
+  */
+  onError?: (failure: OnErrorParams<TParams>) => void;
+  /**
+  * **A callback invoked whenever fresh data is successfully fetched.**
+  * Receives the transformed data and the store's set function, which can optionally be used to update store state.
+  */
+  onFetched?: (info: OnFetchedParams<TData, TParams, CustomState, S>) => void;
+  /**
+  * **A function that overrides the default behavior of setting the fetched data in the store's query cache.**
+  * Receives an object containing the transformed data, the query parameters, the query key, and the store's set function.
+  *
+  * When using `setData`, it’s important to note that you are taking full responsibility for managing query data. If your
+  * query supports variable parameters (and thus multiple query keys) and you want to cache data for each key, you’ll need
+  * to manually handle storing data based on the provided `params` or `queryKey`. Naturally, you will also bear
+  * responsibility for pruning this data in the event you do not want it persisted indefinitely.
+  *
+  * Automatic refetching per your specified `staleTime` is still managed internally by the store. While no query *data*
+  * will be cached internally if `setData` is provided, metadata such as the last fetch time for each query key is still
+  * cached and tracked by the store, unless caching is fully disabled via `disableCache: true`.
+  */
+  setData?: (info: SetDataParams<TData, TParams, CustomState, S>) => void;
+  /**
+  * If `true`, the store will abort any partially completed fetches when:
+  *  - A new fetch is initiated due to a change in parameters
+  *  - All components subscribed to the store via selectors are unmounted
+  * @default true
+  */
+  abortInterruptedFetches?: boolean;
+  /**
+  * The maximum duration, in milliseconds, that fetched data is considered fresh.
+  * After this time, data is considered expired and will be refetched when requested.
+  * @default time.days(7)
+  */
+  cacheTime?: number | ((params: TParams) => number);
+  /**
+  * If `true`, the store will log debug messages to the console.
+  * @default false
+  */
+  debugMode?: boolean;
+  /**
+  * If `true`, the store will **not** trigger automatic refetches when data becomes stale. This is
+  * useful in cases where you want to refetch data on component mount if stale, but not automatically
+  * if data becomes stale while your component is already mounted.
+  * @default false
+  */
+  disableAutoRefetching?: boolean;
+  /**
+  * Controls whether the store's caching mechanisms are disabled. When disabled, the store will always refetch
+  * data when params change, and fetched data will not be stored unless a `setData` function is provided.
+  * @default false
+  */
+  disableCache?: boolean;
+  /**
+  * When `true`, the store actively fetches and refetches data as needed.
+  * When `false`, the store will not automatically fetch data until explicitly enabled.
+  * @default true
+  */
+  enabled?: boolean | ReactiveParam<boolean, S>;
+  /**
+  * When `true`, the store's `getData` method will always return existing data from the cache if it exists,
+  * regardless of whether the cached data is expired, until the data is pruned following a successful refetch.
+  *
+  * Additionally, when params change while the store is enabled, `getData` will return the previous data until
+  * data for the new params is available.
+  * @default false
+  */
+  keepPreviousData?: boolean;
+  /**
+  * Delay before triggering a fetch when parameters change.
+  * Accepts a number (ms), false (no throttling), or debounce options:
+  *
+  * `{ delay: number, leading?: boolean, trailing?: boolean, maxWait?: number }`
+  * @default false
+  */
+  paramChangeThrottle?: false | number | DebounceOptions;
+  /**
+  * Reactive or static parameters to be passed to the fetcher.
+  */
+  params?: QueryStoreParams<TParams, TData, S, CustomState>;
+  /**
+  * Whether failed queries should be retried.
+  * `false` or `0` disables retries, a number limits retries, and a function decides each failure.
+  * Numeric limits must be non-negative integers.
+  * Function policies have no implicit retry limit.
+  * @default 5
+  */
+  retry?: RetryPolicy<TParams>;
+  /**
+  * Finite, non-negative delay before each retry, in milliseconds.
+  * @default Exponential backoff from 5 seconds, doubling after each failure and capped at 5 minutes
+  */
+  retryDelay?: RetryDelay<TParams>;
+  /**
+  * The duration, in milliseconds, that data is considered fresh after fetching.
+  * After becoming stale, the store may automatically refetch data in the background if there are active subscribers.
+  * @default time.minutes(2)
+  */
+  staleTime?: number | ReactiveParam<number, S>;
+  /**
+  * Suppresses warnings in the event a `staleTime` under the minimum is desired.
+  * @default false
+  */
+  suppressStaleTimeWarning?: boolean;
+};
+/**
+* The internal state structure managed by the query store.
+*/
+type QueryStoreInternalState<TData, TParams extends Record<string, unknown>> = {
+  /**
+  * Initiates a data fetch for the given parameters. If no parameters are provided,
+  * the store's current parameters are used.
+  * @param params - Optional parameters to pass to the fetcher function.
+  * @param options - Optional {@link FetchOptions} to customize the fetch behavior.
+  * @returns A promise that resolves when the fetch operation completes.
+  */
+  fetch: (params?: Partial<TParams>, options?: FetchOptions) => Promise<TData | null>;
+  /**
+  * A lower-level helper that provides direct access to raw cache entries. If no query key
+  * or params are specified, the cache entry for the current parameters is returned.
+  * @param paramsOrQueryKey - Optional parameters or query key to retrieve the cache entry.
+  * @returns The relevant cache entry, or `null` if no entry is found.
+  */
+  getCacheEntry: (paramsOrQueryKey?: TParams | Partial<TParams> | string) => CacheEntry<TData> | null;
+  /**
+  * Returns the cached data, if available, for the provided query key or parameters.
+  * If no query key or params are specified, data for the current parameters is returned.
+  * @param paramsOrQueryKey - Optional parameters or query key to retrieve cached data for.
+  * @returns The cached data, or `null` if no data is available.
+  */
+  getData: (paramsOrQueryKey?: TParams | string) => CacheEntry<TData>["data"];
+  /**
+  * Returns expanded status information for the currently specified query parameters.
+  * Pass a status key to avoid building the full status object.
+  * @example
+  * ```ts
+  * const isInitialLoad = myQueryStore.getState().getStatus('isInitialLoad');
+  * ```
+  * @returns The requested status, or the full status object if no key is provided.
+  */
+  getStatus(statusKey: keyof QueryStatusInfo): QueryStatusInfo[keyof QueryStatusInfo];
+  getStatus(): QueryStatusInfo;
+  getStatus(statusKey?: keyof QueryStatusInfo): QueryStatusInfo[keyof QueryStatusInfo] | QueryStatusInfo;
+  /**
+  * Determines if the current data is expired based on whether `cacheTime` has been exceeded.
+  * @param override - An optional override for the default cache time, in milliseconds.
+  * @returns `true` if the data is expired, otherwise `false`.
+  */
+  isDataExpired: (override?: number) => boolean;
+  /**
+  * Determines if the current data is stale based on whether `staleTime` has been exceeded.
+  * Stale data may be refreshed automatically in the background.
+  * @param override - An optional override for the default stale time, in milliseconds.
+  * @returns `true` if the data is stale, otherwise `false`.
+  */
+  isStale: (override?: number) => boolean;
+  /**
+  * Tears down param subscriptions and timers and resets fetch state. Optionally resets store state.
+  * @param resetStoreState - If `true`, the store's state will be reset to its initial state.
+  * @default false
+  */
+  reset: (resetStoreState?: boolean) => void;
+  /**
+  * Indicates whether the store should actively fetch data.
+  * When `false`, the store won't automatically refetch data.
+  */
+  enabled: boolean;
+  /**
+  * The most recent error encountered during a fetch operation, if any.
+  */
+  error: Error | null;
+  /**
+  * The timestamp of the last successful fetch, or null if no successful fetch has occurred.
+  */
+  lastFetchedAt: number | null;
+  /**
+  * A cache of fetched data and metadata, keyed by generated query keys.
+  */
+  queryCache: Record<string, CacheEntry<TData> | undefined>;
+  /**
+  * The current query key, generated deterministically from store parameters.
+  */
+  queryKey: string;
+  /**
+  * The current status of the query's remote data fetching operation.
+  */
+  status: QueryStatus;
+};
+/**
+* The full state structure managed by the query store. This type is generally internal,
+* though the state it defines can be accessed via the store's public interface.
+*/
+type QueryStoreState<TData, TParams extends Record<string, unknown>, CustomState = unknown> = QueryStoreInternalState<TData, TParams> & CustomState;
+/**
+* Defines additional options for a data fetch operation.
+*/
+type FetchOptions = {
+  /**
+  * Overrides the store's default cacheTime for this fetch, which dictates when the data fetched in this operation
+  * will become eligible for pruning.
+  *
+  * Has no effect if `skipStoreUpdates` is set to `true`.
+  */
+  cacheTime?: number;
+  /**
+  * Forces a fetch request even if there is fresh data available in the cache.
+  *
+  * Note: If a pending fetch matches the forced fetch's params, the pending promise *will* be returned.
+  * @default false
+  */
+  force?: boolean;
+  /**
+  * If `true`, the fetch will simply return the data without any internal handling or side effects,
+  * running in parallel with any other ongoing fetches. Use together with `force: true` if you want to
+  * guarantee that a fresh fetch is triggered regardless of the current store state.
+  *
+  * ---
+  * If set to `'withCache'`, the fetch will similarly run in parallel without affecting the store, but the
+  * fetched data will be stored in the cache, as long as the store's config doesn't contain `disableCache: true`.
+  * @default false
+  */
+  skipStoreUpdates?: boolean | "withCache";
+  /**
+  * Overrides the store's default staleTime for this fetch, which dictates how fresh data must be to be returned
+  * from the cache.
+  */
+  staleTime?: number;
+  /**
+  * If `true`, the fetch operation will throw an error if the fetch fails.
+  * @default false
+  */
+  throwOnError?: boolean;
+  /**
+  * Dictates whether the store's `queryKey` should be updated based on the params used in the fetch operation.
+  * Useful if for instance you want to cache the manually fetched data, but skip updating the store's current
+  * `queryKey` (which determines where `getData()` points to).
+  *
+  * ---
+  * Manual fetches default to `false`. Internal query-store fetches default to the store's `keepPreviousData`
+  * behavior. When `skipStoreUpdates` is set, the query key is never updated.
+  */
+  updateQueryKey?: boolean;
+};
+/**
+* A set of constants representing the various stages of a query's remote data fetching process.
+*/
+declare const QueryStatuses: {
+  readonly Error: "error";
+  readonly Idle: "idle";
+  readonly Loading: "loading";
+  readonly Success: "success";
+};
+/**
+* Represents the current status of the query's remote data fetching operation.
+*
+* Possible values:
+*  - **`'error'`**: The most recent request encountered an error.
+*  - **`'idle'`**: No request in progress, no error, no data yet.
+*  - **`'loading'`**: A request is currently in progress.
+*  - **`'success'`**: The most recent request has succeeded and data is available.
+*/
+type QueryStatus = (typeof QueryStatuses)[keyof typeof QueryStatuses];
+/**
+* Expanded status information for the currently specified query parameters.
+*/
+type QueryStatusInfo = {
+  isError: boolean;
+  isIdle: boolean;
+  isInitialLoad: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+};
+/** Error metadata for a query key's latest failed fetch. */
+type QueryErrorInfo = {
+  error: Error;
+  lastFailedAt: number;
+  retryCount: number; /** Whether the retry policy allows another attempt after this failure. */
+  retryAllowed: boolean;
+};
+/**
+* Represents an entry in the query cache, which stores fetched data along with metadata,
+* and error information in the event the most recent fetch failed.
+*/
+type CacheEntry<T> = {
+  cacheTime: number;
+  data: T | null;
+} & ({
+  errorInfo: QueryErrorInfo;
+  lastFetchedAt: null;
+} | {
+  errorInfo: QueryErrorInfo | null;
+  lastFetchedAt: number;
+});
+/**
+* Internal helper type for the config’s params clause.
+*/
+type QueryStoreParams<TParams extends Record<string, unknown>, TData, S extends QueryStoreState<TData, TParams, CustomState>, CustomState = unknown> = [TParams] extends [Record<string, never>] ? undefined : { [K in keyof TParams]: QueryParam<TParams[K], S> };
+/**
+* The keys that make up the internal state of the store.
+*/
+type InternalStateKeys = keyof QueryStoreInternalState<unknown, Record<string, unknown>>;
+/**
+* Params available to retry policy and delay callbacks.
+*/
+type RetryFailureParams<TParams extends Record<string, unknown>> = {
+  readonly error: Error;
+  readonly params: TParams;
+  readonly queryKey: string;
+  /**
+  * Retry attempts already performed in the current sequence.
+  * `0` after the originating request fails, `1` after the first retry fails, and so on.
+  */
+  readonly retryCount: number;
+};
+/**
+* A handled query failure and whether another attempt was scheduled.
+*/
+type OnErrorParams<TParams extends Record<string, unknown>> = RetryFailureParams<TParams> & {
+  readonly willRetry: boolean;
+};
+/**
+* Whether failed queries should be retried.
+*
+* `false` or `0` disables retries, a number limits retries, and a function decides each failure.
+*
+* Numeric limits must be non-negative integers. Function policies have no implicit retry limit.
+*/
+type RetryPolicy<TParams extends Record<string, unknown>> = false | number | ((failure: RetryFailureParams<TParams>) => boolean);
+/**
+* The finite, non-negative delay before each retry, in milliseconds.
+*/
+type RetryDelay<TParams extends Record<string, unknown>> = number | ((failure: RetryFailureParams<TParams>) => number);
+/**
+* Helper type for defining `onFetched` parameters.
+*/
+type OnFetchedParams<TData, TParams extends Record<string, unknown> = Record<string, never>, CustomState = unknown, S extends QueryStoreState<TData, TParams, CustomState> = QueryStoreState<TData, TParams, CustomState>> = {
+  data: TData;
+  fetch: (params?: TParams | Partial<TParams>, options?: FetchOptions) => Promise<TData | null>;
+  params: TParams;
+  set: (update: SetPartial<S>) => void;
+};
+/**
+* Helper type for defining `setData` parameters.
+*/
+type SetDataParams<TData, TParams extends Record<string, unknown> = Record<string, never>, CustomState = unknown, S extends QueryStoreState<TData, TParams, CustomState> = QueryStoreState<TData, TParams, CustomState>> = {
+  data: TData;
+  params: TParams;
+  queryKey: string;
+  set: (update: SetPartial<S>) => void;
+};
+//#endregion
+//#region src/types/objects.d.ts
+/**
+* Forces TypeScript to expand a type for clearer IDE display.
+*/
+type Prettify<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
+/**
+* Enforce no overlapping keys between two objects.
+*/
+type NoOverlap<A, B> = B & Record<Extract<keyof A, keyof B>, never>;
+//#endregion
+//#region src/internal/logger.d.ts
+interface Logger {
+  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;
+}
+//#endregion
+//#region src/internal/config.d.ts
+/**
+* Global configuration for all stores.
+*/
+type StoresConfig = {
+  /**
+  * Custom logger for debug output. Defaults to a no-op logger in production.
+  */
+  logger: Logger;
+  /**
+  * Default options used by all query stores.
+  */
+  queryStoreDefaults: QueryStoreDefaults;
+  /**
+  * Storage backend for persisted stores. Defaults to `localStorage` in browsers,
+  * MMKV in React Native.
+  */
+  storage: AsyncStorageInterface | SyncStorageInterface;
+  /**
+  * Prefix for storage keys built by the default storage adapter.
+  * Should include a delimiter, e.g., `'myapp:'`.
+  * @default 'stores:'
+  */
+  storageKeyPrefix: string;
+  /**
+  * Sync engine for cross-client state synchronization. Defaults to cross-tab sync
+  * in browsers, no-op in other environments.
+  */
+  syncEngine: SyncEngine;
+};
+type QueryStoreDefaults = Prettify<ConfigDefaults<QueryStoreConfig<unknown, Record<string, unknown>>, "disableCache" | "enabled" | "params", "onError" | "retry" | "retryDelay">> & {
+  /**
+  * Minimum stale time for auto-refetching query stores under which to log warnings in development.
+  * `false` disables warnings.
+  * @default false
+  */
+  minStaleTime?: number | false;
+};
+type ConfigDefaults<C, Excluded extends keyof C = never, AllowedFunctions extends keyof C = never> = Omit<{ [K in keyof C as K extends AllowedFunctions ? K : NonFunction<C[K]> extends undefined ? never : K]?: K extends AllowedFunctions ? C[K] : NonFunction<C[K]> }, Excluded>;
+/**
+* Configures global defaults for all stores.
+*
+* If used, must be called before creating any stores.
+*
+* @see {@link StoresConfig}
+*
+* @example
+* ```ts
+* configureStores({
+*   logger: { debug: console.debug, error: console.error },
+*   storageKeyPrefix: 'myapp:',
+* });
+* ```
+*/
+declare function configureStores(config: Partial<StoresConfig>): void;
+//#endregion
+//#region src/internal/errors.d.ts
+/**
+* Error reported or thrown by the stores package itself.
+*
+* If an underlying thrown value caused the failure, it is available as `cause`.
+*/
+declare class StoresError extends Error {
+  cause?: unknown;
+  constructor(message: string, cause?: unknown);
+}
+//#endregion
+//#region src/internal/queryStore/queryStoreDefaults.d.ts
+/**
+* Exponential backoff: starts at `baseDelay` (5s), doubles each retry, capped at `maxDelay` (5m).
+*/
+declare function defaultRetryDelay(retryCount: number): number;
+//#endregion
+//#region src/store/stateUpdate.d.ts
+/**
+* Applies a `setState` payload to the current state.
+*/
+declare function applyStateUpdate<S>(state: S, update: SetPartial<S>, replace?: boolean): S;
+//#endregion
+//#region src/utils/serialization.d.ts
+declare function replacer(_: string, value: unknown): unknown;
+declare function reviver(_: string, value: unknown): unknown;
+//#endregion
+//#region src/internal/storeUtils.d.ts
+/**
+* Calls the appropriate reset or destroy method on the store, if available.
+* Handles both `DerivedStore` and `QueryStore`.
+*/
+declare function destroyStore(store: BaseStore<unknown> | StoreApi<unknown> | QueryStore<unknown, Record<string, unknown>, unknown>, options?: {
+  clearQueryCache?: boolean;
+}): void;
+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.
+*/
+declare function getStoreName(store: BaseStore<unknown>): string;
+/**
+* Checks if a store is a `DerivedStore` and reveals its internal `getSnapshot` method.
+*/
+declare function hasGetSnapshot<T extends BaseStore<unknown> | StoreApi<unknown>>(store: T): store is T & {
+  getSnapshot: () => InferStoreState<T>;
+};
+/**
+* Checks if a store is a `QueryStore`.
+*/
+declare function isQueryStore<T extends object>(store: T): store is Extract<T, BaseStore<QueryStoreState<unknown, Record<string, unknown>, unknown>>>;
+/**
+* Checks if a store is a `DerivedStore`.
+*/
+declare function isDerivedStore<T extends BaseStore<unknown> | StoreApi<unknown>>(store: T): store is T & {
+  destroy: () => void;
+  flushUpdates: () => void;
+};
+/**
+* Checks if a store is persisted.
+*/
+declare function isPersistedStore<T extends BaseStore<unknown> | PersistedStore<unknown>>(store: T): store is T & {
+  persist: PersistedStore<InferStoreState<T>>["persist"];
+};
+/**
+* Checks if a store is a virtual store.
+*/
+declare function isVirtualStore<T extends BaseStore<unknown> | StoreApi<unknown>>(store: T): store is T & BaseStore<InferStoreState<T>>;
+//#endregion
+//#region src/utils/core.d.ts
+/**
+* Returns the argument provided.
+*/
+declare function identity<T>(value: T): T;
+declare function identity<T, _>(value: T): T;
+/**
+* Creates a null-prototype object using the runtime-optimal path:
+*  - React Native: direct literal `{ __proto__: null }`
+*  - Web/Node: `Object.create` with a shared, frozen null prototype
+*/
+declare function nullObject<T extends Record<string, unknown> | object = Record<string, unknown>>(): T;
+//#endregion
+//#region src/internal/createStoreActions.d.ts
+/**
+* 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();
+*/
+declare function createStoreActions<Store extends StoreApi<unknown>>(store: Store): StoreActions<Store>;
+declare function createStoreActions<Store extends StoreApi<unknown>, Bundled extends FunctionRecord>(store: Store, bundledMethods: NoOverlap<InferStoreState<Store>, Bundled>): StoreActions<Store> & Bundled;
+//#endregion
+//#region src/utils/equality.d.ts
+/**
+* **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`.
+*/
+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`.
+*/
+declare function shallowEqual<U>(obj1: U, obj2: U): boolean;
+//#endregion
+//#region src/utils/time.d.ts
+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
+*/
+declare const time: TimeUtils;
+//#endregion
+//#region src/queryStore/queryKey.d.ts
+/**
+* Generates a deterministic query store `queryKey` from the given
+* key payload, consistent with internally generated keys.
+*/
+declare function getQueryKey<TKeyPayload extends Record<string, unknown>>(keyPayload: TKeyPayload): string;
+/**
+* Parses a query store `queryKey` into the key payload it encodes.
+*/
+declare function parseQueryKey<TKeyPayload extends Record<string, unknown> = Record<string, unknown>>(queryKey: string): TKeyPayload;
+//#endregion
+//#region src/createQueryStore.d.ts
+/**
+* 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
+*/
+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, 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
+*/
+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, 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
+*/
+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, 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
+*/
+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, 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`)
+*/
+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`)
+*/
+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
+*/
+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
+*/
+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
+*/
+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> | 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
+*/
+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> | undefined): OptionallyPersistedStore<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>;
+//#endregion
+//#region src/createVirtualStore.d.ts
+type MethodOverrides<Store extends BaseStore<unknown>> = Partial<Pick<Store, "getState" | "setState">>;
+type VirtualStore<Store extends BaseStore<unknown>> = OptionallyPersistedStore<InferStoreState<Store>, InferPersistedState<Store>, InferSetStateReturn<Store>>;
+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);
+* });
+* ```
+*/
+declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>>(createStore: ($: DeriveGetter) => Store, options?: VirtualStoreOptions): VirtualStore<Store>;
+declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>, Overrides extends MethodOverrides<Store>>(createStore: ($: DeriveGetter) => Store, overrides: (getStore: () => Store) => Overrides, options?: VirtualStoreOptions): VirtualStore<Store> & Overrides;
+//#endregion
+export { type AsyncStorageInterface, type BaseStore, type BaseStoreOptions, type CacheEntry, type DebounceOptions, type DeriveGetter, type DeriveOptions, type DerivedStore, type Deserializer, type EnforceStorageKey, type EqualityFn, type FetchOptions, type FieldMetadata, type InferPersistedState, type InferSetStateReturn, type InferStoreState, type InternalStateKeys, type Listener, type ListenerArgs, type NoInfer, type NormalizedSyncConfig, type OnErrorParams, type OnFetchedParams, type OptionallyPersistedStore, type PersistConfig, type PersistedStore, type QueryErrorInfo, type QueryParam, type QueryParamConfig, type QueryParamKey, type QueryStatus, type QueryStatusInfo, QueryStatuses, type QueryStore, type QueryStoreConfig, type QueryStoreInternalState, type QueryStoreParams, type QueryStoreState, type ReactiveParam, type RetryDelay, type RetryFailureParams, type RetryPolicy, type Selector, type SelectorArgs, type Serializer, type SetDataParams, type SetFull, type SetPartial, type SetState, type SetStateArgs, type SetStateOverloads, type SetStatePartialArgs, type SetStateReplaceArgs, type StateCreator, type StorageValue, type Store, type StoreActions, type StoreMutators, type StoreMutatorsWithSelector, StoresError, type SubscribableStore, type SubscribeArgs, type SubscribeFn, type SubscribeOptions, type SubscribeOverloads, type SyncConfig, type SyncEngine, type SyncHandle, type SyncMergeFn, type SyncOption, type SyncRegistration, type SyncStateKey, type SyncStorageInterface, type SyncUpdate, type SyncValues, type Timeout, type UnsubscribeFn, type UseBoundStoreWithEqualityFn, type UseStoreCallSignatures, type WithFlushUpdates, type WithGetSnapshot, applyStateUpdate, configureStores, createBaseStore, createDerivedStore, createQueryStore, createStoreActions, createVirtualStore, deepEqual, defaultRetryDelay, destroyStore, destroyStores, getQueryKey, getStoreName, hasGetSnapshot, identity, isDerivedStore, isPersistedStore, isQueryStore, isVirtualStore, nullObject, parseQueryKey, queryParam, replacer, reviver, shallowEqual, time };