Mobius Model

Overview

对象定位： Mobius Model 是面向 JavaScript 和 TypeScript 生态的建模导向通用基础库（modeling-oriented general-purpose foundation library），由一组可复用、可组合的基础模型模块构成。

存在目的： 应用和库会反复遇到可跨业务复用的问题域能力。Mobius Model 将值得长期维护的能力建模为边界清楚的模块，减少各项目临时拼装相似基础能力的需要。

提供能力： 包含基础数据模型、反应式状态、事件、请求、表单、路由、时间、网络通信、界面组件等模块，并通过适合不同运行环境的公开入口提供这些能力。

职责边界： 各模块表达稳定的问题域和公共语义，尽量不依赖具体业务前提。接入时仍需按运行环境处理兼容性；具体业务模型和流程由使用方负责。

For Understanding

应用和库会反复遇到相似的问题域能力。如果这些能力始终由各个业务代码单独拼装，名称、语义和边界容易随具体项目变化，后续也难以跨项目复用。Mobius Model 将其中值得长期维护的能力组织为模块，以稳定的问题域和公共语义承载。

模块可以按需接入和组合，不要求整体引入。判断能力是否适合进入这个包时，应该看它是否表达了清楚的问题域边界、能否提供可维护的公共语义，以及它是否依赖具体业务前提；代码是否常用本身不足以形成模块边界。

这种组织方式让使用者可以根据问题选择能力，并依据模块文档理解其边界和组合方式。它不替代使用方的业务建模，也不保证每项能力都能在所有运行环境中直接使用；环境专属模块和接入兼容性仍需按各自说明判断。

For Using

当应用或库需要复用已明确建模的问题域能力时，可以按目标环境和需求选择模块。当前模块覆盖基础数据与状态能力、运行环境适配、网络通信、业务基础能力以及 Web 界面组件等方向；具体范围和适用条件见对应模块说明。

包提供 @planet-matrix/mobius-model/base、/web、/node 和 /all 等公开子路径。/base 导出跨运行环境可用的能力，不依赖 Node.js 或浏览器专属能力，也不触发运行时启动副作用；/web 和 /node 分别提供对应运行环境的能力；/all 聚合包的全部公共能力，其中也包含环境专属模块。根据目标运行环境选择入口，从入口导入所需模块，再按模块 README 说明接入；使用 /all 或单环境入口时，仍应该根据目标运行环境和具体模块说明判断能力是否适用。

模块说明文件介绍各自的定位、适用场景、使用路径和扩展边界。选择具体模块后，应该先阅读对应说明，再依据模块公开接口接入。

延伸阅读：

• 模块说明：查阅各模块的定位、适用场景、接入方式和扩展边界。

For Contributing

本 README 说明 packages/model 包的整体职责，各模块 README 说明各自的问题域、适用场景和扩展边界。新增或调整能力时，应该先确定其归属模块，并保持概念边界清楚。

扩展模块时，通常在 src/<module-name>/ 中实现能力，通过模块的 index.ts 选择性导出公共接口，并将单元测试放在 tests/unit/<module-name>/；包含子模块时，应该按子模块边界组织导出和测试。包级入口文件为 src/base.index.ts、src/web.index.ts、src/node.index.ts 和 src/index.ts，package.json 的 exports 将其映射为 /base、/web、/node 和 /all 等公开子路径。

关键外部依赖包括：drizzle-orm 用于数据库模块的 ORM 集成，ws 用于 WebSocket 服务端实现，lit-html 为 Litor 模块提供模板和指令，resend 为邮件模块提供邮件发送适配。评估变更时，应检查对应模块说明与实现是否一致、公共接口是否由预期入口导出，以及相关测试是否覆盖变更行为；涉及外部依赖时，还应核对相应模块的集成行为。

延伸阅读：

• 模块说明：查阅各模块的问题域、职责和扩展边界，判断变更归属及影响范围。

模块说明

• abort
• administrative-division
• ai
• aio
• basic
• color
• component
• component/theme
• credential
• cron
• crypto
• css
• database
• email
• encoding
• environment
• event
• exception
• form
• huawei
• identifier
• json
• litor
• log
• openai
• orchestration
• privacy
• qweather
• random
• reactor
• request
• result
• route
• service
• singleton
• sms
• socket
• store
• timer
• tube
• type
• web
• weixin
• xml

Todos & Drafts

• [ ] reactor 支持作用域（scope）。
• [ ] reactor operators.
  • [ ] 参考 Angular Signals 的 resource（https://angular.dev/guide/signals/resource），并同时参考 SolidJS 的 createResource（https://docs.solidjs.com/reference/basic-reactivity/create-resource）。
  • [ ] delay operator。
  • [ ] timeInterval operator。
  • [ ] timestamp operator。
  • [ ] timeout operator。
  • [ ] timeoutWith operator。
  • [ ] toArray operator。
  • [ ] count operator。
  • [ ] clone operator（>2）。
  • [ ] iif operator。
  • [ ] pluck operator。
  • [ ] sequenceEqual operator。
  • [ ] skip operator。
  • [ ] skipWhile operator。
  • [ ] skipUntil operator。
• [ ] 修复 preact signal 测试。