Result

Result<T, E> represents a value that is either a success (Ok<T>) or a failure (Err<E>). Every Result carries its error type in the signature; no implicit throw, no silent null. Both branches share the same set of chainable methods.

import { chas } from 'ts-chas';

// Ok branch — has .ok === true and .value
const success: chas.Result<number, never> = chas.ok(42);

// Err branch — has .ok === false and .error
const failure: chas.Result<never, string> = chas.err('something went wrong');

Creating Results

`chas.ok(value)`

Wraps a value in an Ok result.

required

The success value to wrap.

Result<T, never>

A result in the Ok state containing value.

const result = chas.ok(42);
// result.ok === true
// result.value === 42

`chas.err(error)`

Wraps an error in an Err result.

required

The error value to wrap.

Result<never, E>

A result in the Err state containing error.

const result = chas.err('not found');
// result.ok === false
// result.error === 'not found'

`chas.okAsync(value)`

Wraps a value (or Promise of a value) in a ResultAsync that resolves to Ok.

T | Promise<T>

required

The success value or promise to wrap.

ResultAsync<T, never>

A ResultAsync that resolves to Ok(value).

const res = chas.okAsync(42);
const result = await res; // Ok(42)

`chas.errAsync(error)`

Wraps an error (or Promise of an error) in a ResultAsync that resolves to Err.

E | Promise<E>

required

The error value or promise to wrap.

ResultAsync<never, E>

A ResultAsync that resolves to Err(error).

const res = chas.errAsync('request failed');
const result = await res; // Err('request failed')

`chas.tryCatch(fn, mapErr?)`

Calls a synchronous function that may throw and wraps the outcome in a Result. Returns Ok on success or Err if the function throws.

() => T

required

The synchronous function to call.

(error: unknown) => E

Maps the thrown value to your error type. When omitted, the error is typed as unknown.

Result<T, E>

Ok(returnValue) or Err(mappedError).

const result = chas.tryCatch(
  () => JSON.parse('{"name":"Alice"}'),
  (e) => new Error(`Invalid JSON: ${e}`)
);

if (result.isOk()) {
  console.log(result.value.name); // 'Alice'
}

`chas.fromPromise(promise, mapErr?)`

Wraps a Promise in a ResultAsync. Resolves to Ok on fulfillment or Err on rejection.

Promise<T>

required

The promise to wrap.

(error: unknown) => E

Maps the rejection reason to your error type. When omitted, the error is typed as unknown.

ResultAsync<T, E>

A ResultAsync wrapping the promise outcome.

const result = await chas.fromPromise(
  fetch('/api/user').then(r => r.json()),
  (e) => `Fetch failed: ${e}`
);

if (result.isOk()) {
  console.log(result.value); // parsed JSON body
}

Instance methods

Every Result<T, E> has the following methods regardless of whether it is Ok or Err.

`.isOk()`

Type guard that narrows to Ok<T>.

boolean

true if the result is Ok<T>, false otherwise. When true, TypeScript narrows the type so result.value is accessible.

const result = chas.ok(5);

if (result.isOk()) {
  console.log(result.value); // 5 — TypeScript knows .value exists here
}

`.isErr()`

Type guard that narrows to Err<E>.

boolean

true if the result is Err<E>, false otherwise. When true, TypeScript narrows the type so result.error is accessible.

const result = chas.err('not found');

if (result.isErr()) {
  console.log(result.error); // 'not found'
}

`.map(fn)`

Transforms the Ok value. Err passes through unchanged.

(value: T) => U

required

Function applied to the Ok value.

Result<U, E>

Ok(fn(value)) or the original Err.

const doubled = chas.ok(5).map(v => v * 2);
// Ok(10)

const passthrough = chas.err('oops').map(v => v * 2);
// Err('oops') — fn is never called

`.mapErr(fn)`

Transforms the Err error. Ok passes through unchanged.

(error: E) => F

required

Function applied to the Err error.

Result<T, F>

The original Ok or Err(fn(error)).

const result = chas.err('not_found').mapErr(e => e.toUpperCase());
// Err('NOT_FOUND')

`.andThen(fn)`

Chains another Result-returning function (flatMap / monadic bind). If Ok, calls fn with the value and returns its result. Err short-circuits.

(value: T) => Result<U, F>

required

Function that receives the Ok value and returns a new Result.

Result<U, E | F>

The result of fn, or the original Err.

function parseAge(raw: string): chas.Result<number, string> {
  const n = parseInt(raw, 10);
  return isNaN(n) ? chas.err('not a number') : chas.ok(n);
}

function validateAge(age: number): chas.Result<number, string> {
  return age >= 18 ? chas.ok(age) : chas.err('too young');
}

const result = parseAge('21').andThen(validateAge);
// Ok(21)

const failed = parseAge('abc').andThen(validateAge);
// Err('not a number') — validateAge is never called

`.orElse(fn)`

Recovers from an Err by calling fn with the error and returning its result. Ok passes through unchanged.

(error: E) => Result<T2, F>

required

Function that receives the Err error and returns a recovery Result.

Result<T | T2, F>

The original Ok, or the result of fn.

const result = chas.err('cache miss')
  .orElse(() => chas.ok('default value'));
// Ok('default value')

`.tap(fn)`

Runs a side effect when Ok. Returns the original result unchanged.

(value: T) => void

required

Side-effect function called with the Ok value.

Result<T, E>

The original result, unmodified.

const result = chas.ok(42)
  .tap(v => console.log('Got value:', v)) // logs 42
  .map(v => v * 2);
// Ok(84) — tap did not alter the value

`.tapErr(fn)`

Runs a side effect when Err. Returns the original result unchanged.

(error: E) => void

required

Side-effect function called with the Err error.

Result<T, E>

The original result, unmodified.

chas.err('upload failed')
  .tapErr(e => console.error('Error:', e))
  .mapErr(e => ({ message: e }));

`.match({ ok, err })`

Exhaustively handles both branches and returns a value. Unlike .map, this always produces a non-Result value.

(value: T) => U

required

Handler called when the result is Ok.

(error: E) => F

required

Handler called when the result is Err.

U | F

The return value of whichever handler ran.

const message = chas.ok(42).match({
  ok: v => `The answer is ${v}`,
  err: e => `Failed: ${e}`,
});
// 'The answer is 42'

`.unwrap()`

Returns the Ok value, or throws the Err error.

The Ok value.

Throws the contained error if the result is Err. Prefer .unwrapOr(), .match(), or type-guarded access in production code.

const value = chas.ok(5).unwrap(); // 5
chas.err('oops').unwrap();          // throws 'oops'

`.unwrapOr(defaultValue)`

Returns the Ok value, or defaultValue if Err.

required

Fallback value returned when the result is Err.

T | T2

The Ok value or the default.

const value = chas.err('missing').unwrapOr(0);
// 0

`.unwrapErr()`

Returns the Err error, or throws if Ok.

The Err error.

const error = chas.err('not found').unwrapErr();
// 'not found'

`.toOption()`

Discards the error and converts to an Option<T>. Ok becomes Some, Err becomes None.

Option<T>

Some(value) when Ok, or None when Err.

const some = chas.ok(42).toOption();  // Some(42)
const none = chas.err('x').toOption(); // None

`.pipe(fn1, fn2, ...)`

Passes the result through a sequence of functions. Each function receives the output of the previous one. Up to 9 functions are supported with full type inference.

(a: A) => B

required

Functions to apply in order.

The output of the last function.

const add5 = (r: chas.Result<number, never>) => r.map(v => v + 5);
const double = (r: chas.Result<number, never>) => r.map(v => v * 2);

const result = chas.ok(1).pipe(add5, double);
// Ok(12)

`.context(ctx)`

Attaches a debug label or metadata object to the error when Err. Context entries are stored in error._context as an array, most recent first. No-op when Ok.

string | Record<string, unknown>

required

A description string or metadata object for the current step.

Result<T, E>

The same result with context prepended to error._context (if Err).

const result = await fetchUser(id)
  .context('fetching user')
  .andThen(u => validatePermissions(u))
  .context('checking permissions');

if (result.isErr()) {
  console.log(result.error._context);
  // ['checking permissions', 'fetching user']
}

`.catchTag(target, handler)`

Catches a specific tagged error variant by its _tag string or error factory, calls handler with it, and removes that tag from the error union type. Unmatched tags pass through unchanged.

string | ErrorFactory

required

The _tag string to match, or an error factory created with chas.defineErrs.

(error: MatchedError) => Result<T2, E2>

required

Recovery function. Return a new Result to replace the caught error.

Result<T | T2, Exclude<E, { _tag: ... }> | E2>

A result with the matched tag removed from the error union.

const AppError = chas.defineErrs({
  NotFound: (resource: string) => ({ resource }),
  Unauthorized: () => ({}),
});

// fetchUser returns Result<User, NotFound | Unauthorized>
const result = getUser(id)
  .catchTag('NotFound', () => chas.ok(GUEST_USER));
// Result<User | GuestUser, Unauthorized> — NotFound is removed from the union

`.tapTag(target, handler)`

Runs a side effect for a specific tagged error, leaving the result unchanged. Use this for logging or telemetry on individual error variants.

string | ErrorFactory

required

The _tag string to match, or an error factory.

(error: MatchedError) => void

required

Side-effect function called when the tag matches.

Result<T, E>

The original result, unmodified.

getUser(id)
  .tapTag('NotFound', (e) => analytics.track('user_not_found', { id }))
  .tapTag('Unauthorized', () => redirectToLogin());

Guard

Task

Other Modules

Result

Creating Results

`chas.ok(value)`

`chas.err(error)`

`chas.okAsync(value)`

`chas.errAsync(error)`

`chas.tryCatch(fn, mapErr?)`

`chas.fromPromise(promise, mapErr?)`

Instance methods

`.isOk()`

`.isErr()`

`.map(fn)`

`.mapErr(fn)`

`.andThen(fn)`

`.orElse(fn)`

`.tap(fn)`

`.tapErr(fn)`

`.match({ ok, err })`

`.unwrap()`

`.unwrapOr(defaultValue)`

`.unwrapErr()`

`.toOption()`

`.pipe(fn1, fn2, ...)`

`.context(ctx)`

`.catchTag(target, handler)`

`.tapTag(target, handler)`

​Creating Results

​chas.ok(value)

​chas.err(error)

​chas.okAsync(value)

​chas.errAsync(error)

​chas.tryCatch(fn, mapErr?)

​chas.fromPromise(promise, mapErr?)

​Instance methods

​.isOk()

​.isErr()

​.map(fn)

​.mapErr(fn)

​.andThen(fn)

​.orElse(fn)

​.tap(fn)

​.tapErr(fn)

​.match({ ok, err })

​.unwrap()

​.unwrapOr(defaultValue)

​.unwrapErr()

​.toOption()

​.pipe(fn1, fn2, ...)

​.context(ctx)

​.catchTag(target, handler)

​.tapTag(target, handler)

Creating Results

`chas.ok(value)`

`chas.err(error)`

`chas.okAsync(value)`

`chas.errAsync(error)`

`chas.tryCatch(fn, mapErr?)`

`chas.fromPromise(promise, mapErr?)`

Instance methods

`.isOk()`

`.isErr()`

`.map(fn)`

`.mapErr(fn)`

`.andThen(fn)`

`.orElse(fn)`

`.tap(fn)`

`.tapErr(fn)`

`.match({ ok, err })`

`.unwrap()`

`.unwrapOr(defaultValue)`

`.unwrapErr()`

`.toOption()`

`.pipe(fn1, fn2, ...)`

`.context(ctx)`

`.catchTag(target, handler)`

`.tapTag(target, handler)`