@mkvlrn/result

Dead simple Result pattern for TypeScript.

No .map(), no .flatMap(), no .andThen(), no .orElse(), no .unwrap(), no monadic gymnastics. Just two types with two functions. Then TypeScript does its thing.

Why this one?

There are dozens of Result pattern libraries for TypeScript. Nearly all of them bolt on method chaining, transformation pipelines, and functional programming utilities that turn a simple concept into an entire paradigm.

This package does one thing: gives you a type-safe Result<T, E> or ResultAsync<T, E> discriminated union with Result.ok()/Result.err() and ResultAsync.ok()/ResultAsync.err() constructors. You use if/else to handle it. TypeScript narrows the type for you. That's the whole API.

If you need .map().flatMap().andThen().orElse().unwrapOr() chains, use neverthrow or ts-results. They're good libraries. This isn't that.

Installation

[!NOTE] This package is hosted at npm, and is ESM only.

| Package manager | cmd | | --------------- | ---------------------------- | | pnpm | pnpm add @mkvlrn/result | | npm | npm install @mkvlrn/result | | yarn | yarn add @mkvlrn/result |

API

| Export | What it does | | ------------------------ | ----------------------------------------------------------------------------------- | | Result<T, E> | Synchronous Result type ({ isError: false, value } or { isError: true, error }) | | ResultAsync<T, E> | Asynchronous Result type (Promise<Result<T, E>>) | | Result.ok(value) | Creates a successful Result object | | Result.err(error) | Creates an error Result object | | ResultAsync.ok(value) | Creates a Promise containing a successful Result object | | ResultAsync.err(error) | Creates a Promise containing an error Result object |

That's it. That's the whole thing.

Usage

import { Result, ResultAsync } from "@mkvlrn/result";

Create results, check results

function divide(a: number, b: number): Result<number, Error> {
  if (b === 0) {
    return Result.err(new Error("Division by zero"));
  }

  return Result.ok(a / b);
}

const result = divide(10, 2);
if (result.isError) {
  console.log(result.error.message); // Error - TypeScript knows
} else {
  console.log(result.value); // number - TypeScript knows
}

No .unwrap(), no .expect(), no other dozens of functions. You just use an if statement and the compiler handles the rest.

Async Operations

async function fetchUser(id: number): ResultAsync<User, Error> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      return ResultAsync.err(new Error(`HTTP ${response.status}`));
    }
    const user = await response.json();

    return ResultAsync.ok(user);
  } catch (error) {
    return ResultAsync.err(error instanceof Error ? error : new Error("Unknown error"));
  }
}

ResultAsync<T, E> is just Promise<Result<T, E>>. It's a type alias.

Custom Error Types

class ValidationError extends Error {
  readonly code: number;

  constructor(code: number, message: string) {
    super(message);
    this.name = "ValidationError";
    this.code = code;
  }
}

function validateEmail(email: string): Result<string, ValidationError> {
  if (!email.includes("@")) {
    return Result.err(new ValidationError(400, "bad-email"));
  }

  return Result.ok(email);
}

const result = validateEmail("invalid-email");
if (result.isError) {
  // TypeScript knows this is a ValidationError, not just Error
  console.log(`${result.error.code}:${result.error.message}`); // 400: bad-email
}

License

MIT