floppy-disk 3.0.0-alpha.3 → 3.0.0-alpha.5

package/esm/react/create-mutation.d.mts

@@ -89,7 +89,7 @@ export type MutationOptions<TData, TVariable> = InitStoreOptions<MutationState<T
  * const { isPending } = useCreateUser();
  * const result = await useCreateUser.execute({ name: 'John' });
  */
-export declare const createMutation: <TData, TVariable = undefined>(mutationFn: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable>) => Promise<TData>, options?: MutationOptions<TData, TVariable>) => (<TStateSlice = MutationState<TData, TVariable>>(selector?: (state: MutationState<TData, TVariable>) => TStateSlice) => TStateSlice) & {
+export declare const createMutation: <TData, TVariable = undefined>(mutationFn: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable>) => Promise<TData>, options?: MutationOptions<TData, TVariable>) => (() => MutationState<TData, TVariable>) & {
     subscribe: (subscriber: import("../vanilla.d.mts").Subscriber<MutationState<TData, TVariable>>) => () => void;
     getSubscribers: () => Set<import("../vanilla.d.mts").Subscriber<MutationState<TData, TVariable>>>;
     getState: () => MutationState<TData, TVariable>;

package/esm/react/create-query.d.mts

@@ -67,9 +67,9 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
-     * While fresh, revalidation will be skipped.
+     * While fresh, revalidation will be skipped unless explicitly invalidated.
      *
-     * @default 2500 ms (2.5 minutes)
+     * @default 2500 ms (2.5 seconds)
      */
     staleTime?: number;
     /**
@@ -131,16 +131,20 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
  * @returns A function to retrieve or create a query instance by variable
  *
  * @remarks
- * - Queries are cached by a deterministic key derived from `variable`.
+ * - Queries are **keyed by variable** (via deterministic hashing).
  * - Each unique variable maps to its own store instance.
- * - Queries support:
- *   - Caching with `staleTime`
- *   - Explicit invalidation independent of freshness
- *   - Automatic garbage collection (`gcTime`)
- *   - Retry logic via `shouldRetry`
- *   - Background revalidation (focus / reconnect)
- * - Execution is deduplicated: multiple calls share the same in-flight promise.
- * - Ongoing executions can be optionally overwritten.
+ *
+ * Core features:
+ * - Caching via `staleTime`
+ * - Explicit invalidation (independent of freshness)
+ * - Retry logic via `shouldRetry`
+ * - Background revalidation (focus / reconnect)
+ * - Garbage collection via `gcTime`
+ *
+ * Execution behavior:
+ * - By default, executions **overwrite ongoing executions**
+ * - Set `overwriteOngoingExecution: false` to enable deduplication
+ * - Internal revalidation (focus/reconnect) uses deduplication by default
  *
  * @example
  * const userQuery = createQuery<UserDetail, { id: string }>(async ({ id }) => {
@@ -153,7 +157,7 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
  *   // ...
  * }
  */
-export declare const createQuery: <TData, TVariable extends Record<string, any> = never>(queryFn: (variable: TVariable, currentState: QueryState<TData>) => Promise<TData>, options?: QueryOptions<TData, TVariable>) => ((variable?: TVariable) => (<TStateSlice = QueryState<TData>>(options?: {
+export declare const createQuery: <TData, TVariable extends Record<string, any> = never>(queryFn: (variable: TVariable, currentState: QueryState<TData>) => Promise<TData>, options?: QueryOptions<TData, TVariable>) => ((variable?: TVariable) => ((options?: {
     /**
      * Whether the query should execute automatically on mount.
      *
@@ -176,7 +180,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * // While loading userId=2, still show userId=1 data
      * useQuery({ id: userId }, { keepPreviousData: true });
      */ keepPreviousData?: boolean;
-}, selector?: (state: QueryState<TData>) => TStateSlice) => TStateSlice) & {
+}) => QueryState<TData>) & {
     metadata: {
         isInvalidated?: boolean;
         promise?: Promise<QueryState<TData>> | undefined;
@@ -208,7 +212,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * @returns A promise resolving to the latest query state
      *
      * @remarks
-     * - By default, each call starts a new execution even if one is already in progress.
+     * - By default, each call **starts a new execution** even if one is already in progress.
      * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
      * - Handles:
      *   - Pending state

package/esm/react/create-store.d.mts

@@ -12,14 +12,17 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  * @remarks
  * - Combines the vanilla store with React integration.
  * - The returned function can be used directly as a hook.
+ *   - The hook uses Proxy-based tracking to automatically detect which state fields are used.
+ *   - Components will only re-render when the accessed values change.
  *
  * @example
- * const useCounter = createStore({ count: 0 });
+ * const useMyStore = createStore({ foo: 1, bar: 2 });
  *
  * function Component() {
- *   const count = useCounter((s) => s.count);
+ *   const state = useMyStore();
+ *   return <div>{state.foo}</div>;
  * }
  *
- * useCounter.setState({ count: 1 });
+ * useMyStore.setState({ foo: 2 }); // only components using foo will re-render
  */
-export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (<TStateSlice = TState>(selector?: (state: TState) => TStateSlice) => TStateSlice) & import("../vanilla.d.mts").StoreApi<TState>;
+export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (() => TState) & import("../vanilla.d.mts").StoreApi<TState>;

package/esm/react/create-stores.d.mts

@@ -12,18 +12,25 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  * - Keys are deterministically hashed, ensuring stable identity.
  * - Stores are lazily created and cached.
  * - Each store has its own state, subscribers, and lifecycle.
+ * - Each returned store includes:
+ *   - React hook (with Proxy-based tracking)
+ *   - Store API methods
+ *   - `delete()` for manual cleanup
  * - Useful for scenarios like:
  *   - Query caches
  *   - Entity-based state
  *   - Dynamic instances
  *
  * @example
- * const getUserStore = createStores({ name: '' });
+ * const userStore = createStores<{ name: string }, { id: number }>({ name: '' });
  *
- * const userStore = getUserStore({ id: 1 });
- * const name = userStore((s) => s.name);
+ * function Component() {
+ *   const useUserStore = userStore({ id: 1 });
+ *   const state = useUserStore();
+ *   return <div>{state.name}</div>;
+ * }
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => (<TStateSlice = TState>(selector?: (state: TState) => TStateSlice) => TStateSlice) & {
+export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => (() => TState) & {
     delete: () => boolean;
     setState: (value: import("../vanilla.d.mts").SetState<TState>) => void;
     getState: () => TState;

package/esm/react/use-store.d.mts

@@ -1,18 +1,28 @@
 import { type StoreApi } from 'floppy-disk/vanilla';
-export declare const useStoreUpdateNotifier: <TState extends Record<string, any>, TStateSlice = TState>(store: StoreApi<TState>, selector: (state: TState) => TStateSlice) => void;
+type Path = Array<string | number | symbol>;
+export declare const getValueByPath: (obj: any, path: Path) => any;
+export declare const isPrefixPath: (candidatePrefix: Path, targetPath: Path) => boolean;
+export declare const compressPaths: (paths: Path[]) => Path[];
+export declare const useStoreStateProxy: <TState extends Record<string, any>>(storeState: TState) => readonly [TState, import("react").RefObject<Path[]>];
 /**
- * React hook for subscribing to a store with optional state selection.
+ * React hook for subscribing to a store using automatic dependency tracking.
  *
  * @param store - The store instance to subscribe to
- * @param selector - Optional selector to derive a slice of state
  *
- * @returns The selected state slice (or full state if no selector is provided)
+ * @returns A proxied version of the store state
  *
  * @remarks
- * - The selector does **not** need to be memoized.
- * - The hook internally keeps the latest selector reference to avoid re-subscription.
+ * - This hook uses a **Proxy-based tracking mechanism** to detect which parts of the state are accessed during render.
+ * - The component will only re-render when the **accessed values actually change**.
+ * - State must be treated as **immutable**:
+ *   - Updates must replace objects rather than mutate them
+ *   - Otherwise, changes may not be detected
+ * - No selector or memoization is needed.
  *
  * @example
- * const count = useStoreState(store, (s) => s.count);
+ * const state = useStoreState(store);
+ * return <div>{state.user.name}</div>;
+ * // Component will only re-render if `user.name` changes
  */
-export declare const useStoreState: <TState extends Record<string, any>, TStateSlice = TState>(store: StoreApi<TState>, selector?: (state: TState) => TStateSlice) => TStateSlice;
+export declare const useStoreState: <TState extends Record<string, any>>(storeState: TState, subscribe: StoreApi<TState>["subscribe"]) => TState;
+export {};

package/esm/react.d.mts

@@ -1,5 +1,5 @@
 export * from './react/use-isomorphic-layout-effect.mjs';
-export * from './react/use-store.mjs';
+export { useStoreState } from './react/use-store.mjs';
 export * from './react/create-store.mjs';
 export * from './react/create-stores.mjs';
 export * from './react/create-query.mjs';

package/esm/react.mjs

@@ -1,30 +1,75 @@
-import { useLayoutEffect, useEffect, useState, useRef } from 'react';
-import { isClient, identity, shallow, initStore, getHash, noop } from 'floppy-disk/vanilla';
+import { useLayoutEffect, useEffect, useState, useRef, useMemo } from 'react';
+import { isClient, initStore, getHash, noop } from 'floppy-disk/vanilla';
 
 const useIsomorphicLayoutEffect = isClient ? useLayoutEffect : useEffect;
 
-const useStoreUpdateNotifier = (store, selector) => {
-  const [, reRender] = useState({});
-  const selectorRef = useRef(selector);
-  selectorRef.current = selector;
-  useIsomorphicLayoutEffect(
-    () => store.subscribe((state, prevState) => {
-      if (selectorRef.current === identity) return reRender({});
-      const prevSlice = selectorRef.current(prevState);
-      const nextSlice = selectorRef.current(state);
-      if (!shallow(prevSlice, nextSlice)) reRender({});
-    }),
-    [store]
-  );
+const getValueByPath = (obj, path) => path.reduce((acc, key) => acc == null ? void 0 : acc[key], obj);
+const isPrefixPath = (candidatePrefix, targetPath) => {
+  if (candidatePrefix.length >= targetPath.length) return false;
+  for (let i = 0; i < candidatePrefix.length; i++) {
+    if (candidatePrefix[i] !== targetPath[i]) return false;
+  }
+  return true;
+};
+const compressPaths = (paths) => {
+  const result = [];
+  let prev = null;
+  for (let i = paths.length - 1; i >= 0; i--) {
+    const current = paths[i];
+    if (!prev || !isPrefixPath(current, prev)) result.push(current);
+    prev = current;
+  }
+  return result;
 };
-const useStoreState = (store, selector = identity) => {
-  useStoreUpdateNotifier(store, selector);
-  return selector(store.getState());
+const useStoreStateProxy = (storeState) => {
+  const usedPathsRef = useRef([]);
+  usedPathsRef.current = [];
+  const trackedState = useMemo(() => {
+    const track = (path) => usedPathsRef.current.push(path);
+    const proxyCache = /* @__PURE__ */ new WeakMap();
+    const createDeepProxy = (target, path = []) => {
+      if (typeof target !== "object" || target === null) {
+        return target;
+      }
+      if (proxyCache.has(target)) {
+        return proxyCache.get(target);
+      }
+      const proxy = new Proxy(target, {
+        get(obj, key) {
+          const newPath = [...path, key];
+          track(newPath);
+          const value = obj[key];
+          return createDeepProxy(value, newPath);
+        }
+      });
+      proxyCache.set(target, proxy);
+      return proxy;
+    };
+    return createDeepProxy(storeState);
+  }, [storeState]);
+  return [trackedState, usedPathsRef];
+};
+const useStoreState = (storeState, subscribe) => {
+  const [trackedState, usedPathsRef] = useStoreStateProxy(storeState);
+  const [, reRender] = useState({});
+  useIsomorphicLayoutEffect(() => {
+    return subscribe((nextState, prevState, changedKeys) => {
+      const paths = compressPaths(usedPathsRef.current);
+      for (const path of paths) {
+        const rootKey = path[0];
+        if (!changedKeys.includes(rootKey)) continue;
+        const prevVal = getValueByPath(prevState, path);
+        const nextVal = getValueByPath(nextState, path);
+        if (!Object.is(prevVal, nextVal)) return reRender({});
+      }
+    });
+  }, [subscribe]);
+  return trackedState;
 };
 
 const createStore = (initialState, options) => {
   const store = initStore(initialState, options);
-  const useStore = (selector) => useStoreState(store, selector);
+  const useStore = () => useStoreState(store.getState(), store.subscribe);
   return Object.assign(useStore, store);
 };
 
@@ -39,9 +84,7 @@ const createStores = (initialState, options) => {
       store = initStore(initialState, options);
       stores.set(keyHash, store);
     }
-    const useStore = (selector) => {
-      return useStoreState(store, selector);
-    };
+    const useStore = () => useStoreState(store.getState(), store.subscribe);
     return Object.assign(useStore, {
       ...store,
       delete: () => {
@@ -323,20 +366,50 @@ const createQuery = (queryFn, options = {}) => {
       stores.set(variableHash, store);
       internals.set(store, configureInternals(store, variable, variableHash));
     }
-    const useStore = (options2 = {}, selector = identity) => {
-      useStoreUpdateNotifier(store, selector);
-      useIsomorphicLayoutEffect(() => {
-        if (options2.enabled !== false) revalidate(store, variable, false);
-      }, [store, options2.enabled]);
+    const useStore = (options2 = {}) => {
+      const { enabled = true, keepPreviousData } = options2;
       const storeState = store.getState();
-      let storeStateToBeUsed = storeState;
       const prevState = useRef({});
-      if (storeState.isSuccess) {
-        prevState.current = { data: storeState.data, dataUpdatedAt: storeState.dataUpdatedAt };
-      } else if (storeState.state === "INITIAL" && options2.keepPreviousData) {
+      let storeStateToBeUsed = storeState;
+      if (storeState.state !== "INITIAL") {
+        prevState.current = {
+          data: storeState.data,
+          dataUpdatedAt: storeState.dataUpdatedAt
+        };
+      } else if (keepPreviousData) {
         storeStateToBeUsed = { ...storeState, ...prevState.current };
       }
-      return selector(storeStateToBeUsed);
+      const [trackedState, usedPathsRef] = useStoreStateProxy(
+        enabled && storeState.state === "INITIAL" ? (
+          // Optimize rendering on initial state
+          // Do { isPending: true } → result
+          // instead of { isPending: false } → { isPending: true } → result
+          { ...storeStateToBeUsed, isPending: true }
+        ) : storeStateToBeUsed
+      );
+      const [, reRender] = useState({});
+      useIsomorphicLayoutEffect(() => {
+        return store.subscribe((nextState, prevState2, changedKeys) => {
+          if (prevState2.state === "INITIAL" && !prevState2.isPending && nextState.isPending) {
+            return;
+          }
+          const paths = compressPaths(usedPathsRef.current);
+          for (const path of paths) {
+            const rootKey = path[0];
+            if (!changedKeys.includes(rootKey)) continue;
+            const prevVal = getValueByPath(prevState2, path);
+            const nextVal = getValueByPath(nextState, path);
+            if (!Object.is(prevVal, nextVal)) return reRender({});
+          }
+        });
+      }, [store]);
+      useIsomorphicLayoutEffect(() => {
+        if (enabled !== false) revalidate(store, variable, false);
+      }, [store, enabled]);
+      if (keepPreviousData) {
+        !!trackedState.error;
+      }
+      return trackedState;
     };
     return Object.assign(useStore, {
       subscribe: store.subscribe,
@@ -408,7 +481,7 @@ const createMutation = (mutationFn, options = {}) => {
   const { onSuccess = noop, onError, onSettled = noop } = options;
   const initialState = INITIAL_STATE;
   const store = initStore(initialState, options);
-  const useStore = (selector) => useStoreState(store, selector);
+  const useStore = () => useStoreState(store.getState(), store.subscribe);
   const execute = (variable) => {
     const stateBeforeExecute = store.getState();
     if (stateBeforeExecute.isPending) {
@@ -500,4 +573,4 @@ const createMutation = (mutationFn, options = {}) => {
   });
 };
 
-export { createMutation, createQuery, createStore, createStores, useIsomorphicLayoutEffect, useStoreState, useStoreUpdateNotifier };
+export { createMutation, createQuery, createStore, createStores, useIsomorphicLayoutEffect, useStoreState };

package/esm/vanilla/basic.d.mts

@@ -6,14 +6,6 @@ export declare const isClient: boolean;
  * Empty function.
  */
 export declare const noop: () => void;
-/**
- * Identity function.
- *
- * It accepts 1 argument, and simply return it.
- *
- * `const identity = value => value`
- */
-export declare const identity: <T>(value: T) => T;
 /**
  * If the value is a function, it will invoke the function.\
  * If the value is not a function, it will just return it.

package/esm/vanilla/store.d.mts

@@ -11,18 +11,21 @@ export type SetState<TState> = Partial<TState> | ((state: TState) => Partial<TSt
  *
  * @param state - The latest state
  * @param prevState - The previous state before the update
+ * @param changedKeys - The top-level keys that changed (shallow diff)
  *
  * @remarks
- * - Subscribers are only called when the state actually changes.
+ * - Subscribers are only called when at least one field changes.
  * - Change detection is performed per key using `Object.is`.
+ * - `changedKeys` only includes top-level keys; nested changes must be inferred by the consumer.
  */
-export type Subscriber<TState> = (state: TState, prevState: TState) => void;
+export type Subscriber<TState> = (state: TState, prevState: TState, changedKeys: Array<keyof TState>) => void;
 /**
  * Core store API for managing state.
  *
  * @remarks
  * - The store performs **shallow change detection per key** before notifying subscribers.
  * - Subscribers are only notified when at least one field changes.
+ * - State is treated as **immutable**. Mutating nested values directly will not trigger updates.
  * - Designed to be framework-agnostic (React bindings are built separately).
  * - By default, `setState` is **disabled on the server** to prevent accidental shared state between requests.
  */
@@ -48,13 +51,17 @@ export type InitStoreOptions<TState extends Record<string, any>> = {
     onSubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onLastUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    /**
+     * By default, calling `setState` on the server is disallowed to prevent shared state across requests.
+     * Set this to `true` only if you explicitly intend to mutate state during server execution.
+     */
     allowSetStateServerSide?: boolean;
 };
 /**
  * Creates a vanilla store with pub-sub capabilities.
  *
- * The store state is expected to be an **object**.\
- * Updates are applied as partial merges, so non-object states are not supported.
+ * The store state must be an **object**.\
+ * Updates are applied as shallow merges, so non-object states are not supported.
  *
  * @param initialState - The initial state of the store
  * @param options - Optional lifecycle hooks
@@ -64,11 +71,13 @@ export type InitStoreOptions<TState extends Record<string, any>> = {
  * @remarks
  * - State updates are **shallowly compared per key** before notifying subscribers.
  * - Subscribers are only notified when at least one updated field changes (using `Object.is` comparison).
- * - Subscribers receive both the new state and the previous state.
+ * - Subscribers receive the new state, previous state, and changed top-level keys.
+ * - State is expected to be treated as **immutable**.
+ *   - Mutating nested values directly will not trigger updates.
  * - Lifecycle hooks allow side-effect management tied to subscription count.
- * - By default, `setState` is **disabled on the server** to prevent accidental shared state between requests.
- *   - This avoids leaking data between users in server environments.
- *   - You can override this by setting `allowSetStateServerSide: true`.
+ * - By default, `setState` is **not allowed on the server** to prevent accidental shared state between requests.
+ *   - This helps avoid leaking data between users in server environments.
+ *   - If you intentionally want to allow this behavior, set `allowSetStateServerSide: true`.
  *
  * @example
  * const store = initStore({ count: 0 });

package/esm/vanilla.d.mts

@@ -1,4 +1,3 @@
 export * from './vanilla/basic.mjs';
-export * from './vanilla/shallow.mjs';
 export * from './vanilla/hash.mjs';
 export * from './vanilla/store.mjs';

package/esm/vanilla.mjs

@@ -1,7 +1,6 @@
 const isClient = typeof window !== "undefined" && !("Deno" in window);
 const noop = () => {
 };
-const identity = (value) => value;
 const getValue = (valueOrComputeValueFn, ...params) => {
   if (typeof valueOrComputeValueFn === "function") {
     return valueOrComputeValueFn(...params);
@@ -9,41 +8,6 @@ const getValue = (valueOrComputeValueFn, ...params) => {
   return valueOrComputeValueFn;
 };
 
-const shallow = (a, b) => {
-  if (Object.is(a, b)) {
-    return true;
-  }
-  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) {
-    return false;
-  }
-  if (a instanceof Map && b instanceof Map) {
-    if (a.size !== b.size) return false;
-    for (const [key, value] of a) {
-      if (!Object.is(value, b.get(key))) {
-        return false;
-      }
-    }
-    return true;
-  }
-  if (a instanceof Set && b instanceof Set) {
-    if (a.size !== b.size) return false;
-    for (const value of a) {
-      if (!b.has(value)) return false;
-    }
-    return true;
-  }
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) {
-    return false;
-  }
-  for (let i = 0; i < keysA.length; i++) {
-    if (!Object.prototype.hasOwnProperty.call(b, keysA[i]) || !Object.is(a[keysA[i]], b[keysA[i]])) {
-      return false;
-    }
-  }
-  return true;
-};
-
 const hasObjectPrototype = (value) => {
   return Object.prototype.toString.call(value) === "[object Object]";
 };
@@ -96,13 +60,15 @@ const initStore = (initialState, options = {}) => {
     }
     const prevState = state;
     const newValue = getValue(value, state);
+    const changedKeys = [];
     for (const key in newValue) {
       if (!Object.is(prevState[key], newValue[key])) {
-        state = { ...prevState, ...newValue };
-        [...subscribers].forEach((subscriber) => subscriber(state, prevState));
-        return;
+        changedKeys.push(key);
       }
     }
+    if (changedKeys.length === 0) return;
+    state = { ...prevState, ...newValue };
+    [...subscribers].forEach((subscriber) => subscriber(state, prevState, changedKeys));
   };
   const storeApi = {
     getState,
@@ -113,4 +79,4 @@ const initStore = (initialState, options = {}) => {
   return storeApi;
 };
 
-export { getHash, getValue, identity, initStore, isClient, isPlainObject, noop, shallow };
+export { getHash, getValue, initStore, isClient, isPlainObject, noop };

package/package.json

@@ -2,7 +2,7 @@
   "name": "floppy-disk",
   "description": "Lightweight, simple, and powerful state management library",
   "private": false,
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.5",
   "publishConfig": {
     "tag": "alpha"
   },

package/react/create-mutation.d.ts

@@ -89,7 +89,7 @@ export type MutationOptions<TData, TVariable> = InitStoreOptions<MutationState<T
  * const { isPending } = useCreateUser();
  * const result = await useCreateUser.execute({ name: 'John' });
  */
-export declare const createMutation: <TData, TVariable = undefined>(mutationFn: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable>) => Promise<TData>, options?: MutationOptions<TData, TVariable>) => (<TStateSlice = MutationState<TData, TVariable>>(selector?: (state: MutationState<TData, TVariable>) => TStateSlice) => TStateSlice) & {
+export declare const createMutation: <TData, TVariable = undefined>(mutationFn: (variable: TVariable, stateBeforeExecute: MutationState<TData, TVariable>) => Promise<TData>, options?: MutationOptions<TData, TVariable>) => (() => MutationState<TData, TVariable>) & {
     subscribe: (subscriber: import("../vanilla.ts").Subscriber<MutationState<TData, TVariable>>) => () => void;
     getSubscribers: () => Set<import("../vanilla.ts").Subscriber<MutationState<TData, TVariable>>>;
     getState: () => MutationState<TData, TVariable>;

package/react/create-query.d.ts

@@ -67,9 +67,9 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
     /**
      * Time (in milliseconds) that data is considered fresh.
      *
-     * While fresh, revalidation will be skipped.
+     * While fresh, revalidation will be skipped unless explicitly invalidated.
      *
-     * @default 2500 ms (2.5 minutes)
+     * @default 2500 ms (2.5 seconds)
      */
     staleTime?: number;
     /**
@@ -131,16 +131,20 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
  * @returns A function to retrieve or create a query instance by variable
  *
  * @remarks
- * - Queries are cached by a deterministic key derived from `variable`.
+ * - Queries are **keyed by variable** (via deterministic hashing).
  * - Each unique variable maps to its own store instance.
- * - Queries support:
- *   - Caching with `staleTime`
- *   - Explicit invalidation independent of freshness
- *   - Automatic garbage collection (`gcTime`)
- *   - Retry logic via `shouldRetry`
- *   - Background revalidation (focus / reconnect)
- * - Execution is deduplicated: multiple calls share the same in-flight promise.
- * - Ongoing executions can be optionally overwritten.
+ *
+ * Core features:
+ * - Caching via `staleTime`
+ * - Explicit invalidation (independent of freshness)
+ * - Retry logic via `shouldRetry`
+ * - Background revalidation (focus / reconnect)
+ * - Garbage collection via `gcTime`
+ *
+ * Execution behavior:
+ * - By default, executions **overwrite ongoing executions**
+ * - Set `overwriteOngoingExecution: false` to enable deduplication
+ * - Internal revalidation (focus/reconnect) uses deduplication by default
  *
  * @example
  * const userQuery = createQuery<UserDetail, { id: string }>(async ({ id }) => {
@@ -153,7 +157,7 @@ export type QueryOptions<TData, TVariable extends Record<string, any>> = InitSto
  *   // ...
  * }
  */
-export declare const createQuery: <TData, TVariable extends Record<string, any> = never>(queryFn: (variable: TVariable, currentState: QueryState<TData>) => Promise<TData>, options?: QueryOptions<TData, TVariable>) => ((variable?: TVariable) => (<TStateSlice = QueryState<TData>>(options?: {
+export declare const createQuery: <TData, TVariable extends Record<string, any> = never>(queryFn: (variable: TVariable, currentState: QueryState<TData>) => Promise<TData>, options?: QueryOptions<TData, TVariable>) => ((variable?: TVariable) => ((options?: {
     /**
      * Whether the query should execute automatically on mount.
      *
@@ -176,7 +180,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * // While loading userId=2, still show userId=1 data
      * useQuery({ id: userId }, { keepPreviousData: true });
      */ keepPreviousData?: boolean;
-}, selector?: (state: QueryState<TData>) => TStateSlice) => TStateSlice) & {
+}) => QueryState<TData>) & {
     metadata: {
         isInvalidated?: boolean;
         promise?: Promise<QueryState<TData>> | undefined;
@@ -208,7 +212,7 @@ export declare const createQuery: <TData, TVariable extends Record<string, any>
      * @returns A promise resolving to the latest query state
      *
      * @remarks
-     * - By default, each call starts a new execution even if one is already in progress.
+     * - By default, each call **starts a new execution** even if one is already in progress.
      * - Set `overwriteOngoingExecution: false` to reuse an ongoing execution (deduplication).
      * - Handles:
      *   - Pending state

package/react/create-store.d.ts

@@ -12,14 +12,17 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  * @remarks
  * - Combines the vanilla store with React integration.
  * - The returned function can be used directly as a hook.
+ *   - The hook uses Proxy-based tracking to automatically detect which state fields are used.
+ *   - Components will only re-render when the accessed values change.
  *
  * @example
- * const useCounter = createStore({ count: 0 });
+ * const useMyStore = createStore({ foo: 1, bar: 2 });
  *
  * function Component() {
- *   const count = useCounter((s) => s.count);
+ *   const state = useMyStore();
+ *   return <div>{state.foo}</div>;
  * }
  *
- * useCounter.setState({ count: 1 });
+ * useMyStore.setState({ foo: 2 }); // only components using foo will re-render
  */
-export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (<TStateSlice = TState>(selector?: (state: TState) => TStateSlice) => TStateSlice) & import("../vanilla.ts").StoreApi<TState>;
+export declare const createStore: <TState extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (() => TState) & import("../vanilla.ts").StoreApi<TState>;

package/react/create-stores.d.ts

@@ -12,18 +12,25 @@ import { type InitStoreOptions } from 'floppy-disk/vanilla';
  * - Keys are deterministically hashed, ensuring stable identity.
  * - Stores are lazily created and cached.
  * - Each store has its own state, subscribers, and lifecycle.
+ * - Each returned store includes:
+ *   - React hook (with Proxy-based tracking)
+ *   - Store API methods
+ *   - `delete()` for manual cleanup
  * - Useful for scenarios like:
  *   - Query caches
  *   - Entity-based state
  *   - Dynamic instances
  *
  * @example
- * const getUserStore = createStores({ name: '' });
+ * const userStore = createStores<{ name: string }, { id: number }>({ name: '' });
  *
- * const userStore = getUserStore({ id: 1 });
- * const name = userStore((s) => s.name);
+ * function Component() {
+ *   const useUserStore = userStore({ id: 1 });
+ *   const state = useUserStore();
+ *   return <div>{state.name}</div>;
+ * }
  */
-export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => (<TStateSlice = TState>(selector?: (state: TState) => TStateSlice) => TStateSlice) & {
+export declare const createStores: <TState extends Record<string, any>, TKey extends Record<string, any>>(initialState: TState, options?: InitStoreOptions<TState>) => (key?: TKey) => (() => TState) & {
     delete: () => boolean;
     setState: (value: import("../vanilla.ts").SetState<TState>) => void;
     getState: () => TState;

package/react/use-store.d.ts

@@ -1,18 +1,28 @@
 import { type StoreApi } from 'floppy-disk/vanilla';
-export declare const useStoreUpdateNotifier: <TState extends Record<string, any>, TStateSlice = TState>(store: StoreApi<TState>, selector: (state: TState) => TStateSlice) => void;
+type Path = Array<string | number | symbol>;
+export declare const getValueByPath: (obj: any, path: Path) => any;
+export declare const isPrefixPath: (candidatePrefix: Path, targetPath: Path) => boolean;
+export declare const compressPaths: (paths: Path[]) => Path[];
+export declare const useStoreStateProxy: <TState extends Record<string, any>>(storeState: TState) => readonly [TState, import("react").RefObject<Path[]>];
 /**
- * React hook for subscribing to a store with optional state selection.
+ * React hook for subscribing to a store using automatic dependency tracking.
  *
  * @param store - The store instance to subscribe to
- * @param selector - Optional selector to derive a slice of state
  *
- * @returns The selected state slice (or full state if no selector is provided)
+ * @returns A proxied version of the store state
  *
  * @remarks
- * - The selector does **not** need to be memoized.
- * - The hook internally keeps the latest selector reference to avoid re-subscription.
+ * - This hook uses a **Proxy-based tracking mechanism** to detect which parts of the state are accessed during render.
+ * - The component will only re-render when the **accessed values actually change**.
+ * - State must be treated as **immutable**:
+ *   - Updates must replace objects rather than mutate them
+ *   - Otherwise, changes may not be detected
+ * - No selector or memoization is needed.
  *
  * @example
- * const count = useStoreState(store, (s) => s.count);
+ * const state = useStoreState(store);
+ * return <div>{state.user.name}</div>;
+ * // Component will only re-render if `user.name` changes
  */
-export declare const useStoreState: <TState extends Record<string, any>, TStateSlice = TState>(store: StoreApi<TState>, selector?: (state: TState) => TStateSlice) => TStateSlice;
+export declare const useStoreState: <TState extends Record<string, any>>(storeState: TState, subscribe: StoreApi<TState>["subscribe"]) => TState;
+export {};

package/react.d.ts

@@ -1,5 +1,5 @@
 export * from './react/use-isomorphic-layout-effect';
-export * from './react/use-store';
+export { useStoreState } from './react/use-store';
 export * from './react/create-store';
 export * from './react/create-stores';
 export * from './react/create-query';

package/react.js

@@ -5,28 +5,73 @@ var vanilla = require('floppy-disk/vanilla');
 
 const useIsomorphicLayoutEffect = vanilla.isClient ? react.useLayoutEffect : react.useEffect;
 
-const useStoreUpdateNotifier = (store, selector) => {
-  const [, reRender] = react.useState({});
-  const selectorRef = react.useRef(selector);
-  selectorRef.current = selector;
-  useIsomorphicLayoutEffect(
-    () => store.subscribe((state, prevState) => {
-      if (selectorRef.current === vanilla.identity) return reRender({});
-      const prevSlice = selectorRef.current(prevState);
-      const nextSlice = selectorRef.current(state);
-      if (!vanilla.shallow(prevSlice, nextSlice)) reRender({});
-    }),
-    [store]
-  );
+const getValueByPath = (obj, path) => path.reduce((acc, key) => acc == null ? void 0 : acc[key], obj);
+const isPrefixPath = (candidatePrefix, targetPath) => {
+  if (candidatePrefix.length >= targetPath.length) return false;
+  for (let i = 0; i < candidatePrefix.length; i++) {
+    if (candidatePrefix[i] !== targetPath[i]) return false;
+  }
+  return true;
+};
+const compressPaths = (paths) => {
+  const result = [];
+  let prev = null;
+  for (let i = paths.length - 1; i >= 0; i--) {
+    const current = paths[i];
+    if (!prev || !isPrefixPath(current, prev)) result.push(current);
+    prev = current;
+  }
+  return result;
 };
-const useStoreState = (store, selector = vanilla.identity) => {
-  useStoreUpdateNotifier(store, selector);
-  return selector(store.getState());
+const useStoreStateProxy = (storeState) => {
+  const usedPathsRef = react.useRef([]);
+  usedPathsRef.current = [];
+  const trackedState = react.useMemo(() => {
+    const track = (path) => usedPathsRef.current.push(path);
+    const proxyCache = /* @__PURE__ */ new WeakMap();
+    const createDeepProxy = (target, path = []) => {
+      if (typeof target !== "object" || target === null) {
+        return target;
+      }
+      if (proxyCache.has(target)) {
+        return proxyCache.get(target);
+      }
+      const proxy = new Proxy(target, {
+        get(obj, key) {
+          const newPath = [...path, key];
+          track(newPath);
+          const value = obj[key];
+          return createDeepProxy(value, newPath);
+        }
+      });
+      proxyCache.set(target, proxy);
+      return proxy;
+    };
+    return createDeepProxy(storeState);
+  }, [storeState]);
+  return [trackedState, usedPathsRef];
+};
+const useStoreState = (storeState, subscribe) => {
+  const [trackedState, usedPathsRef] = useStoreStateProxy(storeState);
+  const [, reRender] = react.useState({});
+  useIsomorphicLayoutEffect(() => {
+    return subscribe((nextState, prevState, changedKeys) => {
+      const paths = compressPaths(usedPathsRef.current);
+      for (const path of paths) {
+        const rootKey = path[0];
+        if (!changedKeys.includes(rootKey)) continue;
+        const prevVal = getValueByPath(prevState, path);
+        const nextVal = getValueByPath(nextState, path);
+        if (!Object.is(prevVal, nextVal)) return reRender({});
+      }
+    });
+  }, [subscribe]);
+  return trackedState;
 };
 
 const createStore = (initialState, options) => {
   const store = vanilla.initStore(initialState, options);
-  const useStore = (selector) => useStoreState(store, selector);
+  const useStore = () => useStoreState(store.getState(), store.subscribe);
   return Object.assign(useStore, store);
 };
 
@@ -41,9 +86,7 @@ const createStores = (initialState, options) => {
       store = vanilla.initStore(initialState, options);
       stores.set(keyHash, store);
     }
-    const useStore = (selector) => {
-      return useStoreState(store, selector);
-    };
+    const useStore = () => useStoreState(store.getState(), store.subscribe);
     return Object.assign(useStore, {
       ...store,
       delete: () => {
@@ -325,20 +368,50 @@ const createQuery = (queryFn, options = {}) => {
       stores.set(variableHash, store);
       internals.set(store, configureInternals(store, variable, variableHash));
     }
-    const useStore = (options2 = {}, selector = vanilla.identity) => {
-      useStoreUpdateNotifier(store, selector);
-      useIsomorphicLayoutEffect(() => {
-        if (options2.enabled !== false) revalidate(store, variable, false);
-      }, [store, options2.enabled]);
+    const useStore = (options2 = {}) => {
+      const { enabled = true, keepPreviousData } = options2;
       const storeState = store.getState();
-      let storeStateToBeUsed = storeState;
       const prevState = react.useRef({});
-      if (storeState.isSuccess) {
-        prevState.current = { data: storeState.data, dataUpdatedAt: storeState.dataUpdatedAt };
-      } else if (storeState.state === "INITIAL" && options2.keepPreviousData) {
+      let storeStateToBeUsed = storeState;
+      if (storeState.state !== "INITIAL") {
+        prevState.current = {
+          data: storeState.data,
+          dataUpdatedAt: storeState.dataUpdatedAt
+        };
+      } else if (keepPreviousData) {
         storeStateToBeUsed = { ...storeState, ...prevState.current };
       }
-      return selector(storeStateToBeUsed);
+      const [trackedState, usedPathsRef] = useStoreStateProxy(
+        enabled && storeState.state === "INITIAL" ? (
+          // Optimize rendering on initial state
+          // Do { isPending: true } → result
+          // instead of { isPending: false } → { isPending: true } → result
+          { ...storeStateToBeUsed, isPending: true }
+        ) : storeStateToBeUsed
+      );
+      const [, reRender] = react.useState({});
+      useIsomorphicLayoutEffect(() => {
+        return store.subscribe((nextState, prevState2, changedKeys) => {
+          if (prevState2.state === "INITIAL" && !prevState2.isPending && nextState.isPending) {
+            return;
+          }
+          const paths = compressPaths(usedPathsRef.current);
+          for (const path of paths) {
+            const rootKey = path[0];
+            if (!changedKeys.includes(rootKey)) continue;
+            const prevVal = getValueByPath(prevState2, path);
+            const nextVal = getValueByPath(nextState, path);
+            if (!Object.is(prevVal, nextVal)) return reRender({});
+          }
+        });
+      }, [store]);
+      useIsomorphicLayoutEffect(() => {
+        if (enabled !== false) revalidate(store, variable, false);
+      }, [store, enabled]);
+      if (keepPreviousData) {
+        !!trackedState.error;
+      }
+      return trackedState;
     };
     return Object.assign(useStore, {
       subscribe: store.subscribe,
@@ -410,7 +483,7 @@ const createMutation = (mutationFn, options = {}) => {
   const { onSuccess = vanilla.noop, onError, onSettled = vanilla.noop } = options;
   const initialState = INITIAL_STATE;
   const store = vanilla.initStore(initialState, options);
-  const useStore = (selector) => useStoreState(store, selector);
+  const useStore = () => useStoreState(store.getState(), store.subscribe);
   const execute = (variable) => {
     const stateBeforeExecute = store.getState();
     if (stateBeforeExecute.isPending) {
@@ -508,4 +581,3 @@ exports.createStore = createStore;
 exports.createStores = createStores;
 exports.useIsomorphicLayoutEffect = useIsomorphicLayoutEffect;
 exports.useStoreState = useStoreState;
-exports.useStoreUpdateNotifier = useStoreUpdateNotifier;

package/vanilla/basic.d.ts

@@ -6,14 +6,6 @@ export declare const isClient: boolean;
  * Empty function.
  */
 export declare const noop: () => void;
-/**
- * Identity function.
- *
- * It accepts 1 argument, and simply return it.
- *
- * `const identity = value => value`
- */
-export declare const identity: <T>(value: T) => T;
 /**
  * If the value is a function, it will invoke the function.\
  * If the value is not a function, it will just return it.

package/vanilla/store.d.ts

@@ -11,18 +11,21 @@ export type SetState<TState> = Partial<TState> | ((state: TState) => Partial<TSt
  *
  * @param state - The latest state
  * @param prevState - The previous state before the update
+ * @param changedKeys - The top-level keys that changed (shallow diff)
  *
  * @remarks
- * - Subscribers are only called when the state actually changes.
+ * - Subscribers are only called when at least one field changes.
  * - Change detection is performed per key using `Object.is`.
+ * - `changedKeys` only includes top-level keys; nested changes must be inferred by the consumer.
  */
-export type Subscriber<TState> = (state: TState, prevState: TState) => void;
+export type Subscriber<TState> = (state: TState, prevState: TState, changedKeys: Array<keyof TState>) => void;
 /**
  * Core store API for managing state.
  *
  * @remarks
  * - The store performs **shallow change detection per key** before notifying subscribers.
  * - Subscribers are only notified when at least one field changes.
+ * - State is treated as **immutable**. Mutating nested values directly will not trigger updates.
  * - Designed to be framework-agnostic (React bindings are built separately).
  * - By default, `setState` is **disabled on the server** to prevent accidental shared state between requests.
  */
@@ -48,13 +51,17 @@ export type InitStoreOptions<TState extends Record<string, any>> = {
     onSubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
     onLastUnsubscribe?: (state: TState, store: StoreApi<TState>) => void;
+    /**
+     * By default, calling `setState` on the server is disallowed to prevent shared state across requests.
+     * Set this to `true` only if you explicitly intend to mutate state during server execution.
+     */
     allowSetStateServerSide?: boolean;
 };
 /**
  * Creates a vanilla store with pub-sub capabilities.
  *
- * The store state is expected to be an **object**.\
- * Updates are applied as partial merges, so non-object states are not supported.
+ * The store state must be an **object**.\
+ * Updates are applied as shallow merges, so non-object states are not supported.
  *
  * @param initialState - The initial state of the store
  * @param options - Optional lifecycle hooks
@@ -64,11 +71,13 @@ export type InitStoreOptions<TState extends Record<string, any>> = {
  * @remarks
  * - State updates are **shallowly compared per key** before notifying subscribers.
  * - Subscribers are only notified when at least one updated field changes (using `Object.is` comparison).
- * - Subscribers receive both the new state and the previous state.
+ * - Subscribers receive the new state, previous state, and changed top-level keys.
+ * - State is expected to be treated as **immutable**.
+ *   - Mutating nested values directly will not trigger updates.
  * - Lifecycle hooks allow side-effect management tied to subscription count.
- * - By default, `setState` is **disabled on the server** to prevent accidental shared state between requests.
- *   - This avoids leaking data between users in server environments.
- *   - You can override this by setting `allowSetStateServerSide: true`.
+ * - By default, `setState` is **not allowed on the server** to prevent accidental shared state between requests.
+ *   - This helps avoid leaking data between users in server environments.
+ *   - If you intentionally want to allow this behavior, set `allowSetStateServerSide: true`.
  *
  * @example
  * const store = initStore({ count: 0 });

package/vanilla.d.ts

@@ -1,4 +1,3 @@
 export * from './vanilla/basic';
-export * from './vanilla/shallow';
 export * from './vanilla/hash';
 export * from './vanilla/store';

package/vanilla.js

@@ -3,7 +3,6 @@
 const isClient = typeof window !== "undefined" && !("Deno" in window);
 const noop = () => {
 };
-const identity = (value) => value;
 const getValue = (valueOrComputeValueFn, ...params) => {
   if (typeof valueOrComputeValueFn === "function") {
     return valueOrComputeValueFn(...params);
@@ -11,41 +10,6 @@ const getValue = (valueOrComputeValueFn, ...params) => {
   return valueOrComputeValueFn;
 };
 
-const shallow = (a, b) => {
-  if (Object.is(a, b)) {
-    return true;
-  }
-  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) {
-    return false;
-  }
-  if (a instanceof Map && b instanceof Map) {
-    if (a.size !== b.size) return false;
-    for (const [key, value] of a) {
-      if (!Object.is(value, b.get(key))) {
-        return false;
-      }
-    }
-    return true;
-  }
-  if (a instanceof Set && b instanceof Set) {
-    if (a.size !== b.size) return false;
-    for (const value of a) {
-      if (!b.has(value)) return false;
-    }
-    return true;
-  }
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) {
-    return false;
-  }
-  for (let i = 0; i < keysA.length; i++) {
-    if (!Object.prototype.hasOwnProperty.call(b, keysA[i]) || !Object.is(a[keysA[i]], b[keysA[i]])) {
-      return false;
-    }
-  }
-  return true;
-};
-
 const hasObjectPrototype = (value) => {
   return Object.prototype.toString.call(value) === "[object Object]";
 };
@@ -98,13 +62,15 @@ const initStore = (initialState, options = {}) => {
     }
     const prevState = state;
     const newValue = getValue(value, state);
+    const changedKeys = [];
     for (const key in newValue) {
       if (!Object.is(prevState[key], newValue[key])) {
-        state = { ...prevState, ...newValue };
-        [...subscribers].forEach((subscriber) => subscriber(state, prevState));
-        return;
+        changedKeys.push(key);
       }
     }
+    if (changedKeys.length === 0) return;
+    state = { ...prevState, ...newValue };
+    [...subscribers].forEach((subscriber) => subscriber(state, prevState, changedKeys));
   };
   const storeApi = {
     getState,
@@ -117,9 +83,7 @@ const initStore = (initialState, options = {}) => {
 
 exports.getHash = getHash;
 exports.getValue = getValue;
-exports.identity = identity;
 exports.initStore = initStore;
 exports.isClient = isClient;
 exports.isPlainObject = isPlainObject;
 exports.noop = noop;
-exports.shallow = shallow;

package/esm/vanilla/shallow.d.mts

@@ -1,6 +0,0 @@
-/**
- * Shallow compare 2 values.
- *
- * Reference: https://github.com/pmndrs/zustand/blob/e414f7ccf41eae09517ee2dcb44c9f5ae8a35a25/src/vanilla/shallow.ts
- */
-export declare const shallow: <T>(a: T, b: T) => boolean;

package/vanilla/shallow.d.ts

@@ -1,6 +0,0 @@
-/**
- * Shallow compare 2 values.
- *
- * Reference: https://github.com/pmndrs/zustand/blob/e414f7ccf41eae09517ee2dcb44c9f5ae8a35a25/src/vanilla/shallow.ts
- */
-export declare const shallow: <T>(a: T, b: T) => boolean;