Advanced Result API

The Result object provides a rich, fluent API heavily inspired by functional programming. These methods allow you to chain operations, transform data, and trigger side-effects without breaking the control flow.

Result Methods

Transformation Methods

map

Transforms the success data using a provided function. If the result is an error, it ignores the function and returns the error as-is.

import { catchErrorSync } from '@catcherjs/core';

const result = catchErrorSync(() => JSON.parse('{"count": 5}'));

const doubled = result.map(data => data.count * 2);

console.log(doubled.unwrap()); 

mapErr

Transforms the error using a provided function. If the result is a success, it returns the success as-is.

const result = catchErrorSync(() => { throw new Error('Not found') });

const customErrorResult = result.mapErr(err => new CustomError(err.message));

Chaining Methods

andThen / flatMap

Chains another operation that also returns a Result. If the first operation fails, the chained operation is skipped. Both andThen and flatMap are identical aliases.

const processData = (raw: string) => {
  return catchErrorSync(() => JSON.parse(raw))
      .andThen(parsed => catchErrorSync(() => validateSchema(parsed)));
};

orElse

Recovers from an error by returning a new Result. If the original result is a success, it ignores the function and returns the success as-is.

const result = catchErrorSync(() => fetchFromCache())
  .orElse(() => catchErrorSync(() => fetchFromDatabase()));

Side-Effect Methods

tap

Executes a side-effect (like logging) if the result is a success. It does not modify the Result and returns it unchanged, allowing further chaining.

const result = catchErrorSync(() => computeValue())
  .tap(data => console.log('Successfully computed:', data))
  .map(data => data * 2);

tapErr

Executes a side-effect if the result is an error.

const result = catchErrorSync(() => riskyOperation())
  .tapErr(err => console.error('Operation failed:', err.message));

Utility Methods

unwrapErr

Returns the contained error if the result is a failure. Throws the contained data if it is a success (the opposite of unwrap).

toPromise

Converts the Result back into a standard Promise. Resolves with the data on success, or rejects with the error on failure.

const result = catchErrorSync(() => 42);
const value = await result.toPromise();

Props

Result Methods