react-native-hox

面向 React Native 的极简状态管理：类型安全、API 零心智负担，单文件架构，包体积极小。

亮点

| 特性 | 说明 | |------|------| | 包体积极小 | 单入口构建，gzip 后 ESM ~1.5 KB / CJS ~1.6 KB；运行时仅依赖 use-sync-external-store，持久化可选依赖 AsyncStorage | | 类型安全 | 全 TypeScript，createModel 泛型推导完整，selector 与 setState 类型即文档 | | API 极简 | 一个 createModel 搞定：组件内用 Hook，组件外用 model.data，无需 Provider | | 按需重渲染 | 支持 selector + 可选 shallow，只在关注字段变化时更新组件 | | 可选持久化 | 内置 persist（默认 AsyncStorage），支持自定义 storage、防抖、迁移钩子 | | React 18 友好 | 基于 useSyncExternalStore，无 tearing，兼容并发渲染 |

快速开始

安装

npm i react-native-hox @react-native-async-storage/async-storage

项目中已有 @react-native-async-storage/async-storage 则无需重复安装。

最小示例

// stores/user.ts
import { createModel } from 'react-native-hox';

export const userStore = createModel({ name: 'Guest' });
// 持久化：createModel({ name: 'Guest' }, { persist: 'user_v1' });

// 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>
  );
}

功能概览

1) 更新状态：自动合并 / 显式替换

const profileStore = createModel({ name: 'Guest', role: 'user' as 'user' | 'admin' });

profileStore.setState({ name: 'Alice' });                    // 合并
profileStore.setState({ name: 'Bob', role: 'admin' }, true);  // 整体替换

2) Selector：只在关注数据变化时重渲染

const count = counterStore.getState((s) => s.count);
// 返回对象时建议用 shallow
const picked = counterStore.getState((s) => ({ count: s.count }), shallow);

3) 组件外读写：Vanilla API

const name = userStore.data.state.name;
userStore.data.getState();
userStore.data.subscribe((next, prev) => {});

4) 持久化

createModel({ token: '' }, { persist: 'auth_v1' });
// 或自定义 storage / beforeRecover / beforePersist
createModel({ token: '' }, { persist: { key: 'auth_v1', storage: myStorage } });

5) reset / destroy / strict

userStore.reset();
userStore.destroy();
createModel({ count: 0 }, { strict: { forbidSetStateAfterDestroy: true } });

进阶

subscribe(selector)：按 slice 订阅

userStore.data.subscribe(
  (s) => s.name,
  (next, prev) => console.log(next, prev),
  { fireImmediately: true }
);

持久化迁移

createModel(
  { token: '', isLogin: false },
  {
    persist: {
      key: 'user_v1',
      beforeRecover: (v) => ({ token: v?.token ?? '', isLogin: Boolean(v?.token) }),
    },
  }
);

初始状态用函数

createModel(() => ({ bootAt: Date.now() }));

API 简表

| 方法 / 属性 | 说明 | |-------------|------| | model() / model.getState() / model.use() / model.useState() | 组件内 Hook，可传 selector + equalityFn | | model.setState(partial, replace?) | 更新状态 | | model.data.state / model.data.getState() | 组件外读状态 | | model.data.setState / model.data.subscribe | 组件外写与订阅 | | model.reset() / model.destroy() | 重置为初始值、销毁 |

options：persist（string 或 { key, storage?, debounce?, beforePersist?, beforeRecover? }）、logger、strict.forbidSetStateAfterDestroy。

License

ISC