zustand-kit 1.0.0 → 1.0.1

package/README.md

@@ -9,9 +9,10 @@
 - 🚀 **简单易用** - 最小化的 API 设计，易于上手
 - 🎯 **类型安全** - 完整的 TypeScript 支持
 - 💾 **持久化** - 内置 localStorage/sessionStorage 支持
+- 🔍 **开发者工具** - 开发环境自动集成 Redux DevTools
 - ⚡ **高性能** - 基于 Zustand，性能卓越
 - 🔄 **灵活更新** - 支持对象部分更新和函数式更新
-- 🎨 **选择器支持** - 细粒度订阅，避免不必要的重渲染
+- 🎨 **智能选择器** - 细粒度订阅，自动检测返回值类型并优化性能
 - 🌐 **非 React 环境支持** - 提供独立的 API 用于非组件场景
 
 ## 📦 安装
@@ -77,7 +78,7 @@ function UserProfile() {
 import { useGlobalState } from 'zustand-kit';
 
 function Settings() {
-  // 使用 localStorage 持久化
+  // 使用 localStorage 持久化（开发环境自动启用 DevTools）
   const [settings, setSettings] = useGlobalState(
     'settings',
     { theme: 'dark', lang: 'zh-CN' },
@@ -105,6 +106,29 @@ function Settings() {
 }
 ```
 
+### Redux DevTools 集成
+
+在开发环境下，所有全局状态会自动集成 Redux DevTools，便于调试：
+
+```tsx
+import { useGlobalState } from 'zustand-kit';
+
+// 开发环境自动启用 DevTools（默认行为）
+const [data, setData] = useGlobalState('data', { count: 0 });
+
+// 禁用 DevTools（即使在开发环境）
+const [privateData, setPrivateData] = useGlobalState('private', {}, {
+  enableDevtools: false
+});
+
+// 强制启用 DevTools（生产环境，不推荐）
+const [debugData, setDebugData] = useGlobalState('debug', {}, {
+  enableDevtools: true
+});
+```
+
+在 Redux DevTools 中，每个状态会以 `GlobalState:{key}` 命名显示。
+
 ### 选择器模式（性能优化）
 
 ```tsx
@@ -112,6 +136,7 @@ import { useGlobalSelector } from 'zustand-kit';
 
 function UserName() {
   // 仅订阅 user.name，其他字段变化不会触发重渲染
+  // 自动检测：基本类型使用 Object.is
   const userName = useGlobalSelector('user', (state) => state.name);
 
   return <p>用户名: {userName}</p>;
@@ -123,6 +148,38 @@ function UserEmail() {
 
   return <p>邮箱: {userEmail}</p>;
 }
+
+// 自动检测：对象返回值自动使用浅比较
+function UserInfo() {
+  const userInfo = useGlobalSelector(
+    'user',
+    (state) => ({ name: state.name, email: state.email })
+    // 无需指定 'shallow'，自动检测对象类型并使用浅比较
+  );
+
+  return (
+    <div>
+      <p>姓名: {userInfo.name}</p>
+      <p>邮箱: {userInfo.email}</p>
+    </div>
+  );
+}
+
+// 显式指定 'shallow' 模式
+function UserInfoExplicit() {
+  const userInfo = useGlobalSelector(
+    'user',
+    (state) => ({ name: state.name, email: state.email }),
+    'shallow' // 显式指定浅比较
+  );
+
+  return (
+    <div>
+      <p>姓名: {userInfo.name}</p>
+      <p>邮箱: {userInfo.email}</p>
+    </div>
+  );
+}
 ```
 
 ### 仅获取 Setter（不订阅状态）
@@ -188,13 +245,18 @@ resetGlobalState('counter');
 
 **返回：** `[state, setState, resetState]`
 
-### `useGlobalSelector<T, R>(key, selector)`
+### `useGlobalSelector<T, R>(key, selector, equalityMode?)`
 
-使用选择器订阅状态的特定部分。
+使用选择器订阅状态的特定部分。支持自动检测返回值类型并选择合适的比较模式。
 
 **参数：**
 - `key: string` - 状态键
 - `selector: (state: T) => R` - 选择器函数
+- `equalityMode?: 'shallow'` - 可选的比较模式
+  - `undefined` (默认)：自动检测返回值类型
+    - 基本类型：使用 `Object.is`
+    - 对象/数组：使用浅比较
+  - `'shallow'`：强制使用浅比较
 
 **返回：** 选择的值
 

package/dist/index.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var V=Object.defineProperty;var d=Object.getOwnPropertySymbols;var x=Object.prototype.hasOwnProperty,A=Object.prototype.propertyIsEnumerable;var g=(t,e,o)=>e in t?V(t,e,{enumerable:!0,configurable:!0,writable:!0,value:o}):t[e]=o,T=(t,e)=>{for(var o in e||(e={}))x.call(e,o)&&g(t,o,e[o]);if(d)for(var o of d(e))A.call(e,o)&&g(t,o,e[o]);return t};var _zustand = require('zustand');var _middleware = require('zustand/middleware');var _react = require('react');var r=new Map;function _(){r.clear()}function B(t,e,o){let{storage:a="none",storageKey:i="global-state"}=o||{};if(!r.has(t)){let u=typeof e=="object"&&e!==null&&!Array.isArray(e),v=s=>({value:e,setValue:l=>{s(typeof l=="function"?p=>({value:l(p.value)}):u&&typeof l=="object"&&l!==null?p=>({value:T(T({},p.value),l)}):{value:l})},reset:()=>s({value:e})}),S;if(a!=="none"){let s=a==="localStorage"?localStorage:sessionStorage;S=_zustand.create.call(void 0, )(_middleware.persist.call(void 0, v,{name:`${i}-${t}`,storage:_middleware.createJSONStorage.call(void 0, ()=>s)}))}else S=_zustand.create.call(void 0, v);r.set(t,S)}let n=r.get(t),w=n(u=>u.value),b=_react.useMemo.call(void 0, ()=>n.getState().setValue,[n]),G=_react.useMemo.call(void 0, ()=>n.getState().reset,[n]);return[w,b,G]}function $(t,e){let o=r.get(t);if(!o)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return o(a=>e(a.value))}function I(t){let e=r.get(t);if(!e)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return _react.useMemo.call(void 0, ()=>e.getState().setValue,[e])}function z(t){let e=r.get(t);return e==null?void 0:e.getState().value}function P(t,e){let o=r.get(t);if(!o){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}o.getState().setValue(e)}function j(t,e){let o=r.get(t);if(!o)return process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`),()=>{};let a=o.getState().value;return o.subscribe(i=>{let n=i.value;n!==a&&(e(n,a),a=n)})}function C(t){let e=r.get(t);if(!e){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}e.getState().reset()}var D=B;exports.__clearAllStates__ = _; exports.default = D; exports.getGlobalState = z; exports.resetGlobalState = C; exports.setGlobalState = P; exports.subscribeGlobalState = j; exports.useGlobalSelector = $; exports.useGlobalSetter = I; exports.useGlobalState = B;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } }var E=Object.defineProperty;var v=Object.getOwnPropertySymbols;var B=Object.prototype.hasOwnProperty,$=Object.prototype.propertyIsEnumerable;var w=(t,e,o)=>e in t?E(t,e,{enumerable:!0,configurable:!0,writable:!0,value:o}):t[e]=o,g=(t,e)=>{for(var o in e||(e={}))B.call(e,o)&&w(t,o,e[o]);if(v)for(var o of v(e))$.call(e,o)&&w(t,o,e[o]);return t};var _react = require('react'); var U = _interopRequireWildcard(_react);var _zustand = require('zustand');var _middleware = require('zustand/middleware');var _shallow = require('zustand/react/shallow');var n=new Map;function J(){n.clear()}function _(t,e,o){let{storage:r="none",storageKey:i="global-state",enableDevtools:a=process.env.NODE_ENV!=="production"}=o||{};if(!n.has(t)){let u=typeof e=="object"&&e!==null&&!Array.isArray(e),p=l=>({value:e,setValue:S=>{l(typeof S=="function"?T=>({value:S(T.value)}):u&&typeof S=="object"&&S!==null?T=>({value:g(g({},T.value),S)}):{value:S})},reset:()=>l({value:e})}),c;if(r!=="none"&&a){let l=r==="localStorage"?localStorage:sessionStorage;c=_zustand.create.call(void 0, )(_middleware.devtools.call(void 0, _middleware.persist.call(void 0, p,{name:`${i}-${t}`,storage:_middleware.createJSONStorage.call(void 0, ()=>l)}),{name:`GlobalState:${t}`}))}else if(r!=="none"){let l=r==="localStorage"?localStorage:sessionStorage;c=_zustand.create.call(void 0, )(_middleware.persist.call(void 0, p,{name:`${i}-${t}`,storage:_middleware.createJSONStorage.call(void 0, ()=>l)}))}else a?c=_zustand.create.call(void 0, )(_middleware.devtools.call(void 0, p,{name:`GlobalState:${t}`})):c=_zustand.create.call(void 0, p);n.set(t,c)}let s=n.get(t),b=s(u=>u.value),A=_react.useMemo.call(void 0, ()=>u=>s.getState().setValue(u),[s]),x=_react.useMemo.call(void 0, ()=>()=>s.getState().reset(),[s]);return[b,A,x]}function M(t,e,o){let r=n.get(t);if(!r)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);let i=_react.useRef.call(void 0, e);_react.useEffect.call(void 0, ()=>{i.current=e});let a=_react.useCallback.call(void 0, s=>i.current(s.value),[]);if(o===void 0){let s=a(r.getState());return s!==null&&typeof s=="object"&&!U.isValidElement(s)?r(_shallow.useShallow.call(void 0, a)):r(a)}return r(o==="shallow"?_shallow.useShallow.call(void 0, a):a)}function k(t){let e=n.get(t);if(!e)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return _react.useMemo.call(void 0, ()=>o=>e.getState().setValue(o),[e])}function F(t){let e=n.get(t);return e==null?void 0:e.getState().value}function H(t,e){let o=n.get(t);if(!o){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}o.getState().setValue(e)}function L(t,e){let o=n.get(t);if(!o)return process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`),()=>{};let r=o.getState().value;return o.subscribe(i=>{let a=i.value;Object.is(a,r)||(e(a,r),r=a)})}function Q(t){let e=n.get(t);if(!e){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}e.getState().reset()}var W=_;exports.__clearAllStates__ = J; exports.default = W; exports.getGlobalState = F; exports.resetGlobalState = Q; exports.setGlobalState = H; exports.subscribeGlobalState = L; exports.useGlobalSelector = M; exports.useGlobalSetter = k; exports.useGlobalState = _;

package/dist/index.esm.js

@@ -1 +1 @@
-var V=Object.defineProperty;var d=Object.getOwnPropertySymbols;var x=Object.prototype.hasOwnProperty,A=Object.prototype.propertyIsEnumerable;var g=(t,e,o)=>e in t?V(t,e,{enumerable:!0,configurable:!0,writable:!0,value:o}):t[e]=o,T=(t,e)=>{for(var o in e||(e={}))x.call(e,o)&&g(t,o,e[o]);if(d)for(var o of d(e))A.call(e,o)&&g(t,o,e[o]);return t};import{create as f}from"zustand";import{persist as h,createJSONStorage as U}from"zustand/middleware";import{useMemo as c}from"react";var r=new Map;function _(){r.clear()}function B(t,e,o){let{storage:a="none",storageKey:i="global-state"}=o||{};if(!r.has(t)){let u=typeof e=="object"&&e!==null&&!Array.isArray(e),v=s=>({value:e,setValue:l=>{s(typeof l=="function"?p=>({value:l(p.value)}):u&&typeof l=="object"&&l!==null?p=>({value:T(T({},p.value),l)}):{value:l})},reset:()=>s({value:e})}),S;if(a!=="none"){let s=a==="localStorage"?localStorage:sessionStorage;S=f()(h(v,{name:`${i}-${t}`,storage:U(()=>s)}))}else S=f(v);r.set(t,S)}let n=r.get(t),w=n(u=>u.value),b=c(()=>n.getState().setValue,[n]),G=c(()=>n.getState().reset,[n]);return[w,b,G]}function $(t,e){let o=r.get(t);if(!o)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return o(a=>e(a.value))}function I(t){let e=r.get(t);if(!e)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return c(()=>e.getState().setValue,[e])}function z(t){let e=r.get(t);return e==null?void 0:e.getState().value}function P(t,e){let o=r.get(t);if(!o){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}o.getState().setValue(e)}function j(t,e){let o=r.get(t);if(!o)return process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`),()=>{};let a=o.getState().value;return o.subscribe(i=>{let n=i.value;n!==a&&(e(n,a),a=n)})}function C(t){let e=r.get(t);if(!e){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}e.getState().reset()}var D=B;export{_ as __clearAllStates__,D as default,z as getGlobalState,C as resetGlobalState,P as setGlobalState,j as subscribeGlobalState,$ as useGlobalSelector,I as useGlobalSetter,B as useGlobalState};
+var E=Object.defineProperty;var v=Object.getOwnPropertySymbols;var B=Object.prototype.hasOwnProperty,$=Object.prototype.propertyIsEnumerable;var w=(t,e,o)=>e in t?E(t,e,{enumerable:!0,configurable:!0,writable:!0,value:o}):t[e]=o,g=(t,e)=>{for(var o in e||(e={}))B.call(e,o)&&w(t,o,e[o]);if(v)for(var o of v(e))$.call(e,o)&&w(t,o,e[o]);return t};import*as U from"react";import{create as f}from"zustand";import{persist as V,createJSONStorage as G,devtools as h}from"zustand/middleware";import{useMemo as d,useRef as R,useCallback as N,useEffect as O}from"react";import{useShallow as m}from"zustand/react/shallow";var n=new Map;function J(){n.clear()}function _(t,e,o){let{storage:r="none",storageKey:i="global-state",enableDevtools:a=process.env.NODE_ENV!=="production"}=o||{};if(!n.has(t)){let u=typeof e=="object"&&e!==null&&!Array.isArray(e),p=l=>({value:e,setValue:S=>{l(typeof S=="function"?T=>({value:S(T.value)}):u&&typeof S=="object"&&S!==null?T=>({value:g(g({},T.value),S)}):{value:S})},reset:()=>l({value:e})}),c;if(r!=="none"&&a){let l=r==="localStorage"?localStorage:sessionStorage;c=f()(h(V(p,{name:`${i}-${t}`,storage:G(()=>l)}),{name:`GlobalState:${t}`}))}else if(r!=="none"){let l=r==="localStorage"?localStorage:sessionStorage;c=f()(V(p,{name:`${i}-${t}`,storage:G(()=>l)}))}else a?c=f()(h(p,{name:`GlobalState:${t}`})):c=f(p);n.set(t,c)}let s=n.get(t),b=s(u=>u.value),A=d(()=>u=>s.getState().setValue(u),[s]),x=d(()=>()=>s.getState().reset(),[s]);return[b,A,x]}function M(t,e,o){let r=n.get(t);if(!r)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);let i=R(e);O(()=>{i.current=e});let a=N(s=>i.current(s.value),[]);if(o===void 0){let s=a(r.getState());return s!==null&&typeof s=="object"&&!U.isValidElement(s)?r(m(a)):r(a)}return r(o==="shallow"?m(a):a)}function k(t){let e=n.get(t);if(!e)throw new Error(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return d(()=>o=>e.getState().setValue(o),[e])}function F(t){let e=n.get(t);return e==null?void 0:e.getState().value}function H(t,e){let o=n.get(t);if(!o){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}o.getState().setValue(e)}function L(t,e){let o=n.get(t);if(!o)return process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`),()=>{};let r=o.getState().value;return o.subscribe(i=>{let a=i.value;Object.is(a,r)||(e(a,r),r=a)})}function Q(t){let e=n.get(t);if(!e){process.env.NODE_ENV!=="production"&&console.warn(`Global state with key "${t}" not found. Initialize it with useGlobalState first.`);return}e.getState().reset()}var W=_;export{J as __clearAllStates__,W as default,F as getGlobalState,Q as resetGlobalState,H as setGlobalState,L as subscribeGlobalState,M as useGlobalSelector,k as useGlobalSetter,_ as useGlobalState};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zustand-kit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "⚡️ A minimalist React global state management library based on Zustand with persistence, TypeScript and fine-grained subscriptions",
   "keywords": [
     "zustand",

package/types/index.d.ts

@@ -1,7 +1,3 @@
-/**
- * @file src/index.tsx
- * @author leon.wang
- */
 /**
  * Clear all global states (for testing purposes)
  * @internal
@@ -11,6 +7,10 @@ export declare function __clearAllStates__(): void;
  * Storage type for persistence
  */
 export type StorageType = 'localStorage' | 'sessionStorage' | 'none';
+/**
+ * Helper type for setter value - supports partial updates for objects
+ */
+type SetterValue<T> = T extends Record<string, unknown> ? Partial<T> | ((prev: T) => T) : T | ((prev: T) => T);
 /**
  * Options for useGlobalState
  */
@@ -25,14 +25,19 @@ export interface UseGlobalStateOptions {
      * @default 'global-state'
      */
     storageKey?: string;
+    /**
+     * Enable Redux DevTools integration
+     * @default true in development, false in production
+     */
+    enableDevtools?: boolean;
 }
 /**
  * Universal global state hook - supports both simple values and objects
- * Performance optimized with selector pattern
+ * Performance optimized with selector pattern and automatic Redux DevTools integration
  *
  * @param key - Unique key for the state
  * @param initialState - Initial state (any type)
- * @param options - Configuration options including persistence
+ * @param options - Configuration options including persistence and devtools
  * @returns [state, setState, resetState]
  *
  * @example
@@ -45,42 +50,72 @@ export interface UseGlobalStateOptions {
  * const [user, setUser, resetUser] = useGlobalState('user', {
  *   name: 'John',
  *   email: 'john@example.com',
+ *   age: 30
  * });
- * setUser({ name: 'Jane' }); // Partial update
+ * setUser({ name: 'Jane' }); // Partial update - only updates name field
+ * setUser(prev => ({ ...prev, age: prev.age + 1 })); // Functional update
  *
- * // With localStorage persistence
+ * // With localStorage persistence (DevTools enabled by default in development)
  * const [settings, setSettings] = useGlobalState('settings', { theme: 'dark' }, {
  *   storage: 'localStorage'
  * });
  *
- * // With sessionStorage persistence
+ * // With sessionStorage persistence and custom storage key
  * const [tempData, setTempData] = useGlobalState('temp', { foo: 'bar' }, {
  *   storage: 'sessionStorage',
  *   storageKey: 'my-app'
  * });
  *
+ * // Disable DevTools in development
+ * const [privateData, setPrivateData] = useGlobalState('private', {}, {
+ *   enableDevtools: false
+ * });
+ *
+ * // Force enable DevTools in production (not recommended)
+ * const [debugData, setDebugData] = useGlobalState('debug', {}, {
+ *   enableDevtools: true
+ * });
+ *
  * // For non-React usage, see: getGlobalState, setGlobalState, subscribeGlobalState, resetGlobalState
  */
-export declare function useGlobalState<T>(key: string, initialState: T, options?: UseGlobalStateOptions): [
-    T,
-    (value: T extends Record<string, unknown> ? Partial<T> | ((prev: T) => T) : T | ((prev: T) => T)) => void,
-    () => void
-];
+export declare function useGlobalState<T>(key: string, initialState: T, options?: UseGlobalStateOptions): [T, (value: SetterValue<T>) => void, () => void];
 /**
  * Advanced hook with custom selector for fine-grained subscriptions
  * Only re-renders when selected value changes
+ * Automatically detects return type and uses appropriate comparison mode
+ *
+ * @param key - Global state key
+ * @param selector - Function to select part of the state
+ * @param equalityMode - Optional comparison mode:
+ *   - undefined (default): Auto-detect based on return type (shallow for objects/arrays, Object.is for primitives)
+ *   - 'shallow': Force shallow comparison
+ *   - false: Force Object.is comparison
  *
  * @example
- * // Only subscribe to user name, not the whole user object
+ * // Auto mode: uses Object.is for primitive
  * const userName = useGlobalSelector('user', (state) => state.name);
  *
- * // Multiple values
- * const { name, email } = useGlobalSelector(
+ * // Auto mode: uses shallow for object
+ * const userInfo = useGlobalSelector(
  *   'user',
  *   (state) => ({ name: state.name, email: state.email })
  * );
+ *
+ * // Force shallow comparison
+ * const userInfo = useGlobalSelector(
+ *   'user',
+ *   (state) => ({ name: state.name, email: state.email }),
+ *   'shallow'
+ * );
+ *
+ * // Force Object.is comparison (even for objects)
+ * const userInfo = useGlobalSelector(
+ *   'user',
+ *   (state) => ({ name: state.name, email: state.email }),
+ *   false
+ * );
  */
-export declare function useGlobalSelector<T, R>(key: string, selector: (state: T) => R): R;
+export declare function useGlobalSelector<T, R>(key: string, selector: (state: T) => R, equalityMode?: 'shallow' | false): R;
 /**
  * Hook to get setter function only (doesn't subscribe to state changes)
  * Useful when you only need to update state without reading it
@@ -90,7 +125,7 @@ export declare function useGlobalSelector<T, R>(key: string, selector: (state: T
  * setCount(5);
  * setCount(prev => prev + 1);
  */
-export declare function useGlobalSetter<T>(key: string): (value: T extends Record<string, unknown> ? Partial<T> | ((prev: T) => T) : T | ((prev: T) => T)) => void;
+export declare function useGlobalSetter<T>(key: string): (value: SetterValue<T>) => void;
 /**
  * Get global state value (for non-React usage)
  * @example
@@ -104,7 +139,7 @@ export declare function getGlobalState<T>(key: string): T | undefined;
  * setGlobalState('counter', prev => prev + 1);
  * setGlobalState('user', { name: 'Jane' }); // Partial update for objects
  */
-export declare function setGlobalState<T>(key: string, value: T extends Record<string, unknown> ? Partial<T> | ((prev: T) => T) : T | ((prev: T) => T)): void;
+export declare function setGlobalState<T>(key: string, value: SetterValue<T>): void;
 /**
  * Subscribe to global state changes (for non-React usage)
  * Returns unsubscribe function