@brettchalupa/result

A TypeScript library implementing the Result pattern for type-safe error handling, inspired by Rust's Result<T, E>.

Features

• Type-safe error handling - Errors are part of the function signature
• Method chaining - Fluent API for transforming and combining results
• Zero dependencies - Lightweight and fast
• Full TypeScript support - Complete type inference and safety
• Well tested - Comprehensive test suite with 50+ tests

Installation

# Deno
deno add jsr:@brettchalupa/result

# pnpm 10.9+
pnpm add jsr:@brettchalupa/result

# yarn 4.9+
yarn add jsr:@brettchalupa/result

# npm, bun, and older versions of yarn or pnpm
npx jsr add @brettchalupa/result # replace npx with any of yarn dlx, pnpm dlx, or bunx

Or import directly in Deno without installation:

import { err, ok, Result } from "jsr:@brettchalupa/result";

const result = ok(42);

Quick Start

import { err, ok, type Result } from "@brettchalupa/result";

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return err("Cannot divide by zero");
  }
  return ok(a / b);
}

const result = divide(10, 2);
if (result.isOk()) {
  console.log("Result:", result.data); // Result: 5
} else {
  console.error("Error:", result.error);
}

Usage

Basic Results

Create successful or failed results:

import { err, ok } from "@brettchalupa/result";

// Success
const success = ok(42);
console.log(success.data); // 42

// Failure
const failure = err("Something went wrong");
console.log(failure.error); // "Something went wrong"

Method Chaining

Transform results with a fluent API:

const result = ok(5)
  .map((x) => x * 2)
  .map((x) => x.toString()); // ok("10")

const error = err("not_found").mapErr((code) => ({
  code,
  message: "Resource not found",
}));

Handling Async Operations

import { Result } from "@brettchalupa/result";

// Wrap throwing code
const parsed = Result.try(() => JSON.parse(jsonString));

// Wrap async operations
const data = await Result.tryAsync(() => fetch(url).then((r) => r.json()));

Combining Results

import { err, ok, Result } from "@brettchalupa/result";

// Collect all successes or get first error
const results = [ok(1), ok(2), ok(3)];
const combined = Result.all(results); // ok([1, 2, 3])

// Partition successes and failures
const mixed = [ok(1), err("error"), ok(3)];
const [successes, failures] = Result.partition(mixed);
// successes: [1, 3]
// failures: ["error"]

Repository Pattern

import { err, ok, type Result } from "@brettchalupa/result";

type User = { id: string; name: string };

// Define your own domain-specific error types
type DbError = "NOT_FOUND" | "CONNECTION_ERROR" | "PERMISSION_DENIED";

async function findUser(id: string): Promise<Result<User, DbError>> {
  try {
    const user = await db.findOne({ id });
    if (!user) {
      return err("NOT_FOUND");
    }
    return ok(user);
  } catch (error) {
    return err("CONNECTION_ERROR");
  }
}

API Reference

Constructors

• ok<T>(data: T): Ok<T> - Create a successful result
• err<E>(error: E): Err<E> - Create a failed result

Instance Methods

Both Ok and Err types support:

• .isOk() - Type guard for success
• .isErr() - Type guard for failure
• .map(fn) - Transform the success value
• .mapErr(fn) - Transform the error value
• .andThen(fn) - Chain operations that return Results
• .unwrapOr(defaultValue) - Get value or default
• .unwrap() - Get value or throw
• .expect(message) - Get value or throw with message

Utility Functions

The Result namespace provides:

• Result.try(fn) - Wrap a throwing function
• Result.tryAsync(fn) - Wrap an async throwing function
• Result.all(results) - Combine results
• Result.partition(results) - Separate successes and failures
• Result.collectErrors(results) - Get all errors
• Result.map(result, fn) - Static map function
• Result.mapErr(result, fn) - Static mapErr function
• Result.andThen(result, fn) - Static andThen function
• Result.unwrapOr(result, default) - Static unwrapOr function
• Result.unwrap(result) - Static unwrap function
• Result.expect(result, message) - Static expect function

Development

# Run tests
deno test

# Run all checks (format, lint, type check, test)
deno task ok

# Watch mode
deno task dev

License

This is free and unencumbered software released into the public domain. See UNLICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.