@e7w/easy-model 0.1.6 → 0.1.8

package/README.md

@@ -1,533 +1,233 @@
-# easy-model
-
-一个功能强大的 React 状态管理库，集成了状态管理、IoC 容器、观察者模式和加载器等功能。
-
-## 特性
-
-- 🚀 **简单易用** - 基于类的状态管理，直观的 API 设计
-- 🔄 **响应式** - 自动观察状态变化，精确更新组件
-- 💉 **IoC 容器** - 内置依赖注入容器，支持命名空间隔离
-- 🎯 **类型安全** - 完整的 TypeScript 支持，基于 Zod 的运行时类型验证
-- ⚡ **性能优化** - 智能缓存和垃圾回收机制
-- 🔧 **加载状态管理** - 内置异步操作加载状态管理
-- 🧩 **模块化** - 可按需使用各个功能模块
-
-## 安装
-
-```bash
-npm install @e7w/easy-model
-# 或
-yarn add @e7w/easy-model
-# 或
-pnpm add @e7w/easy-model
-```
-
-## 核心概念
-
-### 1. 状态管理
-
-基于类的状态管理，支持自动观察和响应式更新。
-
-```tsx
-import { useModel } from "@e7w/easy-model";
-
-class CounterModel {
-  constructor(public name: string) {}
-
-  count = 0;
-
-  increment() {
-    this.count++;
-  }
-
-  decrement() {
-    this.count--;
-  }
-
-  reset() {
-    this.count = 0;
-  }
-}
-
-function Counter() {
-  const { count, increment, decrement, reset } = useModel(CounterModel, [
-    "main",
-  ]);
-
-  return (
-    <div>
-      <h2>计数器: {count}</h2>
-      <button onClick={increment}>+1</button>
-      <button onClick={decrement}>-1</button>
-      <button onClick={reset}>重置</button>
-    </div>
-  );
-}
-```
-
-### 2. IoC 容器
-
-内置的依赖注入容器，支持值注入、构造函数注入和装饰器注入。
-
-```tsx
-import { Container, VInjection, CInjection, inject } from "@e7w/easy-model";
-import { z } from "zod";
-
-// 定义配置 schema
-const configSchema = z.object({
-  apiUrl: z.string(),
-  timeout: z.number(),
-});
-
-const loggerSchema = z.object({
-  log: z.function(),
-});
-
-// 定义服务类
-class Logger {
-  log(message: string) {
-    console.log(`[LOG] ${message}`);
-  }
-}
-
-class ApiService {
-  @inject(configSchema)
-  config: z.infer<typeof configSchema> = { apiUrl: "", timeout: 0 };
-
-  @inject(loggerSchema)
-  logger: Logger | undefined;
-
-  async fetchData() {
-    this.logger?.log(`Fetching data from ${this.config.apiUrl}`);
-    // 实际的 API 调用逻辑
-  }
-}
-
-function App() {
-  return (
-    <Container namespace="app">
-      {/* 注入配置值 */}
-      <VInjection
-        schema={configSchema}
-        val={{ apiUrl: "https://api.example.com", timeout: 5000 }}
-      />
-
-      {/* 注入构造函数 */}
-      <CInjection schema={loggerSchema} ctor={Logger} />
-
-      <YourComponents />
-    </Container>
-  );
-}
-```
-
-### 3. 观察者模式
-
-手动观察对象变化，适用于非 React 环境。注意：`observe` 函数是内部实现，不对外导出。
-
-```tsx
-import { watch } from "@e7w/easy-model";
-
-// 注意：observe 函数未导出，这里仅作为概念说明
-// 实际使用中，观察功能已集成在 useModel 和 useInstance 中
-
-// 监听对象变化的概念示例（实际需要通过 useModel 等方式）
-const unwatch = watch(someObservableObject, (path, oldValue, newValue) => {
-  console.log(`属性 ${path.join(".")} 从 ${oldValue} 变为 ${newValue}`);
-});
-
-// 取消监听
-unwatch();
-```
-
-### 4. 加载状态管理
-
-内置的异步操作加载状态管理，支持全局和局部加载状态。
-
-```tsx
-import { loader } from "@e7w/easy-model";
-
-class DataService {
-  data: any[] = [];
-
-  @loader.load(true) // true 表示全局加载状态
-  async fetchData() {
-    const response = await fetch("/api/data");
-    this.data = await response.json();
-    return this.data;
-  }
-
-  @loader.load() // 局部加载状态
-  async updateItem(id: string, updates: any) {
-    const response = await fetch(`/api/data/${id}`, {
-      method: "PUT",
-      body: JSON.stringify(updates),
-    });
-    return response.json();
-  }
-
-  @loader.once() // 只执行一次的异步操作
-  async initializeApp() {
-    // 初始化逻辑
-  }
-}
-
-function DataComponent() {
-  const service = useModel(DataService, []);
-  const { globalLoading } = useModel(loader, []);
-
-  return (
-    <div>
-      {globalLoading > 0 && <div>全局加载中...</div>}
-      <button onClick={() => service.fetchData()}>加载数据</button>
-      {service.data.map(item => (
-        <div key={item.id}>{item.name}</div>
-      ))}
-    </div>
-  );
-}
-```
-
-## API 参考
-
-### 状态管理
-
-#### `useModel<T>(Constructor: T, args: ConstructorParameters<T>): InstanceType<T>`
-
-创建或获取模型实例，自动观察状态变化并更新组件。
-
-**参数:**
-
-- `Constructor`: 模型类构造函数
-- `args`: 构造函数参数数组
-
-**返回值:** 模型实例，包含所有属性和方法
-
-#### `useInstance<T>(instance: T): T`
-
-直接使用现有实例，自动观察状态变化。
-
-**参数:**
-
-- `instance`: 要观察的对象实例
-
-**返回值:** 观察后的实例
-
-#### `provide<T>(Constructor: T): T`
-
-为类提供实例缓存和观察功能。
-
-**参数:**
-
-- `Constructor`: 要包装的类构造函数
-
-**返回值:** 包装后的构造函数，支持实例缓存
-
-### IoC 容器
-
-#### `Container`
-
-IoC 容器组件，提供依赖注入的上下文环境。
-
-**Props:**
-
-- `namespace?: string` - 命名空间，用于隔离不同的依赖注入环境
-- `children: ReactNode` - 子组件
-
-#### `VInjection<T>`
-
-值注入组件，将值注入到容器中。
-
-**Props:**
-
-- `schema: ZodType<T>` - Zod schema，用于类型验证
-- `val: T` - 要注入的值
-
-#### `CInjection<T>`
-
-构造函数注入组件，将构造函数注入到容器中。
-
-**Props:**
-
-- `schema: ZodType<T>` - Zod schema，用于类型验证
-- `ctor: new () => T` - 要注入的构造函数
-
-#### `inject<T>(schema: ZodType<T>, namespace?: string)`
-
-装饰器函数，用于从容器中注入依赖到类属性。
-
-**参数:**
-
-- `schema: ZodType<T>` - Zod schema，用于类型验证
-- `namespace?: string` - 可选的命名空间
-
-**返回值:** 装饰器函数
-
-### 观察者模式
-
-#### `watch(target: object, callback: WatchCallback): () => void`
-
-监听对象的变化。
-
-**参数:**
-
-- `target: object` - 要监听的对象
-- `callback: WatchCallback` - 变化时的回调函数
-
-**返回值:** 取消监听的函数
-
-**WatchCallback 类型:**
-
-```typescript
-type WatchCallback = (
-  path: Array<string | symbol>,
-  oldValue: any,
-  newValue: any
-) => void;
-```
-
-### 加载器
-
-#### `loader.load(isGlobal?: boolean)`
-
-异步方法装饰器，自动管理加载状态。
-
-**参数:**
-
-- `isGlobal?: boolean` - 是否影响全局加载状态，默认为 false
-
-**返回值:** 方法装饰器
-
-#### `loader.once()`
-
-确保异步方法只执行一次的装饰器。
-
-**返回值:** 方法装饰器
-
-#### `loader.isLoading(target: Function): boolean`
-
-检查指定方法是否正在加载中。
-
-**参数:**
-
-- `target: Function` - 要检查的方法
-
-**返回值:** 是否正在加载
-
-#### `loader.isGlobalLoading: boolean`
-
-获取全局加载状态。
-
-**返回值:** 是否有全局加载正在进行
-
-#### `loader.globalLoading: number`
-
-获取当前全局加载的数量。
-
-**返回值:** 正在进行的全局加载数量
-
-#### `finalizationRegistry(model: object)`
-
-为模型注册垃圾回收回调。
-
-**参数:**
-
-- `model: object` - 要监听垃圾回收的对象
-
-**返回值:** 包含 `register` 和 `unregister` 方法的对象
-
-## 高级用法
-
-### 组件间通信
-
-```tsx
-// 全局状态模型
-class AppState {
-  user: User | null = null;
-  theme: "light" | "dark" = "light";
-
-  setUser(user: User) {
-    this.user = user;
-  }
-
-  toggleTheme() {
-    this.theme = this.theme === "light" ? "dark" : "light";
-  }
-}
-
-// 在任何组件中使用
-function Header() {
-  const { user, theme, toggleTheme } = useModel(AppState, []);
-
-  return (
-    <header className={theme}>
-      <span>欢迎, {user?.name}</span>
-      <button onClick={toggleTheme}>切换主题</button>
-    </header>
-  );
-}
-
-function Sidebar() {
-  const { user } = useModel(AppState, []); // 同一个实例
-
-  return <aside>{user && <UserProfile user={user} />}</aside>;
-}
-```
-
-### 嵌套模型
-
-```tsx
-class UserModel {
-  constructor(public id: string) {}
-
-  name = "";
-  email = "";
-
-  updateProfile(data: Partial<UserModel>) {
-    Object.assign(this, data);
-  }
-}
-
-class TeamModel {
-  members: UserModel[] = [];
-
-  addMember(userId: string) {
-    const user = provide(UserModel)(userId);
-    this.members.push(user);
-  }
-
-  removeMember(userId: string) {
-    this.members = this.members.filter(m => m.id !== userId);
-  }
-}
-
-function TeamManagement() {
-  const team = useModel(TeamModel, ["team-1"]);
-
-  return (
-    <div>
-      <h2>团队成员</h2>
-      {team.members.map(member => (
-        <UserCard key={member.id} user={member} />
-      ))}
-    </div>
-  );
-}
-
-function UserCard({ user }: { user: UserModel }) {
-  const observedUser = useInstance(user);
-
-  return (
-    <div>
-      <span>{observedUser.name}</span>
-      <span>{observedUser.email}</span>
-    </div>
-  );
-}
-```
-
-### 命名空间隔离
-
-```tsx
-function App() {
-  return (
-    <div>
-      {/* 开发环境配置 */}
-      <Container namespace="dev">
-        <VInjection schema={configSchema} val={devConfig} />
-        <DevTools />
-      </Container>
-
-      {/* 生产环境配置 */}
-      <Container namespace="prod">
-        <VInjection schema={configSchema} val={prodConfig} />
-        <MainApp />
-      </Container>
-    </div>
-  );
-}
-```
-
-## 最佳实践
-
-### 1. 模型设计
-
-- **单一职责**: 每个模型类应该只负责一个特定的业务领域
-- **不可变更新**: 尽量使用不可变的方式更新状态
-- **类型安全**: 充分利用 TypeScript 的类型系统
-
-```tsx
-// ✅ 好的实践
-class UserModel {
-  constructor(public id: string) {}
-
-  private _profile: UserProfile | null = null;
-
-  get profile() {
-    return this._profile;
-  }
-
-  updateProfile(updates: Partial<UserProfile>) {
-    this._profile = { ...this._profile, ...updates };
-  }
-}
-
-// ❌ 避免的实践
-class BadModel {
-  // 避免在模型中直接操作 DOM
-  updateUI() {
-    document.getElementById("user-name")!.textContent = this.name;
-  }
-}
-```
-
-### 2. 依赖注入
-
-- **明确依赖**: 使用 Zod schema 明确定义依赖的类型
-- **命名空间**: 使用命名空间隔离不同环境的配置
-- **懒加载**: 只在需要时注入依赖
-
-### 3. 性能优化
-
-- **合理使用参数**: 相同参数会返回相同实例，利用这一点进行优化
-- **避免过度观察**: 不要观察不必要的对象
-- **及时清理**: 使用 `finalizationRegistry` 进行资源清理
-
-## 类型定义
-
-```typescript
-// 主要导出的类型
-export interface WatchCallback {
-  (path: Array<string | symbol>, oldValue: any, newValue: any): void;
-}
-
-export interface FinalizationRegistry {
-  register(callback: () => void): void;
-  unregister(): void;
-}
-
-export interface LoaderInstance {
-  loading: Record<symbol, [Function, Promise<unknown>]>;
-  globalLoading: number;
-  load(isGlobal?: boolean): MethodDecorator;
-  once(): MethodDecorator;
-}
-```
-
-## 兼容性
-
-- **React**: >= 17.0.0
-- **TypeScript**: >= 4.5.0
-- **Zod**: ^4.1.5
-
-## 许可证
-
-MIT License - 详见 [LICENSE.md](./LICENSE.md)
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
-## 更新日志
-
-详见 [CHANGELOG.md](./CHANGELOG.md)
+# easy-model
+
+轻量级的 React 状态管理与依赖注入库。
+
+easy-model 专注于在 React 中提供简洁、高效的状态管理，减少样板代码并保持良好的可组合性。
+
+---
+
+## 特性
+
+- 极简 API：基于 Hook 的使用方式，易上手、易迁移。
+- 依赖注入：内置简单的容器，支持按类型/命名空间注入与清理。
+- 响应式观察：`watch` 支持对对象变化进行监听并触发更新。
+- Loader：统一的异步数据加载与缓存机制，搭配 `useLoader` 使用。
+- 体积小、无侵入：适合大中小型项目或逐步引入到现有项目中。
+
+---
+
+## 安装
+
+推荐使用 `pnpm`：
+
+```bash
+pnpm add @e7w/easy-model
+```
+
+或使用 `npm` / `yarn`：
+
+```bash
+npm install @e7w/easy-model
+yarn add @e7w/easy-model
+```
+
+开发（安装依赖并运行测试）：
+
+```bash
+pnpm install
+pnpm test
+```
+
+（如需启动示例项目，使用 Vite 的 `pnpm dev`，请参考 `package.json` 脚本。）
+
+---
+
+## 快速上手（React）
+
+下面演示核心用法，适合在函数组件中使用：
+
+```tsx
+import React from "react";
+import {
+  provide,
+  useModel,
+  loader,
+  useLoader,
+  inject,
+  watch,
+} from "easy-model";
+
+class Counter {
+  count = 0;
+}
+
+// 组件中读取并响应模型变化
+function Counter() {
+  const model = useModel(Counter, []);
+  return (
+    <div>
+      <button onClick={() => model.count--}>-</button>
+      <span>{model.count}</span>
+      <button onClick={() => model.count++}>+</button>
+    </div>
+  );
+}
+
+// 异步 loader 示例
+class Photos {
+  @loader.load(true)
+  data = [];
+  async fetcher() {
+    const res = await fetch("/api/photos");
+    this.data = res.json();
+  }
+}
+
+function Gallery() {
+  const { data, fetcher } = useModel(Photos, []);
+  const { isGlobalLoading, isLoading } = useLoader();
+  useEffect(() => {
+    fetcher();
+  }, [fetcher]);
+  if (isGlobalLoading) return <div>全局loading</div>;
+  if (isLoading(fetcher)) return <div>本函数loading...</div>;
+  return (
+    <ul>
+      {data.map((p: any) => (
+        <li key={p.id}>{p.title}</li>
+      ))}
+    </ul>
+  );
+}
+
+// 依赖注入示例（类/服务）
+const schema = object({
+  number: number(),
+}).describe("测试用schema");
+const schema2 = object({
+  xxx: number(),
+}).describe("Test类的schema");
+
+class Test {
+  xxx = 1;
+}
+class MFoo {
+  @inject(schema)
+  bar?: Infer<typeof schema>;
+  baz?: number;
+  @inject(schema2)
+  qux?: Infer<typeof schema2>;
+}
+
+config(
+  <>
+    <Container>
+      <CInjection schema={schema2} ctor={Test} />
+      <VInjection
+        schema={schema}
+        val={{
+          number: 100,
+        }}
+      />
+    </Container>
+  </>
+);
+
+const Foo = provide(MFoo);
+let foo: MFoo | undefined = Foo();
+foo.baz = 20;
+document.writeln(JSON.stringify(foo.bar));
+document.writeln(String(foo.baz));
+document.writeln(JSON.stringify(foo.qux));
+```
+
+更多示例见项目自带的 [example](example).
+
+---
+
+## API（概览）
+
+- `watch` — 响应式监听函数。
+- `provide`, `finalizationRegistry` — 提供和清理模型/服务。
+- `useModel`, `useInstance`, `useWatcher` — React Hook，用于绑定模型或自定义观察者。
+- `loader`, `useLoader` — 异步加载器与 Hook。
+- `Container`, `CInjection`, `VInjection`, `inject`, `clearNamespace`, `isRegistered`, `config` — IoC/容器与注入相关工具。
+
+---
+
+## 与常见库对比（简要）
+
+- Redux：
+  - Redux 适合大型、严格的全局状态管理，具有强大的中间件生态，但模板代码较多（actions/reducers）。
+  - easy-model 更轻量，基于对象与 Hook，适合快速开发，整合 DI 和 loader，减少样板代码。
+
+- MobX：
+  - MobX 提供细粒度响应式，学习曲线较低。easy-model 提供类似的响应式监听器和 Hook，但 API 更显式，集成 DI 更方便。
+
+- Zustand：
+  - Zustand 也很小巧，以 store 函数为中心。easy-model 的优势在于：内建依赖注入、loader 管理与更直接的对象模型（常见类/实例注入更友好）。
+
+- React Context：
+  - Context 适合简单传递，性能需配合 memo/selector 优化。easy-model 提供专门的 Hook 与内部优化，减少组件重新渲染并支持按需注入。
+
+总的来说，easy-model 的优势可以概括为：
+
+- **组合性强**：同一套模型既可以作为 React 状态容器，又可以作为依赖注入的服务，还可以挂载 loader / watch 等逻辑，减少在多个库之间来回穿梭。
+- **API 简单、一致**：以“类 + Hook”为中心（`useModel` / `useInstance`），不需要额外的 action、reducer 或复杂的装饰器配置，迁移成本低。
+- **性能可接受且易优化**：在典型的批量更新场景中，相比 Redux 有数量级的性能优势，同时通过内部的批量调度与轻量级响应式实现，保证在多数业务场景下不会成为性能瓶颈。
+- **渐进式引入友好**：无需改造全局 store，可以从单个模块/页面开始使用模型类和 Hook，逐步替换原有状态管理方案。
+
+### 简单 benchmark 结论
+
+项目在 `example/benchmark.tsx` 中提供了一个**粗略的**对比示例，核心场景为：
+
+- 初始化一个包含 10,000 个数字的数组；
+- 点击按钮后，对所有元素做 5 轮自增；
+- 使用 `performance.now()` 统计这段同步计算与状态写入时间（不计入 React 首屏渲染）。
+
+在一台常规开发机上的一次测试结果（单位：ms，取单次运行的代表值）大致如下：
+
+| 实现       | 耗时（ms） | 说明                                |
+| ---------- | ---------- | ----------------------------------- |
+| easy-model | ≈ 3.1      | 基于类实例 + `observe` 的响应式模型 |
+| Redux      | ≈ 51.5     | `createSlice` + Immer 不可变更新    |
+| MobX       | ≈ 16.9     | `makeAutoObservable` + observer     |
+| Zustand    | ≈ 0.6      | 极简 store 函数实现                 |
+
+从这个场景可以得到几个结论（仅作趋势参考）：
+
+- **对比 Redux**：easy-model 在该批量场景中大约比 Redux 快一个数量级（\~3ms vs \~50ms），同时完全避免了 action / reducer 等模板代码，更新路径更直接。
+- **对比 MobX**：easy-model 与 MobX 属于同一数量级，前者以更简单的 Hook API + DI/loader 一体化为主打，后者在响应式生态上更成熟。
+- **对比 Zustand**：Zustand 在这个极简数组场景下可以做到非常小的开销；easy-model 并不以“单一场景下绝对最快”为目标，而是在保持性能可接受的前提下，提供更丰富的能力组合（依赖注入、loader、watch 等）。
+
+整体来说：
+
+- 在常见的批量更新场景里，**easy-model 相比 Redux 有明显的性能和开发体验优势**；
+- 与 MobX / Zustand 相比，easy-model 的优势更多体现在**组合能力与 API 一致性**：一套模型可以同时承担状态管理、依赖注入和异步加载，而不需要在多个库之间来回切换。
+
+> 说明：该 benchmark 仅为示例级别，不是严谨的基准测试。不同设备、浏览器和实现细节都会显著影响具体数值，建议按需 clone 仓库后自行在本地运行 `pnpm dev`，并在示例页面的 “Benchmark” 区块里手动对比。
+
+---
+
+## 开发 & 测试
+
+运行测试：
+
+```bash
+pnpm install
+pnpm test
+```
+
+查看示例：打开 `example/index.tsx` 并参考 `vite`/`npm` 脚本运行本地示例（一般为 `pnpm dev`）。
+
+---
+
+## 贡献
+
+欢迎提交 issue 和 PR。请遵循项目的代码风格与测试约定。若要运行或修改示例，请先安装依赖并运行 `pnpm test` 验证现有用例。
+
+---
+
+## 许可证
+
+MIT