typescript

TypeScript コードスタイルガイド

型と型安全性

• TypeScript が型を推論できる場合は、明示的な型注釈を避けます
• 暗黙的な any を避け、必要に応じて明示的に型を指定します
• 正確な型を使います。object や any よりも Record<PropertyKey, unknown> を優先します
• オブジェクトの形状（React の props など）には interface を、ユニオン型／交差型には type を優先します
• 単なる as const よりも as const satisfies XyzInterface を優先します
• @ts-ignore や as any よりも @ts-expect-error を優先します
• 意味のない null／undefined パラメーターを避け、厳密な関数の契約を設計します
• namespace よりも ES モジュール拡張（declare module '...'）を優先します。namespace を使った拡張パターンは導入しないでください
• 型に拡張性が必要な場合は、拡張フィールドをすべて 1 つのレジストリファイルに集約するのではなく、元の型の場所に小さなマージ可能なインターフェースを公開し、各機能／プラグインがローカルで拡張するようにします
• PipelineContext.metadata のようなパッケージ内の拡張パターンでは、メタデータのフィールドを、それを読み書きするプロセッサー／プロバイダー／プラグインの近くに定義します

非同期パターン

• I/O では非同期を優先：新しい I/O コード（fs、child_process など）では、境界で非同期 API を使う必要があります。import { readFile } from 'fs/promises' のような Promise ベースのものを使い、デフォルトでは *Sync を使わないでください。関数の色付けは非対称です。非同期から同期への移行は不要ですが、同期から非同期への移行では、I/O が遅くなったり、並行性が必要になったり、サブプロセス／ネットワーク呼び出しが追加されたりすると、呼び出し元をすべて上流まで書き換える必要が生じます。同期優先の負債は積み重なります。非同期処理の微小なコスト（スレッドプールのディスパッチ、キャッシュ競合）は正当な理由になりません。競合は、結果ではなく Promise をキャッシュすることで解決できます
• *Sync が許容されるのは、制御できない同期契約に呼び出し箇所が拘束されている場合に限ります。既存の同期シグネチャーチェーン（バグ修正でレガシーな同期チェーンを広範囲にリファクタリングしないでください。ただし、新しい独立モジュールでそのようなチェーンを延長してはいけません）、または process.on('exit') のような同期専用コールバックが該当します。モジュール読み込み時や CLI 起動時の初期化は例外ではありません。その場合はトップレベルの await（ESM）を使ってください

インポート

• リントで simple-import-sort/imports と consistent-type-imports を適用し、個別の import type 文を使います（fixStyle: 'separate-type-imports'）。

コード構造

• export default よりも 名前付きエクスポート を優先します。リファクタリング時の名前変更と IDE の自動インポートが同期され、import Foo from './foo' で発生する default の名前変更の不整合を防げます。export default は、フレームワークで必須となるファイル（Next.js の page／route／layout、React.lazy の対象、vitest.config.ts のような設定ファイル）に限定してください。コードベースには今も export default が多数ありますが、これは過去からの負債であり、踏襲するパターンではありません。上記のフレームワークで必須となるケース以外では、既存の export default の使い方を新しいコードの手本にしないでください

再利用性

• ガード、パース、正規化、時間計測、JSON 安全なヘルパーを追加する前に、packages/utils とインストール済みパッケージを検索してください。機能ごとにヘルパーを重複して実装するのではなく、@lobechat/utils または関連するサブパスを再利用します
• typeof value === 'object' && value !== null のような、再利用可能なレコード／オブジェクトマップのガードを独自に実装しないでください。@lobechat/utils/object から isRecord、isPlainRecord、isObjectLike、toRecord、pickString、UnknownRecord などのヘルパーをインポートします
• Date.now() は一度だけ定数に代入し、一貫性のために再利用します

ロギング

• ユーザーの個人情報（API キーなど）を決してログに記録しないでください
• import { log } from 'debug' を直接使わないでください（コンソールにログが出力されます）
• catch ブロックでは debug パッケージではなく console.error を使います
• .catch() コールバックでは必ずエラーをログに記録します。何もせずに .catch(() => fallback) とすると、失敗が握りつぶされ、デバッグが不可能になります