javascript

JavaScript

最新の JavaScript と Node に関するチーム規約です。新規作成または変更するコードに適用してください。依頼がない限り、変更していないファイルを規約に合わせてリファクタリングしないでください。

規約

• どこでも ESM を使います。 新しいパッケージには "type": "module" を設定します。1 つのパッケージ内で CJS と ESM を混在させると、デュアルパッケージの問題が発生します。状態が別々のモジュールが 2 つ読み込まれ、競合状態のように見える形で失敗します。
• 意図に合ったコンビネーターを選びます。 ループ内で await を順番に使うと、独立した処理が直列化されます。Promise.all は 1 つでも拒否されるとバッチ全体が失敗します。部分的な成功を許容できる場合は allSettled を使います。選択を誤ると、レイテンシーの問題やエラーが握りつぶされる問題になります。どちらもレビューでは問題がないように見えてしまいます。
• すべての catch で処理するか、再スローします。 ログを記録して続行する catch は、失敗を下流での状態破損に変えてしまい、スタックトレースから原因を特定できなくなります。有用な処理がないなら、catch しないでください。
• キャンセル可能な処理には AbortController を使います — フェッチ、タイマー、ストリーム、リスナー（{ signal }）などです。これを使わないと、放棄されたリクエストがハンドラーとクロージャーを保持し続けます。
• イベントループをブロックしないでください。 リクエストの処理経路では、readFileSync や長時間かかる同期的な解析・暗号処理を行いません。Node は同じスレッドから他のすべてのリクエストを処理します。CPU 負荷の高い処理はワーカースレッドに移します。
• 引数を変更しないでください。 関数が入力を書き換えると、呼び出し元のオブジェクトが代入した形跡もなく変更されます。新しい値を返し、目的に合った非破壊的な配列メソッドを使います。toSorted、toReversed、toSpliced、with があります。arr.sort() が呼び出し元の配列をその場で並べ替えるのは、JS で最もよくある意図しない変更の 1 つです。
• 組み込みモジュールには node: プレフィックスを付けます。 曖昧さがなく、同名のユーザーランドパッケージによるシャドーイングも防げます。
• 依存関係を追加する前に、プラットフォームの機能を使います。 structuredClone、Intl、URL／URLSearchParams、crypto.randomUUID、Array.prototype.at／findLast、Object.groupBy があれば、ユーティリティーライブラリーをインストールしていた用途の大半をカバーできます。

パッケージの公開

exports マップが公開 API です。そこに記載されていないものにはアクセスできません。それが目的です。これにより、利用側に影響を与えずに内部をリファクタリングできます。sideEffects: false（または副作用のあるファイルの一覧）を宣言すると、バンドラーが未使用のエクスポートを削除できます。宣言しない場合、ツリーシェイキングではモジュールのインポートに何らかの処理が伴うと想定する必要があり、すべてが残されます。

{
  "type": "module",
  "exports": {
    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "./package.json": "./package.json"
  },
  "sideEffects": false
}

つまずくと最も時間を取られる ESM の事実が 2 つあります。相対インポートにはファイル拡張子が必要です（./utils ではなく ./utils.js）。また、__dirname はありません。fileURLToPath(import.meta.url) で代替するか、CJS 専用パッケージの読み込みが本当に必要な場合は createRequire(import.meta.url) を使ってください。