react-native-hox 0.0.1-beta → 0.0.2

package/README.md

@@ -1,139 +1,239 @@
 # react-native-hox
 
-**为复杂业务场景而生的状态管理解决方案**。
+面向 React Native 的轻量状态管理方案：类型安全、API 极简，支持组件内 Hook 与组件外 Vanilla 读写，并内置可选持久化能力。
 
-我们把 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://www.npmjs.com/package/react-native-hox)
 
----
+## 快速开始
 
-## 核心特性
+### 安装
 
-*   **一个 API**：`createModel` 创建全局模型。
-*   **组件内/外都能用**：组件内 `model()` / `model(selector)` 订阅更新；组件外用 `model.data / model.getState()` 获取最新快照（不触发渲染）。
-*   **内置优化**：对象更新自动合并、无变化不更新（减少无意义重渲染）。
-*   **生产力优先**：可选持久化（Persist）、可选 Web 多窗口同步（BroadcastChannel）。
+```bash
+npm i react-native-hox
+```
 
----
+### 最小示例
 
-## 快速上手（推荐）
+```ts
+// stores/user.ts
+import { createModel } from 'react-native-hox';
 
-### 安装
+export const userStore = createModel({ name: 'Guest' }); // 数据只存在内存
+// export const userStore = createModel({ name: 'Guest' }, { persist: 'user_v1' }); // 数据存在缓存 AsyncStorage
+```
 
-```bash
-npm install react-native-hox
-# or
-yarn add react-native-hox
+```tsx
+// Profile.tsx
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import { userStore } from './stores/user';
+
+export function Profile() {
+  const user = userStore.getState();
+  return (
+    <View>
+      <Text>Hello, {user.name}</Text>
+      <Button title="Set Name" onPress={() => userStore.setState({ name: 'Tom' })} />
+    </View>
+  );
+}
 ```
 
-### 创建一个全局模型
+## 功能点
 
-适用于用户信息、全局配置、表单草稿、token 等场景。
-**完全不需要 Provider，也不需要修改入口文件。**
+### 1) 更新状态：自动合并 / 显式替换
 
-```tsx
-// store.ts
+```ts
 import { createModel } from 'react-native-hox';
 
-// 定义一个支持持久化的用户状态
-// createModel(initialState, options?)
-export const userModel = createModel({
-  name: 'Guest',
-  token: '',
-  theme: 'light'
-}, {
-  persist: 'user_store', // 开启持久化，自动写入 Storage
-});
+export const profileStore = createModel({ name: 'Guest', role: 'user' as 'user' | 'admin' });
+```
+
+```tsx
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import { profileStore } from './stores/profile';
 
-// 推荐：在组件内使用 useXxxModel 作为 Hook 别名（同一个对象）
-// 这样更符合 Hook 心智模型，也能被 eslint-plugin-react-hooks 正确识别
-export const useUserModel = userModel;
+export function UpdateExample() {
+  const profile = profileStore.getState();
+
+  return (
+    <View>
+      <Text>{profile.name}</Text>
+      <Text>{profile.role}</Text>
+      <Button title="Merge Update" onPress={() => profileStore.setState({ name: 'Alice' })} />
+      <Button title="Replace" onPress={() => profileStore.setState({ name: 'Bob', role: 'admin' }, true)} />
+    </View>
+  );
+}
 ```
 
-**组件中使用：**
+### 2) Selector：只在关注的数据变化时重渲染
 
-```tsx
-import { useUserModel } from './store';
+```ts
+import { createModel } from 'react-native-hox';
+
+export const counterStore = createModel({ count: 0, text: 'a' });
+```
 
-function UserProfile() {
-  // 直接调用 model() 获取响应式 state
-  const user = useUserModel.useState();
+```tsx
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import { counterStore } from './stores/counter';
 
-  const login = () => {
-    // 自动合并更新：只更新 token 和 name，theme 保持不变
-    useUserModel.setState({ 
-      token: 'xyz', 
-      name: 'User' 
-    });
-  };
+export function SelectorExample() {
+  const count = counterStore.getState((s) => s.count);
 
   return (
     <View>
-      <Text>{user.name}</Text>
-      <Button onPress={login}>Login</Button>
+      <Text>{count}</Text>
+      <Button title="Inc" onPress={() => counterStore.setState((s) => ({ count: s.count + 1 }))} />
+      <Button title="Change Text" onPress={() => counterStore.setState({ text: String(Math.random()) })} />
     </View>
   );
 }
 ```
 
-> 说明：组件渲染是否更新，取决于你是否用 `useUserModel.useState()` / `useUserModel.useState(selector)`（或直接 `useUserModel()`）订阅了状态；`userModel.data` / `useUserModel.data` 是快照不会触发渲染。`setState` 如果没有真正改变值会被自动忽略（减少无意义重渲染）。
+当 selector 返回对象/数组时，传入 `equalityFn`（例如 `shallow`）避免无意义重渲染：
 
-**什么时候用 `useXxxModel()` / `getState()` / `data`？**
+```tsx
+import { shallow } from 'react-native-hox';
+import { counterStore } from './stores/counter';
 
-- 组件渲染里：用 `useUserModel.useState()`（或 `useUserModel.useState(s => s.token)`），它会订阅更新，状态变了组件会跟着重渲染
-- 组件外（网络请求拦截器、工具函数、非 React 环境）：用 `userModel.getState()` / `userModel.data` 读取最新快照，或 `userModel.subscribe(...)` 订阅
-- 不建议在组件渲染里用 `useUserModel.getState()` / `useUserModel.data`：它们是“快照读取”，不会触发组件更新，容易出现 UI 不刷新
+const picked = counterStore.getState((s) => ({ count: s.count }), shallow);
+```
 
-**组件外使用：**
+### 3) 组件外读写：Vanilla API
 
 ```ts
-import { userModel } from './store';
+import { userStore } from './stores/user';
+
+const name1 = userStore.data.state.name;
+const name2 = userStore.data.getState().name;
 
-// 在 Axios 拦截器中读取 Token
-axios.interceptors.request.use(config => {
-  const { token } = userModel.data; // 直接获取最新快照（非 Hook）
-  if (token) config.headers.Authorization = token;
-  return config;
+const unsub = userStore.data.subscribe((next, prev) => {
+  console.log(next, prev);
 });
+unsub();
+```
 
-// 在任意函数中更新状态
-export function logout() {
-  userModel.setState({ token: '', name: 'Guest' });
-}
+### 4) 持久化：persist（默认 AsyncStorage）
+
+只要提供一个 key 即可开启持久化（默认使用 `@react-native-async-storage/async-storage`，无需重复传 `storage`）：
+
+```ts
+import { createModel } from 'react-native-hox';
+
+export const authStore = createModel({ token: '' }, { persist: 'auth_v1' });
 ```
 
----
+如果你希望替换存储引擎，可以在 `persist.storage` 传入实现同等接口的存储对象：
+
+```ts
+import { createModel } from 'react-native-hox';
+import type { StorageEngine } from 'react-native-hox';
 
-## 全局配置（可选）
+const storage: StorageEngine = {
+  getItem: async (key) => null,
+  setItem: async (key, value) => {},
+  removeItem: async (key) => {},
+};
 
-`persist` 默认会使用 **Web 端的 `localStorage`（零配置）**。在 React Native 环境没有默认持久化存储，需要你通过 `setup` 注入（也可以用 `setup` 覆盖 Web 默认实现）。
+export const authStore = createModel({ token: '' }, { persist: { key: 'auth_v1', storage } });
+```
+
+### 5) reset / destroy / strict
 
 ```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 { userStore } from './stores/user';
+
+userStore.reset();
+userStore.destroy();
 ```
 
-## 高级特性
+```ts
+import { createModel } from 'react-native-hox';
+
+export const strictStore = createModel(
+  { count: 0 },
+  { strict: { forbidSetStateAfterDestroy: true } }
+);
+```
 
-### Web 端多窗口同步
+## 进阶使用
 
-如果你在使用 `react-native-web`，或者在 WebView 场景下需要多 Tab 状态同步，可以开启 `sync` 选项。
+### 1) subscribe(selector)：只在 slice 变化时触发
+
+```tsx
+import React, { useEffect } from 'react';
+import { View, Text } from 'react-native';
+import { userStore } from './stores/user';
+
+export function SubscribeExample() {
+  const name = userStore.getState((s) => s.name);
+
+  useEffect(() => {
+    const unsub = userStore.data.subscribe(
+      (s) => s.name,
+      (next, prev) => {
+        console.log('name changed:', prev, '->', next);
+      },
+      { fireImmediately: true }
+    );
+    return unsub;
+  }, []);
+
+  return (
+    <View>
+      <Text>{name}</Text>
+    </View>
+  );
+}
+```
+
+### 2) 持久化安全边界：版本化与数据迁移
 
 ```ts
-const userModel = createModel({ ... }, {
-  persist: 'user',
-});
+import { createModel } from 'react-native-hox';
+
+export const userPersistStore = createModel(
+  { token: '', isLogin: false },
+  {
+    persist: {
+      key: 'user_v1',
+      beforeRecover: (v) => ({
+        token: v?.token ?? '',
+        isLogin: Boolean(v?.token),
+      }),
+    },
+  }
+);
+```
+
+### 3) initialState 支持纯函数
+
+```ts
+import { createModel } from 'react-native-hox';
+
+export const appStore = createModel(() => ({ bootAt: Date.now() }));
 ```
+
+## API 参考（简版）
+
+### `createModel(initialState, options?)`
+
+- `initialState`: `T` 或 `() => T`
+- `options.persist`: `string` 或 `{ key, storage?, debounce?, beforePersist?, beforeRecover? }`
+- `options.strict.forbidSetStateAfterDestroy`: `boolean`
+- `options.logger`: `{ warn, error }`
+
+返回的 `Model` 同时支持：
+
+- 组件内（Hook）：`model.getState()` / `model.use()` / `model.useState()`
+- 组件外（Vanilla）：`model.data.state` / `model.data.getState()` / `model.data.setState()` / `model.data.subscribe()`
+
+## License
+
+ISC

package/dist/index.d.mts

@@ -1,4 +1,9 @@
 type Listener<T> = (state: T, prevState: T) => void;
+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 EqualityFn<T> = (a: T, b: T) => boolean;
 
 type Selector<T, U> = (state: T) => U;
@@ -8,58 +13,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,4 +1,9 @@
 type Listener<T> = (state: T, prevState: T) => void;
+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 EqualityFn<T> = (a: T, b: T) => boolean;
 
 type Selector<T, U> = (state: T) => U;
@@ -8,58 +13,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 };