@harusame0616/result

TypeScript向けの型安全なResult型ライブラリ

概要

プレーンオブジェクトベースのResult型をTypeScriptで提供します。エラーハンドリングを型安全に行うことができます。

特徴

• ✅ プレーンオブジェクト実装（シリアライズ可能）
• ✅ TypeScriptの型ガード（Discriminated Union）に対応
• ✅ 軽量・シンプルな API
• ✅ ビルド済みファイル同梱（インストール後すぐ使える）

インストール

# npm経由でインストール
npm install @harusame0616/result
# または
pnpm add @harusame0616/result
# または
yarn add @harusame0616/result

使い方

基本的な使い方

import { succeed, fail, type Result } from '@harusame0616/result';

// 成功値を返す
const success: Result<number, string> = succeed(42);

// エラー値を返す
const failure: Result<number, string> = fail('エラーが発生しました');

// 型ガードで値にアクセス
if (success.success) {
  console.log(success.data); // 42
}

if (!failure.success) {
  console.log(failure.error); // 'エラーが発生しました'
}

引数なしで呼び出す

import { succeed } from '@harusame0616/result';

// 引数なしで呼び出すと undefined を返す
const result = succeed();
console.log(result.success); // true
console.log(result.data); // undefined

例外のキャッチ

import { tryCatch, tryCatchAsync } from '@harusame0616/result';

// 同期関数
const result = tryCatch(
  () => JSON.parse('invalid json'),
  (e) => `Parse error: ${e}`
);

if (!result.success) {
  console.log(result.error); // Parse error: ...
}

// 非同期関数
const asyncResult = await tryCatchAsync(
  async () => {
    const response = await fetch('https://api.example.com');
    return response.json();
  },
  (e) => `Fetch error: ${e}`
);

if (asyncResult.success) {
  console.log(asyncResult.data); // レスポンスデータ
}

Result 型の展開

tryCatch / tryCatchAsync の中で succeed や fail を返すと、型が自動的に展開されます。

import { tryCatch, succeed, fail } from '@harusame0616/result';

// succeed を返すと Success 側に展開される
const result1 = tryCatch(() => succeed("成功"));
// result1: Result<string, Error>

// fail を返すと Failure 側に展開される
const result2 = tryCatch(() => fail("失敗"));
// result2: Result<never, string | Error>

// 条件によって succeed/fail を返す
const result3 = tryCatch(() => {
  const value = getValue();
  if (value > 0) {
    return succeed(value);
  }
  return fail("値が不正です");
});
// result3: Result<number, string | Error>

if (result3.success) {
  console.log(result3.data); // number型
} else {
  console.log(result3.error); // string | Error型
}

API

型定義

Result<T, E>

成功（Success<T>）または失敗（Failure<E>）を表すユニオン型

type Result<T, E> = Success<T> | Failure<E>;

Success

成功を表す型

type Success<T> = {
  success: true;
  data: T;
};

Failure

失敗を表す型

type Failure<E> = {
  success: false;
  error: E;
};

関数

succeed(data: T): Success

成功値を持つResultを生成

const result = succeed(42);
// { success: true, data: 42 }

succeed(): Success

引数なしで呼び出すとundefinedを持つ成功を生成

const result = succeed();
// { success: true, data: undefined }

fail(error: E): Failure

エラー値を持つResultを生成

const result = fail('エラーメッセージ');
// { success: false, error: 'エラーメッセージ' }

ユーティリティ関数

tryCatch<T, E>(fn: () => T, onError?: (error: unknown) => E): Result<T, E>

例外をキャッチしてResultに変換

const result = tryCatch(
  () => JSON.parse('invalid'),
  (e) => `Parse failed: ${e}`
);

tryCatchAsync<T, E>(fn: () => Promise, onError?: (error: unknown) => E): Promise<Result<T, E>>

非同期関数の例外をキャッチしてResultに変換

const result = await tryCatchAsync(
  async () => await fetchData(),
  (e) => `Fetch failed: ${e}`
);

型ヘルパー

Result 型を操作するためのユーティリティ型を提供しています。

ExcludeFailure

任意の型から Failure 型を除外します。

import type { ExcludeFailure, Failure } from '@harusame0616/result';

type A = string | number | Failure<Error>;
type B = ExcludeFailure<A>; // string | number

ExtractSuccessType

任意の型から Success 型のみを抽出します。

import type { ExtractSuccessType, Success, Failure } from '@harusame0616/result';

type A = string | number | Success<string> | Failure<Error>;
type B = ExtractSuccessType<A>; // Success<string>

ExtractFailure

任意の型から Failure 型のみを抽出します。

import type { ExtractFailure, Success, Failure } from '@harusame0616/result';

type A = string | number | Success<string> | Failure<Error>;
type B = ExtractFailure<A>; // Failure<Error>

型ガード

Result型は TypeScript の Discriminated Union として実装されているため、successプロパティで型を絞り込めます。

const result: Result<number, string> = succeed(42);

if (result.success) {
  // この中では result は Success<number> 型
  console.log(result.data); // number型としてアクセス可能
} else {
  // この中では result は Failure<string> 型
  console.log(result.error); // string型としてアクセス可能
}

開発

リリース方法

GitHub Actions で自動的に npm に公開されます。

1. package.json の version を更新
2. 変更をコミット
3. Git タグを作成してプッシュ

# バージョンを更新（例: 1.0.0 → 1.0.1）
npm version patch  # または minor, major

# タグをプッシュ
git push --follow-tags

GitHub Actions が自動的にテスト・ビルド・npm への公開を実行します。

初回セットアップ

GitHub リポジトリの Settings > Secrets and variables > Actions から、以下のシークレットを設定してください：

• NPM_TOKEN: npm のアクセストークン（https://www.npmjs.com/settings/[username]/tokens から取得）

ライセンス

MIT