zustand-kit 0.1.0

package/README.md

@@ -0,0 +1,299 @@
+# zustand-kit
+
+[English](./README_EN.md) | 简体中文
+
+一个基于 Zustand 构建的轻量级、灵活的 React 状态管理库。
+
+## ✨ 特性
+
+- 🚀 **简单易用** - 最小化的 API 设计，易于上手
+- 🎯 **类型安全** - 完整的 TypeScript 支持
+- 💾 **持久化** - 内置 localStorage/sessionStorage 支持
+- ⚡ **高性能** - 基于 Zustand，性能卓越
+- 🔄 **灵活更新** - 支持对象部分更新和函数式更新
+- 🎨 **选择器支持** - 细粒度订阅，避免不必要的重渲染
+- 🌐 **非 React 环境支持** - 提供独立的 API 用于非组件场景
+
+## 📦 安装
+
+yarn add zustand-x zustand
+```bash
+npm install zustand-kit zustand
+# 或
+yarn add zustand-kit zustand
+# 或
+pnpm add zustand-kit zustand
+```
+
+## 🎯 快速开始
+
+### 基础用法
+
+```tsx
+import { useGlobalState } from 'zustand-kit';
+
+function Counter() {
+  const [count, setCount, resetCount] = useGlobalState('counter', 0);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => setCount(count + 1)}>增加</button>
+      <button onClick={() => setCount(prev => prev - 1)}>减少</button>
+      <button onClick={resetCount}>重置</button>
+    </div>
+  );
+}
+```
+
+### 对象状态（支持部分更新）
+
+```tsx
+import { useGlobalState } from 'zustand-x';
+
+function UserProfile() {
+  const [user, setUser, resetUser] = useGlobalState('user', {
+    name: 'John',
+    email: 'john@example.com',
+    age: 30
+  });
+
+  return (
+    <div>
+      <p>名称: {user.name}</p>
+      <p>邮箱: {user.email}</p>
+      {/* 部分更新 - 只更新 name，其他字段保持不变 */}
+      <button onClick={() => setUser({ name: 'Jane' })}>
+        更改名称
+      </button>
+      <button onClick={resetUser}>重置</button>
+    </div>
+  );
+}
+```
+
+### 持久化状态
+
+```tsx
+import { useGlobalState } from 'zustand-x';
+
+function Settings() {
+  // 使用 localStorage 持久化
+  const [settings, setSettings] = useGlobalState(
+    'settings',
+    { theme: 'dark', lang: 'zh-CN' },
+    { storage: 'localStorage' }
+  );
+
+  // 使用 sessionStorage 持久化
+  const [tempData, setTempData] = useGlobalState(
+    'temp',
+    { foo: 'bar' },
+    {
+      storage: 'sessionStorage',
+      storageKey: 'my-app' // 自定义存储键前缀
+    }
+  );
+
+  return (
+    <div>
+      <p>主题: {settings.theme}</p>
+      <button onClick={() => setSettings({ theme: 'light' })}>
+        切换主题
+      </button>
+    </div>
+  );
+}
+```
+
+### 选择器模式（性能优化）
+
+```tsx
+import { useGlobalSelector } from 'zustand-x';
+
+function UserName() {
+  // 仅订阅 user.name，其他字段变化不会触发重渲染
+  const userName = useGlobalSelector('user', (state) => state.name);
+
+  return <p>用户名: {userName}</p>;
+}
+
+function UserEmail() {
+  // 仅订阅 user.email
+  const userEmail = useGlobalSelector('user', (state) => state.email);
+
+  return <p>邮箱: {userEmail}</p>;
+}
+```
+
+### 仅获取 Setter（不订阅状态）
+
+```tsx
+import { useGlobalSetter } from 'zustand-x';
+
+function IncrementButton() {
+  // 只获取 setter，不订阅状态变化（不会重渲染）
+  const setCount = useGlobalSetter<number>('counter');
+
+  return (
+    <button onClick={() => setCount(prev => prev + 1)}>
+      增加
+    </button>
+  );
+}
+```
+
+## 🔧 非 React 环境使用
+
+zustand-x 提供了独立的 API，可以在非 React 组件中使用：
+
+```typescript
+import {
+  getGlobalState,
+  setGlobalState,
+  subscribeGlobalState,
+  resetGlobalState
+} from 'zustand-x';
+
+// 获取状态
+const count = getGlobalState<number>('counter');
+
+// 设置状态
+setGlobalState('counter', 5);
+setGlobalState('counter', prev => prev + 1);
+
+// 订阅状态变化
+const unsubscribe = subscribeGlobalState('counter', (newValue, prevValue) => {
+  console.log(`Counter 从 ${prevValue} 变为 ${newValue}`);
+});
+
+// 取消订阅
+unsubscribe();
+
+// 重置状态
+resetGlobalState('counter');
+```
+
+## 📖 API 参考
+
+### `useGlobalState<T>(key, initialState, options?)`
+
+创建或连接到全局状态。
+
+**参数：**
+- `key: string` - 状态的唯一标识符
+- `initialState: T` - 初始状态值
+- `options?: UseGlobalStateOptions` - 可选配置
+  - `storage?: 'localStorage' | 'sessionStorage' | 'none'` - 持久化类型（默认 'none'）
+  - `storageKey?: string` - 存储键前缀（默认 'global-state'）
+
+**返回：** `[state, setState, resetState]`
+
+### `useGlobalSelector<T, R>(key, selector)`
+
+使用选择器订阅状态的特定部分。
+
+**参数：**
+- `key: string` - 状态键
+- `selector: (state: T) => R` - 选择器函数
+
+**返回：** 选择的值
+
+### `useGlobalSetter<T>(key)`
+
+仅获取 setter 函数，不订阅状态变化。
+
+**参数：**
+- `key: string` - 状态键
+
+**返回：** setter 函数
+
+### `getGlobalState<T>(key)`
+
+获取全局状态值（非 React 环境）。
+
+### `setGlobalState<T>(key, value)`
+
+设置全局状态值（非 React 环境）。
+
+### `subscribeGlobalState<T>(key, callback)`
+
+订阅全局状态变化（非 React 环境）。返回取消订阅函数。
+
+### `resetGlobalState(key)`
+
+重置全局状态为初始值（非 React 环境）。
+
+## 🎨 TypeScript 支持
+
+zustand-x 使用 TypeScript 编写，提供完整的类型推断：
+
+```typescript
+// 自动推断类型
+const [count, setCount] = useGlobalState('counter', 0);
+// count: number
+// setCount: (value: number | ((prev: number) => number)) => void
+
+// 对象状态支持部分更新
+const [user, setUser] = useGlobalState('user', {
+  name: 'John',
+  age: 30
+});
+// user: { name: string; age: number }
+// setUser: (value: Partial<{name: string; age: number}> | ((prev) => ...)) => void
+
+// 显式类型声明
+interface User {
+  name: string;
+  email: string;
+}
+const [user, setUser] = useGlobalState<User>('user', {
+  name: 'John',
+  email: 'john@example.com'
+});
+```
+
+## 🤝 对比其他方案
+
+| 特性 | zustand-x | Zustand | Redux | Context API |
+|------|-----------|---------|-------|-------------|
+| 学习曲线 | ⭐️ 简单 | ⭐️⭐️ 较简单 | ⭐️⭐️⭐️ 复杂 | ⭐️⭐️ 中等 |
+| 包体积 | 极小 | 小 | 大 | 无 |
+| 性能 | 优秀 | 优秀 | 优秀 | 较差 |
+| TypeScript | ✅ 完整 | ✅ 完整 | ✅ 完整 | ⚠️ 基础 |
+| 持久化 | ✅ 内置 | ✅ 中间件 | 需要插件 | ❌ |
+| 选择器 | ✅ | ✅ | ✅ | ❌ |
+| 易用性 | ⭐️⭐️⭐️⭐️⭐️ | ⭐️⭐️⭐️⭐️ | ⭐️⭐️ | ⭐️⭐️⭐️ |
+
+## 🧪 测试
+
+```bash
+# 运行测试
+npm test
+
+# 监听模式运行测试
+npm run test:watch
+
+# 生成覆盖率报告
+npm run test:coverage
+```
+
+测试覆盖率：93%+ （语句、分支、函数覆盖率）
+
+## 📄 许可证
+
+MIT
+
+## 🔗 链接
+
+- [GitHub](https://github.com/leonwgc/zustand-x)
+- [Issues](https://github.com/leonwgc/zustand-x/issues)
+- [Zustand](https://github.com/pmndrs/zustand)
+
+## 👨‍💻 作者
+
+leon.wang
+
+---
+
+如果这个项目对你有帮助，欢迎给个 ⭐️！

package/dist/index.cjs.js

@@ -0,0 +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;

package/dist/index.esm.js

@@ -0,0 +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};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "zustand-kit",
+  "version": "0.1.0",
+  "description": "⚡️ A minimalist React global state management library based on Zustand with persistence, TypeScript and fine-grained subscriptions",
+  "keywords": [
+    "zustand",
+    "react",
+    "state-management",
+    "hooks"
+  ],
+  "license": "MIT",
+  "repository": "https://github.com/leonwgc/zustand-kit",
+  "bugs": {
+    "url": "https://github.com/leonwgc/zustand-kit/issues"
+  },
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "typings": "types/index.d.ts",
+  "scripts": {
+    "build": "tsup && tsc",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build",
+    "publish--patch": "./publish.sh patch",
+    "publish--minor": "./publish.sh minor",
+    "publish--major": "./publish.sh major"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.3.1",
+    "@types/node": "^25.0.3",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.10",
+    "@typescript-eslint/eslint-plugin": "^5.6.0",
+    "@typescript-eslint/parser": "^5.6.0",
+    "@vitejs/plugin-react": "^4.7.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "antd": "^6.1.4",
+    "eslint": "^8.34.0",
+    "eslint-plugin-react": "^7.19.0",
+    "eslint-plugin-react-hooks": "^2.5.0",
+    "jsdom": "^23.2.0",
+    "packrs": "^1.0.1",
+    "prettier": "^2.2.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^1.6.1",
+    "yargs": "^15.3.1",
+    "zustand": "^5.0.9"
+  },
+  "files": [
+    "dist",
+    "types"
+  ]
+}

package/types/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @file src/index.tsx
+ * @author leon.wang
+ */
+/**
+ * Clear all global states (for testing purposes)
+ * @internal
+ */
+export declare function __clearAllStates__(): void;
+/**
+ * Storage type for persistence
+ */
+export type StorageType = 'localStorage' | 'sessionStorage' | 'none';
+/**
+ * Options for useGlobalState
+ */
+export interface UseGlobalStateOptions {
+    /**
+     * Enable persistence and specify storage type
+     * @default 'none'
+     */
+    storage?: StorageType;
+    /**
+     * Custom storage key prefix
+     * @default 'global-state'
+     */
+    storageKey?: string;
+}
+/**
+ * Universal global state hook - supports both simple values and objects
+ * Performance optimized with selector pattern
+ *
+ * @param key - Unique key for the state
+ * @param initialState - Initial state (any type)
+ * @param options - Configuration options including persistence
+ * @returns [state, setState, resetState]
+ *
+ * @example
+ * // Simple value (number, string, boolean)
+ * const [count, setCount, resetCount] = useGlobalState('counter', 0);
+ * setCount(5);
+ * setCount(prev => prev + 1);
+ *
+ * // Object state - supports partial updates
+ * const [user, setUser, resetUser] = useGlobalState('user', {
+ *   name: 'John',
+ *   email: 'john@example.com',
+ * });
+ * setUser({ name: 'Jane' }); // Partial update
+ *
+ * // With localStorage persistence
+ * const [settings, setSettings] = useGlobalState('settings', { theme: 'dark' }, {
+ *   storage: 'localStorage'
+ * });
+ *
+ * // With sessionStorage persistence
+ * const [tempData, setTempData] = useGlobalState('temp', { foo: 'bar' }, {
+ *   storage: 'sessionStorage',
+ *   storageKey: 'my-app'
+ * });
+ *
+ * // 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
+];
+/**
+ * Advanced hook with custom selector for fine-grained subscriptions
+ * Only re-renders when selected value changes
+ *
+ * @example
+ * // Only subscribe to user name, not the whole user object
+ * const userName = useGlobalSelector('user', (state) => state.name);
+ *
+ * // Multiple values
+ * const { name, email } = useGlobalSelector(
+ *   'user',
+ *   (state) => ({ name: state.name, email: state.email })
+ * );
+ */
+export declare function useGlobalSelector<T, R>(key: string, selector: (state: T) => R): R;
+/**
+ * Hook to get setter function only (doesn't subscribe to state changes)
+ * Useful when you only need to update state without reading it
+ *
+ * @example
+ * const setCount = useGlobalSetter<number>('counter');
+ * 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;
+/**
+ * Get global state value (for non-React usage)
+ * @example
+ * const count = getGlobalState<number>('counter');
+ */
+export declare function getGlobalState<T>(key: string): T | undefined;
+/**
+ * Set global state value (for non-React usage)
+ * @example
+ * setGlobalState('counter', 5);
+ * 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;
+/**
+ * Subscribe to global state changes (for non-React usage)
+ * Returns unsubscribe function
+ * @example
+ * const unsubscribe = subscribeGlobalState('counter', (newValue, prevValue) => {
+ *   console.log('Counter changed from', prevValue, 'to', newValue);
+ * });
+ * // Later: unsubscribe();
+ */
+export declare function subscribeGlobalState<T>(key: string, callback: (newValue: T, prevValue: T) => void): () => void;
+/**
+ * Reset global state to initial value (for non-React usage)
+ * @example
+ * resetGlobalState('counter');
+ */
+export declare function resetGlobalState(key: string): void;
+export default useGlobalState;