Result

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

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

Examples

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
}
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

Type AliasDescription
FailureRepresents a failed result.
ResultA union type representing either a success or a failure.
ResultAsyncAn asynchronous variant of Result, wrapped in a Promise.
ResultForResolves to the appropriate Result type (sync or async) based on the input type.
ResultMaybeAsyncA result that may be either synchronous or asynchronous.
SuccessRepresents a successful result.

Infer Types

Type AliasDescription
InferFailureInfers the Failure value type E from a Result or a function returning a Result.
InferSuccessInfers the Success value type T from a Result or a function returning a Result.

Creators

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

Combinators

FunctionDescription
andThenChains 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.
andThroughRuns an additional computation using the success value of a Result or ResultAsync, but returns the original result if the additional computation is successful.
bindChains another Result-producing computation and merges its success value into the existing object under the specified key.
inspectExecutes 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.
inspectErrorExecutes 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.
mapApplies a transformation function to the success value of a Result or ResultAsync. If the input is a Failure, it will be returned unchanged.
mapErrorApplies a transformation function to the error value of a Result or ResultAsync. If the input is a Success, it will be returned unchanged.
orElseChains 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

FunctionDescription
unwrapExtracts the success value from a Result or ResultAsync.
unwrapErrorExtracts the error value from a Result or ResultAsync.

Assertions

FunctionDescription
assertFailureAsserts that a Result or ResultAsync is a Failure and returns it. If the result is a Success, throws an error.
assertSuccessAsserts that a Result or ResultAsync is a Success and returns it. If the result is a Failure, throws an error.

Type Guards

FunctionDescription
isFailureType guard to check if a Result is a Failure.
isResultType guard to check if a value is a Result.
isSuccessType guard to check if a Result is a Success.

Utilities

FunctionDescription
combineCombines 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.
parseParses a value using a Standard Schema compatible schema. Returns a Result with the parsed value on success or validation errors on failure.
pipeApplies a sequence of functions to a value, from left to right.