# @type-dom/signals

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

Latest version **0.9.0** (published 2026-09-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install @type-dom/signals
pnpm add @type-dom/signals
yarn add @type-dom/signals
bun add @type-dom/signals
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2026-09-10 |
| First published | 2025-02-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 46.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | TypeDOM Core Team |
| Maintainers | xjf7711 |
| Keywords | signals, reactive, reactivity, push-pull, alien-signals, typedom |

## Links

- npm: https://www.npmjs.com/package/@type-dom/signals
- Repository: https://github.com/type-dom/signals
- Homepage: https://github.com/type-dom/signals#readme
- Issues: https://github.com/type-dom/signals/issues
- npm.io page: https://npm.io/package/@type-dom/signals

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2.3.0

## Recent versions

- 0.9.0 (latest) — 2026-09-10
- 0.8.3 — 2026-09-10
- 0.8.1 — 2026-03-14
- 0.8.0 — 2026-03-14
- 0.7.0 — 2026-03-14
- 0.6.3 — 2025-06-24
- 0.6.2 — 2025-06-24
- 0.6.1 — 2025-05-09
- 0.6.0 — 2025-04-29
- 0.5.0 — 2025-04-28
- 0.4.0 — 2025-03-31
- 0.3.0 — 2025-03-15
- 0.0.1 — 2025-02-11

## README

# 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/rules/agent-workflow.md) - AI Agent 工作流程规则
- [coding-standards.md](.ai/rules/coding-standards.md) - Signals 编码规范

### Standards (人类开发者)
**已整合到 Rules 中**,通过 `coding-standards.md` 提供:
- ✅ API 使用规范
- ✅ 测试编写标准
- ✅ 性能优化指南
- ✅ 常见陷阱和反模式

### 源码（仅 3 个文件）
- [src/index.ts](src/index.ts) - 主入口：Signal/Computed 类 + 全部工厂函数（524 行）
- [src/system.ts](src/system.ts) - 底层系统：ReactiveNode / Link / propagate（282 行）
- [src/batch.ts](src/batch.ts) - batch() / batchEffect() 批处理封装（33 行）

### 测试（vitest，非 bun test）
- [tests/api-coverage.spec.ts](tests/api-coverage.spec.ts) - API 覆盖测试
- [tests/conformance.spec.ts](tests/conformance.spec.ts) - 语义一致性测试
- [tests/effect.spec.ts](tests/effect.spec.ts) - Effect 测试
- [tests/effectScope.spec.ts](tests/effectScope.spec.ts) - EffectScope 测试
- [tests/batch.spec.ts](tests/batch.spec.ts) - Batch / batchEffect 测试
- [tests/trigger.spec.ts](tests/trigger.spec.ts) - Trigger 测试
- [tests/bench/](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（每秒操作数，**越高越好**）。

### 运行方式

```bash
# 生成 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

---
_Source: https://npm.io/package/@type-dom/signals · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._