byethrow

The @praha/byethrow library provides a lightweight, tree-shakable Result type for handling errors explicitly.

Core characteristics:

• Tree-shakable: Only the utilities you import are included in your bundle.
• Object-based: Uses plain objects instead of classes to avoid overhead and magic.
• Unified sync/async: Designed to work seamlessly with both Result<T, E> and Promise<Result<T, E>>.
• Focused API: Provides a consistent and predictable API for handling both synchronous and asynchronous fallible operations without unnecessary complexity.

byethrow is a lightweight, tree-shakable Result type library designed for type-safe error handling in TypeScript. It aims to replace the use of throw with a more predictable Result<T, E> pattern.

Key features include:

• Tree-shakable: Optimized for modern bundlers to ensure only used code is included.
• Object-based Design: Uses plain objects instead of complex class hierarchies, making it easy to debug.
• Unified Sync/Async: Seamlessly handles both synchronous Result<T, E> and asynchronous Promise<Result<T, E>> types.
• Composable Pipeline: Provides utilities like pipe, andThen, and andThrough for clean, chainable data flows.
• Fully Type-Safe: All functions are rigorously type-tested to prevent type errors in your application logic.

The Result.pipe function is the core mechanism in @praha/byethrow for chaining operations in a readable, left-to-right flow. It takes an initial value (or a Result) and passes it through a series of functions, where each subsequent function receives the output of the previous one. This pattern replaces deeply nested function calls and the need for multiple intermediate variables.

import { Result } from '@praha/byethrow';

const result = Result.pipe(
  5,                    // Start with 5
  (x) => x + 1,         // 5 + 1 = 6
  (x) => x * 2,         // 6 * 2 = 12
  (x) => `Result: ${x}` // 'Result: 12'
);

The core abstraction in @praha/byethrow is the Result type. It represents the outcome of an operation that might fail, making error handling explicit instead of relying on exceptions. A Result can be one of two states:

• Success: Contains a value of type T.
• Failure: Contains an error of type E.

You can check the state of a result using Result.isSuccess(result) or Result.isFailure(result).

import { Result } from '@praha/byethrow';

const success = Result.succeed('Hello, World!');
const failure = Result.fail(new Error('Something went wrong'));

if (Result.isSuccess(success)) {
  console.log(success.value); // "Hello, World!"
}

if (Result.isFailure(failure)) {
  console.log(failure.error.message); // "Something went wrong"
}

Use this library when you want to handle errors explicitly as part of your application logic rather than using exceptions. Ideal use cases include:

• API calls: Handling network failures or non-200 responses.
• Data validation: Managing multiple validation errors gracefully.
• File operations: Dealing with I/O or permission errors.
• Parser implementations: Handling invalid input without crashing.
• Business logic: Treating expected error states as first-class citizens in your domain logic.

Deciding which method to use depends on whether you need a reusable utility or a single execution.

When choosing an error handling strategy, @praha/byethrow positions itself relative to these common patterns: