Wrap errors into results with that simple library.
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.
- ✅ 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
YErrorRegistrytype. - ✅ 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).
npm install zresult yerrorimport { 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 }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);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);
}Useful for transforming a Promise from a third-party library into a Result.
import { settle } from 'zresult';
const result = await settle(externalApi.call());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']);- ok()
Create a successful result
- fail()
Create a failure result using a YError code and debug values
- failWith()
Wrap an existing error into a failure result
- settle()
Transform a Promise into a Result catching any error
- settleFrom()
Transform a Promise into a Result catching only known errors and letting unknown pass through
- attempt()
Runs an asynchronous function and provides a Result catching any error
- attemptFrom()
Runs an asynchronous function and provides a Result catching only known errors and letting unknown pass through
- attemptSync()
Runs a synchronous function and provides a Result catching any error
- attemptSyncFrom()
Runs a synchronous function and provides a Result catching only known errors and letting unknown pass through
Create a successful result
Create a failure result using a YError code and debug values
Wrap an existing error into a failure result
Transform a Promise into a Result catching any error
Transform a Promise into a Result catching only known errors and letting unknown pass through
Runs an asynchronous function and provides a Result catching any error
Runs an asynchronous function and provides a Result catching only known errors and letting unknown pass through
Runs a synchronous function and provides a Result catching any error
Runs a synchronous function and provides a Result catching only known errors and letting unknown pass through
Kind: global function