node

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use

适用场景

Use this skill whenever you are dealing with Node.js code to obtain domain-specific knowledge for building robust, performant, and maintainable Node.js applications.

当你处理Node.js代码时，即可使用本技能获取构建健壮、高性能且可维护的Node.js应用的领域专属知识。

TypeScript with Type Stripping

带类型剥离的TypeScript

When writing TypeScript for Node.js, use type stripping (Node.js 22.6+) instead of build tools like ts-node or tsx. Type stripping runs TypeScript directly by removing type annotations at runtime without transpilation.

Key requirements for type stripping compatibility:

Use
```
import type
```
for type-only imports
Use const objects instead of enums
Avoid namespaces and parameter properties
Use
```
.ts
```
extensions in imports

Minimal example — a valid type-stripped TypeScript file:

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

Run directly with:

bash

node greet.ts

See rules/typescript.md for complete configuration and examples.

在为Node.js编写TypeScript代码时，使用类型剥离（Node.js 22.6+）替代ts-node或tsx等构建工具。类型剥离会在运行时直接移除类型注解，无需转译即可运行TypeScript代码。

类型剥离兼容性的关键要求：

对仅类型导入使用
```
import type
```
使用const对象替代枚举（enums）
避免命名空间和参数属性
在导入中使用.ts扩展名

最简示例 —— 一个有效的类型剥离TypeScript文件：

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

直接运行：

bash

node greet.ts

查看rules/typescript.md获取完整配置和示例。

Common Workflows

常见工作流

For multi-step processes, follow these high-level sequences before consulting the relevant rule file:

Graceful shutdown: Register signal handlers (SIGTERM/SIGINT) → stop accepting new work → drain in-flight requests → close external connections (DB, cache) → exit with appropriate code. See rules/graceful-shutdown.md.

Error handling: Define a shared error base class → classify errors (operational vs programmer) → add async boundary handlers (

process.on('unhandledRejection')

) → propagate typed errors through the call stack → log with context before responding or crashing. See rules/error-handling.md.

Diagnosing flaky tests: Isolate the test with

--test-only

→ check for shared state or timer dependencies → inspect async teardown order → add retry logic as a temporary diagnostic step → fix root cause. See rules/flaky-tests.md.

Profiling a slow path: Reproduce under realistic load → capture a CPU profile with

--cpu-prof

→ identify hot functions → check for stream backpressure or unnecessary serialisation → validate improvement with a benchmark. See rules/profiling.md and rules/performance.md.

对于多步骤流程，请在查阅相关规则文件前遵循以下高级流程：

优雅停机：注册信号处理器（SIGTERM/SIGINT）→ 停止接收新任务→ 处理完进行中的请求→ 关闭外部连接（数据库、缓存）→ 以合适的代码退出。查看rules/graceful-shutdown.md。

错误处理：定义共享的错误基类→ 对错误分类（操作型错误vs程序员错误）→ 添加异步边界处理器（

process.on('unhandledRejection')

）→ 通过调用栈传播类型化错误→ 在响应或崩溃前记录上下文信息。查看rules/error-handling.md。

诊断不稳定测试：使用

--test-only

隔离测试→ 检查共享状态或计时器依赖→ 检查异步销毁顺序→ 添加重试逻辑作为临时诊断步骤→ 修复根本原因。查看rules/flaky-tests.md。

慢路径性能分析：在真实负载下复现问题→ 使用

--cpu-prof

捕获CPU性能分析报告→ 定位热点函数→ 检查流背压或不必要的序列化操作→ 通过基准测试验证优化效果。查看rules/profiling.md和rules/performance.md。

High-priority activation checklist (streams + caching)

高优先级激活检查清单（流 + 缓存）

When the task mentions CSV, ETL, ingestion pipelines, large file processing, backpressure, repeated lookups, or deduplicating concurrent async calls, explicitly apply this checklist:

Use
```
await pipeline(...)
```
from
```
node:stream/promises
```
(prefer this over chained
```
.pipe()
```
in guidance/code).
Include at least one explicit
```
async function*
```
transform when data is being transformed in-stream.
Choose a cache strategy when repeated work appears:
- ```
lru-cache
```
  for bounded in-memory reuse in a single process.
- ```
async-cache-dedupe
```
  for async request deduplication / stale-while-revalidate behavior.
Show where backpressure is handled (implicitly via
```
pipeline()
```
or explicitly via
```
drain
```
).

当任务提及CSV、ETL、数据摄入管道、大文件处理、背压、重复查询或并发异步请求去重时，请明确应用以下检查清单：

使用
```
node:stream/promises
```
中的
```
await pipeline(...)
```
（在指导/代码中优先使用此方式而非链式
```
.pipe()
```
）。
当在流中转换数据时，至少包含一个显式的
```
async function*
```
转换。
当出现重复操作时选择缓存策略：
- ```
lru-cache
```
  用于单进程中有限的内存复用。
- ```
async-cache-dedupe
```
  用于异步请求去重 / 失效时返回旧值（stale-while-revalidate）的行为。
展示背压的处理位置（通过
```
pipeline()
```
隐式处理或通过
```
drain
```
显式处理）。

Integrated example pattern (CSV/ETL)

集成示例模式（CSV/ETL）

For CSV/ETL-style prompts, prefer an answer structure like:

```
createReadStream(input)
```
```
async function*
```
parser/transform
optional cached enrichment lookup (
```
async-cache-dedupe
```
or
```
lru-cache
```
)
```
await pipeline(...)
```
to a writable destination

Link relevant rules directly in explanations so models can retrieve details:

rules/streams.md
rules/caching.md

对于CSV/ETL类请求，优先采用如下回答结构：

```
createReadStream(input)
```
```
async function*
```
解析器/转换器
可选的缓存增强查询（
```
async-cache-dedupe
```
或
```
lru-cache
```
）
```
await pipeline(...)
```
到可写入目标

在解释中直接链接相关规则，以便模型获取详细信息：

rules/streams.md
rules/caching.md

How to use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/error-handling.md - Error handling patterns in Node.js
rules/async-patterns.md - Async/await and Promise patterns
rules/streams.md - Working with Node.js streams
rules/modules.md - ES Modules and CommonJS patterns
rules/testing.md - Testing strategies for Node.js applications
rules/flaky-tests.md - Identifying and diagnosing flaky tests with node:test
rules/node-modules-exploration.md - Navigating and analyzing node_modules directories
rules/performance.md - Performance optimization techniques
rules/caching.md - Caching patterns and libraries
rules/profiling.md - Profiling and benchmarking tools
rules/logging.md - Logging and debugging patterns
rules/environment.md - Environment configuration and secrets management
rules/graceful-shutdown.md - Graceful shutdown and signal handling
rules/typescript.md - TypeScript configuration and type stripping in Node.js

阅读单个规则文件获取详细说明和代码示例：

rules/error-handling.md - Node.js中的错误处理模式
rules/async-patterns.md - Async/await与Promise模式
rules/streams.md - Node.js流的使用
rules/modules.md - ES模块与CommonJS模式
rules/testing.md - Node.js应用的测试策略
rules/flaky-tests.md - 使用node:test识别和诊断不稳定测试
rules/node-modules-exploration.md - 浏览和分析node_modules目录
rules/performance.md - 性能优化技巧
rules/caching.md - 缓存模式与库
rules/profiling.md - 性能分析与基准测试工具
rules/logging.md - 日志记录与调试模式
rules/environment.md - 环境配置与密钥管理
rules/graceful-shutdown.md - 优雅停机与信号处理
rules/typescript.md - Node.js中的TypeScript配置与类型剥离