node

使用する場面

Node.js のコードを扱う際は、堅牢で高性能かつ保守しやすい Node.js アプリケーションを構築するための、ドメイン固有の知識を得るためにこのスキルを使用してください。

型ストリッピングを使用した TypeScript

Node.js 向けの TypeScript を記述する場合は、ts-node や tsx などのビルドツールではなく、型ストリッピング（Node.js 22.6+）を使用してください。型ストリッピングでは、実行時に型注釈を削除することで、TypeScript を直接実行できます。トランスパイルは行いません。

型ストリッピングとの互換性に関する主な要件：

• 型のみのインポートには import type を使用します
• enum の代わりに const オブジェクトを使用します
• namespace とパラメータープロパティは避けます
• インポートでは .ts 拡張子を使用します

最小限の例 — 型ストリッピングが有効な TypeScript ファイル：

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

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

次のコマンドで直接実行します：

node greet.ts

完全な設定と例については、rules/typescript.md を参照してください。

よくあるワークフロー

複数のステップからなるプロセスでは、該当するルールファイルを確認する前に、次の大まかな手順に従ってください。

グレースフルシャットダウン：シグナルハンドラーを登録する（SIGTERM/SIGINT） → 新しい処理の受け付けを停止する → 処理中のリクエストを完了させる → 外部接続（DB、キャッシュ）を閉じる → 適切なコードで終了する。rules/graceful-shutdown.md を参照してください。

エラー処理：共有の基底エラークラスを定義する → エラーを分類する（運用上のエラーとプログラマーエラー） → 非同期境界のハンドラーを追加する（process.on('unhandledRejection')） → 呼び出しスタック全体に型付きエラーを伝播させる → 応答または異常終了の前に、コンテキストを含めてログに記録する。rules/error-handling.md を参照してください。

不安定なテストの診断：--test-only でテストを分離する → 共有状態やタイマーへの依存を確認する → 非同期の後処理順序を調べる → 一時的な診断手段として再試行ロジックを追加する → 根本原因を修正する。rules/flaky-tests.md を参照してください。

停止したプロセス／テストの診断（node --test がハングする、「process did not exit」、CI のタイムアウト、未解放のハンドル）：ファイル／テストを分離する → 明示的なタイムアウト／レポーターを指定して実行する → why-is-node-running（SIGUSR1）でハンドルを調べる → リソースを作成するスコープ内で、確実に実行される後処理を実装する → 分離実行と全テストスイートの実行を、安定するまで繰り返す。rules/stuck-processes-and-tests.md を参照してください。

遅い処理経路のプロファイリング：現実的な負荷で再現する → --cpu-prof で CPU プロファイルを取得する → ホット関数を特定する → ストリームのバックプレッシャーや不要なシリアライズを確認する → ベンチマークで改善を検証する。rules/profiling.md と rules/performance.md を参照してください。

優先度の高い適用チェックリスト（ストリーム＋キャッシュ）

タスクに CSV、ETL、データ取り込みパイプライン、大容量ファイルの処理、バックプレッシャー、繰り返し行われるルックアップ、または 同時実行される非同期呼び出しの重複排除 が含まれる場合は、次のチェックリストを明示的に適用してください。

1. node:stream/promises の await pipeline(...) を使用します（ガイダンスやコードでは、連結した .pipe() よりもこちらを優先してください）。
2. データをストリーム内で変換する場合は、少なくとも 1 つの明示的な async function* 変換処理を含めます。
3. 繰り返し行われる処理がある場合は、キャッシュ戦略を選択します。
   • 単一プロセス内で、上限のあるメモリー上の再利用には lru-cache を使用します。
   • 非同期リクエストの重複排除や stale-while-revalidate の動作には async-cache-dedupe を使用します。
4. バックプレッシャーがどこで処理されるかを示します（pipeline() による暗黙的な処理、または drain による明示的な処理）。

統合例のパターン（CSV/ETL）

CSV/ETL 形式のプロンプトには、次のような回答構成を優先してください。

• createReadStream(input)
• async function* パーサー／変換処理
• オプションのキャッシュ付きエンリッチメント検索（async-cache-dedupe または lru-cache）
• 書き込み可能な宛先への await pipeline(...)

モデルが詳細を参照できるよう、説明の中で関連ルールへのリンクを直接記載してください。

• rules/streams.md
• rules/caching.md

使い方

詳しい説明とコード例については、個々のルールファイルをお読みください。

• rules/error-handling.md - Node.js のエラー処理パターン
• rules/async-patterns.md - Async/await と Promise のパターン
• rules/streams.md - Node.js のストリームの操作
• rules/modules.md - ES Modules と CommonJS のパターン
• rules/testing.md - Node.js アプリケーションのテスト戦略
• rules/flaky-tests.md - node:test を使用した不安定なテストの特定と診断
• rules/stuck-processes-and-tests.md - 終了しないプロセスや停止するテストの診断
• 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 - TypeScript の設定と Node.js における型ストリッピング