react-native-hox 0.0.1-beta → 0.0.1

package/README.md

@@ -1,21 +1,29 @@
 # react-native-hox
 
-**为复杂业务场景而生的状态管理解决方案**。
+> **下一代 React Native 状态管理方案。**
+> 极简、高性能、生产级特性开箱即用。
 
-我们把 API 收敛到一个：`createModel`。组件内像 Hook 一样用，组件外（如网络请求拦截器）也能直接读取/订阅最新状态。
+[![NPM Version](https://img.shields.io/npm/v/react-native-hox)](https://www.npmjs.com/package/react-native-hox)
+[![TypeScript](https://img.shields.io/badge/language-TypeScript-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/react-native-hox)](https://github.com/wangwenshan/react-native-hox/blob/main/LICENSE)
 
----
+## 为什么选择 Hox？
+
+在 React Native 开发中，我们经常在 Redux 的繁琐、Context 的性能陷阱和 Zustand 的手动配置之间挣扎。
+
+`react-native-hox` 重新思考了移动端状态管理的最佳实践，提供了一种**"零配置、全功能"**的开发体验。它不仅是一个状态库，更内置了移动端开发必不可少的工程化能力。
 
-## 核心特性
+### 核心亮点
 
-*   **一个 API**：`createModel` 创建全局模型。
-*   **组件内/外都能用**：组件内 `model()` / `model(selector)` 订阅更新；组件外用 `model.data / model.getState()` 获取最新快照（不触发渲染）。
-*   **内置优化**：对象更新自动合并、无变化不更新（减少无意义重渲染）。
-*   **生产力优先**：可选持久化（Persist）、可选 Web 多窗口同步（BroadcastChannel）。
+*   ⚡️ **零样板代码**：告别 Action、Reducer、Provider。一行代码即可创建全局状态。
+*   💾 **智能持久化**：内置异步存储支持。只需配置 `persist` key，自动处理防抖写入与初始化读取。
+*   🧬 **自动合并 (Auto-Merge)**：延续 `setState` 的直觉体验，自动合并对象属性，无需手动 spread `...state`。
+*   🎯 **精准渲染**：支持 Selector 选择器，确保组件仅在关注的数据变化时更新。
+*   🔌 **脱离组件运行**：完整的 Vanilla API，支持在 Axios 拦截器、事件回调等非组件环境读写状态。
 
 ---
 
-## 快速上手（推荐）
+## 快速开始
 
 ### 安装
 
@@ -25,115 +33,180 @@ npm install react-native-hox
 yarn add react-native-hox
 ```
 
-### 创建一个全局模型
+### 1. 基础用法：全局状态 (Global Store)
 
-适用于用户信息、全局配置、表单草稿、token 等场景。
-**完全不需要 Provider，也不需要修改入口文件。**
+适用于：用户信息、应用配置、Token 管理等。
 
-```tsx
-// store.ts
+```typescript
+// store/user.ts
 import { createModel } from 'react-native-hox';
 
-// 定义一个支持持久化的用户状态
-// createModel(initialState, options?)
-export const userModel = createModel({
+// 创建一个自动持久化的用户 Store
+export const userStore = createModel({
   name: 'Guest',
   token: '',
-  theme: 'light'
+  isLogin: false,
 }, {
-  persist: 'user_store', // 开启持久化，自动写入 Storage
+  persist: 'user_v1', // 开启持久化，数据自动存入 AsyncStorage/localStorage
 });
-
-// 推荐：在组件内使用 useXxxModel 作为 Hook 别名（同一个对象）
-// 这样更符合 Hook 心智模型，也能被 eslint-plugin-react-hooks 正确识别
-export const useUserModel = userModel;
 ```
 
-**组件中使用：**
-
 ```tsx
-import { useUserModel } from './store';
+// components/UserProfile.tsx
+import { userStore } from '../store/user';
 
-function UserProfile() {
-  // 直接调用 model() 获取响应式 state
-  const user = useUserModel.useState();
+export default function UserProfile() {
+  // 1. 读取状态 (Hook)
+  // 支持传入 selector，仅在关注的属性变化时重渲染
+  const name = userStore.getState(s => s.name);
 
   const login = () => {
-    // 自动合并更新：只更新 token 和 name，theme 保持不变
-    useUserModel.setState({ 
-      token: 'xyz', 
-      name: 'User' 
+    // 2. 更新状态：自动合并，无需 ...user
+    userStore.setState({ 
+      name: 'Admin', 
+      isLogin: true 
     });
   };
 
   return (
     <View>
-      <Text>{user.name}</Text>
-      <Button onPress={login}>Login</Button>
+      <Text>Hello, {name}</Text>
+      <Button onPress={login} title="Login" />
     </View>
   );
 }
 ```
 
-> 说明：组件渲染是否更新，取决于你是否用 `useUserModel.useState()` / `useUserModel.useState(selector)`（或直接 `useUserModel()`）订阅了状态；`userModel.data` / `useUserModel.data` 是快照不会触发渲染。`setState` 如果没有真正改变值会被自动忽略（减少无意义重渲染）。
+### 2. 进阶用法：精细控制 (Selector & Reset)
 
-**什么时候用 `useXxxModel()` / `getState()` / `data`？**
+```tsx
+  // 只有当 count > 10 发生变化时，组件才会重渲染
+  const isHigh = userStore.getState(state => state.count > 10);
+  
+  // 重置状态为初始值
+  userStore.reset();
+  ```
 
-- 组件渲染里：用 `useUserModel.useState()`（或 `useUserModel.useState(s => s.token)`），它会订阅更新，状态变了组件会跟着重渲染
-- 组件外（网络请求拦截器、工具函数、非 React 环境）：用 `userModel.getState()` / `userModel.data` 读取最新快照，或 `userModel.subscribe(...)` 订阅
-- 不建议在组件渲染里用 `useUserModel.getState()` / `useUserModel.data`：它们是“快照读取”，不会触发组件更新，容易出现 UI 不刷新
+---
 
-**组件外使用：**
+## 解决痛点
 
-```ts
-import { userModel } from './store';
+### 痛点 1：持久化配置太麻烦
+**以前**：安装中间件 -> 配置白名单 -> 处理 Hydration -> 处理防抖。
+**现在**：
+
+```typescript
+const store = createModel({ theme: 'dark' }, { 
+  persist: 'app_theme' // ✅ Done. 自动防抖，自动恢复。
+});
+```
+
+### 痛点 2：非组件环境无法访问状态
+**以前**：为了在 API 拦截器里拿 Token，不得不把 store 挂载到 window 或者引入复杂的 hack。
+**现在**：
+
+```typescript
+// api.ts
+import { userStore } from './store/user';
 
-// 在 Axios 拦截器中读取 Token
 axios.interceptors.request.use(config => {
-  const { token } = userModel.data; // 直接获取最新快照（非 Hook）
-  if (token) config.headers.Authorization = token;
+  // ✅ 直接读取最新状态
+  const token = userStore.data.state.token;
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
   return config;
 });
 
-// 在任意函数中更新状态
-export function logout() {
-  userModel.setState({ token: '', name: 'Guest' });
-}
-```
+// 甚至可以直接修改
+userStore.data.setState({ token: '' }); // 登出
+```+ ### 3. API 统一性 (New)
++ **以前**：Redux `useSelector` vs `dispatch`，Context `useContext` vs `dispatch`。
++ **现在**：
++ *   读 (React)：`userStore.getState()`
++ *   读 (Vanilla)：`userStore.data.state`
++ *   写 (Universal)：`userStore.setState()`
 
----
+## 生产实践
 
-## 全局配置（可选）
-
-`persist` 默认会使用 **Web 端的 `localStorage`（零配置）**。在 React Native 环境没有默认持久化存储，需要你通过 `setup` 注入（也可以用 `setup` 覆盖 Web 默认实现）。
+### 1) Token 管理：拦截器读取 + 401 统一登出
 
 ```ts
-import { setup } from 'react-native-hox';
-import AsyncStorage from '@react-native-async-storage/async-storage';
-import { MMKV } from 'react-native-mmkv';
-
-// 适配 AsyncStorage
-setup({ storage: AsyncStorage });
-
-// 或者适配 MMKV
-const storage = new MMKV();
-setup({
-  storage: {
-    getItem: (key) => storage.getString(key),
-    setItem: (key, val) => storage.set(key, val),
-    removeItem: (key) => storage.delete(key),
+import axios from 'axios';
+import { userStore } from './store/user';
+
+axios.interceptors.request.use((config) => {
+  const token = userStore.data.state.token;
+  if (token) {
+    config.headers = config.headers ?? {};
+    config.headers.Authorization = `Bearer ${token}`;
   }
+  return config;
 });
-```
 
-## 高级特性
+axios.interceptors.response.use(
+  (resp) => resp,
+  (err) => {
+    if (err?.response?.status === 401) {
+      userStore.setState({ token: '', isLogin: false });
+    }
+    return Promise.reject(err);
+  }
+);
+```
 
-### Web 端多窗口同步
+### 2) 持久化：推荐的安全边界
 
-如果你在使用 `react-native-web`，或者在 WebView 场景下需要多 Tab 状态同步，可以开启 `sync` 选项。
+*   `persist` 的恢复是异步的：首屏会先用 `initialState`，恢复完成后再更新一次。
+*   强烈建议把版本号编码进 key（如 `user_v1`），避免不可控的 schema 变化。
+*   需要兼容旧数据时，用 `beforeRecover` 做兜底转换。
 
 ```ts
-const userModel = createModel({ ... }, {
-  persist: 'user',
-});
+export const userStore = createModel(
+  { token: '', isLogin: false },
+  {
+    persist: {
+      key: 'user_v1',
+      beforeRecover: (v) => ({
+        token: v?.token ?? '',
+        isLogin: Boolean(v?.token),
+      }),
+    },
+  }
+);
+```
+
+### 3) Selector 性能：避免无意义重渲染
+
+*   selector 尽量返回 primitive（string/number/boolean）或稳定引用。
+*   如果 selector 返回对象/数组，传入 `equalityFn`（例如 `shallow`）以避免每次新建对象触发重渲染。
+
+```tsx
+import { shallow } from 'react-native-hox';
+
+const user = userStore.getState((s) => ({ name: s.name, isLogin: s.isLogin }), shallow);
 ```
+
+## API 参考
+
+### `createModel(initialState, options?)`
+
+创建全局 Store。
+
+*   `initialState`: 初始状态对象，或返回初始状态的纯函数。
+*   `options`:
+    *   `persist`: `string` (可选) - 持久化存储的唯一 Key。
+
+返回 `Model` 实例：
+*   `getState(selector?, equalityFn?)`: React Hook，在组件中读取状态。
+*   `useState(selector?, equalityFn?)`: `getState` 的别名。
+*   `use(selector?, equalityFn?)`: `getState` 的别名。
+*   `setState(patch)`: 更新状态。
+*   `reset()`: 重置为初始状态。
+*   `data`: 组件外 API，包含 `state` (getter), `getState` (fn), `setState`, `subscribe`, `reset`, `destroy`。
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,3 +1,9 @@
+interface StorageEngine {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+}
+
 type Listener<T> = (state: T, prevState: T) => void;
 type EqualityFn<T> = (a: T, b: T) => boolean;
 
@@ -8,58 +14,49 @@ type ModelHook<T> = {
 };
 interface PersistOptions<T> {
     key: string;
+    storage?: StorageEngine;
     debounce?: number;
     beforePersist?: (state: T) => any;
-    beforeRecover?: (value: any) => T;
+    beforeRecover?: (value: any) => T | Partial<T>;
+}
+interface Logger {
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
 }
 interface CreateModelOptions<T> {
-    /**
-     * 开启持久化。建议直接传 key：persist: 'user_store'
-     */
     persist?: string | PersistOptions<T>;
-    /**
-     * Web 多窗口同步（BroadcastChannel）。需要 persist key 才能工作。
-     */
-    sync?: boolean;
+    logger?: Logger;
+    strict?: {
+        forbidSetStateAfterDestroy?: boolean;
+    };
 }
 interface SubscribeWithSelectorOptions<U> {
     equalityFn?: EqualityFn<U>;
     fireImmediately?: boolean;
 }
-interface Model<T> {
-    (): T;
-    <U>(selector: Selector<T, U>, equalityFn?: EqualityFn<U>): U;
-    /**
-     * 更显式的 Hook 入口（等价于直接调用 model()）
-     * 推荐在组件内写：const state = useUserModel.useState()
-     */
-    useState: ModelHook<T>;
-    /**
-     * useState 的别名（更短），保留给喜欢 `useXxx.use()` 风格的团队
-     */
-    use: ModelHook<T>;
+interface Subscribe<T> {
+    (listener: Listener<T>): () => void;
+    <U>(selector: Selector<T, U>, listener: (selected: U, prevSelected: U) => void, options?: SubscribeWithSelectorOptions<U>): () => void;
+}
+interface ModelData<T> {
     getState: () => T;
     setState: (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean) => void;
-    subscribe: {
-        (listener: Listener<T>): () => void;
-        <U>(selector: Selector<T, U>, listener: (selected: U, prevSelected: U) => void, options?: SubscribeWithSelectorOptions<U>): () => void;
-    };
+    subscribe: Subscribe<T>;
     destroy: () => void;
     reset: () => void;
-    data: T;
+    state: T;
 }
+type Model<T> = ModelHook<T> & {
+    getState: ModelHook<T>;
+    useState: ModelHook<T>;
+    setState: (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean) => void;
+    destroy: () => void;
+    reset: () => void;
+    data: ModelData<T>;
+    use: ModelHook<T>;
+};
 declare function createModel<T>(initialState: T | (() => T), options?: CreateModelOptions<T>): Model<T>;
 
-interface StorageEngine {
-    getItem: (key: string) => string | null | Promise<string | null>;
-    setItem: (key: string, value: string) => void | Promise<void>;
-    removeItem: (key: string) => void | Promise<void>;
-}
-interface Config {
-    storage?: StorageEngine;
-}
-declare const setup: (options: Config) => void;
-
-declare const shallow: EqualityFn<any>;
+declare function shallow<T>(objA: T, objB: T): boolean;
 
-export { type CreateModelOptions, type Model, type PersistOptions, type StorageEngine, type SubscribeWithSelectorOptions, createModel, setup, shallow };
+export { type CreateModelOptions, type Model, type ModelData, type PersistOptions, type StorageEngine, type SubscribeWithSelectorOptions, createModel, shallow };

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+interface StorageEngine {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+}
+
 type Listener<T> = (state: T, prevState: T) => void;
 type EqualityFn<T> = (a: T, b: T) => boolean;
 
@@ -8,58 +14,49 @@ type ModelHook<T> = {
 };
 interface PersistOptions<T> {
     key: string;
+    storage?: StorageEngine;
     debounce?: number;
     beforePersist?: (state: T) => any;
-    beforeRecover?: (value: any) => T;
+    beforeRecover?: (value: any) => T | Partial<T>;
+}
+interface Logger {
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
 }
 interface CreateModelOptions<T> {
-    /**
-     * 开启持久化。建议直接传 key：persist: 'user_store'
-     */
     persist?: string | PersistOptions<T>;
-    /**
-     * Web 多窗口同步（BroadcastChannel）。需要 persist key 才能工作。
-     */
-    sync?: boolean;
+    logger?: Logger;
+    strict?: {
+        forbidSetStateAfterDestroy?: boolean;
+    };
 }
 interface SubscribeWithSelectorOptions<U> {
     equalityFn?: EqualityFn<U>;
     fireImmediately?: boolean;
 }
-interface Model<T> {
-    (): T;
-    <U>(selector: Selector<T, U>, equalityFn?: EqualityFn<U>): U;
-    /**
-     * 更显式的 Hook 入口（等价于直接调用 model()）
-     * 推荐在组件内写：const state = useUserModel.useState()
-     */
-    useState: ModelHook<T>;
-    /**
-     * useState 的别名（更短），保留给喜欢 `useXxx.use()` 风格的团队
-     */
-    use: ModelHook<T>;
+interface Subscribe<T> {
+    (listener: Listener<T>): () => void;
+    <U>(selector: Selector<T, U>, listener: (selected: U, prevSelected: U) => void, options?: SubscribeWithSelectorOptions<U>): () => void;
+}
+interface ModelData<T> {
     getState: () => T;
     setState: (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean) => void;
-    subscribe: {
-        (listener: Listener<T>): () => void;
-        <U>(selector: Selector<T, U>, listener: (selected: U, prevSelected: U) => void, options?: SubscribeWithSelectorOptions<U>): () => void;
-    };
+    subscribe: Subscribe<T>;
     destroy: () => void;
     reset: () => void;
-    data: T;
+    state: T;
 }
+type Model<T> = ModelHook<T> & {
+    getState: ModelHook<T>;
+    useState: ModelHook<T>;
+    setState: (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean) => void;
+    destroy: () => void;
+    reset: () => void;
+    data: ModelData<T>;
+    use: ModelHook<T>;
+};
 declare function createModel<T>(initialState: T | (() => T), options?: CreateModelOptions<T>): Model<T>;
 
-interface StorageEngine {
-    getItem: (key: string) => string | null | Promise<string | null>;
-    setItem: (key: string, value: string) => void | Promise<void>;
-    removeItem: (key: string) => void | Promise<void>;
-}
-interface Config {
-    storage?: StorageEngine;
-}
-declare const setup: (options: Config) => void;
-
-declare const shallow: EqualityFn<any>;
+declare function shallow<T>(objA: T, objB: T): boolean;
 
-export { type CreateModelOptions, type Model, type PersistOptions, type StorageEngine, type SubscribeWithSelectorOptions, createModel, setup, shallow };
+export { type CreateModelOptions, type Model, type ModelData, type PersistOptions, type StorageEngine, type SubscribeWithSelectorOptions, createModel, shallow };