|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## 项目概述 |
| 6 | + |
| 7 | +FastEvent 是一个功能强大、类型安全、经过充分测试的事件发射器库,支持 Node.js 和浏览器环境。项目使用 TypeScript 开发,采用 Monorepo 架构。 |
| 8 | + |
| 9 | +## 核心架构 |
| 10 | + |
| 11 | +### 包结构 |
| 12 | + |
| 13 | +- **packages/native**: 核心包,包含 FastEvent 主实现 |
| 14 | + - `src/event.ts`: FastEvent 核心类,事件监听器树管理 |
| 15 | + - `src/scope.ts`: FastEventScope 类,事件作用域实现 |
| 16 | + - `src/types/index.ts`: 核心类型定义 |
| 17 | + - `src/executors/`: 监听器执行器(parallel, race, series, waterfall, first, last, random, balance) |
| 18 | + - `src/pipes/`: 监听器管道(queue, throttle, debounce, timeout, retry, memorize) |
| 19 | + - `src/eventbus/`: EventBus 实现 |
| 20 | + - `src/utils/`: 工具函数 |
| 21 | + - `src/__tests__/`: 单元测试(320+ 测试用例,99%+ 覆盖率) |
| 22 | + - `src/__benchmarks__`: 性能测试 |
| 23 | + |
| 24 | +### 核心设计概念 |
| 25 | + |
| 26 | +1. **监听器树结构**: 事件监听器以树形结构存储,支持层级事件命名(如 `user/login`) |
| 27 | +2. **通配符支持**: |
| 28 | + - `*` 匹配单级路径(如 `user/*` 匹配 `user/login`) |
| 29 | + - `**` 匹配多级路径(如 `user/**` 匹配 `user/login`, `user/profile/update`) |
| 30 | +3. **作用域(Scope)**: 共享父级监听器表,自动为事件名添加前缀,不是隔离的命名空间 |
| 31 | +4. **执行器(Executor)**: 控制监听器的执行方式(并行、串行、竞速等) |
| 32 | +5. **管道(Pipe)**: 包装监听器函数以实现额外功能(队列、节流、重试等) |
| 33 | +6. **保留事件**: 使用 `retain: true` 保留最后一次事件数据,新订阅者立即接收 |
| 34 | + |
| 35 | +## 常用命令 |
| 36 | + |
| 37 | +### 构建 |
| 38 | + |
| 39 | +```bash |
| 40 | +# 构建所有包 |
| 41 | +bun run build |
| 42 | + |
| 43 | +# 或使用 turbo |
| 44 | +turbo build |
| 45 | + |
| 46 | +# 构建 native 包 |
| 47 | +cd packages/native && bun run build |
| 48 | +``` |
| 49 | + |
| 50 | +### 测试 |
| 51 | + |
| 52 | +```bash |
| 53 | +# 运行所有测试 |
| 54 | +bun run test |
| 55 | + |
| 56 | +# 运行测试并生成覆盖率报告 |
| 57 | +bun run test:coverage |
| 58 | + |
| 59 | +# 运行单个测试文件 |
| 60 | +npx vitest run <test-file-path> |
| 61 | + |
| 62 | +# 监听模式运行测试 |
| 63 | +npx vitest |
| 64 | +``` |
| 65 | + |
| 66 | +### 性能测试 |
| 67 | + |
| 68 | +```bash |
| 69 | +bun run bench |
| 70 | +``` |
| 71 | + |
| 72 | +### 文档 |
| 73 | + |
| 74 | +```bash |
| 75 | +# 启动文档开发服务器 |
| 76 | +bun run docs:dev |
| 77 | + |
| 78 | +# 构建文档 |
| 79 | +bun run docs:build |
| 80 | + |
| 81 | +# 预览文档 |
| 82 | +bun run docs:preview |
| 83 | +``` |
| 84 | + |
| 85 | +### 发布 |
| 86 | + |
| 87 | +```bash |
| 88 | +# 创建 changeset |
| 89 | +bun run changeset |
| 90 | + |
| 91 | +# 发布到 npm(先构建,再版本更新,最后发布) |
| 92 | +bun run release |
| 93 | + |
| 94 | +# 同步到 cnpm |
| 95 | +bun run sync |
| 96 | +``` |
| 97 | + |
| 98 | +## 开发指南 |
| 99 | + |
| 100 | +### 添加新功能时的注意事项 |
| 101 | + |
| 102 | +1. **类型安全**: 所有新功能必须有完整的 TypeScript 类型定义 |
| 103 | +2. **测试覆盖**: 必须为功能添加单元测试,确保覆盖率保持在 99%+ |
| 104 | +3. **向后兼容**: 不能破坏现有 API,新增功能通过可选参数或新方法实现 |
| 105 | +4. **文档更新**: 更新 README.md 和 docs/ 目录下的文档 |
| 106 | + |
| 107 | +### 核心文件说明 |
| 108 | + |
| 109 | +- **src/event.ts**: FastEvent 主类,包含事件订阅/发布的核心逻辑 |
| 110 | + |
| 111 | + - `_addListener`: 添加监听器到树结构 |
| 112 | + - `_traverseToPath`: 遍历监听器树,支持通配符匹配 |
| 113 | + - `_executeListeners`: 执行匹配的监听器 |
| 114 | + - `emit`: 同步触发事件 |
| 115 | + - `emitAsync`: 异步触发事件(使用 Promise.allSettled) |
| 116 | + |
| 117 | +- **src/scope.ts**: FastEventScope 类 |
| 118 | + - 作用域不创建新的监听器表,而是共享父级的监听器表 |
| 119 | + - `bind`: 绑定到 FastEvent 实例并设置前缀 |
| 120 | + - `_getScopeListener`: 包装监听器以处理前缀逻辑 |
| 121 | + |
| 122 | +### 类型系统 |
| 123 | + |
| 124 | +项目使用高级 TypeScript 类型特性: |
| 125 | + |
| 126 | +- **泛型约束**: Events, Meta, Context 三个泛型参数 |
| 127 | +- **条件类型**: 根据 Transform 配置动态推导消息类型 |
| 128 | +- **通配符展开**: `ExpandWildcard`, `WildcardEvents` 等类型工具 |
| 129 | +- **作用域事件**: `ScopeEvents` 用于推导作用域的事件类型 |
| 130 | + |
| 131 | +### 代码注释语言 |
| 132 | + |
| 133 | +所有代码注释使用**中文**编写,保持与现有代码库一致。 |
| 134 | + |
| 135 | +## 发布流程 |
| 136 | + |
| 137 | +项目使用 Changesets 进行版本管理: |
| 138 | + |
| 139 | +1. 使用 `bun run changeset` 创建 changeset,描述变更内容 |
| 140 | +2. 版本号会根据 changeset 自动升级(major/minor/patch) |
| 141 | +3. 发布前会自动生成 CHANGELOG.md |
| 142 | +4. 发布会同步到 cnpm 镜像 |
| 143 | + |
| 144 | +## 构建输出 |
| 145 | + |
| 146 | +- **主包**: `dist/index.js`, `dist/index.mjs`, `dist/index.d.ts` |
| 147 | +- **Executors**: `dist/executors/*` |
| 148 | +- **Pipes**: `dist/pipes/*` |
| 149 | +- **EventBus**: `dist/eventbus/*` |
| 150 | +- **DevTools**: `devTools.js`, `devTools.mjs` |
| 151 | + |
| 152 | +构建使用 `tsup`(基于 esbuild),输出 ESM 和 CJS 双格式,包含 TypeScript 类型定义和 source maps。 |
| 153 | + |
| 154 | +## 注意事项 |
| 155 | + |
| 156 | +- 使用 Bun 作为包管理器(`bun@1.3.5`) |
| 157 | +- Node.js 版本要求:ES2020+ |
| 158 | +- 测试框架:Vitest |
| 159 | +- 代码风格:Biome(替代 ESLint/Prettier) |
| 160 | +- CI/CD:使用 GitHub Actions |
0 commit comments