Result - result/mod.ts - Trellis TypeScript API documentation

Examples

Example 1

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

const result = divide(10, 2)
  .map(x => x * 2)
  .map(x => x + 1);

const value = result.take();
if (isErr(value)) return value;
console.log(value); // 11

Type Parameters

The type of the success value



E extends BaseError

The type of the error (must extend BaseError)

Static Methods



all<T, E extends BaseError>(results: readonly Result<T, E>[]): Result<T[], E>

Combines multiple Results into a single Result containing an array.

If all Results are Ok, returns Ok with an array of all values. If any Result is Err, returns the first Err encountered.



any<T, E extends BaseError>(results: readonly Result<T, E>[]): Result<T, E>

Returns the first Ok result from an array of Results.

If any Result is Ok, returns that Ok result. If all Results are Err, returns the last Err.



err<E extends BaseError, T = never>(error: E): Result<T, E>

Creates a failed Result containing an error.



isErr<T, E extends BaseError>(result: Result<T, E>): result is Result<never, E>

Type guard to check if a value is an Err Result.

This function has multiple overloads:

Check if a Result is Err
Check if any value (including from take()) is Err



isErr<T, E extends BaseError>(value: T | Result<never, E>): value is Result<never, E>



isOk<T, E extends BaseError>(result: Result<T, E>): result is Result<T, never>

Type guard to check if a value is an Ok Result.



ok<T, E extends BaseError = never>(value: T): Result<T, E>

Creates a successful Result containing a value.



try<T>(fn: () => T,
context?: Record<string, unknown>
): Result<T, UnexpectedError>

Wraps a function that might throw into a Result.

Catches any exceptions and wraps them in UnexpectedError.

Properties

readonly



error: E

Gets the error from an Err Result.

Only call this after checking isErr(). If called on Ok, throws an error.

Methods



_unsafeValue(): ResultValue<T, E>

Internal method to get the raw value (for testing/debugging). Not recommended for general use - prefer take() instead.



andThen<U, F extends BaseError>(fn: (value: T) => Result<U, F>): Result<U, E | F>

Chains operations that return Results (also known as flatMap).

If this Result is Ok, calls the function with the Ok value and returns its Result. If this Result is Err, returns the Err without calling the function.



context(message: string,
extra?: Record<string, unknown>
): Result<T, E>

Adds context to an Err result for early returns. Chainable with take() for adding context when propagating errors.



inspect(fn: (value: T) => void): Result<T, E>

Performs a side effect on the Ok value without changing the Result.



inspectErr(fn: (error: E) => void): Result<T, E>

Performs a side effect on the Err value without changing the Result.



isErr(): this is Result<never, E>

Type guard to check if this Result is Err.



isOk(): this is Result<T, never>

Type guard to check if this Result is Ok.



map<U>(fn: (value: T) => U): Result<U, E>

Transforms the Ok value using a mapper function, leaving Err untouched.



mapErr<F extends BaseError>(fn: (error: E) => F): Result<T, F>

Transforms the Err value using a mapper function, leaving Ok untouched.



match<U>(pattern: { ok: (value: T) => U; err: (error: E) => U;  }): U

Pattern matching for Results - handle both Ok and Err cases.



or<U>(other: Result<U, E>): Result<T | U, E>

Returns this result if Ok, otherwise returns the fallback result.



orElse<U, F extends BaseError>(fn: (error: E) => Result<U, F>): Result<T | U, F>

Returns this result if Ok, otherwise computes a fallback from the error.



orThrow(): T

Returns the Ok value or throws the Err error.

This is useful at process or demo boundaries where exception-style control flow is acceptable and a caller wants to avoid repetitive take() / isErr(...) branching.



take(): [T] extends [never] ? Result<never, E> : T | Result<never, E>

Extracts the value from Ok or returns the Err for early returns.

This is the equivalent of Rust's ? operator. Use it with isErr() for early returns in functions that return Results.

Returns either:

The unwrapped value T if this result is Ok
An Err Result<never, E> if this result is Err (can be directly returned)



unwrapOr<U>(defaultValue: U): T | U

Returns the Ok value or a default value if Err.



unwrapOrElse<U>(fn: (error: E) => U): T | U

Returns the Ok value or computes a default from the error.