昨日の記事「【TypeScript】try...catchに頼らない型安全なエラーハンドリング」では、TypeScriptでのエラー処理における課題と、その解決策としてeffect-tsとts-resultによる「Result型パターン」について紹介しました。

今回は、その続編として、Result型パターンを実装したライブラリの一つである「neverthrow」について解説します。

前回紹介した課題をおさらいしておくと：

型の安全性がない: try...catchでは、エラーの型がanyまたはunknownになり、どのような種類のエラーが発生するかコンパイル時に把握できない
暗黙的な制御フロー: 関数のシグネチャからは、その関数が例外をスローする可能性があるかどうかわからない
捕捉すべき場所が不明確: どこでエラーをキャッチすべきか、コードから読み取りにくい

neverthrowは、これらの問題を解決するためのTypeScriptライブラリで、RustのResult型に着想を得た型安全なエラーハンドリングを提供します。今回はneverthrowの基本的な使い方から実践的なケースまで解説していきます。

neverthrowとは

neverthrowは、エラーを値として扱い、成功（Ok）または失敗（Err）のいずれかを表現するResult型を中心としたライブラリです。関数が例外をスローする代わりにResultを返すことで、型安全性を保ちながらエラーハンドリングを行うことができます。

同期処理にはResult型、非同期処理にはResultAsync型を使用します。ResultAsyncはPromise<Result<T, E>>をラップし、Resultと同様のAPIを提供します。

インストール方法

npmまたはyarnを使ってインストールできます：

npm install neverthrow
# または
yarn add neverthrow

基本的な使い方

1. Result型の作成

最も基本的な使い方は、ok関数とerr関数を使ってResult型のインスタンスを作成することです：

import { ok, err, Result } from 'neverthrow'

// 成功の場合
const successResult: Result<number, string> = ok(42)

// 失敗の場合
const errorResult: Result<number, string> = err("計算エラー")

Result<T, E>の型パラメータは、Tが成功時の値の型、Eが失敗時のエラーの型を表します。

2. Resultの状態確認

Resultが成功か失敗かを確認するには、isOk()とisErr()メソッドを使います：

if (successResult.isOk()) {
  console.log("成功:", successResult.value)
}

if (errorResult.isErr()) {
  console.log("エラー:", errorResult.error)
}

3. map、mapErrによる変換

値を変換するにはmapとmapErrメソッドを使います：

// 成功値の変換
const doubledResult = successResult.map(value => value * 2)
// doubledResult は ok(84) となる

// エラーの変換
const betterErrorResult = errorResult.mapErr(error => `${error} (エラーコード: E001)`)
// betterErrorResult は err("計算エラー (エラーコード: E001)") となる

4. 実用的な例: 数値の除算

次の例では、0による除算を安全に行う関数を実装します：

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return err("ゼロ除算エラー")
  }
  return ok(a / b)
}

// 使用例
const result1 = divide(10, 2)
const result2 = divide(10, 0)

result1.match(
  value => console.log("結果:", value),
  error => console.error("エラー:", error)
)
// 出力: "結果: 5"

result2.match(
  value => console.log("結果:", value),
  error => console.error("エラー:", error)
)
// 出力: "エラー: ゼロ除算エラー"

この例では、divide関数が0による除算を検出した場合にerrを返します。呼び出し元ではmatchメソッドを使って、成功・失敗それぞれのケースを明示的に処理しています。

連鎖的な処理（Railway Oriented Programming）

neverthrowの最も強力な機能の一つが、連鎖的な処理を可能にするandThenメソッドです。これは「Railway Oriented Programming」と呼ばれるパターンを実現します。

andThenによる処理の連鎖

andThenは、前の操作が成功した場合にのみ次の操作を実行します。これにより、複数の操作を連鎖させる際に、エラーハンドリングを簡潔に書けます：

import { ok, err, Result } from 'neverthrow'

// ユーザー入力を検証する関数
function validateUsername(username: string): Result<string, string> {
  if (username.length < 3) {
    return err("ユーザー名は3文字以上である必要があります")
  }
  return ok(username)
}

// ユーザー名からIDを生成する関数
function generateUserId(username: string): Result<number, string> {
  // もちろん下記のUSER_ID生成は例ですので
  return ok(username.length * 100 + Math.floor(Math.random() * 100))
}

// ユーザー登録を行う関数
function registerUser(username: string): Result<{ id: number, name: string }, string> {
  return validateUsername(username)
    .andThen(validUsername => generateUserId(validUsername)
      .map(userId => ({ id: userId, name: validUsername }))
    )
}

// 使用例
const registrationResult = registerUser("alice")
registrationResult.match(
  user => console.log("登録成功:", user),
  error => console.error("登録失敗:", error)
)
// 出力例: "登録成功: { id: 512, name: 'alice' }"

const failedRegistration = registerUser("al")
failedRegistration.match(
  user => console.log("登録成功:", user),
  error => console.error("登録失敗:", error)
)
// 出力: "登録失敗: ユーザー名は3文字以上である必要があります"

この例では、ユーザー登録プロセスを複数のステップに分け、andThenで連鎖させています。最初のステップでエラーが発生すると、後続のステップは実行されず、エラーが最終結果として返されます。

非同期処理での使用（ResultAsync）

現実のアプリケーションでは、APIリクエストやデータベース操作など、非同期処理が不可欠です。neverthrowのResultAsyncクラスは、そのような非同期処理をサポートします。

ResultAsyncの基本

ResultAsyncはPromise<Result<T, E>>のラッパーですが、Resultと同様のAPIを提供します：

import { okAsync, errAsync, ResultAsync } from 'neverthrow'

// 非同期処理の成功
const successAsync = okAsync(42)

// 非同期処理の失敗
const errorAsync = errAsync("非同期処理エラー")

// 使用例
successAsync.match(
  value => console.log("成功:", value),
  error => console.error("エラー:", error)
).then(() => {
  // matchの後はPromiseが返る
})

Promise から ResultAsync への変換

既存のPromiseベースのAPIを使ってResultAsyncを作成するには、fromPromiseメソッドを使います：

import { ResultAsync } from 'neverthrow'

// APIから何かをフェッチする関数
async function fetchData(url: string): Promise<any> {
  const response = await fetch(url)
  return response.json()
}

// ResultAsyncに変換
const result = ResultAsync.fromPromise(
  fetchData('https://api.example.com/data'),
  error => `APIエラー: ${error instanceof Error ? error.message : String(error)}`
)

// 使用
result
  .map(data => {
    console.log("データを受信:", data)
    return data
  })
  .mapErr(error => {
    console.error(error)
    return error
  })
  .then(finalResult => {
    // finalResultはResult<any, string>型
  })

非同期処理の連鎖

非同期処理もandThenで連鎖させることができます：

import { ok, err, Result, ResultAsync } from 'neverthrow'

// ユーザーIDからユーザー情報を取得する関数
function fetchUser(id: number): ResultAsync<User, string> {
  return ResultAsync.fromPromise(
    fetch(`https://api.example.com/users/${id}`)
      .then(res => res.json()),
    () => "ユーザー情報の取得に失敗しました"
  )
}

// ユーザーの注文履歴を取得する関数
function fetchOrders(user: User): ResultAsync<Order[], string> {
  return ResultAsync.fromPromise(
    fetch(`https://api.example.com/users/${user.id}/orders`)
      .then(res => res.json()),
    () => "注文履歴の取得に失敗しました"
  )
}

// 使用例: ユーザーIDから注文履歴を取得
const userId = 123
const ordersResult = fetchUser(userId)
  .andThen(user => fetchOrders(user))

ordersResult.match(
  orders => console.log(`${orders.length}件の注文が見つかりました`),
  error => console.error(error)
).then(() => {
  // 処理完了
})

実践的なパターン

neverthrowをより効果的に使うためのパターンをいくつか紹介します。

1. try/catchをResultに変換

既存コードの例外処理をResultパターンに変換するためのヘルパー関数：

import { ok, err, Result } from 'neverthrow'

// 例外をResultに変換するヘルパー関数
function tryCatch<T, E = Error>(fn: () => T): Result<T, E> {
  try {
    return ok(fn())
  } catch (error) {
    return err(error as E)
  }
}

// JSONパースでの使用例
function safeJsonParse(json: string): Result<unknown, Error> {
  return tryCatch(() => JSON.parse(json))
}

// 使用例
const validJson = '{"name": "John", "age": 30}'
const invalidJson = '{name: John}'

safeJsonParse(validJson).match(
  data => console.log("パース成功:", data),
  error => console.error("パース失敗:", error.message)
)

safeJsonParse(invalidJson).match(
  data => console.log("パース成功:", data),
  error => console.error("パース失敗:", error.message)
)

2. カスタムエラー型の使用

より型安全なエラーハンドリングのためにカスタムエラー型を定義できます：

// エラー型の定義
type ValidationError = {
  type: 'VALIDATION'
  field: string
  message: string
}

type NetworkError = {
  type: 'NETWORK'
  status: number
  message: string
}

// 使用するエラー型
type AppError = ValidationError | NetworkError

// ユーザー検証関数
function validateUser(user: any): Result<User, ValidationError> {
  if (!user.name) {
    return err({
      type: 'VALIDATION',
      field: 'name',
      message: '名前は必須です'
    })
  }
  
  if (!user.email) {
    return err({
      type: 'VALIDATION',
      field: 'email',
      message: 'メールアドレスは必須です'
    })
  }
  
  return ok(user as User)
}

// APIからユーザーを取得する関数
function fetchUser(id: string): ResultAsync<any, NetworkError> {
  return ResultAsync.fromPromise(
    fetch(`/api/users/${id}`).then(res => {
      if (!res.ok) {
        throw {
          type: 'NETWORK',
          status: res.status,
          message: `HTTPエラー: ${res.status}`
        }
      }
      return res.json()
    }),
    (error): NetworkError => {
      if (typeof error === 'object' && error !== null && 'type' in error && error.type === 'NETWORK') {
        return error as NetworkError
      }
      return {
        type: 'NETWORK',
        status: 0,
        message: '未知のネットワークエラー'
      }
    }
  )
}

// エラー型に基づいた処理
fetchUser('123')
  .andThen(user => validateUser(user))
  .match(
    validUser => {
      console.log("有効なユーザー:", validUser)
    },
    error => {
      switch (error.type) {
        case 'VALIDATION':
          console.error(`バリデーションエラー - ${error.field}: ${error.message}`)
          break
        case 'NETWORK':
          console.error(`ネットワークエラー (${error.status}): ${error.message}`)
          break
      }
    }
  )

このパターンでは、エラー型にタグを付けることで、発生したエラーの種類を型安全に識別できます。

3. フォームバリデーションでの活用

Webフォームの検証は、neverthrowが特に有用なユースケースです：

type FormData = {
  username: string
  email: string
  password: string
}

type FormValidationError = {
  field: keyof FormData
  message: string
}

// 個別のフィールド検証関数
function validateUsername(username: string): Result<string, FormValidationError> {
  if (username.length < 3) {
    return err({
      field: 'username',
      message: 'ユーザー名は3文字以上必要です'
    })
  }
  return ok(username)
}

function validateEmail(email: string): Result<string, FormValidationError> {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
  if (!emailRegex.test(email)) {
    return err({
      field: 'email',
      message: '有効なメールアドレスを入力してください'
    })
  }
  return ok(email)
}

function validatePassword(password: string): Result<string, FormValidationError> {
  if (password.length < 8) {
    return err({
      field: 'password',
      message: 'パスワードは8文字以上必要です'
    })
  }
  return ok(password)
}

// フォームの検証
function validateForm(formData: FormData): Result<FormData, FormValidationError> {
  // 各フィールドを検証
  const usernameResult = validateUsername(formData.username)
  const emailResult = validateEmail(formData.email)
  const passwordResult = validatePassword(formData.password)
  
  // 最初に見つかったエラーを返す（早期リターン）
  if (usernameResult.isErr()) return usernameResult.mapErr(e => e)
  if (emailResult.isErr()) return emailResult.mapErr(e => e)
  if (passwordResult.isErr()) return passwordResult.mapErr(e => e)
  
  // すべてのフィールドが有効な場合
  return ok(formData)
}

// 使用例
const formData: FormData = {
  username: 'al',  // 無効
  email: 'alice@example.com',
  password: 'securepassword'
}

const validationResult = validateForm(formData)

validationResult.match(
  validData => {
    console.log("フォームの検証に成功しました:", validData)
    // フォームの送信処理
  },
  error => {
    console.error(`${error.field}が無効です: ${error.message}`)
    // エラーメッセージの表示など
  }
)

combine機能：複数のResultを組み合わせる

複数のResultを一度に処理するには、combine静的メソッドが便利です：

import { ok, err, Result } from 'neverthrow'

// いくつかのResult
const result1 = ok(1)
const result2 = ok(2)
const result3 = err("エラー発生")
const result4 = ok(4)

// 同種のResultを組み合わせる
const results = [result1, result2, result4]
const combined = Result.combine(results)
// combined は ok([1, 2, 4]) となる

// エラーがある場合
const resultsWithError = [result1, result2, result3, result4]
const combinedWithError = Result.combine(resultsWithError)
// combinedWithError は err("エラー発生") となる
// 最初のエラーで短絡評価される

// すべてのエラーを収集したい場合
const allErrors = Result.combineWithAllErrors(resultsWithError)
// allErrors は err(["エラー発生"]) となる
// 複数のエラーがある場合はそれらすべてが配列に含まれる

この機能は、例えば複数のフォームフィールドを検証し、すべてのエラーを一度に表示したい場合などに役立ちます。

テストでのneverthrowの使用

neverthrowはテストを書きやすくします。Resultインスタンスは比較可能なため、期待値と直接比較できます：

import { ok, err } from 'neverthrow'

// テスト用の関数
function divide(a: number, b: number) {
  if (b === 0) {
    return err("ゼロ除算エラー")
  }
  return ok(a / b)
}

// Jestなどのテストフレームワークを使ったテスト
describe('divide', () => {
  it('正常な除算ができること', () => {
    expect(divide(10, 2)).toEqual(ok(5))
  })
  
  it('ゼロ除算でエラーを返すこと', () => {
    expect(divide(10, 0)).toEqual(err("ゼロ除算エラー"))
  })
})

また、内部的なテスト用に_unsafeUnwrapと_unsafeUnwrapErrメソッドも提供されていますが、これらはテスト環境でのみ使用すべきです。

eslint-plugin-neverthrow

neverthrowを効果的に使うために、eslint-plugin-neverthrowというESLintプラグインが公開されています。このプラグインは、Resultを適切に処理することを強制し、エラーハンドリングの漏れを防ぎます。

インストール：

npm install eslint-plugin-neverthrow --save-dev

eslint-plugin-neverthrowを使うと、次の3つの方法のいずれかでResultを消費することが強制されます：

.matchの呼び出し
.unwrapOrの呼び出し
._unsafeUnwrapの呼び出し（テスト用）

これにより、エラーハンドリングを忘れることがなくなります。これはRustのmust-use属性と同様の機能です。

Effectとneverthrowの比較

前回の記事で紹介した「Effect」ライブラリとneverthrowの主な違いをおさらいしましょう：

特徴	neverthrow	Effect
複雑さ	シンプル	高度
学習曲線	比較的緩やか	比較的急
実行モデル	即時評価	遅延評価
機能範囲	エラーハンドリングに特化	包括的な関数型プログラミング機能セット
依存性注入	含まれていない	組み込みサポートあり
非同期処理	基本的なサポート	高度なサポート

neverthrowは、特にエラーハンドリングに焦点を当てたシンプルなライブラリであり、導入しやすい点が魅力です。一方、Effectはより豊富な機能を提供しています。

まとめ

neverthrowは、TypeScriptでの型安全なエラーハンドリングを実現する強力なライブラリです。主なメリットは：

型安全性: エラーの種類がコンパイル時に明確になります
明示的なエラー処理: 関数のシグネチャからエラーの可能性が明確になります
合成可能性: 関数を安全に連鎖させて複雑な操作を構築できます

従来のtry...catchによるエラー処理と比較して、neverthrowを使用することで：

エラーハンドリングの漏れを減らせる
コードが読みやすく、メンテナンスしやすくなる
型システムの恩恵を最大限に受けられる

特に複数の処理を連鎖させる場合や、明確なエラータイプの区別が必要な場合に、neverthrowは真価を発揮します。個人的にも、neverthrowこそが私の求めていたものだと感じました！

参考リンク