typescript-result

When working with asynchronous operations, typescript-result provides AsyncResult. This is essentially a Promise containing a Result. It allows you to chain operations like .map() without manually await-ing every intermediate step or nesting multiple if (result.ok) checks. The library automatically converts synchronous Result instances into AsyncResult when an async operation is introduced into the chain.

import { Result } from "typescript-result";

// The library automatically handles the transition from Result to AsyncResult
const result = await Result.ok(12)
  // map the value to a Promise -> returns AsyncResult
  .map((value) => Promise.resolve(value * 2))
  // map async to another result -> returns AsyncResult
  .map(async (value) => {
    if (value < 10) {
      return Result.error(new Error("Value too low"));
    }
    return Result.ok("All good!");
  });

The map method is polymorphic and can change the type of the Result or AsyncResult based on the return value of the callback. Depending on what the callback returns, the chain can transition between different types:

• Returning a plain value: Keeps the same Result type.
• Returning a Result.ok(...): Keeps the same Result type (due to automatic flattening).
• Returning a Promise or using an async function: Converts the Result into an AsyncResult.
• Returning a Generator (function*) with yield*: Converts the Result into an AsyncResult.

import { Result } from "typescript-result";

declare function someOperation(): Result<number, Error>;
// ---cut-before---
declare const result: Result<number, Error>;

const nextResult = result // Result<number, Error>
  .map((value) => value * 2) // Result<number, Error> 
  .map((value) => Result.ok(value * 2)) // Result<number, Error>
  .map((value) => Promise.resolve(value * 2)) // AsyncResult<number, Error>
  .map(async (value) => value * 2) // AsyncResult<number, Error>
  .map(async (value) => Result.ok(value * 2)) // AsyncResult<number, Error>
  .map(function* (value) {
    const other = yield* someOperation();
    return value * other;
  }); // AsyncResult<number, Error>

If you are using a function that must return a value (like the callback in getOrElse), you can leverage TypeScript's noImplicitReturn compiler option to enforce exhaustive error handling.

When noImplicitReturn is enabled (which is automatic if strict is enabled), TypeScript will flag an error if a switch statement handling error types fails to provide a return statement for every possible case. This prevents accidental fall-through when a new error type is introduced to the union.

import { Result } from "typescript-result";

class ErrorA extends Error { readonly type = "error-a"; }
class ErrorB extends Error { readonly type = "error-b"; }

declare const result: Result<string, ErrorA | ErrorB>;

// If noImplicitReturn is enabled, this will error because ErrorB is not handled
const output = result.getOrElse((error) => {
  switch (error.type) {
    case "error-a":
      return "Fallback for Error A";
    // ErrorB is missing a return case, triggering a TS error
  }
});

To avoid repetitive if (!result.ok) return result; checks (the Go-style pattern), you can chain operations on a Result instance.

• .map(fn): Transforms the successful value inside a Result. If the function returns another Result, the chain becomes polymorphic (nested Results).
• .mapCatching(fn, errorMapper): Similar to map, but allows the transformation function itself to throw. If it throws, the error is caught and transformed using the provided errorMapper.

This allows you to build complex workflows where each step only executes if the previous one succeeded.

import { Result } from "typescript-result";

// Chaining multiple wrapped functions
function readConfig(filePath: string) {
  return readFile(filePath)
    .map((contents) => parseJSON(contents))
    .map((json) => parseConfig(json));
}

// Using mapCatching to inline a throwing operation
function readConfigInline(filePath: string) {
  return readFile(filePath)
    .mapCatching(
      (contents) => JSON.parse(contents),
      () => new ParseError(`Unable to parse JSON`)
    )
    .map((json) => parseConfig(json));
}

The library supports two primary patterns for interacting with Result and AsyncResult instances:

1. Chaining Style (Functional): Uses methods like .map() to transform values. This is best for simple, single-line transformations and keeps code compact. It allows for centralized error handling at the end of the chain.
2. Generator Style (Imperative): Uses generator functions and yield* to write code that looks like normal sequential operations. This is best for complex control flows involving loops, conditionals, or deeply nested transformations.

Decision Guide:

• Use Chaining if you are performing simple transformations.
• Use Generators if you have complex logic, loops, or many nested steps.

// Chaining style (Functional)
const result = someOperation()
  .map((value) => anotherOperation(value))
  .map((value) => yetAnotherOperation(value));

// Generator style (Imperative)
function* getValues() {
  const a = yield* operationA();
  const b = yield* operationB(a);
  return b;
}
const result = Result.gen(getValues());