@storesjs/stores 0.8.7 → 0.10.0

package/dist/sync/types.d.ts

@@ -1,4 +1,4 @@
-type UnknownFunction = (...args: unknown[]) => unknown;
+import { UnknownFunction } from '../types/functions';
 /**
  * Metadata for a field's last write.
  */
@@ -9,147 +9,86 @@ export type SyncStateKey<T extends Record<string, unknown>> = Extract<{
 export type SyncValues<T extends Record<string, unknown>> = Partial<T> & {
     [K in SyncStateKey<T>]?: T[K];
 };
-export type RecordDeltaPayload<TValue = unknown> = {
-    readonly clear?: true;
-    readonly del?: readonly string[];
-    readonly set?: Record<string, TValue>;
-    readonly patch?: Record<string, RecordDeltaPayload>;
-};
-export type SyncDeltaPayload<TValue = unknown> = {
-    readonly kind: 'record';
-} & RecordDeltaPayload<TValue>;
-export type SyncDeltaDescriptor = {
-    /**
-     * Minimum fraction of the full payload the delta must save (0–1).
-     */
-    readonly minSavingsRatio?: number;
-    /**
-     * Minimum number of bytes the delta must save compared to sending the full payload.
-     */
-    readonly minSavingsBytes?: number;
-};
-/**
- * Per-field delta configuration. Use `true` to enable with defaults, or provide thresholds.
- */
-export type SyncDeltaConfig<T extends Record<string, unknown>> = Partial<Record<SyncStateKey<T>, SyncDeltaDescriptor | true>>;
-export type SyncDeltaMap<T extends Record<string, unknown>> = Partial<Record<SyncStateKey<T>, SyncDeltaPayload<T[SyncStateKey<T>]>>>;
 export type SyncUpdate<T extends Record<string, unknown>> = {
-    deltas?: SyncDeltaMap<T>;
     replace: boolean;
     sessionId: string;
     timestamp: number;
     values: SyncValues<T>;
 };
+/**
+ * Passed to `SyncEngine.register()` to connect a store to the sync system.
+ */
 export 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;
-    delta?: SyncDeltaConfig<T>;
 };
+/**
+ * Returned by `SyncEngine.register()`. Controls the lifecycle of a synced store.
+ */
 export 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.
+ */
 export interface SyncEngine {
-    register<T extends Record<string, unknown>>(registration: SyncRegistration<T>): SyncHandle<T>;
-    registerPresence?<Presence>(registration: SyncPresenceRegistration<Presence>): SyncPresenceChannel<Presence> | null;
     /**
-     * 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`).
+     * 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;
 }
 export type SyncMergeFn<T, TState = unknown> = (incoming: T, current: T, currentState: TState, incomingValues: Partial<TState>) => T;
-export type SyncPresenceJoinHandler<Presence> = (userId: string, data: Presence) => void;
-export type SyncPresenceUpdateHandler<Presence> = (userId: string, data: Presence) => void;
-export type SyncPresenceLeaveHandler = (userId: string) => void;
-export type PresencePruneStrategy = 'updates' | 'activity';
-type PresenceActivityField<Presence> = Presence extends Record<string, unknown> ? Extract<keyof Presence, string> : string;
-export type SyncPresenceHeartbeatConfig<Presence> = {
-    /** Interval in milliseconds between heartbeat broadcasts */
-    interval: number;
-    /** Reuse the last presence payload for each heartbeat (default). */
-    behavior?: 'reuse' | undefined;
-} | {
-    /** Interval in milliseconds between heartbeat broadcasts */
-    interval: number;
-    /** Clone the payload and refresh an activity field on every heartbeat. */
-    behavior: 'refresh-activity';
-    /**
-     * Field from the presence payload to refresh. Defaults to the prune strategy's activity field or `timestamp`.
-     */
-    activityField?: PresenceActivityField<Presence>;
-} | {
-    /** Interval in milliseconds between heartbeat broadcasts */
-    interval: number;
-    /** Derive a custom payload for each heartbeat. */
-    behavior: 'transform';
-    /**
-     * Transform invoked before each heartbeat. Return a payload to broadcast, or void to reuse the current data.
-     */
-    onHeartbeat: (currentData: Presence) => Presence | void;
-};
-export type SyncPresenceRegistration<Presence> = {
-    key: string;
-    /**
-     * Optional heartbeat configuration. When enabled, presence data is re-broadcast at the
-     * specified interval. Use `'reuse'` (default) to emit the last payload unchanged, `'refresh-activity'`
-     * to automatically update a timestamp-like field on object payloads, or `'transform'` to derive a custom payload.
-     */
-    heartbeat?: SyncPresenceHeartbeatConfig<Presence>;
-    /**
-     * Optional stale presence pruning. When enabled, remote presence entries that
-     * haven't been updated within the specified threshold are automatically removed.
-     */
-    pruneStale?: {
-        /**
-         * Determines how staleness is evaluated.
-         * - `updates` (default) considers the time since the last presence message arrived.
-         * - `activity` considers a timestamp field within the presence payload (defaults to `timestamp`).
-         */
-        basedOn?: PresencePruneStrategy;
-        /**
-         * Field from the presence payload to inspect when `basedOn` is set to `activity`.
-         * Defaults to `timestamp`.
-         */
-        activityField?: PresenceActivityField<Presence>;
-        /** Time in milliseconds after which presence is considered stale */
-        after: number;
-        /** Optional callback invoked before removing stale presence */
-        onPrune?: (userId: string, data: Presence) => void;
-    };
-    onJoin?: SyncPresenceJoinHandler<Presence>;
-    onLeave?: SyncPresenceLeaveHandler;
-    onUpdate?: SyncPresenceUpdateHandler<Presence>;
-};
-export interface SyncPresenceChannel<Presence> {
-    join(userId: string, data: Presence): void;
-    leave(): void;
-    update(data: Presence): void;
-    /**
-     * Destroys the presence channel and cleans up all resources.
-     * Automatically calls leave() and clears all timers.
-     * Safe to call multiple times.
-     */
-    destroy(): void;
-}
 export type SyncConfig<T extends Record<string, unknown>> = {
-    engine?: SyncEngine;
-    fields?: ReadonlyArray<SyncStateKey<T>>;
     /**
-     * The delta configuration for the sync engine.
+     * The sync engine implementation to use.
      *
-     * Only takes effect when used with delta-enabled engines like `NetworkSyncEngine`.
-     * @default undefined
+     * Defaults to cross-tab sync in browser environments. No-op in other environments unless a
+     * custom engine is provided.
      */
-    delta?: SyncDeltaConfig<T>;
+    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.
@@ -160,7 +99,9 @@ export type SyncConfig<T extends Record<string, unknown>> = {
      * @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>;
     };
@@ -171,20 +112,4 @@ export type SyncConfig<T extends Record<string, unknown>> = {
 export type NormalizedSyncConfig<T extends Record<string, unknown>> = SyncConfig<T> & {
     key: string;
 };
-export type SyncAuthPhase = 'connect' | 'refresh' | 'challenge';
-export type SyncAuthPayload = {
-    readonly headers?: Record<string, string>;
-    readonly query?: Record<string, string>;
-    readonly token?: string;
-};
-export type SyncAuthFailure = {
-    readonly code: string;
-    readonly message?: string;
-    readonly retryable: boolean;
-};
-export type SyncAuthenticator = {
-    readonly getPayload: (phase: SyncAuthPhase) => Promise<SyncAuthPayload | null> | SyncAuthPayload | null;
-    readonly onFailure?: (failure: SyncAuthFailure) => void;
-};
-export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types/functions.d.ts

@@ -1,7 +1,24 @@
-/** Extract the keys of T whose values are functions. */
+/**
+ * Relaxes function parameter variance to allow subtype
+ * assignment otherwise blocked by strict contravariance.
+ */
+export type BivariantMethod<T extends Record<string, UnknownFunction>> = T[keyof T];
+/**
+ * Extract the keys of `T` whose values are functions.
+ */
 export type FunctionKeys<T> = {
     [K in keyof T]-?: T[K] extends UnknownFunction ? K : never;
 }[keyof T];
-export type OmitFunctionKeys<T> = Omit<T, FunctionKeys<T>>;
+/**
+ * A record of string keys to unknown functions.
+ */
+export type FunctionRecord = Record<string, UnknownFunction>;
+/**
+ * Return `T` if it is **not** a function, otherwise `never`.
+ */
+export type NonFunction<T> = T extends (...args: infer _) => unknown ? never : T;
+/**
+ * Unknown generic function type.
+ */
 export type UnknownFunction = (...args: never[]) => unknown;
 //# sourceMappingURL=functions.d.ts.map

package/dist/types/objects.d.ts

@@ -1,4 +1,11 @@
-import { FunctionKeys, UnknownFunction } from './functions';
-export type NoOverlap<State, Bundled extends ObjectMethods> = Extract<keyof Bundled, FunctionKeys<State>> extends never ? Bundled : never;
-export type ObjectMethods = Record<string, UnknownFunction>;
+/**
+ * Forces TypeScript to expand a type for clearer IDE display.
+ */
+export type Prettify<T> = T extends infer U ? {
+    [K in keyof U]: U[K];
+} : never;
+/**
+ * Enforce no overlapping keys between two objects.
+ */
+export type NoOverlap<A, B> = B & Record<Extract<keyof A, keyof B>, never>;
 //# sourceMappingURL=objects.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,112 +1,64 @@
-import { Mutate, StateCreator as ZustandStateCreator, StoreApi } from 'zustand';
-import { PersistOptions } from 'zustand/middleware';
-import { UseBoundStoreWithEqualityFn } from 'zustand/traditional';
-import { StorageValue } from './storage/storageTypes';
-import { SyncConfig } from './sync/types';
-type SubscribeWithSelector = ['zustand/subscribeWithSelector', never];
-type HydrationPromise<PersistReturn> = PersistReturn extends Promise<void> ? {
-    /** Invoke to get a promise that resolves once hydration completes. */
-    hydrationPromise: () => Promise<void>;
-} : {
-    hydrationPromise?: undefined;
-};
-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 BaseStore<S, ExtraSubscribeOptions extends boolean = false> = UseBoundStoreWithEqualityFn<Mutate<StoreApi<S>, [SubscribeWithSelector]>> & {
+import type { StorageValue } from './storage/storageTypes';
+import type { PersistOptions, StateCreator as StoreStateCreator, StoreApi, StoreMutators, WithPersist } from './store/types';
+import type { SyncConfig } from './sync/types';
+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> = {
-    (): S;
-    <U>(selector: (state: S) => U, equalityFn?: (a: U, b: U) => boolean): U;
-} & 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;
 /**
- * Extracts the return type of setState from a store.
- * Returns `void` for non-persisted or sync-persisted stores.
- * Returns `Promise<void>` for async-persisted stores.
+ * 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.
+ *  - `Promise<void>` for async persisted stores.
  */
 export type InferSetStateReturn<Store> = Store extends {
     setState(...args: SetStateArgs<infer S>): infer R;
 } ? R : void;
 /**
- * Extracts the PersistedState type from a store's persist property.
- * Returns `Partial<State>` if the store doesn't have persistence.
+ * Extracts a store's `PersistedState` type.
+ * Returns `never` if the store doesn't use persistence.
  */
-export type InferPersistedState<Store, State> = Store extends {
-    persist: {
-        getOptions: () => infer Options;
-    };
-} ? Options extends {
-    name?: string;
-} ? Partial<State> : Partial<State> : Partial<State>;
-export type SetPartial<S> = Partial<S> | ((state: S) => Partial<S>);
-export type SetFull<S> = S | ((state: S) => S);
-export type SetStateReplaceArgs<S, ExtraArgs extends unknown[] = []> = [update: SetFull<S>, replace: true, ...extraArgs: ExtraArgs];
-export type SetStatePartialArgs<S, ExtraArgs extends unknown[] = []> = [update: SetPartial<S>, replace?: false, ...extraArgs: ExtraArgs];
-export type SetStateArgs<S, ExtraArgs extends unknown[] = []> = SetStatePartialArgs<S, ExtraArgs> | SetStateReplaceArgs<S, ExtraArgs>;
-export type SetState<S, ExtraArgs extends unknown[] = [], PersistReturn extends Promise<void> | void = void> = (...args: SetStateArgs<S, ExtraArgs>) => PersistReturn;
-export type SetStateOverloads<S, PersistReturn extends Promise<void> | void = void> = {
-    (update: SetPartial<S>, replace?: false): PersistReturn;
-    (update: SetFull<S>, replace: true): PersistReturn;
-};
-export type WithAsyncSet<Store extends StoreApi<unknown>, S, PersistedState, PersistReturn> = Omit<Store, 'persist' | 'setState'> & {
-    persist?: PersistedStore<S, PersistedState, PersistReturn, false>['persist'];
-    setState(update: SetPartial<InferStoreState<Store>>, replace?: false): PersistReturn;
-    setState(update: SetFull<InferStoreState<Store>>, replace: true): PersistReturn;
-};
-export type SubscribeOptions<Selected> = {
-    equalityFn?: EqualityFn<Selected>;
-    fireImmediately?: boolean;
-    isDerivedStore?: boolean;
-};
-export type ListenerArgs<S> = [listener: Listener<S>];
-export type SelectorArgs<S, Selected> = [
-    selector: Selector<S, Selected>,
-    listener: Listener<Selected>,
-    options?: SubscribeOptions<Selected>
-];
-export type SubscribeOverloads<S, ExtraOptions extends boolean = false> = {
-    (listener: Listener<S>): UnsubscribeFn<ExtraOptions>;
-    <Selected>(selector: Selector<S, Selected>, listener: Listener<Selected>, options?: SubscribeOptions<Selected>): UnsubscribeFn<ExtraOptions>;
+export type InferPersistedState<PersistedStore> = PersistedStore extends Store<infer _, infer PersistedState> ? PersistedState : never;
+/**
+ * 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 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 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 & {
     /**
@@ -124,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>;
 };
@@ -200,25 +151,25 @@ 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.
      * Acts as the default before falling back to the framework implementation.
      */
-    readonly deserializer?: <PersistedState>(serializedState: SerializedState) => StorageValue<PersistedState>;
+    deserializer?<PersistedState>(serializedState: SerializedState): StorageValue<PersistedState>;
     /**
      * Adapter-level serializer used when a store does not supply its own.
      * Acts as the default before falling back to the framework implementation.
      */
-    readonly serializer?: <PersistedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+    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.
@@ -229,12 +180,12 @@ export type AsyncStorageInterface<SerializedState = unknown> = {
      * Adapter-level deserializer used when a store does not supply its own.
      * Acts as the default before falling back to the framework implementation.
      */
-    readonly deserializer?: <PersistedState>(serializedState: SerializedState) => StorageValue<PersistedState>;
+    deserializer?<PersistedState>(serializedState: SerializedState): StorageValue<PersistedState>;
     /**
      * Adapter-level serializer used when a store does not supply its own.
      * Acts as the default before falling back to the framework implementation.
      */
-    readonly serializer?: <PersistedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+    serializer?<PersistedState>(storageValue: StorageValue<PersistedState>): SerializedState;
     clearAll(): Promise<void>;
     contains(key: string): Promise<boolean>;
     delete(key: string): Promise<void>;
@@ -245,15 +196,15 @@ 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.
      */
-    deserializer?: <SerializedState>(serializedState: SerializedState) => StorageValue<PersistedState>;
+    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'];
     /**
@@ -271,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)
@@ -281,7 +232,7 @@ export type PersistConfig<S, PersistedState = Partial<S>, PersistReturn = void>
      * A function to serialize the state and version for storage.
      * If not provided, the storage adapter's `serializer` is used before falling back to the default implementation.
      */
-    serializer?: <SerializedState>(storageValue: StorageValue<PersistedState>) => SerializedState;
+    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.
@@ -301,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;
@@ -316,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;
 };
 /**
@@ -333,5 +283,4 @@ export type DebounceOptions = {
     maxWait?: number;
     trailing?: boolean;
 };
-export {};
 //# sourceMappingURL=types.d.ts.map