typescript

JavaScript 和 TypeScript

主要参考资料：TypeScript 文档。以下规则文件链接到其对应的官方文档章节；如果规则与官方文档不一致，以文档为准，并应更新规则。

遵循项目规范

使用仓库配置的运行时、导入方式、测试运行器和验证命令。 更改工具或引入工作流之前，请先阅读项目的 Agent 指南和配置。

路由到子技能

type-system/ 和 zod/ 是按需从此路由读取的参考资料包——它们不是独立发现的技能，因此其自身的 frontmatter 有意保持精简（无需重复触发列表）。

→ 类型系统（unknown/any、缩窄、可辨识联合、映射类型……）→ type-system/SKILL.md → Total TypeScript / Matt Pocock（类型推导、satisfies、泛型推断、NoInfer、分配性、类型测试）→ references/total-typescript.md → Zod（架构验证、转换、强制转换、品牌类型……）→ zod/SKILL.md → 函数式组合（pipe/compose、柯里化、纯函数、工厂、函数式混入、幺半群……）→ composition/SKILL.md → Node.js 设计模式（异步控制流、流、EventEmitter、DI、批处理、工作线程、扩展）→ references/node-patterns.md → JS 运行时机制（this、闭包、原型、生成器、事件循环顺序、Promise）→ references/js-runtime-mechanics.md → JS 陷阱与惯用法（强制转换、字典、数组/迭代、API 设计、异步规范、经久耐用的模式）→ references/js-pitfalls-and-idioms.md → 按版本划分的 ES 特性（ES2015–ES2025 新增内容、现代替代方案、target/lib 指南）→ references/es-features-by-edition.md → 领域建模（将工作流建模为管道、通过类型表示状态机、Result 错误、DTO 边界、在边缘进行持久化）→ references/domain-modeling-functional.md → TS 语言缺口（变性、重载、断言函数、模块解析、类型驱动设计）→ references/ts-language-gaps.md → Deno 运行时（运行时停止维护通知；仅维护现有项目：配置、权限、依赖、HTTP、测试、Node 兼容性）→ references/deno.md → 设计模式（Strategy、Factory、Builder、Decorator、Mixin……）→ object-oriented-programming 技能 → SOLID 原则（SRP、OCP、LSP、ISP、DIP）→ object-oriented-programming 技能 → 测试（单元测试、mock 与 stub、脆弱测试、测试金字塔）→ testing 技能

---

错误处理

策略	调用方是否必须处理？	可组合性
返回 T | null	是（检查 null）	低
抛出异常	否——容易遗漏	高
返回异常 T | ErrorA | ErrorB	是——必须穷尽联合类型	中
Option/Either 类型	通过 .flatMap 链处理	高（需要库）

返回异常（预期失败时优先采用）：

class BadRequestError extends Error {
  readonly status = 400 as const;
}
class UnauthorizedError extends Error {
  readonly status = 401 as const;
}
class NotFoundError extends Error {
  readonly status = 404 as const;
}

function resolveUser(
  token: string,
  id: string,
): User | BadRequestError | UnauthorizedError | NotFoundError {
  if (!id.trim()) return new BadRequestError("Missing user ID");
  if (!isValidJwt(token)) return new UnauthorizedError("Invalid token");
  const user = userStore.get(id);
  if (!user) return new NotFoundError(`User ${id} not found`);
  return user;
}

const result = resolveUser(authHeader, userId);
if (result instanceof BadRequestError) res.status(400).send(result.message);
else if (result instanceof UnauthorizedError)
  res.status(401).send(result.message);
else if (result instanceof NotFoundError) res.status(404).send(result.message);
else res.status(200).json(result);

---

大规模使用 TypeScript

1. 全局启用 "strict": true，并在 CI 中强制执行（Compiler Options）；另外启用 strict 未包含的选项：noUncheckedIndexedAccess、noImplicitReturns、noFallthroughCasesInSwitch、noUnusedLocals、noUnusedParameters
2. 优先使用 @ts-expect-error，而非 @ts-ignore
3. 通过 @typescript-eslint/no-explicit-any 跟踪 any 的使用情况
4. 将 API/DTO 类型与领域类型分开——在边界处进行映射（示例如下）
5. 在边界处使用 Zod 验证外部输入（API 请求体、环境变量、队列）（示例：zod/SKILL.md）
6. 将领域契约作为 @org/contracts 发布；使用项目引用划分边界（Project References）

按需阅读

• Effect TS — 使用官方文档了解类型化错误、并发、资源管理和依赖要求。使用 API 示例前，请确保文档版本与项目安装的 effect 版本一致。
• 领域类型与 DTO 映射示例 — DTO 结构绝不应泄漏到领域中：

export type UserDTO = {
  user_id: string;
  display_name: string;
  created_at: string;
};

export type User = { id: string; name: string; createdAt: Date };

export function toDomain(dto: UserDTO): User {
  return {
    id: dto.user_id,
    name: dto.display_name,
    createdAt: new Date(dto.created_at),
  };
}

• Zod 边界验证示例：zod/SKILL.md。
• Node.js 运行时主题（事件循环/libuv、核心模块、CJS/ESM、调试与性能分析、HTTP 生态、npm/打包、安全）：参见免费电子书 "Become a Node.js developer"（在线阅读）。注意：法语版已完成；英语版为部分内容。
• ECMAScript 版本历史（ES1 1997 → ES2025）：参见 MDN 的 JavaScript 版本时间线。可用于判断某项功能首次在哪个版本推出、旧版运行时需要哪些 polyfill、哪些语法适用于目标环境，或选择 tsconfig 的 target/lib。

规则（始终适用的 JavaScript 与 TypeScript 规则）

JavaScript 基础

规则	文件
遵循 JavaScript 通用约定（命名、const/let、解构、模板字面量）	rules/js-general-conventions.md
优先使用显式上下文（参数），而非隐式的 this	rules/prefer-explicit-context-over-this.md
不要使用 barrel 文件（index.js/index.ts 重新导出）	rules/no-barrel-files.md
避免在热点路径中创建中间数组（filter().map() 链式调用）	rules/avoid-intermediate-arrays.md
缺失值使用 undefined，API/外部契约使用 null	rules/null-undefined.md

TypeScript 专属

规则	文件
避免类型断言（as T、!、as unknown as T）	rules/avoid-type-assertions.md
优先使用现有类型，而非 as const	rules/favor-existing-types-over-as-const.md
接口名称不要以 I 为前缀	rules/no-interface-prefix.md
将属性和数组标记为 readonly，以表明其不可变性	rules/readonly.md
对明显的局部返回值进行推断；为公共 API 和有风险的类型推断添加注解；启用 noImplicitAny	rules/explicit-return-types.md
使用模块而非命名空间；优先采用命名导出	rules/module-organization.md
优先使用随包提供的类型 / @types/*；否则添加最精简的 .d.ts	rules/js-interop-declarations.md

---

基准测试

此路由器没有自己的场景。门禁数据位于各叶节点的页脚中：

• type-system/SKILL.md → ## Benchmark（场景 typescript-001 为 PASS，typescript-002 为 SOFT PASS，运行于 2026-08-31）。
• composition/SKILL.md → ## Benchmark（场景 composing-software-001，运行于 2026-08-31，PASS）。
• 优化器历史运行记录：run-history.md（包含每项技能的门禁目标）。

门禁依据 .agents/skills/skill-optimizer/rules/release-gates.md。