Namespace Result

Re-exports core Result-handling utilities under two convenient namespaces:

Result: Verbose and explicit usage
R: Shorthand alias for more concise code

Example: Basic Usage

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

const validateId = (id: string) => {
  if (!id.startsWith('u')) {
    return Result.fail(new Error('Invalid ID format'));
  }
  return Result.succeed();
};

const findUser = Result.try({
  try: (id: string) => {
    return { id, name: 'John Doe' };
  },
  catch: (error) => new Error('Failed to find user', { cause: error }),
});

const result = Result.pipe(
  Result.succeed('u123'),
  Result.andThrough(validateId),
  Result.andThen(findUser),
);

if (Result.isSuccess(result)) {
  console.log(result.value); // User found: John Doe
}

Example: Shorthand Usage

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

const validateId = (id: string) => {
  if (!id.startsWith('u')) {
    return R.fail(new Error('Invalid ID format'));
  }
  return R.succeed();
};

const findUser = R.try({
  try: (id: string) => {
    return { id, name: 'John Doe' };
  },
  catch: (error) => new Error('Failed to find user', { cause: error }),
});

const result = R.pipe(
  R.succeed('u123'),
  R.andThrough(validateId),
  R.andThen(findUser),
);

if (R.isSuccess(result)) {
  console.log(result.value); // User found: John Doe
}

Core Types

Failure: Represents a failed result.
Result: A union type representing either a success or a failure.
ResultAsync: An asynchronous variant of Result, wrapped in a Promise.
ResultFor: Resolves to the appropriate Result type (sync or async) based on the input type.
ResultMaybeAsync: A result that may be either synchronous or asynchronous.
Success: Represents a successful result.

Infer Types

InferFailure: Infers the Failure value type E from a Result or a function returning a Result.
InferSuccess: Infers the Success value type T from a Result or a function returning a Result.

Creators

do: Alias for succeed({}). Commonly used as a neutral base value in functional chains or monadic pipelines.
fail: Creates a Failure result from a given error. Automatically wraps the error in a Promise if it is asynchronous.
succeed: Creates a Success result from a given value. Automatically wraps the value in a Promise if it is asynchronous.
try: Wraps a function execution (sync or async) in a Result or ResultAsync type, capturing errors and returning them in a structured way.

Combinators

andThen: Chains the next computation using the success value of a Result or ResultAsync. If the original result is a Failure, it is returned unchanged. Otherwise, the provided function is called, and its result is returned as-is.
andThrough: Runs an additional computation using the success value of a Result or ResultAsync, but returns the original result if the additional computation is successful.
bind: Chains another Result-producing computation and merges its success value into the existing object under the specified key.
inspect: Executes a side effect function on the success value of a Result or ResultAsync, without modifying the original result. This is useful for debugging, logging, or performing other side effects while maintaining the original value and error state.
inspectError: Executes a side effect function on the error value of a Result or ResultAsync, without modifying the original result. This is useful for debugging, logging, or performing other side effects while maintaining the original value and error state.
map: Applies a transformation function to the success value of a Result or ResultAsync. If the input is a Failure, it will be returned unchanged.
mapError: Applies a transformation function to the error value of a Result or ResultAsync. If the input is a Success, it will be returned unchanged.
orElse: Chains the next computation using the error value of a Result or ResultAsync. If the original result is a Success, it is returned unchanged. Otherwise, the provided function is called, and its result is returned as-is.

Unwraps

unwrap: Extracts the success value from a Result, ResultAsync.
unwrapError: Extracts the error value from a Result, ResultAsync.

Type Guards

isFailure: Type guard to check if a Result is a Failure.
isSuccess: Type guard to check if a Result is a Success.

Utilities

combine: Combines multiple Result or ResultAsync values into a single result. If all inputs are Success, returns a Success with combined values. If any input is a Failure, returns a Failure with an array of all errors.
pipe: Applies a sequence of functions to a value, from left to right.

Namespace Result

Example: Basic Usage

Example: Shorthand Usage

Core Types

Infer Types

Creators

Combinators

Unwraps

Type Guards

Utilities

Settings

On This Page