@type-dom/signals

Signals 库文档说明

@type-dom/signals - TypeDOM 响应式系统核心库

---

目录结构

libs/signals/
├── .ai/
│   └── rules/
│       ├── agent-workflow.md      # AI Agent 工作流程规则 ⭐
│       └── coding-standards.md    # Signals 编码规范 ⭐
├── AI-D2C/                      # 📚 AI 学习文档
│   ├── AI-README.md             # AI-D2C 总索引
│   ├── DOCS-NAVIGATION.md       # 完整文档导航
│   ├── SIGNALS-BASICS-GUIDE.md  # 基础入门指南
│   ├── QUICK-REFERENCE.md       # 快速参考卡片
│   ├── AI-OPTIMIZATION-GUIDE.md # 概念完全指南
│   ├── ADVANCED-PATTERNS.md     # 高级模式指南
│   ├── TRIGGER-COMPLETE-GUIDE.md # Trigger API 指南
│   ├── TROUBLESHOOTING-GUIDE.md # 问题排查指南
│   ├── AI-CODE-CHECKLIST.md     # 代码检查清单
│   ├── ADVANCED/                # 🔬 高级技术文档
│   │   └── SIGNALS_DETAILED_ANALYSIS.md # 深度技术分析
│   └── ARCHIVES/                # 📦 历史归档
│       ├── README.md
│       ├── COMPLETION-REPORT.md
│       ├── TEST-ADDITION-REPORT.md
│       └── DOCUMENT-INTEGRATION-REPORT.md
├── src/                          # 💻 源代码（仅 3 个文件）
│   ├── index.ts                 # 主入口：Signal/Computed 类 + 全部工厂函数 (524 行)
│   ├── system.ts                # 底层系统：ReactiveNode / Link / propagate (282 行)
│   └── batch.ts                 # batch() / batchEffect() 批处理封装 (33 行)
├── tests/                        # 🧪 单元测试与基准（vitest）
│   ├── api-coverage.spec.ts     # API 覆盖测试
│   ├── conformance.spec.ts      # 语义一致性测试
│   ├── bench/                   # 跨框架性能基准（32 场景 × 6 框架）
│   └── ...
├── benchmarks/                   # 📊 生成的 HTML 性能报告
└── README.md                     # 本文件

注意：signal.ts / computed.ts / effect.ts / types.ts / utils.ts 在当前版本中不存在。 Signal 与 Computed 以类形式定义在 src/index.ts 内。测试框架为 vitest（非 bun test）。

---

文档分类

Rules (规则) - .ai/rules/

目标: 指导 AI Agent 的工作流程和编码标准

包含内容:

• AI Agent 如何阅读和理解代码
• 开发流程和最佳实践
• Signal/Computed/Effect API 使用规范
• 测试编写标准和模板
• 性能优化最佳实践
• 搜索和调试技巧

当前文件:

• agent-workflow.md - AI Agent 工作流程规则
• coding-standards.md - Signals 编码规范

特点:

• 都有 trigger: always_on 元数据
• AI Agent 处理 signals 代码时自动加载
• 包含"怎么做"和"做什么"

---

Standards (规范) - 已整合到 Rules 中

在 signals 项目中,编码规范已整合到 coding-standards.md 中,与 agent-workflow.md 一起作为 Rules 的一部分。

这与 Claude Code 项目的模式一致:

• agent-workflow.md - 工作流程规则
• coding-standards.md - 编码规范规则

两者都有 trigger: always_on,AI Agent 会自动加载。

---

如何使用

AI Agent 使用 Rules

当 AI Agent 处理 signals 相关代码时:

1. 自动加载: agent-workflow.md (因为有 trigger: always_on)
2. 遵循流程: 按照文档中的工作流程执行
3. 参考源码: 优先阅读 src/ 和 tests/
4. 查阅文档: 需要详细信息时参考 AI-D2C/

人类开发者使用 Standards

当人类开发者需要:

1. 学习 API: 阅读 docs/API-SPECIFICATION.md
2. 编写测试: 参考 docs/TESTING-GUIDE.md
3. 优化性能: 查看 docs/PERFORMANCE-GUIDE.md
4. 理解架构: 阅读 docs/ARCHITECTURE.md
5. 深入原理: 研究 docs/IMPLEMENTATION-DETAILS.md

---

快速链接

Rules (AI Agent)

• agent-workflow.md - AI Agent 工作流程规则
• coding-standards.md - Signals 编码规范

Standards (人类开发者)

已整合到 Rules 中,通过 coding-standards.md 提供:

• API 使用规范
• 测试编写标准
• 性能优化指南
• 常见陷阱和反模式

源码（仅 3 个文件）

• src/index.ts - 主入口：Signal/Computed 类 + 全部工厂函数（524 行）
• src/system.ts - 底层系统：ReactiveNode / Link / propagate（282 行）
• src/batch.ts - batch() / batchEffect() 批处理封装（33 行）

测试（vitest，非 bun test）

• tests/api-coverage.spec.ts - API 覆盖测试
• tests/conformance.spec.ts - 语义一致性测试
• tests/effect.spec.ts - Effect 测试
• tests/effectScope.spec.ts - EffectScope 测试
• tests/batch.spec.ts - Batch / batchEffect 测试
• tests/trigger.spec.ts - Trigger 测试
• tests/bench/ - 跨框架性能基准（32 场景 × 6 框架）

---

性能基准报告（跨框架对比）

数据来源：tests/cross-framework.bench.ts + tests/cross-framework.report.ts，由 nx run signals:bench-report 生成的 benchmarks/report-*.html。 下文为 2026-08-28T13-04-17 一次运行的快照，共 32 个场景，对比 6 个响应式框架。 数值单位 hz（每秒操作数，越高越好）。

运行方式

# 生成 HTML 报告（含数据矩阵、内存表、总结评价）
nx run signals:bench-report
# 等同于 vitest run --config vitest.report.mts

总览（综合排名）

框架	胜场（32 场景）	平均名次	几何均值速度
@type-dom/signals	28	1.3	0.964
@preact/signals-core	1	2.3	0.667
alien-signals	3	2.7	0.611
@vue/reactivity	0	4.3	0.325
solid-js	0	4.9	0.172
mobx	0	5.7	0.099

signals 在 32 个场景中拿下 28 项第一（胜率 87.5%），且从不垫底，是测试集里综合最快的框架。

性能数据矩阵（hz，越高越好）

场景	@type-dom/signals	@vue/reactivity	@preact/signals-core	alien-signals	solid-js	mobx	第一名
createSignals: create 1000 signals	25,296	15,280	26,815	26,479	19,956	9,669	@preact/signals-core
updateSignals: 10000 writes (no subscribers)	155,165	6,871	16,066	27,909	13,700	3,596	@type-dom/signals
noOpWrites: 10000 writes of same value (short-circuit)	193,567	6,966	26,241	12,980	14,739	4,325	@type-dom/signals
readSignals: 10000 reads	83,799	25,732	29,084	27,371	22,965	22,968	@type-dom/signals
createComputations: build 100-deep computed chain	170,130	107,890	159,375	154,884	69,676	23,639	@type-dom/signals
computedRecompute: 10000 cold recomputes (cache miss)	2,069	786	1,476	1,633	223	174	@type-dom/signals
computedCache: 10000 cached reads	68,005	13,358	14,845	14,259	9,005	1,608	@type-dom/signals
untrackedReads: 10000 untracked reads	9,226	1,261	5,849	2,007	5,892	2,164	@type-dom/signals
diamond: A → (B, C) → D, 1000 cycles	12,184	6,551	11,534	7,711	1,481	1,171	@type-dom/signals
triangle: glitch-free redundant edge, 1000 cycles	16,269	9,681	14,851	9,942	2,409	1,886	@type-dom/signals
broadPropagation: 1 → 100 computeds fan-out	5,020	2,606	3,760	2,737	791	1,372	@type-dom/signals
deepPropagation: 100-level chain updates	4,182	2,562	3,600	3,433	547	303	@type-dom/signals
mux: two signals fan-in, 1000 cycles	7,911	3,646	6,865	5,343	942	830	@type-dom/signals
avoidablePropagation: constant computed cuts propagation	20,978	8,884	19,414	14,347	3,085	2,553	@type-dom/signals
molBench: ring of 10 atoms, 1000 cycles	3,156	1,261	1,647	1,873	465	107	@type-dom/signals
cellx1000: 1000-deep computation chain, 100 cycles	372	272	349	353	53	30	@type-dom/signals
effectFanout: 1 signal → 100 effects, 1000 writes	456	283	324	300	101	52	@type-dom/signals
dynamicDeps: branch switch, 1000 cycles	5,207	2,394	4,873	3,844	813	670	@type-dom/signals
randomGraph: 10x10x5, lazy 80%, 200 cycles	5,004	2,644	4,313	3,973	866	164	@type-dom/signals
randomGraph: 10x10x5, dyn 25%, lazy 80%, 200 cycles	4,859	2,220	4,368	3,972	794	674	@type-dom/signals
randomGraph: 6x20x5, dyn 50%, lazy 50%, 100 cycles	3,913	1,951	3,622	3,263	598	514	@type-dom/signals
unstable: 1 source switches routed deps every cycle	5,900	2,579	4,782	4,126	927	738	@type-dom/signals
batchedWrites: batch of 100 writes → 1 flush	568,988	5,372	314,996	354,134	100,583	134,718	@type-dom/signals
nestedBatch: 10 inner batches x 5 writes	850,996	20,166	543,883	585,805	187,289	201,469	@type-dom/signals
repeatedObservers: create + dispose 1000 effects	13,196	6,915	14,922	18,850	2,222	1,453	alien-signals
effectScope: create 1000 effects in scope, dispose once	10,373	8,739	13,408	14,839	1,971	1,541	alien-signals
[LARGE] churn: create + dispose 100000 effects (GC pressure)	129	70	140	194	22	16	alien-signals
[LARGE] deepChain: 1000-level chain, 30 cycles	1,231	791	1,124	1,043	177	99	@type-dom/signals
[LARGE] wideFanout: 1 → 1000 computeds, 30 cycles	1,312	897	1,107	888	259	446	@type-dom/signals
[LARGE] bigGraph: 20x100x4, dyn 10%, 30 cycles	4,251	2,333	3,059	3,634	1,010	148	@type-dom/signals
[LARGE] effectFanout: 1 signal → 1000 effects, 100 writes	387	256	311	302	91	50	@type-dom/signals
[LARGE] wideGraph: 25x1000x5, dyn 5%, 10 cycles	486	262	375	407	97	29	@type-dom/signals

内存占用（每对象堆字节 + 规模峰值，越小越好）

框架	每 Signal	每 Effect	10 万 Signal 峰值
@type-dom/signals	371.5 B	598.5 B	−16.1 MB
@vue/reactivity	379.7 B	786.8 B	−3.9 MB
@preact/signals-core	306.1 B	406.0 B	−210.3 MB
alien-signals	345.2 B	592.8 B	3.1 MB
solid-js	426.4 B	1270.4 B	11.4 MB
mobx	562.7 B	764.7 B	32.5 MB

「10 万 Signal 峰值」列基于 process.memoryUsage().heapUsed 前后差值，受 V8 GC 时机影响噪声较大（负值即采样期间发生回收），仅作量级参考；「每 Signal / 每 Effect」列取 3 次平均更可靠。signals 每 Signal 371.5 B 与 alien 345.2 B 仅差 ~9%，差距被 Link 连接边开销稀释。

总结与对 @type-dom/signals 的评价

结论：综合最强梯队。 在 32 个场景中拿下 28 项第一（胜率 87.5%），几何均值速度全场最高，平均名次 1.3，从不垫底，是测试集中综合最快的框架。

核心优势（碾压级）：

• 写入 / 批处理：updateSignals 是 Vue 的 21×、MobX 的 43×；batchedWrites 是 Vue 的 125×，nestedBatch 是 Vue 的 47×。Signal.set 的 if (this.pendingValue !== value) 同值短路在 noOpWrites 直接体现（193,567 hz，是 Vue 的 24×、alien 的 15×）。
• computed 计算：createComputations / computedRecompute / computedCache 全部第一；缓存命中是 MobX 的 35×、Vue 的 5.6×。
• 图传播 / 大规模：diamond / triangle / mux / molBench / 随机动态图 / deepChain / wideFanout / bigGraph / wideGraph 全胜；[LARGE] bigGraph 是 MobX 的 28×，规模越大优势越明显。
• 动态依赖：dynamicDeps 及全部随机图场景第一，相对第二名约 1.2× 稳定优势；unstable（依赖图重建）也第一。

真实短板（仅相对理论最优，非工程缺陷）：

• GC 压力：Lifecycle 三场景系统性落后 alien-signals——repeatedObservers 1.34×、effectScope 1.52×、[LARGE] churn（10 万次创建+销毁）1.65×。根因是类实例模型（Signal/Computed/EffectNode 必进堆）vs alien 的字面量（可被逃逸分析栈分配）。但相对 Vue/Preact/MobX 仍占优（churn 是 Preact 的 1.2×、Vue 的 1.6×）。
• 超深链：cellx1000（1000 层）以 372 hz 小幅落后 Preact 的 349（约 1.06×）——唯一被非 alien 框架反超的场景，极深链逐层传播有微小优化空间。
• 内存自动化：内存已纳入自动化（每 Signal 371.5 B，alien 345.2 B，差 ~9%；10 万 Signal 峰值见上表），但 GC 次数 / 对象存活时长等长周期指标仍依赖手动采样，未做分代统计。

结论：@type-dom/signals 是一套生产级、综合最强的响应式库：写入、批处理、计算缓存、图传播与大规模场景全面碾压 Vue / Preact / MobX / Solid，且从不垫底。其唯一相对弱点是高频创建+销毁的 GC 压力（类实例 vs 字面量），以及极深链传播的微小落后——这两点相对主流框架依然占优，属于「与理论最优实现的差距」而非工程缺陷。后续优化应优先聚焦 Lifecycle / churn 场景的对象分配与回收（约 1.65× 差距）。

注：alien-signals 用纯字面量节点（可被 V8 逃逸分析栈分配），在高频创建+销毁场景 GC 压力更小；signals 用 Signal/Computed 类实例换取类型安全与生产可维护性，代价是单次创建/销毁成本略高。两者定位不同：alien = 算法参考实现，signals = 带生产级优化的完整库。

---

核心原则

Rules vs Standards 的关系

在 signals 项目中,Rules 包含 Standards:

文件	内容类型	trigger
agent-workflow.md	工作流程规则	always_on
coding-standards.md	编码规范规则	always_on

两者都是 Rules,都有 trigger,AI Agent 都会自动加载。

这与 Claude Code 项目的模式一致。

---

维护指南

添加新的 Rule 文件

1. 在 .ai/rules/ 创建 .md 文件
2. 必须添加 trigger: always_on 元数据
3. 聚焦特定主题 (如: testing-guide.md, performance-tips.md)
4. 保持与现有文件职责不重叠

更新现有 Rules

• agent-workflow.md: 更新工作流程、策略、技巧
• coding-standards.md: 更新 API 规范、测试标准、最佳实践
• 保持两者职责清晰,不重叠

文档组织原则

• 小而专注: 每个文件聚焦一个主题
• 交叉引用: 相关文档互相链接
• 易于查找: 清晰的命名和结构

---

下一步计划

短期 (1-2 周)

• 创建 docs/API-SPECIFICATION.md
• 创建 docs/TESTING-GUIDE.md
• 验证 AI Agent 正确加载 rules

中期 (1-2 月)

• 创建 docs/PERFORMANCE-GUIDE.md
• 创建 docs/ARCHITECTURE.md
• 创建 docs/IMPLEMENTATION-DETAILS.md

长期 (持续)

• 根据反馈优化 rules
• 完善 standards 文档
• 保持文档与代码同步

---

最后更新: 2026-04-07
维护者: TypeDOM Core Team