@storesjs/stores 0.8.7 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # Stores
 
-Stores provides a minimal, reactive state layer built on top of Zustand.
+Stores provides a minimal, reactive state layer that runs with or without React.
 
 It defines three types of runtime-evaluated stores—**base**, **derived**, and **query**—each representing a distinct state type: local, computed, or asynchronously fetched. Stores track dependencies at runtime, evaluate lazily, and clean up automatically when unused.
 
@@ -10,10 +10,32 @@ All stores expose a consistent interface and can be used both inside and outside
 - **Derived stores** compute values from other stores and re-run only when inputs change.
 - **Query stores** fetch and cache async data, refetching when reactive parameters change.
 
-All store types share a common interface: a React-compatible hook, a
-stable store object with `.getState()` and `.subscribe()`, and optional
-support for persistence. They compose naturally, interoperate cleanly,
-and scale as application complexity grows.
+All store types expose a stable store object with `.getState()` and
+`.subscribe()`, plus optional support for persistence. In the React build,
+stores are also callable hooks. In the vanilla build, stores remain plain store
+objects. They compose naturally, interoperate cleanly, and scale as application
+complexity grows.
+
+## Runtime Modes
+
+The root import is mode-aware:
+
+- React web apps use `@storesjs/stores` by default.
+- React Native apps use `@storesjs/stores`; the `react-native` package condition selects the native build.
+- Vanilla apps use `@storesjs/stores` with the `vanilla` package condition enabled.
+
+For TypeScript vanilla projects, use a condition-aware resolver and add the
+same condition to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "customConditions": ["vanilla"]
+  }
+}
+```
 
 ## Base Store
 
@@ -21,7 +43,7 @@ A base store defines local state along with an interface for reading and
 updating that state.
 
 ```ts
-export const useSettingsStore = createBaseStore<Settings>(set => ({
+export const settingsStore = createBaseStore<Settings>(set => ({
   currency: 'USD',
   setCurrency: currency => set({ currency }),
 }));
@@ -30,14 +52,14 @@ export const useSettingsStore = createBaseStore<Settings>(set => ({
 In React, subscribe to values with selectors:
 
 ```ts
-const currency = useSettingsStore(s => s.currency);
+const currency = settingsStore(s => s.currency);
 ```
 
 Outside React:
 
 ```ts
-useSettingsStore.getState().currency;
-useSettingsStore.subscribe(selector, listener, options);
+settingsStore.getState().currency;
+settingsStore.subscribe(selector, listener, options);
 ```
 
 Enable persistence per store:
@@ -52,7 +74,7 @@ createBaseStore<Settings>(set => ({ ... }), {
 You can also export actions as a stable object:
 
 ```ts
-export const settingsActions = createStoreActions(useSettingsStore);
+export const settingsActions = createStoreActions(settingsStore);
 ```
 
 ## Derived Store
@@ -61,9 +83,9 @@ Derived stores compute values from other stores. The `$` accessor tracks
 dependencies at runtime:
 
 ```ts
-export const useTotal = createDerivedStore($ => {
-  const { currency } = $(useSettingsStore);
-  const { subtotal, tax } = $(useCartStore);
+export const totalStore = createDerivedStore($ => {
+  const { currency } = $(settingsStore);
+  const { subtotal, tax } = $(cartStore);
   return formatTotal(currency, subtotal, tax);
 });
 ```
@@ -78,10 +100,10 @@ Query stores manage remote data. They fetch, cache, and revalidate based
 on reactive parameters:
 
 ```ts
-export const useAccountStore = createQueryStore<Account, Params>({
+export const accountStore = createQueryStore<Account, Params>({
   fetcher: fetchAccount,
   params: {
-    userId: $ => $(useAuthStore).userId,
+    userId: $ => $(authStore).userId,
   },
   staleTime: time.minutes(10),
 });
@@ -93,13 +115,13 @@ idle.
 Use it in React:
 
 ```ts
-const account = useAccountStore(s => s.getData());
+const account = accountStore(s => s.getData());
 ```
 
 Or imperatively:
 
 ```ts
-useAccountStore.getState().fetch();
+accountStore.getState().fetch();
 ```
 
 Query stores support full customization: extended local state, manual cache control, configurable staleness and retry behavior, and optional persistence.
@@ -108,22 +130,26 @@ They deduplicate fetches across consumers and compute stable query keys automati
 
 ## Store Interface
 
-All stores implement the same API:
+All stores implement the same store-object API:
 
 ```ts
-useStore()
-useStore(selector, equalityFn?)
+store.getState()
+store.setState() // Except for derived stores
+store.subscribe(selector, listener, options?)
+```
 
-useStore.getState()
-useStore.setState() // Except for derived stores
-useStore.subscribe(selector, listener, options?)
+In the React build, stores are also callable hooks:
+
+```ts
+store()
+store(selector, equalityFn?)
 ```
 
 ## Composed Example
 
 ```ts
-export const useCurrencyFormatter = createDerivedStore($ => {
-  const { currency, locale } = $(useSettingsStore);
+export const currencyFormatterStore = createDerivedStore($ => {
+  const { currency, locale } = $(settingsStore);
   return new Intl.NumberFormat(locale, {
     currency,
     style: 'currency',
@@ -132,16 +158,16 @@ export const useCurrencyFormatter = createDerivedStore($ => {
 ```
 
 ```ts
-export const useAccountBalance = createDerivedStore($ => {
-  const balance = $(useAccountStore).getData()?.balance ?? 0;
-  const formatter = $(useCurrencyFormatter);
+export const accountBalanceStore = createDerivedStore($ => {
+  const balance = $(accountStore).getData()?.balance ?? 0;
+  const formatter = $(currencyFormatterStore);
   return formatter.format(balance);
 });
 ```
 
 ```ts
 function AccountSummary() {
-  const balance = useAccountBalance();
+  const balance = accountBalanceStore();
   return <Text>Balance: {balance}</Text>;
 }
 ```

package/dist/createBaseStore.d.ts

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

package/dist/createDerivedStore.d.ts

@@ -1,8 +1,8 @@
-import { DeriveOptions, DerivedStore, EqualityFn, Store, Selector, InferStoreState } from './types';
+import type { DeriveGetter, DeriveOptions, DerivedStore } from './types';
 /**
  * ### `createDerivedStore`
  *
- * Creates a **read-only** store derived from one or more underlying Zustand stores.
+ * 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.
@@ -28,10 +28,10 @@ import { DeriveOptions, DerivedStore, EqualityFn, Store, Selector, InferStoreSta
  *
  * ---
  * Derived stores automatically unsubscribe from all dependencies when no consumers remain, and
- * resubscribe when new consumers appear. The returned function doubles as:
+ * resubscribe when new consumers appear. The returned store exposes:
  *
- * - A **React hook** (`const state = useDerivedStore(selector, equalityFn?)`)
  * - 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)
@@ -44,28 +44,20 @@ import { DeriveOptions, DerivedStore, EqualityFn, Store, Selector, InferStoreSta
  * @example
  * ```ts
  * // Create a derived store
- * const useSearchResults = createDerivedStore($ => {
- *   const query = $(useSearchStore).query.trim().toLowerCase();
- *   const items = $(useItemsStore).items;
+ * const searchResultsStore = createDerivedStore($ => {
+ *   const query = $(searchStore).query.trim().toLowerCase();
+ *   const items = $(itemsStore).items;
  *   return findResults(query, items);
  * }, shallowEqual);
  *
- * function SearchResults() {
- *   // Consume the derived state
- *   const results = useSearchResults(); // Or (selector, equalityFn?)
- *   return <ResultsList items={results} />;
- * }
+ * 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 (usable as a hook or standard store object).
+ * @returns A read-only derived store. In the React build, it is also callable as a hook.
  */
 export declare function createDerivedStore<Derived>(deriveFunction: ($: DeriveGetter) => Derived, optionsOrEqualityFn?: DeriveOptions<Derived>): DerivedStore<Derived>;
-export type DeriveGetter = {
-    <S extends Store<unknown>>(store: S): InferStoreState<S>;
-    <S extends Store<unknown>, Selected>(store: S, selector: Selector<InferStoreState<S>, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
-};
 //# sourceMappingURL=createDerivedStore.d.ts.map

package/dist/createQueryStore.d.ts

@@ -1,5 +1,7 @@
-import { QueryStoreConfig, QueryStoreState } from './queryStore/types';
-import { BaseStoreOptions, OptionallyPersistedStore, PersistedStore, StateCreator, Store } from './types';
+import { defaultRetryDelay } from './internal/runtime';
+import type { QueryStoreConfig, QueryStoreState } from './queryStore/types';
+import type { BaseStoreOptions, OptionallyPersistedStore, PersistedStore, StateCreator, Store } from './types';
+export { defaultRetryDelay };
 /**
  * Creates a persisted, query-enabled store with data fetching capabilities (sync storage).
  *
@@ -91,7 +93,7 @@ export declare function createQueryStore<TQueryFnData, TParams extends Record<st
  * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
  * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
  */
-export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends void = void>(config: QueryStoreConfig<TQueryFnData, TParams, TData, QueryStoreState<TData, TParams>>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn> | undefined): OptionallyPersistedStore<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>;
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends void = void>(config: QueryStoreConfig<TQueryFnData, TParams, TData>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn> | undefined): OptionallyPersistedStore<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>;
 /**
  * Creates a conditionally persisted, query-enabled store with data fetching capabilities (async storage).
  *
@@ -102,24 +104,7 @@ export declare function createQueryStore<TQueryFnData, TParams extends Record<st
  * @template TData - The transformed data type, if applicable (defaults to `TQueryFnData`)
  * @template PersistedState - The persisted state type, if a stricter type than `Partial<CustomState>` is desired
  */
-export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends Promise<void> = Promise<void>>(config: QueryStoreConfig<TQueryFnData, TParams, TData, QueryStoreState<TData, TParams>>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn> | undefined): OptionallyPersistedStore<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>;
-/**
- * The default query store `retryDelay` function.
- *
- * Exponential backoff starting at `baseDelay` (5s default), doubling each retry, capped at `maxDelay` (5m default).
- *
- * ```ts
- * retryCount => Math.min(baseDelay * Math.pow(2, retryCount), maxDelay)
- * ```
- */
-export declare function defaultRetryDelay(retryCount: number, options?: {
-    baseDelay?: number;
-    maxDelay?: number;
-}): number;
-/**
- * @deprecated Use `getQueryKey` instead, unless using for non-parsable query keys.
- */
-export declare function getLegacyQueryKey<TParams extends Record<string, unknown>>(params: TParams): string;
+export declare function createQueryStore<TQueryFnData, TParams extends Record<string, unknown> = Record<string, never>, TData = TQueryFnData, PersistedState extends Partial<QueryStoreState<TData, TParams>> = Partial<QueryStoreState<TData, TParams>>, PersistReturn extends Promise<void> = Promise<void>>(config: QueryStoreConfig<TQueryFnData, TParams, TData>, options: BaseStoreOptions<QueryStoreState<TData, TParams>, PersistedState, PersistReturn> | undefined): OptionallyPersistedStore<QueryStoreState<TData, TParams>, PersistedState, PersistReturn>;
 /**
  * Generates a deterministic query store `queryKey` from the given parameters,
  * consistent with internally generated keys.

package/dist/createVirtualStore.d.ts

@@ -1,6 +1,6 @@
-import { DeriveGetter } from './createDerivedStore';
-import { BaseStore, InferPersistedState, InferSetStateReturn, InferStoreState, OptionallyPersistedStore } from './types';
-type MethodOverrides<Store extends BaseStore<State>, State = InferStoreState<Store>> = Partial<Pick<Store, 'getState' | 'setState'>>;
+import type { BaseStore, DeriveGetter, InferPersistedState, InferSetStateReturn, InferStoreState, OptionallyPersistedStore } from './types';
+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;
     /**
@@ -34,7 +34,7 @@ type VirtualStoreOptions = {
  * });
  * ```
  */
-export declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>>(createStore: ($: DeriveGetter) => Store, options?: VirtualStoreOptions): OptionallyPersistedStore<InferStoreState<Store>, InferPersistedState<Store, InferStoreState<Store>>, InferSetStateReturn<Store>>;
-export declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>, Overrides extends MethodOverrides<Store>>(createStore: ($: DeriveGetter) => Store, overrides: (getStore: () => Store) => Overrides, options?: VirtualStoreOptions): OptionallyPersistedStore<InferStoreState<Store>, InferPersistedState<Store, InferStoreState<Store>>, InferSetStateReturn<Store>> & Overrides;
+export declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>>(createStore: ($: DeriveGetter) => Store, options?: VirtualStoreOptions): VirtualStore<Store>;
+export declare function createVirtualStore<Store extends BaseStore<InferStoreState<Store>>, Overrides extends MethodOverrides<Store>>(createStore: ($: DeriveGetter) => Store, overrides: (getStore: () => Store) => Overrides, options?: VirtualStoreOptions): VirtualStore<Store> & Overrides;
 export {};
 //# sourceMappingURL=createVirtualStore.d.ts.map

package/dist/env.native.d.ts

@@ -1,9 +1,7 @@
-import { unstable_batchedUpdates } from 'react-native';
 export declare const IS_REACT_NATIVE = true;
 export declare const IS_BROWSER = false;
 export declare const IS_IOS: boolean;
 export declare const IS_ANDROID: boolean;
 export declare const IS_DEV: boolean;
 export declare const IS_TEST: boolean;
-export { unstable_batchedUpdates };
 //# sourceMappingURL=env.native.d.ts.map

package/dist/env.web.d.ts

@@ -4,5 +4,4 @@ export declare const IS_IOS = false;
 export declare const IS_ANDROID = false;
 export declare const IS_DEV: boolean;
 export declare const IS_TEST: boolean;
-export declare const unstable_batchedUpdates: <T>(callback: () => T) => T;
 //# sourceMappingURL=env.web.d.ts.map

package/dist/hooks/useListen.d.ts

@@ -61,7 +61,7 @@ export type UseListenOptions<Selected> = {
 /**
  * ### `useListen`
  *
- * Subscribes to a slice of a Zustand store and runs a callback whenever that slice changes,
+ * Subscribes to a slice of a store and runs a callback whenever that slice changes,
  * **without triggering re-renders**.
  *
  * Useful for forwarding updates to non-React state (e.g. Reanimated shared values), scoped side
@@ -75,7 +75,7 @@ export type UseListenOptions<Selected> = {
  * They take effect only if a resubscription occurs.
  *
  * ---
- * @param store - Zustand store to listen to. Should be a stable reference.
+ * @param store - Store to listen to. Should be a stable reference.
  * @param selector - Selects the slice of the store state to listen to.
  * @param react - Triggered when the selected slice changes. Receives `(current, previous, unsubscribe)`.
  * @param optionsOrEqualityFn - Optional `equalityFn`, `fireImmediately` settings, forwarded to `store.subscribe`.

package/dist/hooks/useSyncExternalStoreWithSelector.d.ts

@@ -0,0 +1,5 @@
+import type { EqualityFn, Selector, SubscribeOverloads } from '../types';
+export declare function useSyncExternalStoreWithSelector<State>(subscribe: SubscribeOverloads<State>, getSnapshot: () => State, getServerSnapshot?: (() => State) | undefined, selector?: undefined, equalityFn?: undefined): State;
+export declare function useSyncExternalStoreWithSelector<State, Selected>(subscribe: SubscribeOverloads<State>, getSnapshot: () => State, getServerSnapshot: (() => State) | undefined, selector: Selector<State, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
+export declare function useSyncExternalStoreWithSelector<State, Selected>(subscribe: SubscribeOverloads<State>, getSnapshot: () => State, getServerSnapshot: (() => State) | undefined, selector: Selector<State, Selected> | undefined, equalityFn?: EqualityFn<Selected>): State | Selected;
+//# sourceMappingURL=useSyncExternalStoreWithSelector.d.ts.map

package/dist/index.d.ts

@@ -1,17 +1,4 @@
-export { configureStores } from './config';
-export { createBaseStore } from './createBaseStore';
-export * from './createDerivedStore';
-export * from './createQueryStore';
-export * from './createVirtualStore';
-export { replacer, reviver } from './utils/serialization';
-export { applyStateUpdate, destroyStore, destroyStores, getStoreName, isDerivedStore, isPersistedStore, isQueryStore, isVirtualStore, } from './utils/storeUtils';
+export * from './index.shared';
 export * from './hooks/useListen';
 export * from './hooks/useStableValue';
-export * from './sync/types';
-export * from './queryStore/types';
-export * from './storage/storageTypes';
-export * from './types';
-export * from './utils/createStoreActions';
-export { deepEqual, shallowEqual } from './utils/equality';
-export { time } from './utils/time';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.shared.d.ts

@@ -0,0 +1,14 @@
+export * from './createBaseStore';
+export * from './createDerivedStore';
+export * from './createQueryStore';
+export * from './createVirtualStore';
+export { configureStores, StoresError } from './internal/runtime';
+export { applyStateUpdate, replacer, reviver } from './internal/runtime';
+export { destroyStore, destroyStores, getStoreName, hasGetSnapshot, isDerivedStore, isPersistedStore, isQueryStore, isVirtualStore, } from './internal/runtime';
+export type * from './sync/types';
+export { QueryStatuses } from './internal/runtime';
+export type * from './queryStore/types';
+export type * from './storage/storageTypes';
+export type * from './types';
+export { createStoreActions, deepEqual, identity, nullObject, shallowEqual, time } from './internal/runtime';
+//# sourceMappingURL=index.shared.d.ts.map

package/dist/index.vanilla.d.ts

@@ -0,0 +1,2 @@
+export * from './index.shared';
+//# sourceMappingURL=index.vanilla.d.ts.map

package/dist/internal/baseStore.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=baseStore.d.ts.map

package/dist/internal/config.d.ts

@@ -0,0 +1,64 @@
+import { QueryStoreConfig } from '../queryStore/types';
+import { SyncEngine } from '../sync/types';
+import { AsyncStorageInterface, SyncStorageInterface } from '../types';
+import { NonFunction } from '../types/functions';
+import { Prettify } from '../types/objects';
+import { Logger } from './logger';
+/**
+ * Global configuration for all stores.
+ */
+export 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;
+};
+export type QueryStoreDefaults = Prettify<ConfigDefaults<QueryStoreConfig<unknown, Record<string, unknown>>, 'disableCache' | 'enabled' | 'params', '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:',
+ * });
+ * ```
+ */
+export declare function configureStores(config: Partial<StoresConfig>): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/{utils → internal}/createStoreActions.d.ts

@@ -1,8 +1,7 @@
-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>>>;
+import type { StoreApi } from '../store/types';
+import type { InferStoreState, StoreActions } from '../types';
+import type { FunctionRecord } from '../types/functions';
+import type { NoOverlap } from '../types/objects';
 /**
  * Given a store instance, produces a new object containing only its actions.
  *
@@ -21,5 +20,5 @@ export type StoreActions<Store extends StoreApi<unknown>> = Pick<InferStoreState
  * 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;
+export declare function createStoreActions<Store extends StoreApi<unknown>, Bundled extends FunctionRecord>(store: Store, bundledMethods: NoOverlap<InferStoreState<Store>, Bundled>): StoreActions<Store> & Bundled;
 //# sourceMappingURL=createStoreActions.d.ts.map

package/dist/internal/derivedStore/cascadeScheduler.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cascade Scheduler
+ *
+ * - Coalesces derivations into a single microtask.
+ * - Tasks run once at their maximum rank via a ranked dirty queue.
+ * - Doesn't retain snapshots or dependency graphs.
+ * - Component listeners get notified after all derivations have settled.
+ */
+type Rank = number;
+type StoreId = string;
+type Task = () => void;
+export declare function isCascadeActive(): boolean;
+/**
+ * Rank of the currently running derive batch, or null if not in a batch.
+ */
+export declare function getCurrentDeriveRank(): Rank | null;
+/**
+ * Arms the cascade and schedules a single microtask flush.
+ */
+export declare function activateCascade(): void;
+/**
+ * Enlist one per-store component flush (idempotent per store).
+ */
+export declare function joinCascade(storeId: StoreId, task: Task): void;
+/**
+ * Enqueue (or upgrade) a derive task with the given rank.
+ * If the task is already present, we keep the maximum rank (run later).
+ */
+export declare function enqueueDerive(task: Task, rank: Rank): void;
+export {};
+//# sourceMappingURL=cascadeScheduler.d.ts.map

package/dist/internal/derivedStore/deriveProxy.d.ts

@@ -0,0 +1,15 @@
+import { BaseStore } from '../../types';
+import { TrackPathFn } from './pathFinder';
+/**
+ * Gets or creates a lightweight tracking proxy that records path access and store
+ * method invocations via proxy traps. Used to auto-generate selectors that point
+ * to either the accessed path or the value returned by an invoked store method.
+ */
+export declare function getOrCreateProxy<S>(store: BaseStore<S>, rootProxyCache: WeakMap<object, unknown>, trackPath: TrackPathFn): S;
+/**
+ * Strips tracking proxies from published values to ensure
+ * proxies remain confined to internal tracking contexts.
+ */
+export declare function stripProxies<T>(value: T): T;
+export declare function stripProxies(value: unknown, seen?: WeakSet<object>): unknown;
+//# sourceMappingURL=deriveProxy.d.ts.map

package/dist/internal/derivedStore/pathFinder.d.ts

@@ -0,0 +1,26 @@
+import { Selector, SubscribableStore } from '../../types';
+type TrackedInvocation = {
+    args: unknown[] | undefined;
+};
+type PathEntry = {
+    path: string[];
+    store: SubscribableStore;
+    invocation?: TrackedInvocation;
+    isLeaf: boolean;
+};
+type SubscriptionBuilder = (store: SubscribableStore, selector: Selector<unknown, unknown>, path: string[]) => void;
+export type PathFinder = {
+    buildProxySubscriptions(createSubscription: SubscriptionBuilder, shouldLog: boolean, minConsolidationDepth?: number, shouldBuild?: (paths: Set<PathEntry>) => boolean): void;
+    reset(): void;
+    trackPath: TrackPathFn;
+};
+export type TrackPathFn = (store: SubscribableStore, path: string[], isLeaf: boolean, invocation?: TrackedInvocation) => void;
+/**
+ * A factory that returns a proxy path-tracking object with three methods:
+ *  - `buildProxySubscriptions()`: builds subscriptions to the final paths
+ *  - `reset()`: clears all tracked paths
+ *  - `trackPath()`: records usage of a store path
+ */
+export declare function createPathFinder(): PathFinder;
+export {};
+//# sourceMappingURL=pathFinder.d.ts.map

package/dist/internal/derivedStore.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=derivedStore.d.ts.map

package/dist/internal/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error reported or thrown by the stores package itself.
+ *
+ * If an underlying thrown value caused the failure, it is available as `cause`.
+ */
+export declare class StoresError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/{logger.d.ts → internal/logger.d.ts}

@@ -1,7 +1,3 @@
-export declare class StoresError extends Error {
-    cause: Error;
-    constructor(message: string, error?: unknown);
-}
 export interface Logger {
     debug: (message: string, context?: Record<string, unknown>) => void;
     error: {
@@ -11,7 +7,4 @@ export interface Logger {
     info: (message: string, context?: Record<string, unknown>) => void;
     warn: (message: string, context?: Record<string, unknown>) => void;
 }
-export declare let logger: Logger;
-export declare function ensureError(error: unknown): Error;
-export declare function setLogger(customLogger: Logger): void;
 //# sourceMappingURL=logger.d.ts.map