# byethrow

> A lightweight, tree-shakable Result type library for type-safe error handling in TypeScript.

## Guide

- [Introduction](/byethrow/guide/start/introduction.md): Overview of @praha/byethrow, a tree-shakable TypeScript Result type library for explicit, type-safe error handling.
- [Why byethrow?](/byethrow/guide/start/why.md): Why @praha/byethrow over neverthrow, effect-ts, or try/catch — practical TypeScript error handling without functional programming overhead.
- [Quick Start](/byethrow/guide/start/quick.md): Install @praha/byethrow and learn core patterns — Result.succeed, Result.fail, Result.pipe, map, andThen, and async operations.
- [Result Type](/byethrow/guide/tutorial/basics/result-type.md): The Result<T, E> union type structure — Success, Failure, ResultAsync — and why it beats exceptions for type-safe error handling.
- [Creating Results](/byethrow/guide/tutorial/basics/creating-results.md): Creating Success and Failure results with Result.succeed, Result.fail, and Result.do, including async and void variants.
- [Checking Results](/byethrow/guide/tutorial/basics/checking-results.md): Using isSuccess, isFailure, and isResult type guards to safely inspect and narrow Result types in TypeScript.
- [Wrapping Functions](/byethrow/guide/tutorial/basics/wrapping-functions.md): Wrapping throwing functions into Result types using Result.fn for reusable wrappers and Result.try for one-off executions.
- [Pipe Basics](/byethrow/guide/tutorial/chaining/pipe-basics.md): How Result.pipe chains operations left-to-right, replacing nested calls and intermediate variables, with sync and async support.
- [Mapping Results](/byethrow/guide/tutorial/chaining/mapping-results.md): Transforming Result values with Result.map for success and Result.mapError for errors, with practical HTTP and UI formatting examples.
- [Chaining Results](/byethrow/guide/tutorial/chaining/chaining-results.md): Chaining Result computations with andThen for sequential success steps and orElse for error recovery and fallback strategies.
- [Validation and Recovery](/byethrow/guide/tutorial/chaining/validation-recovery.md): Running side-effect validations with andThrough and cleanup on failure with orThrough while preserving the original Result value.
- [Debugging](/byethrow/guide/tutorial/chaining/debugging.md): Using Result.inspect and Result.inspectError to log values at each pipeline step without altering the Result flow.
- [Building Objects](/byethrow/guide/tutorial/combining/building-objects.md): Accumulating Result values into typed objects step by step using the Result.do and Result.bind pattern.
- [Aggregating Results](/byethrow/guide/tutorial/combining/aggregating-results.md): Combining multiple Results with Result.sequence (stop on first failure) and Result.collect (gather all errors, parallel async).
- [Unwrapping Results](/byethrow/guide/tutorial/resolving/unwrapping.md): Extracting values from Result with unwrap and unwrapError, including default values, async support, and when to use them safely.
- [Asserting Results](/byethrow/guide/tutorial/resolving/asserting.md): Compile-time Result assertions with assertSuccess and assertFailure, requiring never error or success types for safe unwrapping.
- [Result vs throw](/byethrow/guide/best-practices/result-vs-throw.md): When to use Result for anticipated business errors versus letting exceptions throw, and how Result.fn improves stack traces.
- [Importing Result](/byethrow/guide/best-practices/importing-result.md): Two import styles for @praha/byethrow — the Result namespace and the R shorthand alias — with tree-shaking support explained.
- [Custom Error](/byethrow/guide/best-practices/custom-error.md): How to define custom error classes for Result.fail(), including stack traces, error chaining, and the @praha/error-factory library.
- [Pattern Matching](/byethrow/guide/best-practices/pattern-matching.md): Handling union error types in Result using ts-pattern, instanceof checks, and discriminated unions with switch statements.
- [LLM Integration](/byethrow/guide/ecosystem/llm-integration.md): Integrate byethrow documentation into Claude, GitHub Copilot, and Cursor using the @praha/byethrow-docs CLI init command.
- [Testing](/byethrow/guide/ecosystem/testing.md): Custom test matchers for asserting @praha/byethrow Result types with Jest, Vitest, and Rstest.
- [Linter Plugin](/byethrow/guide/ecosystem/linter/index.md): @praha/byethrow-oxlint Oxlint plugin — installation, setup, settings, and rule list for enforcing byethrow best practices
- [consistent-namespace](/byethrow/guide/ecosystem/linter/consistent-namespace.md): Oxlint rule that enforces a single namespace alias — Result or R — for @praha/byethrow imports, with auto-fix support
- [no-ambiguous-error-type](/byethrow/guide/ecosystem/linter/no-ambiguous-error-type.md): Oxlint rule that disallows vague types such as unknown, any, or Error in the error position of Result, ResultAsync, and ResultMaybeAsync
- [no-ambiguous-success-type](/byethrow/guide/ecosystem/linter/no-ambiguous-success-type.md): Oxlint rule that disallows vague types such as unknown, any, or object in the success position of Result, ResultAsync, and ResultMaybeAsync
- [no-negated-type-guards](/byethrow/guide/ecosystem/linter/no-negated-type-guards.md): Oxlint rule that disallows the negation operator on Result.isSuccess() or Result.isFailure() — auto-fixes to the direct type guard equivalent
- [no-throw-in-callback](/byethrow/guide/ecosystem/linter/no-throw-in-callback.md): Oxlint rule that disallows throw statements inside @praha/byethrow callbacks — use Result.fail() to represent errors instead
- [no-try-catch-in-callback](/byethrow/guide/ecosystem/linter/no-try-catch-in-callback.md): Oxlint rule that disallows try-catch blocks inside @praha/byethrow callbacks — use Result.fn() to wrap throwing code instead
- [prefer-result-async](/byethrow/guide/ecosystem/linter/prefer-result-async.md): Oxlint rule that enforces ResultAsync over Promise-wrapped Result for async byethrow values, with auto-fix support
- [prefer-result-matchers](/byethrow/guide/ecosystem/linter/prefer-result-matchers.md): Oxlint rule that enforces toBeSuccess() and toBeFailure() matchers over boolean isSuccess/isFailure assertions in tests, with auto-fix
- [prefer-result-maybe-async](/byethrow/guide/ecosystem/linter/prefer-result-maybe-async.md): Oxlint rule that enforces ResultMaybeAsync over the Result-or-ResultAsync union type, with auto-fix support

## Examples

- [Parse package.json](/byethrow/examples/parse-package-json.md): Example using @praha/byethrow to parse a package.json file and handle file-read and parse errors with Result.
- [API Request CLI](/byethrow/examples/api-request-cli.md): Example CLI application using @praha/byethrow to make API requests and handle errors with the Result type.

## API Reference

- [byethrow](/byethrow/api/index.md)
- [Namespace: Result](/byethrow/api/modules/Result.md): Re-exports core Result-handling utilities under two convenient namespaces:
- [Type Alias: Failure<E>](/byethrow/api/types/Result.Failure.md): Represents a failed result.
- [Type Alias: InferFailure<T>](/byethrow/api/types/Result.InferFailure.md): Infers the Failure value type `E` from a Result or a function returning a Result.
- [Type Alias: InferSuccess<T>](/byethrow/api/types/Result.InferSuccess.md): Infers the Success value type `T` from a Result or a function returning a Result.
- [Type Alias: Result<T, E>](/byethrow/api/types/Result.Result.md): A union type representing either a success or a failure.
- [Type Alias: ResultAsync<T, E>](/byethrow/api/types/Result.ResultAsync.md): An asynchronous variant of Result, wrapped in a `Promise`.
- [Type Alias: ResultFor<R, T, E>](/byethrow/api/types/Result.ResultFor.md): Resolves to the appropriate Result type (sync or async) based on the input type.
- [Type Alias: ResultMaybeAsync<T, E>](/byethrow/api/types/Result.ResultMaybeAsync.md): A result that may be either synchronous or asynchronous.
- [Type Alias: Success<T>](/byethrow/api/types/Result.Success.md): Represents a successful result.
- [Function: andThen()](/byethrow/api/functions/Result.andThen.md): 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.
- [Function: andThrough()](/byethrow/api/functions/Result.andThrough.md): Runs an additional computation using the success value of a Result or ResultAsync, but **returns the original result** if the additional computation is successful.
- [Function: assertFailure()](/byethrow/api/functions/Result.assertFailure.md): Asserts that a Result or ResultAsync is a Failure and returns it. This function requires that the result's success type is `never`, meaning the result is guaranteed to be a Failure at the type level. If the result is a Success at runtime, throws an error.
- [Function: assertSuccess()](/byethrow/api/functions/Result.assertSuccess.md): Asserts that a Result or ResultAsync is a Success and returns it. This function requires that the result's error type is `never`, meaning the result is guaranteed to be a Success at the type level. If the result is a Failure at runtime, throws an error.
- [Function: bind()](/byethrow/api/functions/Result.bind.md): Chains another Result-producing computation and **merges its success value** into the existing object under the specified key.
- [Function: collect()](/byethrow/api/functions/Result.collect.md): Processes multiple Result or ResultAsync values into a single result. If all results are Success, returns a Success containing all values. If any result is a Failure, returns a Failure containing an array of all errors.
- [Function: do()](/byethrow/api/functions/Result.do.md): Alias for `succeed({})`. Commonly used as a neutral base value in functional chains or monadic pipelines.
- [Function: fail()](/byethrow/api/functions/Result.fail.md): Creates a Failure result from a given error.
- [Function: fn()](/byethrow/api/functions/Result.fn.md): Wraps a function that may throw and returns a new function that returns a Result or ResultAsync.
- [Function: inspect()](/byethrow/api/functions/Result.inspect.md): 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.
- [Function: inspectError()](/byethrow/api/functions/Result.inspectError.md): 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.
- [Function: isFailure()](/byethrow/api/functions/Result.isFailure.md): Type guard to check if a Result is a Failure.
- [Function: isResult()](/byethrow/api/functions/Result.isResult.md): Type guard to check if a value is a Result.
- [Function: isSuccess()](/byethrow/api/functions/Result.isSuccess.md): Type guard to check if a Result is a Success.
- [Function: map()](/byethrow/api/functions/Result.map.md): Applies a transformation function to the success value of a Result or ResultAsync. If the input is a Failure, it will be returned unchanged.
- [Function: mapError()](/byethrow/api/functions/Result.mapError.md): Applies a transformation function to the error value of a Result or ResultAsync. If the input is a Success, it will be returned unchanged.
- [Function: orElse()](/byethrow/api/functions/Result.orElse.md): 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.
- [Function: orThrough()](/byethrow/api/functions/Result.orThrough.md): Runs an additional computation using the error value of a Result or ResultAsync, but **returns the original failure** if the additional computation is successful.
- [Function: parse()](/byethrow/api/functions/Result.parse.md): Parses a value using a Standard Schema compatible schema. Returns a Result with the parsed value on success or validation errors on failure.
- [Function: pipe()](/byethrow/api/functions/Result.pipe.md): Applies a sequence of functions to a value, from left to right.
- [Function: sequence()](/byethrow/api/functions/Result.sequence.md): Processes multiple Result or ResultAsync values into a single result. If all results are Success, returns a Success containing all values. If any result is a Failure, immediately stops processing and returns a Failure with that single error.
- [Function: succeed()](/byethrow/api/functions/Result.succeed.md): Creates a Success result from a given value.
- [Function: try()](/byethrow/api/functions/Result.try.md): Executes a function that may throw and wraps the result in a Result or ResultAsync.
- [Function: unwrap()](/byethrow/api/functions/Result.unwrap.md): Extracts the success value from a Result or ResultAsync.
- [Function: unwrapError()](/byethrow/api/functions/Result.unwrapError.md): Extracts the error value from a Result or ResultAsync.