result/mod.ts - Trellis TypeScript API documentation

Examples

Basic usage with static methods

import { Result } from "@qlever-llc/result";

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 (Result.isErr(value)) return value;
console.log(value); // 11

Async operations

import { AsyncResult, Result } from "@qlever-llc/result";

const user = AsyncResult.try(async () => {
  const response = await fetch(`/api/users/123`);
  return await response.json();
});

const result = user
  .map(user => user.name)
  .map(name => name.toUpperCase());

const value = await result.take();
if (Result.isErr(value)) return value;
console.log(value); // "ALICE"

Classes

c

AsyncResult<T, E extends BaseError>(promise: Promise<Result<T, E>>)

An asynchronous Result class that represents a Promise of Result<T, E>.

all<T, E extends BaseError>(results: readonly (AsyncResult<T, E> | Promise<Result<T, E>>)[]): AsyncResult<T[], E>
Combines multiple AsyncResults into a single AsyncResult containing an array.
andThen<U, F extends BaseError>(fn: (value: T) => Result<U, F> | AsyncResult<U, F> | Promise<Result<U, F>>): AsyncResult<U, E | F>
Chains operations that return Results.
any<T, E extends BaseError>(results: readonly (AsyncResult<T, E> | Promise<Result<T, E>>)[]): AsyncResult<T, E>
Returns the first Ok result from an array of AsyncResults.
context(
message: string,
extra?: Record<string, unknown>
): AsyncResult<T, E>
Adds context to an Err result for early returns. Async version - can be chained before take().
err<E extends BaseError, T = never>(error: E): AsyncResult<T, E>
Creates a failed AsyncResult with the given error.
from<T, E extends BaseError>(promise: Promise<Result<T, E>>): AsyncResult<T, E>
Creates an AsyncResult from a Promise of Result.
inspect(fn: (value: T) => void | Promise<void>): AsyncResult<T, E>
Performs a side effect on the Ok value without changing the result.
inspectErr(fn: (error: E) => void | Promise<void>): AsyncResult<T, E>
Performs a side effect on the Err value without changing the result.
lift<T, E extends BaseError>(value: Result<T, E> | AsyncResult<T, E> | Promise<Result<T, E>>): AsyncResult<T, E>
Creates an AsyncResult from a Result, AsyncResult, or Promise<Result>.
map(fn: (value: T) => U): AsyncResult<U, E>
Transforms the Ok value using a mapper function, leaving Err untouched.
mapErr<F extends BaseError>(fn: (error: E) => F): AsyncResult<T, F>
Transforms the Err value using a mapper function, leaving Ok untouched.
match(pattern: { ok: (value: T) => U; err: (error: E) => U; }): Promise
Pattern matching for async Results.
ok<T, E extends BaseError = never>(value: T): AsyncResult<T, E>
Creates a successful AsyncResult with the given value.
or(other: Result<U, E> | AsyncResult<U, E> | Promise<Result<U, E>>): AsyncResult<T | U, E>
Returns this result if Ok, otherwise returns the fallback.
orElse<U, F extends BaseError>(fn: (error: E) => Result<U, F> | AsyncResult<U, F> | Promise<Result<U, F>>): AsyncResult<T | U, F>
Returns this result if Ok, otherwise computes a fallback from the error.
orThrow(): Promise<T>
Returns the Ok value or throws the Err error.
take(): Promise<T | Result<never, E>>
Extracts the value from Ok or returns the Err for early returns.
then<TResult1 = Result<T, E>, TResult2 = never>(
onfulfilled?:
((value: Result<T, E>) => TResult1 | PromiseLike<TResult1>)
| null,
onrejected?:
((reason: unknown) => TResult2 | PromiseLike<TResult2>)
| null
): Promise<TResult1 | TResult2>
Implements PromiseLike to make AsyncResult awaitable.
try<T>(
fn: () => Promise<T>,
context?: Record<string, unknown>
): AsyncResult<T, UnexpectedError>
Wraps an async function that might throw into an AsyncResult.
unwrapOr(defaultValue: U): Promise<T | U>
Returns the Ok value or a default value if Err.
unwrapOrElse(fn: (error: E) => U): Promise<T | U>
Returns the Ok value or computes a default from the error.

c

BaseError<TData extends BaseErrorSchema = BaseErrorSchema>(

message: string,

options?: BaseErrorOptions

)

Base class for all errors used in Result<T, E>.

baseSerializable(): BaseErrorSchema
Helper method to get base serializable fields. Subclasses should use this to build their complete serializable object.
getContext(): Record<string, unknown>
Get the current context object.
getTraceId(): string | undefined
Get the trace ID for this error. Returns the trace ID captured at error creation time.
id: string
Unique identifier for this error instance
name: string
Error type name (used for discrimination)
toJSON(): string
Serializes error to JSON string.
toSerializable(): TData
Serializes error to a plain object. Subclasses must implement this to return their specific data type.
traceIdGetter: (() => string | undefined) | undefined
Optional callback to provide a trace ID from ambient context (e.g. OpenTelemetry).
withContext(context?: Record<string, unknown>): this
Add contextual information to this error. Useful for adding runtime context like request IDs, user IDs, etc.
withTraceId(traceId: string | undefined): this
Attach a trace ID if one was not captured when the error was created.