rusty-result-kit

English Document

rusty-result-kit 是一个轻量的 Result<T, E> 容器，帮助你在 TypeScript 项目里显式描述成功与失败的结果，而不用处处抛异常，同时保留 Rust Result 的使用体验。

特性

• 基于判别属性的成功 / 失败容器，读取状态清晰 (ok / err)。
• 同时支持同步与异步代码：from、fromAsync、fromPromise 帮你捕获异常或拒绝。
• 提供丰富的链式工具（map、mapErr、mapAsync）与兜底方法（unwrap、unwrapOr、expect）。
• 无额外运行时依赖，内置 ESM、CJS、UMD、IIFE 多种构建格式与类型声明。

安装

任选常用的包管理器：

pnpm add rusty-result-kit
# 或者
yarn add rusty-result-kit
# 或者
npm install rusty-result-kit

快速上手

将可能抛错的逻辑包装成 Result，让调用方显式处理失败场景：

import { Result } from 'rusty-result-kit';

function parseCount(input: string): Result<number, Error> {
  return Result.from(() => {
    const value = Number.parseInt(input, 10);
    if (Number.isNaN(value)) {
      throw new Error('count 必须是数字');
    }
    return value;
  });
}

const count = parseCount('3')
  .map((value) => value * 2)
  .unwrapOr(0); // -> 6

const fallback = parseCount('oops').unwrapOr(0); // -> 0

显式处理错误

把异步流程转成 Result，无需再写「try/catch 套 try/catch」：

const result = await Result.fromAsync(async () => {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error('请求失败');
  }
  return response.json();
});

const data = result.match({
  ok: (value) => value,
  err: (error) => {
    console.error(error);
    return null;
  },
});

模式匹配与副作用

利用链式函数保持逻辑的声明式风格：

const message = Result.from(() => maybeFailingSyncWork())
  .inspect((value) => console.log('success', value))
  .inspectErr((error) => console.warn('error', error))
  .match({
    ok: (value) => `Finished with ${value}`,
    err: (error) => `Could not finish: ${error.message}`,
  });

如果只关心布尔值，isOkAnd 与 isErrAnd 会自动收窄类型：

const result = Result.from(() => findUser(id));

if (result.isOkAnd((user) => user.isActive)) {
  // 在此分支中 `user` 会被推断为活跃用户
}

API 概览

静态方法

| 方法 | 说明 | | --- | --- | | Result.ok(value) | 包装一个成功值。 | | Result.err(error) | 包装一个错误载荷。 | | Result.from(fn) | 捕获同步函数抛出的异常。 | | Result.fromAsync(fn) | 捕获异步函数抛出的异常或拒绝。 | | Result.fromPromise(promise) | 将现有 Promise 转成 Result。 |

实例方法

| 方法 | 说明 | | --- | --- | | ok、error、value | 访问内部状态。 | | map、mapAsync | 转换成功分支。 | | mapErr | 转换失败分支。 | | unwrap、unwrapOr、expect | 以不同兜底方式取出成功值。 | | match | 在成功 / 失败间进行穷尽式分支。 | | inspect、inspectErr | 执行副作用但返回原始结果。 | | isOkAnd、isErrAnd | 返回布尔并收窄承载的类型。 | | [Symbol.iterator] | 需要时可解构为 [value, error]。 |

类型提示

错误类型完全由你自定义，可用于表达更具体的领域错误：

type ParseError =
  | { kind: 'invalid-number'; input: string }
  | { kind: 'negative-number'; input: number };

function parsePositiveInt(input: string): Result<number, ParseError> {
  return Result.from(() => {
    const parsed = Number.parseInt(input, 10);
    if (Number.isNaN(parsed)) {
      throw { kind: 'invalid-number', input } satisfies ParseError;
    }
    if (parsed < 0) {
      throw { kind: 'negative-number', input: parsed } satisfies ParseError;
    }
    return parsed;
  });
}

在 parsePositiveInt 之后继续链式调用时，会一直保持 Result<number, ParseError> 推断，从而保证编译期的正确性。

分发形式

包内提供多种构建产物，可根据你的工具链自由选择：

• 默认导出为 ESM（import）。
• CommonJS 使用 require('rusty-result-kit')。
• 浏览器可直接通过 rusty-result-kit/umd 使用 UMD 版本。
• 临时脚本场景可以引入 rusty-result-kit/iife 的 IIFE 构建文件。
• 所有类型声明都位于 rusty-result-kit 或 rusty-result-kit/index.d.ts。

实现本身体积小且无副作用，打包工具能很好地进行 tree shaking。