react-native-hox 0.0.1 → 0.0.2

package/README.md

@@ -1,168 +1,204 @@
 # react-native-hox
 
-> **下一代 React Native 状态管理方案。**
-> 极简、高性能、生产级特性开箱即用。
+面向 React Native 的轻量状态管理方案：类型安全、API 极简，支持组件内 Hook 与组件外 Vanilla 读写，并内置可选持久化能力。
 
 [![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)
+[![License](https://img.shields.io/npm/l/react-native-hox)](https://www.npmjs.com/package/react-native-hox)
 
-## 为什么选择 Hox？
+## 快速开始
 
-在 React Native 开发中，我们经常在 Redux 的繁琐、Context 的性能陷阱和 Zustand 的手动配置之间挣扎。
+### 安装
 
-`react-native-hox` 重新思考了移动端状态管理的最佳实践，提供了一种**"零配置、全功能"**的开发体验。它不仅是一个状态库，更内置了移动端开发必不可少的工程化能力。
+```bash
+npm i react-native-hox
+```
 
-### 核心亮点
+### 最小示例
 
-*   ⚡️ **零样板代码**：告别 Action、Reducer、Provider。一行代码即可创建全局状态。
-*   💾 **智能持久化**：内置异步存储支持。只需配置 `persist` key，自动处理防抖写入与初始化读取。
-*   🧬 **自动合并 (Auto-Merge)**：延续 `setState` 的直觉体验，自动合并对象属性，无需手动 spread `...state`。
-*   🎯 **精准渲染**：支持 Selector 选择器，确保组件仅在关注的数据变化时更新。
-*   🔌 **脱离组件运行**：完整的 Vanilla API，支持在 Axios 拦截器、事件回调等非组件环境读写状态。
+```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
+```
 
-## 快速开始
+```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>
+  );
+}
+```
 
-```bash
-npm install react-native-hox
-# or
-yarn add react-native-hox
+## 功能点
+
+### 1) 更新状态：自动合并 / 显式替换
+
+```ts
+import { createModel } from 'react-native-hox';
+
+export const profileStore = createModel({ name: 'Guest', role: 'user' as 'user' | 'admin' });
 ```
 
-### 1. 基础用法：全局状态 (Global Store)
+```tsx
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import { profileStore } from './stores/profile';
 
-适用于：用户信息、应用配置、Token 管理等。
+export function UpdateExample() {
+  const profile = profileStore.getState();
 
-```typescript
-// store/user.ts
+  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：只在关注的数据变化时重渲染
+
+```ts
 import { createModel } from 'react-native-hox';
 
-// 创建一个自动持久化的用户 Store
-export const userStore = createModel({
-  name: 'Guest',
-  token: '',
-  isLogin: false,
-}, {
-  persist: 'user_v1', // 开启持久化，数据自动存入 AsyncStorage/localStorage
-});
+export const counterStore = createModel({ count: 0, text: 'a' });
 ```
 
 ```tsx
-// components/UserProfile.tsx
-import { userStore } from '../store/user';
-
-export default function UserProfile() {
-  // 1. 读取状态 (Hook)
-  // 支持传入 selector，仅在关注的属性变化时重渲染
-  const name = userStore.getState(s => s.name);
-
-  const login = () => {
-    // 2. 更新状态：自动合并，无需 ...user
-    userStore.setState({ 
-      name: 'Admin', 
-      isLogin: true 
-    });
-  };
+import React from 'react';
+import { View, Text, Button } from 'react-native';
+import { counterStore } from './stores/counter';
+
+export function SelectorExample() {
+  const count = counterStore.getState((s) => s.count);
 
   return (
     <View>
-      <Text>Hello, {name}</Text>
-      <Button onPress={login} title="Login" />
+      <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>
   );
 }
 ```
 
-### 2. 进阶用法：精细控制 (Selector & Reset)
+当 selector 返回对象/数组时，传入 `equalityFn`（例如 `shallow`）避免无意义重渲染：
 
 ```tsx
-  // 只有当 count > 10 发生变化时，组件才会重渲染
-  const isHigh = userStore.getState(state => state.count > 10);
-  
-  // 重置状态为初始值
-  userStore.reset();
-  ```
+import { shallow } from 'react-native-hox';
+import { counterStore } from './stores/counter';
+
+const picked = counterStore.getState((s) => ({ count: s.count }), shallow);
+```
 
----
+### 3) 组件外读写：Vanilla API
 
-## 解决痛点
+```ts
+import { userStore } from './stores/user';
 
-### 痛点 1：持久化配置太麻烦
-**以前**：安装中间件 -> 配置白名单 -> 处理 Hydration -> 处理防抖。
-**现在**：
+const name1 = userStore.data.state.name;
+const name2 = userStore.data.getState().name;
 
-```typescript
-const store = createModel({ theme: 'dark' }, { 
-  persist: 'app_theme' // ✅ Done. 自动防抖，自动恢复。
+const unsub = userStore.data.subscribe((next, prev) => {
+  console.log(next, prev);
 });
+unsub();
 ```
 
-### 痛点 2：非组件环境无法访问状态
-**以前**：为了在 API 拦截器里拿 Token，不得不把 store 挂载到 window 或者引入复杂的 hack。
-**现在**：
+### 4) 持久化：persist（默认 AsyncStorage）
 
-```typescript
-// api.ts
-import { userStore } from './store/user';
+只要提供一个 key 即可开启持久化（默认使用 `@react-native-async-storage/async-storage`，无需重复传 `storage`）：
 
-axios.interceptors.request.use(config => {
-  // ✅ 直接读取最新状态
-  const token = userStore.data.state.token;
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`;
-  }
-  return config;
-});
+```ts
+import { createModel } from 'react-native-hox';
+
+export const authStore = createModel({ token: '' }, { persist: 'auth_v1' });
+```
 
-// 甚至可以直接修改
-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.storage` 传入实现同等接口的存储对象：
 
-## 生产实践
+```ts
+import { createModel } from 'react-native-hox';
+import type { StorageEngine } from 'react-native-hox';
 
-### 1) Token 管理：拦截器读取 + 401 统一登出
+const storage: StorageEngine = {
+  getItem: async (key) => null,
+  setItem: async (key, value) => {},
+  removeItem: async (key) => {},
+};
+
+export const authStore = createModel({ token: '' }, { persist: { key: 'auth_v1', storage } });
+```
+
+### 5) reset / destroy / strict
 
 ```ts
-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;
-});
+import { userStore } from './stores/user';
 
-axios.interceptors.response.use(
-  (resp) => resp,
-  (err) => {
-    if (err?.response?.status === 401) {
-      userStore.setState({ token: '', isLogin: false });
-    }
-    return Promise.reject(err);
-  }
+userStore.reset();
+userStore.destroy();
+```
+
+```ts
+import { createModel } from 'react-native-hox';
+
+export const strictStore = createModel(
+  { count: 0 },
+  { strict: { forbidSetStateAfterDestroy: true } }
 );
 ```
 
-### 2) 持久化：推荐的安全边界
+## 进阶使用
 
-*   `persist` 的恢复是异步的：首屏会先用 `initialState`，恢复完成后再更新一次。
-*   强烈建议把版本号编码进 key（如 `user_v1`），避免不可控的 schema 变化。
-*   需要兼容旧数据时，用 `beforeRecover` 做兜底转换。
+### 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
-export const userStore = createModel(
+import { createModel } from 'react-native-hox';
+
+export const userPersistStore = createModel(
   { token: '', isLogin: false },
   {
     persist: {
@@ -176,37 +212,28 @@ export const userStore = createModel(
 );
 ```
 
-### 3) Selector 性能：避免无意义重渲染
+### 3) initialState 支持纯函数
 
-*   selector 尽量返回 primitive（string/number/boolean）或稳定引用。
-*   如果 selector 返回对象/数组，传入 `equalityFn`（例如 `shallow`）以避免每次新建对象触发重渲染。
-
-```tsx
-import { shallow } from 'react-native-hox';
+```ts
+import { createModel } from 'react-native-hox';
 
-const user = userStore.getState((s) => ({ name: s.name, isLogin: s.isLogin }), shallow);
+export const appStore = createModel(() => ({ bootAt: Date.now() }));
 ```
 
-## API 参考
+## API 参考（简版）
 
 ### `createModel(initialState, options?)`
 
-创建全局 Store。
-
-*   `initialState`: 初始状态对象，或返回初始状态的纯函数。
-*   `options`:
-    *   `persist`: `string` (可选) - 持久化存储的唯一 Key。
+- `initialState`: `T` 或 `() => T`
+- `options.persist`: `string` 或 `{ key, storage?, debounce?, beforePersist?, beforeRecover? }`
+- `options.strict.forbidSetStateAfterDestroy`: `boolean`
+- `options.logger`: `{ warn, error }`
 
-返回 `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`。
+返回的 `Model` 同时支持：
 
----
+- 组件内（Hook）：`model.getState()` / `model.use()` / `model.useState()`
+- 组件外（Vanilla）：`model.data.state` / `model.data.getState()` / `model.data.setState()` / `model.data.subscribe()`
 
 ## License
 
-MIT
+ISC

package/dist/index.d.mts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,43 +1,23 @@
 'use strict';
 
 var useSyncExternalStoreExports = require('use-sync-external-store/shim/with-selector');
+var AsyncStorage = require('@react-native-async-storage/async-storage');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var useSyncExternalStoreExports__default = /*#__PURE__*/_interopDefault(useSyncExternalStoreExports);
+var AsyncStorage__default = /*#__PURE__*/_interopDefault(AsyncStorage);
 
 // src/createModel.ts
 
-// src/config.ts
-var cachedDefaultWebStorage;
-var hasCachedDefaultWebStorage = false;
-function getDefaultWebStorage() {
-  if (hasCachedDefaultWebStorage) {
-    return cachedDefaultWebStorage;
-  }
-  hasCachedDefaultWebStorage = true;
-  try {
-    const anyGlobal = globalThis;
-    const storage = anyGlobal == null ? void 0 : anyGlobal.localStorage;
-    if (!storage) {
-      return void 0;
-    }
-    const testKey = "__react_native_hox_test__";
-    storage.setItem(testKey, "1");
-    storage.removeItem(testKey);
-    cachedDefaultWebStorage = {
-      getItem: (key) => storage.getItem(key),
-      setItem: (key, value) => storage.setItem(key, value),
-      removeItem: (key) => storage.removeItem(key)
-    };
-    return cachedDefaultWebStorage;
-  } catch {
-    cachedDefaultWebStorage = void 0;
-    return void 0;
+// src/vanilla.ts
+function isPlainObject(value) {
+  if (Object.prototype.toString.call(value) !== "[object Object]") {
+    return false;
   }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
 }
-
-// src/vanilla.ts
 var createStore = (initialState) => {
   let state = initialState;
   const listeners = /* @__PURE__ */ new Set();
@@ -45,7 +25,8 @@ var createStore = (initialState) => {
     const nextState = typeof partial === "function" ? partial(state) : partial;
     if (!Object.is(nextState, state)) {
       const previousState = state;
-      state = (replace != null ? replace : typeof nextState !== "object" || nextState === null) ? nextState : Object.assign({}, state, nextState);
+      const shouldReplace = replace != null ? replace : !isPlainObject(state) || !isPlainObject(nextState);
+      state = shouldReplace ? nextState : Object.assign({}, state, nextState);
       listeners.forEach((listener) => listener(state, previousState));
     }
   };
@@ -216,7 +197,7 @@ function setupModelSideEffects(store, options, logger) {
   var _a, _b, _c, _d;
   const persist = typeof (options == null ? void 0 : options.persist) === "string" ? { key: options.persist } : options == null ? void 0 : options.persist;
   const persistKey = persist == null ? void 0 : persist.key;
-  const storage = (_a = persist == null ? void 0 : persist.storage) != null ? _a : getDefaultWebStorage();
+  const storage = (_a = persist == null ? void 0 : persist.storage) != null ? _a : AsyncStorage__default.default;
   if (!persistKey) {
     return;
   }
@@ -225,7 +206,7 @@ function setupModelSideEffects(store, options, logger) {
   const debounceMs = (_d = persist == null ? void 0 : persist.debounce) != null ? _d : 100;
   if (!storage) {
     logger.warn(
-      "[react-native-hox] persist \u5DF2\u5F00\u542F\u4F46 storage \u4E0D\u53EF\u7528\uFF1AWeb \u9700\u8981 localStorage \u53EF\u7528\uFF1BReact Native/Node \u8BF7\u5728 persist.storage \u4F20\u5165 AsyncStorage/MMKV \u7B49\u3002"
+      "[react-native-hox] persist \u5DF2\u5F00\u542F\u4F46 storage \u4E0D\u53EF\u7528\uFF1A\u8BF7\u5728 persist.storage \u4F20\u5165 AsyncStorage/MMKV \u7B49\u3002"
     );
     return;
   }

package/dist/index.mjs

@@ -1,37 +1,16 @@
 import useSyncExternalStoreExports from 'use-sync-external-store/shim/with-selector';
+import AsyncStorage from '@react-native-async-storage/async-storage';
 
 // src/createModel.ts
 
-// src/config.ts
-var cachedDefaultWebStorage;
-var hasCachedDefaultWebStorage = false;
-function getDefaultWebStorage() {
-  if (hasCachedDefaultWebStorage) {
-    return cachedDefaultWebStorage;
-  }
-  hasCachedDefaultWebStorage = true;
-  try {
-    const anyGlobal = globalThis;
-    const storage = anyGlobal == null ? void 0 : anyGlobal.localStorage;
-    if (!storage) {
-      return void 0;
-    }
-    const testKey = "__react_native_hox_test__";
-    storage.setItem(testKey, "1");
-    storage.removeItem(testKey);
-    cachedDefaultWebStorage = {
-      getItem: (key) => storage.getItem(key),
-      setItem: (key, value) => storage.setItem(key, value),
-      removeItem: (key) => storage.removeItem(key)
-    };
-    return cachedDefaultWebStorage;
-  } catch {
-    cachedDefaultWebStorage = void 0;
-    return void 0;
+// src/vanilla.ts
+function isPlainObject(value) {
+  if (Object.prototype.toString.call(value) !== "[object Object]") {
+    return false;
   }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
 }
-
-// src/vanilla.ts
 var createStore = (initialState) => {
   let state = initialState;
   const listeners = /* @__PURE__ */ new Set();
@@ -39,7 +18,8 @@ var createStore = (initialState) => {
     const nextState = typeof partial === "function" ? partial(state) : partial;
     if (!Object.is(nextState, state)) {
       const previousState = state;
-      state = (replace != null ? replace : typeof nextState !== "object" || nextState === null) ? nextState : Object.assign({}, state, nextState);
+      const shouldReplace = replace != null ? replace : !isPlainObject(state) || !isPlainObject(nextState);
+      state = shouldReplace ? nextState : Object.assign({}, state, nextState);
       listeners.forEach((listener) => listener(state, previousState));
     }
   };
@@ -210,7 +190,7 @@ function setupModelSideEffects(store, options, logger) {
   var _a, _b, _c, _d;
   const persist = typeof (options == null ? void 0 : options.persist) === "string" ? { key: options.persist } : options == null ? void 0 : options.persist;
   const persistKey = persist == null ? void 0 : persist.key;
-  const storage = (_a = persist == null ? void 0 : persist.storage) != null ? _a : getDefaultWebStorage();
+  const storage = (_a = persist == null ? void 0 : persist.storage) != null ? _a : AsyncStorage;
   if (!persistKey) {
     return;
   }
@@ -219,7 +199,7 @@ function setupModelSideEffects(store, options, logger) {
   const debounceMs = (_d = persist == null ? void 0 : persist.debounce) != null ? _d : 100;
   if (!storage) {
     logger.warn(
-      "[react-native-hox] persist \u5DF2\u5F00\u542F\u4F46 storage \u4E0D\u53EF\u7528\uFF1AWeb \u9700\u8981 localStorage \u53EF\u7528\uFF1BReact Native/Node \u8BF7\u5728 persist.storage \u4F20\u5165 AsyncStorage/MMKV \u7B49\u3002"
+      "[react-native-hox] persist \u5DF2\u5F00\u542F\u4F46 storage \u4E0D\u53EF\u7528\uFF1A\u8BF7\u5728 persist.storage \u4F20\u5165 AsyncStorage/MMKV \u7B49\u3002"
     );
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-hox",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "一个轻量级、类型安全、零心智负担的 React Native 状态管理解决方案。",
   "keywords": [
     "react-native",
@@ -45,11 +45,12 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@react-native-async-storage/async-storage": "^2.2.0",
     "use-sync-external-store": "^1.6.0"
   },
   "peerDependencies": {
     "react": ">=16.8",
-    "react-native": ">=0.64"
+    "react-native": ">=0.65"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",