@storesjs/stores 0.9.0 → 0.10.0

package/dist/store/createStore.d.ts

@@ -0,0 +1,6 @@
+import type { Mutate, StateCreator, StoreApi, StoreMutators } from './types';
+/**
+ * Creates the internal core store API.
+ */
+export declare function createStore<State, Mutators extends StoreMutators = []>(createState: StateCreator<State, [], Mutators>): Mutate<StoreApi<State>, Mutators>;
+//# sourceMappingURL=createStore.d.ts.map

package/dist/store/persist.d.ts

@@ -0,0 +1,14 @@
+import type { PersistOptions, StateCreator, StoreMutators } from './types';
+type PersistMutators<PersistedState, PersistReturn, Mutators extends StoreMutators> = [
+    [
+        'stores/persist',
+        [PersistedState, PersistReturn]
+    ],
+    ...Mutators
+];
+/**
+ * Wraps a state creator with persistence.
+ */
+export declare function persist<State, PersistedState extends Partial<State>, PersistReturn extends void | Promise<void> = void, Mutators extends StoreMutators = []>(createState: StateCreator<State, [], Mutators>, initialOptions: PersistOptions<State, PersistedState>): StateCreator<State, [], PersistMutators<PersistedState, PersistReturn, Mutators>>;
+export {};
+//# sourceMappingURL=persist.d.ts.map

package/dist/store/stateUpdate.d.ts

@@ -0,0 +1,10 @@
+import type { SetStateArgs, SetStateOverloads } from '../types';
+/**
+ * Calls a `setState` function with captured `setState` arguments.
+ */
+export declare function applySetState<S, SetReturn extends Promise<void> | void>(set: SetStateOverloads<S, SetReturn>, args: SetStateArgs<S>): SetReturn;
+/**
+ * Applies a `setState` payload to the current state.
+ */
+export declare function applyStateUpdate<S>(state: S, ...setArgs: SetStateArgs<S>): S;
+//# sourceMappingURL=stateUpdate.d.ts.map

package/dist/store/types.d.ts

@@ -0,0 +1,108 @@
+import type { StorageValue } from '../storage/storageTypes';
+import type { SetStateOverloads } from '../types/setState';
+import type { SubscribeOverloads } from '../types/subscribe';
+/**
+ * Store object contract shared by creators, middleware, and internal store utilities.
+ */
+export 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.
+ */
+export type StateCreator<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.
+ */
+export 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.
+ */
+export 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.
+ */
+export type PersistStorage<State, PersistedState = Partial<State>> = AsyncPersistStorage<State, PersistedState> | SyncPersistStorage<State, PersistedState>;
+/**
+ * Resolved storage config for persisted stores.
+ */
+export type PersistStorageConfig<State, PersistedState extends Partial<State>> = {
+    async: false;
+    persistStorage: SyncPersistStorage<State, PersistedState>;
+    version: number;
+} | {
+    async: true;
+    persistStorage: AsyncPersistStorage<State, PersistedState>;
+    version: number;
+};
+/**
+ * Persistence options consumed by the persistence wrapper.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface StoreMutatorMap<Store, Args> {
+    'stores/persist': PersistMutator<Store, Args>;
+}
+/**
+ * Ordered list of store mutators applied to a state creator.
+ */
+export type StoreMutators = [StoreMutatorIdentifier, unknown][];
+/**
+ * Applies a list of store mutators to a store API type.
+ */
+export 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;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types/setState.d.ts

@@ -0,0 +1,22 @@
+import type { BivariantMethod } from './functions';
+export type SetPartial<S> = S | Partial<S> | BivariantMethod<{
+    updater(state: S): S | Partial<S>;
+}>;
+export type SetFull<S> = S | BivariantMethod<{
+    updater(state: S): S;
+}>;
+export type SetStateReplaceArgs<S, ExtraArgs extends unknown[] = []> = [update: SetFull<S>, replace: true, ...extraArgs: ExtraArgs];
+export type SetStatePartialArgs<S, ExtraArgs extends unknown[] = []> = [update: SetPartial<S>, replace?: false, ...extraArgs: ExtraArgs];
+export type SetStateArgs<S, ExtraArgs extends unknown[] = []> = SetStatePartialArgs<S, ExtraArgs> | SetStateReplaceArgs<S, ExtraArgs>;
+/**
+ * Rest-argument form of `setState`, used when forwarding calls.
+ */
+export 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.
+ */
+export type SetStateOverloads<S, PersistReturn extends Promise<void> | void = void> = BivariantMethod<{
+    setState(update: SetPartial<S>, replace?: false): PersistReturn;
+    setState(update: SetFull<S>, replace: true): PersistReturn;
+}>;
+//# sourceMappingURL=setState.d.ts.map

package/dist/types/subscribe.d.ts

@@ -0,0 +1,28 @@
+export type Listener<S> = (state: S, prevState: S) => void;
+export type Selector<S, Selected> = (state: S) => Selected;
+export type EqualityFn<T = unknown> = (a: T, b: T) => boolean;
+/**
+ * Minimum store API required for subscription.
+ */
+export type SubscribableStore = {
+    subscribe(selector: Selector<unknown, unknown>, listener: () => void, options?: SubscribeOptions<unknown>): UnsubscribeFn;
+};
+export type SubscribeOptions<Selected> = {
+    equalityFn?: EqualityFn<Selected>;
+    fireImmediately?: boolean;
+    isDerivedStore?: boolean;
+};
+export type ListenerArgs<S> = [listener: Listener<S>];
+export type SelectorArgs<S, Selected> = [
+    selector: Selector<S, Selected>,
+    listener: Listener<Selected>,
+    options?: SubscribeOptions<Selected>
+];
+export type SubscribeArgs<S, Selected = unknown> = ListenerArgs<S> | SelectorArgs<S, Selected>;
+export type UnsubscribeFn<Options extends boolean = false> = Options extends true ? (skipAbortFetch?: boolean) => void : () => void;
+export type SubscribeFn<S, Selected = S> = (...args: SubscribeArgs<S, Selected>) => UnsubscribeFn;
+export type SubscribeOverloads<S, ExtraOptions extends boolean = false> = {
+    (listener: Listener<S>): UnsubscribeFn<ExtraOptions>;
+    <Selected>(selector: Selector<S, Selected>, listener: Listener<Selected>, options?: SubscribeOptions<Selected>): UnsubscribeFn<ExtraOptions>;
+};
+//# sourceMappingURL=subscribe.d.ts.map

package/dist/types/useStoreCallSignatures.d.ts

@@ -0,0 +1,2 @@
+export type { UseStoreCallSignatures } from './useStoreCallSignatures.react';
+//# sourceMappingURL=useStoreCallSignatures.d.ts.map

package/dist/types/useStoreCallSignatures.react.d.ts

@@ -0,0 +1,6 @@
+import type { EqualityFn, Selector } from './subscribe';
+export type UseStoreCallSignatures<State> = {
+    (): State;
+    <Selected>(selector: Selector<State, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
+};
+//# sourceMappingURL=useStoreCallSignatures.react.d.ts.map

package/dist/types/useStoreCallSignatures.vanilla.d.ts

@@ -0,0 +1,2 @@
+export type UseStoreCallSignatures<_> = Record<never, never>;
+//# sourceMappingURL=useStoreCallSignatures.vanilla.d.ts.map

package/dist/types/utils.d.ts

@@ -6,4 +6,8 @@ export declare function hasOwn<T extends Record<string, unknown>, K extends stri
  * Checks prototype is `Object.prototype` or `null`. Excludes arrays, class instances, etc.
  */
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Checks for non-null, non-array objects.
+ */
+export declare function isRecordLike(value: unknown): value is Record<string, unknown>;
 //# sourceMappingURL=utils.d.ts.map

package/dist/types.d.ts

@@ -1,59 +1,42 @@
-import type { Mutate, StateCreator as ZustandStateCreator, StoreApi, StoreMutatorIdentifier } from 'zustand';
-import type { PersistOptions } from 'zustand/middleware';
 import type { StorageValue } from './storage/storageTypes';
+import type { PersistOptions, StateCreator as StoreStateCreator, StoreApi, StoreMutators, WithPersist } from './store/types';
 import type { SyncConfig } from './sync/types';
-type SubscribeWithSelector = ['zustand/subscribeWithSelector', never];
-export type StoreMutators = [StoreMutatorIdentifier, unknown][];
-export type StoreMutatorsWithSelector<Mutators extends StoreMutators = StoreMutators> = [SubscribeWithSelector, ...Mutators];
-type HydrationPromise<PersistReturn> = PersistReturn extends Promise<void> ? {
-    /** Invoke to get a promise that resolves once hydration completes. */
-    hydrationPromise: () => Promise<void>;
-} : {
-    hydrationPromise?: undefined;
-};
-type WithPersist<Store, PersistedState, PersistReturn> = Store extends {
-    getState: () => infer S;
-    setState: {
-        (...args: infer SetPartialArgs): infer _;
-        (...args: infer SetFullArgs): infer _;
-    };
-} ? {
-    setState(...args: SetPartialArgs): PersistReturn;
-    setState(...args: SetFullArgs): PersistReturn;
-    persist: {
-        clearStorage: () => void;
-        getOptions: () => Partial<PersistOptions<S, PersistedState>>;
-        hasHydrated: () => boolean;
-        onHydrate: (listener: (state: S) => void) => () => void;
-        onFinishHydration: (listener: (state: S) => void) => () => void;
-        rehydrate: () => Promise<void> | void;
-        setOptions: (options: Partial<PersistOptions<S, PersistedState, PersistReturn>>) => void;
-    } & HydrationPromise<PersistReturn>;
-} : never;
-export type StateCreator<S, U = S> = ZustandStateCreator<S, [SubscribeWithSelector], [SubscribeWithSelector], U>;
-export type UseBoundStoreWithEqualityFn<Store extends StoreApi<unknown>, State = InferStoreState<Store>> = UseStoreCallSignatures<State> & Store;
-export type BaseStore<S, ExtraSubscribeOptions extends boolean = false> = UseBoundStoreWithEqualityFn<Mutate<StoreApi<S>, [SubscribeWithSelector]>> & {
+import type { FunctionKeys } from './types/functions';
+import type { SetFull, SetPartial, SetStateArgs } from './types/setState';
+import type { EqualityFn, Selector, SubscribeOverloads } from './types/subscribe';
+import type { UseStoreCallSignatures } from './types/useStoreCallSignatures';
+export type { StoreMutators } from './store/types';
+export type * from './types/setState';
+export type * from './types/subscribe';
+export type * from './types/useStoreCallSignatures';
+export type StoreMutatorsWithSelector<Mutators extends StoreMutators = StoreMutators> = Mutators;
+export type StateCreator<S, U = S> = StoreStateCreator<S, [], [], U>;
+export type UseBoundStoreWithEqualityFn<Store extends {
+    getState: () => unknown;
+}, State = InferStoreState<Store>> = UseStoreCallSignatures<State> & Store;
+export type BaseStore<S, ExtraSubscribeOptions extends boolean = false> = UseBoundStoreWithEqualityFn<StoreApi<S>> & {
     subscribe: SubscribeOverloads<S, ExtraSubscribeOptions>;
 };
-export type PersistedStore<S, PersistedState = Partial<S>, PersistReturn = unknown, ExtraSubscribeOptions extends boolean = false> = UseStoreCallSignatures<S> & Omit<BaseStore<S, ExtraSubscribeOptions>, 'setState' | 'persist'> & WithPersist<BaseStore<S, ExtraSubscribeOptions>, PersistedState, PersistReturn>;
-export type Store<S, PersistedState extends Partial<S> = never, PersistReturn = unknown, ExtraSubscribeOptions extends boolean = false> = [
-    PersistedState
-] extends [never] ? BaseStore<S, ExtraSubscribeOptions> : PersistedStore<S, PersistedState, PersistReturn, ExtraSubscribeOptions>;
-export type OptionallyPersistedStore<S, PersistedState, PersistReturn = void> = WithAsyncSet<Store<S>, S, PersistedState, PersistReturn> & UseStoreCallSignatures<S> & {
+export type PersistedStore<S, PersistedState = Partial<S>, PersistReturn extends void | Promise<void> = void | Promise<void>, ExtraSubscribeOptions extends boolean = false> = UseStoreCallSignatures<S> & WithPersist<BaseStore<S, ExtraSubscribeOptions>, PersistedState, PersistReturn>;
+export type Store<S, PersistedState extends Partial<S> = never, PersistReturn extends void | Promise<void> = void | Promise<void>, ExtraSubscribeOptions extends boolean = false> = [PersistedState] extends [never] ? BaseStore<S, ExtraSubscribeOptions> : PersistedStore<S, PersistedState, PersistReturn, ExtraSubscribeOptions>;
+/**
+ * Store returned by creators that accept optional persistence options.
+ * `persist` exists only when persistence is configured.
+ */
+export type OptionallyPersistedStore<S, PersistedState, PersistReturn extends void | Promise<void> = void> = UseStoreCallSignatures<S> & Omit<BaseStore<S>, 'setState'> & {
     persist?: PersistedStore<S, PersistedState, PersistReturn, false>['persist'];
+    setState(update: SetPartial<S>, replace?: false): PersistReturn;
+    setState(update: SetFull<S>, replace: true): PersistReturn;
 };
 export type NoInfer<T> = [T][T extends unknown ? 0 : never];
 export type Timeout = ReturnType<typeof setTimeout>;
-export type Listener<S> = (state: S, prevState: S) => void;
-export type Selector<S, Selected> = (state: S) => Selected;
-export type EqualityFn<T = unknown> = (a: T, b: T) => boolean;
-export type UseStoreCallSignatures<S> = {
-    (): S;
-    <Selected>(selector: Selector<S, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
-};
-export type InferStoreState<Store extends StoreApi<unknown>> = Store extends {
+export type InferStoreState<Store> = Store extends {
     getState: () => infer T;
 } ? T : never;
+/**
+ * Action methods returned by `createStoreActions(store)`.
+ */
+export 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.
@@ -67,45 +50,15 @@ export type InferSetStateReturn<Store> = Store extends {
  * Returns `never` if the store doesn't use persistence.
  */
 export type InferPersistedState<PersistedStore> = PersistedStore extends Store<infer _, infer PersistedState> ? PersistedState : never;
-export type SetPartial<S> = Partial<S> | ((state: S) => Partial<S>);
-export type SetFull<S> = S | ((state: S) => S);
-export type SetStateReplaceArgs<S, ExtraArgs extends unknown[] = []> = [update: SetFull<S>, replace: true, ...extraArgs: ExtraArgs];
-export type SetStatePartialArgs<S, ExtraArgs extends unknown[] = []> = [update: SetPartial<S>, replace?: false, ...extraArgs: ExtraArgs];
-export type SetStateArgs<S, ExtraArgs extends unknown[] = []> = SetStatePartialArgs<S, ExtraArgs> | SetStateReplaceArgs<S, ExtraArgs>;
-export type SetState<S, ExtraArgs extends unknown[] = [], PersistReturn extends Promise<void> | void = void> = (...args: SetStateArgs<S, ExtraArgs>) => PersistReturn;
-export type SetStateOverloads<S, PersistReturn extends Promise<void> | void = void> = {
-    (update: SetPartial<S>, replace?: false): PersistReturn;
-    (update: SetFull<S>, replace: true): PersistReturn;
-};
-export type WithAsyncSet<Store extends StoreApi<unknown>, S, PersistedState, PersistReturn> = Omit<Store, 'persist' | 'setState'> & {
-    persist?: PersistedStore<S, PersistedState, PersistReturn, false>['persist'];
-    setState(update: SetPartial<InferStoreState<Store>>, replace?: false): PersistReturn;
-    setState(update: SetFull<InferStoreState<Store>>, replace: true): PersistReturn;
-};
 /**
- * Minimum store API required for subscription.
+ * Reads store state and records the dependencies of a derived computation.
+ *  - `$(store, selector, equalityFn?)` depends on the selected state
+ *  - `$(store)` depends on accessed state paths
  */
-export type SubscribableStore = {
-    subscribe(selector: Selector<unknown, unknown>, listener: () => void, options?: SubscribeOptions<unknown>): UnsubscribeFn;
+export type DeriveGetter = {
+    <S extends Store<InferStoreState<S>>>(store: S): InferStoreState<S>;
+    <S extends Store<InferStoreState<S>>, Selected>(store: S, selector: Selector<InferStoreState<S>, Selected>, equalityFn?: EqualityFn<Selected>): Selected;
 };
-export type SubscribeOptions<Selected> = {
-    equalityFn?: EqualityFn<Selected>;
-    fireImmediately?: boolean;
-    isDerivedStore?: boolean;
-};
-export type ListenerArgs<S> = [listener: Listener<S>];
-export type SelectorArgs<S, Selected> = [
-    selector: Selector<S, Selected>,
-    listener: Listener<Selected>,
-    options?: SubscribeOptions<Selected>
-];
-export type SubscribeOverloads<S, ExtraOptions extends boolean = false> = {
-    (listener: Listener<S>): UnsubscribeFn<ExtraOptions>;
-    <Selected>(selector: Selector<S, Selected>, listener: Listener<Selected>, options?: SubscribeOptions<Selected>): UnsubscribeFn<ExtraOptions>;
-};
-export type SubscribeArgs<S, Selected = unknown> = ListenerArgs<S> | SelectorArgs<S, Selected>;
-export type UnsubscribeFn<Options extends boolean = false> = Options extends true ? (skipAbortFetch?: boolean) => void : () => void;
-export type SubscribeFn<S, Selected = S> = (...args: SubscribeArgs<S, Selected>) => UnsubscribeFn;
 export type DerivedStore<S> = WithFlushUpdates<ReadOnlyDerivedStore<BaseStore<S>>>;
 export type WithFlushUpdates<Store extends StoreApi<unknown>> = Store & {
     /**
@@ -123,8 +76,7 @@ export type WithFlushUpdates<Store extends StoreApi<unknown>> = Store & {
 };
 export type WithGetSnapshot<Store extends StoreApi<unknown>> = Store & {
     /**
-     * Provided to `useSyncExternalStoreWithSelector` to ensure it activates the derived
-     * store when it gets the initial state before subscribing to the store.
+     * Reads the current snapshot while activating lazy derived stores before subscription.
      */
     getSnapshot: () => InferStoreState<Store>;
 };
@@ -199,7 +151,7 @@ export type Serializer<SerializedState> = <PersistedState>(storageValue: Storage
  * Synchronous storage interface.
  * Used for localStorage and MMKV implementations.
  */
-export interface SyncStorageInterface<SerializedState = unknown> {
+export type SyncStorageInterface<SerializedState = unknown> = {
     readonly async?: false;
     /**
      * Adapter-level deserializer used when a store does not supply its own.
@@ -217,7 +169,7 @@ export interface SyncStorageInterface<SerializedState = unknown> {
     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.
@@ -244,7 +196,7 @@ export type AsyncStorageInterface<SerializedState = unknown> = {
 /**
  * Configuration options for creating a persistable store.
  */
-export type PersistConfig<S, PersistedState = Partial<S>, PersistReturn = void> = {
+export 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.
@@ -252,7 +204,7 @@ export type PersistConfig<S, PersistedState = Partial<S>, PersistReturn = void>
     deserializer?: (serializedState: unknown) => StorageValue<PersistedState>;
     /**
      * A function to merge persisted state with current state during hydration.
-     * By default, zustand does a shallow merge, but this allows custom logic for deep merging nested objects.
+     * By default, persisted state is shallow-merged into the current state.
      */
     merge?: PersistOptions<S, PersistedState>['merge'];
     /**
@@ -270,7 +222,7 @@ export type PersistConfig<S, PersistedState = Partial<S>, PersistReturn = void>
      * A function that determines which parts of the state should be persisted.
      * By default, the entire state is persisted.
      */
-    partialize?: (state: S) => PersistedState;
+    partialize?: (state: Readonly<S>) => PersistedState;
     /**
      * The throttle rate for the persist operation in milliseconds.
      * @default iOS: time.seconds(3) | Android: time.seconds(5)
@@ -300,7 +252,7 @@ export type PersistConfig<S, PersistedState = Partial<S>, PersistReturn = void>
 export type EnforceStorageKey<Options> = {
     storageKey: string;
 } extends Options ? Options : never;
-export type BaseStoreOptions<S, PersistedState = Partial<S>, PersistReturn = void> = (PersistConfig<S, PersistedState, PersistReturn> & {
+export 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;
@@ -315,12 +267,11 @@ export type SyncOption<S extends Record<string, unknown>> = SyncConfig<S> | stri
 type SyncWithoutStorageOption<S extends Record<string, unknown>> = string | (Omit<SyncConfig<S>, 'injectStorageMetadata' | 'key'> & {
     injectStorageMetadata?: never;
     key: SyncWithoutStorageKey<SyncConfig<S>>;
-    readonly __syncStateBrand?: (state: S) => S;
 });
 type SyncWithoutStorageKey<Config> = Config extends {
     key?: infer Key;
 } ? Extract<Key, string> extends never ? string : Extract<Key, string> : string;
-type UndefinedPersistKeys<S, PersistedState, PersistReturn> = {
+type UndefinedPersistKeys<S, PersistedState extends Partial<S>, PersistReturn> = {
     [K in keyof PersistConfig<S, PersistedState, PersistReturn>]?: undefined;
 };
 /**
@@ -332,5 +283,4 @@ export type DebounceOptions = {
     maxWait?: number;
     trailing?: boolean;
 };
-export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/utils/time.d.ts

@@ -33,12 +33,5 @@ type TimeUtils = {
  * time.zero // 0
  */
 export declare const time: TimeUtils;
-/**
- * Waits for microtasks to complete.
- * Uses setTimeout(0) to allow microtasks scheduled via queueMicrotask to execute.
- *
- * Useful in tests when waiting for async operations scheduled via microtasks.
- */
-export declare function waitForMicrotask(): Promise<void>;
 export {};
 //# sourceMappingURL=time.d.ts.map

package/dist/vanilla/createBaseStore.d.ts

@@ -0,0 +1,35 @@
+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 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 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 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 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 store with the specified state and optional persistence.
+ */
+export declare function createBaseStore<S, PersistedState extends Partial<S> = Partial<S>, PersistReturn extends Promise<void> = Promise<void>>(createState: StateCreator<S>, options?: BaseStoreOptions<S, PersistedState, PersistReturn>): OptionallyPersistedStore<S, PersistedState, PersistReturn>;

package/dist/vanilla/createDerivedStore.d.ts

@@ -0,0 +1,62 @@
+import type { DeriveGetter, DeriveOptions, DerivedStore } from './types';
+/**
+ * ### `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.
+ */
+export declare function createDerivedStore<Derived>(deriveFunction: ($: DeriveGetter) => Derived, optionsOrEqualityFn?: DeriveOptions<Derived>): DerivedStore<Derived>;