zresult

It helps to know the error you'll get.

zresult is an ultra-lightweight TypeScript wrapper designed to transform error handling into a predictable, strictly typed, and elegant data flow. Inspired by the Result pattern from Rust and Go, it integrates natively with yerror to provide absolute Type Safety for your error codes.

Key Features

• ✅ No more noisy try/catch: Handle errors as return values.
• ✅ Exhaustive Type Safety: Your error codes and debug data are validated via the yerror's YErrorRegistry type.
• ✅ Explicit Flow: Clear distinction between synchronous and asynchronous operations.
• ✅ Selective Catching: Capture only the errors you know how to handle, let the others bubble up (e.g., unexpected bugs or ReferenceError).

Installation

npm install zresult yerror

Quick Start

1. Creating Success or Failure

import { ok, fail } from 'zresult';

const success = ok(42);
// returns { ok: true, value: 42 }

const failure = fail('E_USER_NOT_FOUND', ['123']);
// returns { ok: false, error: YError }

2. Executing a Function (Attempt)

Use attempt for asynchronous functions and attemptSync for the synchronous world.

import { attempt, attemptSync } from 'zresult';

// Asynchronous
const result = await attempt(fetchUser, userId);

if (!result.ok) {
  console.error(result.error.code); // Strictly typed!
  return;
}
console.log(result.value.name);

// Synchronous
const config = attemptSync(parseConfig, rawData);

3. Selective Capture (The "From" Pattern)

Only handle expected errors and let unexpected bugs crash the process cleanly.

import { attemptFrom } from 'zresult';

// We only capture 'E_NETWORK' errors
const result = await attemptFrom(['E_NETWORK'], sendMessage, msg);

if (!result.ok) {
  // result.error is strictly typed as YError<'E_NETWORK'> here
  return retry(msg);
}

4. Stabilizing an existing Promise (Settle)

Useful for transforming a Promise from a third-party library into a Result.

import { settle } from 'zresult';

const result = await settle(externalApi.call());

Integration with YError

zresult shines when used with a declared YErrorRegistry. TypeScript will prevent you from using non-existent error codes or invalid debug arguments.

declare module 'yerror' {
  interface YErrorRegistry {
    E_ACCESS_DENIED: [userId: string];
  }
}

// TypeScript validates both 'E_ACCESS_DENIED' and the debug array contents
return fail('E_ACCESS_DENIED', ['user_123']);

API

Functions

ok()

Create a successful result

Kind: global function

fail()

Create a failure result using a YError code and debug values

Kind: global function

failWith()

Wrap an existing error into a failure result

Kind: global function

settle()

Transform a Promise into a Result catching any error

Kind: global function

settleFrom()

Transform a Promise into a Result catching only known errors and letting unknown pass through

Kind: global function

attempt()

Runs an asynchronous function and provides a Result catching any error

Kind: global function

attemptFrom()

Runs an asynchronous function and provides a Result catching only known errors and letting unknown pass through

Kind: global function

attemptSync()

Runs a synchronous function and provides a Result catching any error

Kind: global function

attemptSyncFrom()

Runs a synchronous function and provides a Result catching only known errors and letting unknown pass through

Kind: global function

Authors

• Nicolas Froidure

License

MIT