better-result 採用

既存のコードベースに better-result を段階的に採用し、すべてを一度に書き直すことなく進めます。

使用時期

ユーザーが以下を望む場合、このスキルを使用します：

• try/catch から Result.try または Result.tryPromise へ移行
• null を返す値を型付き Result<T, E> で置き換え
• domain 固有の TaggedError 型を定義
• ネストされたエラー処理を andThen チェーンまたは Result.gen にリファクタリング
• サービスまたはモジュール全体でエラー処理を標準化

読む順序

タスク	読むべきファイル
モジュールで better-result を採用	このファイル
エラー型を定義または確認	references/tagged-errors.md
ライブラリ実装の詳細を検査	opensrc/ （存在する場合）

前提条件

コード編集前に以下を確認してください：

1. ターゲットプロジェクトに better-result がインストール済みであることを確認。
2. opensrc/ ディレクトリがあるかチェック。ある場合は、そこのパッケージソースを読んで現在のパターンを確認。
3. まず移行スコープを特定：1 ファイル、1 モジュール、または 1 境界レイヤー。

移行戦略

1. 境界から始める

I/O 境界と例外が多いコードから始めます：

• HTTP クライアント
• データベースアクセス
• ファイルシステム操作
• パースと検証
• フレームワークアダプター

コードベース全体を一度に変換しないこと。

2. 既存の失敗を分類

カテゴリ	例	ターゲット形状
Domain エラー	見つからない、検証、認証	TaggedError + Result.err
インフラストラクチャ	ネットワーク、DB、ファイル I/O	Result.tryPromise + mapped error
プログラマの欠陥	不正な仮定、null 参照	throw のまま；欠陥は Result コールバック内で Panic に

3. この順序で移行

1. エラー型を定義。
2. Result.try / Result.tryPromise で throw 境界をラップ。
3. null または boolean sentinel リターンを Result で置き換え。
4. コールサイトをリファクタリングして Result 値を伝播。
5. ネストされた分岐を andThen、mapError、または Result.gen に折りたたむ。

コア変換

Try/catch → Result.try

function parseConfig(json: string): Result<Config, ParseError> {
  return Result.try({
    try: () => JSON.parse(json) as Config,
    catch: (cause) => new ParseError({ cause, message: `Parse failed: ${cause}` }),
  });
}

Async throws → Result.tryPromise

async function fetchUser(id: string): Promise<Result<User, ApiError | UnhandledException>> {
  return Result.tryPromise({
    try: async () => {
      const res = await fetch(`/api/users/${id}`);
      if (!res.ok) throw new ApiError({ status: res.status, message: `API ${res.status}` });
      return res.json() as Promise<User>;
    },
    catch: (cause) => (cause instanceof ApiError ? cause : new UnhandledException({ cause })),
  });
}

Null sentinel → Result

function findUser(id: string): Result<User, NotFoundError> {
  const user = users.find((candidate) => candidate.id === id);
  return user
    ? Result.ok(user)
    : Result.err(new NotFoundError({ id, message: `User ${id} not found` }));
}

ネストされたフロー → Result.gen

async function processOrder(orderId: string): Promise<Result<OrderResult, OrderError>> {
  return Result.gen(async function* () {
    const order = yield* Result.await(fetchOrder(orderId));
    const validated = yield* validateOrder(order);
    const result = yield* Result.await(submitOrder(validated));
    return Result.ok(result);
  });
}

実行ワークフロー

1. ターゲットモジュールを監査して、try、catch、.catch(...)、throw、null、undefined、status フラグエラー処理を探す。
2. 制御フローを変更する前に、TaggedError クラスを定義または更新。
3. 境界関数を最初に変換し、シグネチャを Result<T, E> または Promise<Result<T, E>> に変更。
4. 即座の呼び出し元を更新して、新しい Result を処理または伝播。
5. 複数の Result 返却ステップが構成される場所では、Result.gen または andThen を使用。
6. エラーコンテキストを保持して、cause、ID、メッセージ、その他の構造化フィールドを保存。
7. テストを実行し、成功パスと少なくとも 1 つの代表的なエラーパスに対応するテストカバレッジを追加。

完了基準

移行は以下を満たす場合に完了です：

• ターゲット関数が、期待される domain の失敗に対して try/catch に依存しない
• null または sentinel エラーリターンが明示的な Result 値で置き換えられている
• domain の失敗が型付き TaggedError クラスを使用している
• 呼び出し元が Result を伝播するか、明示的にアンラップまたはマッチしている
• テストが少なくとも 1 つの成功パスと 1 つの代表的なエラーパスをカバーしている

よくある落とし穴

• 境界から始める代わりに、すべてをオーバーラップ
• エラーをマップするときに元の失敗コンテキストを失う
• 同じフロー内で throw ベースと Result ベースの API を混ぜる
• 根本的な欠陥を修正せず Panic をキャッチする

このリファレンス内

ファイル	目的
references/tagged-errors.md	TaggedError パターン、マッチング、型ガード、例

opensrc/ が存在する場合、実装の詳細と現在の API 動作の信頼できるソースとして扱ってください。