Package Exports

@appboypov/turbo-response

Readme

turbo-response

A TypeScript library providing a type-safe Result type (Success/Fail) for handling operation outcomes without exceptions.

Installation

npm install @appboypov/turbo-response

Features

Type-safe result handling with discriminated unions
Zero dependencies
Full TypeScript support with complete type inference
Functional programming utilities for chaining and transforming results
Async support with andThenAsync, recoverAsync, and traverse
Batch operations with sequence for combining multiple results

Quick Start

import { success, fail, fold, isSuccess, TurboResponse } from '@appboypov/turbo-response';

// Creating responses
const successResult = success({ id: '123', name: 'John' });
const failResult = fail(new Error('Not found'));

// Type guards
if (isSuccess(response)) {
  console.log(response.result);
}

// Pattern matching with fold
const message = fold(
  response,
  (data) => `Found user: ${data.name}`,
  (error) => `Error: ${error}`
);

API

Creating Responses

`success<T>(result: T, title?: string, message?: string): Success<T>`

Creates a successful response.

const user = success({ id: '1', name: 'John' });
const withMeta = success(data, 'Created', 'User created successfully');

`fail<T>(error: unknown, title?: string, message?: string, stackTrace?: string): Fail<T>`

Creates a failed response.

const error = fail(new Error('Not found'));
const withMeta = fail(err, 'Not Found', 'User does not exist');

Type Guards

`isSuccess<T>(r: TurboResponse<T>): r is Success<T>`

if (isSuccess(response)) {
  console.log(response.result); // TypeScript knows this is Success<T>
}

`isFail<T>(r: TurboResponse<T>): r is Fail<T>`

if (isFail(response)) {
  console.log(response.error); // TypeScript knows this is Fail<T>
}

Pattern Matching

`fold<T, R>(response, onSuccess, onFail): R`

Transform a response into a single value.

const message = fold(
  response,
  (user) => `Hello, ${user.name}`,
  (error) => `Error: ${error}`
);

`when<T, R>(response, handlers): R`

Pattern match with full response access.

const result = when(response, {
  success: (s) => `Got ${s.result.name} - ${s.message}`,
  fail: (f) => `Failed: ${f.title}`,
});

`maybeWhen<T, R>(response, handlers): R`

Pattern match with optional handlers and fallback.

const result = maybeWhen(response, {
  success: (s) => s.result.name,
  orElse: () => 'Unknown',
});

Transformations

`mapSuccess<T, R>(r, fn): TurboResponse<R>`

Transform the success value.

const nameResponse = mapSuccess(userResponse, (user) => user.name);

`mapFail<T>(r, fn): TurboResponse<T>`

Transform the error value.

const mapped = mapFail(response, (err) => new CustomError(err));

Chaining

`andThen<T, R>(r, fn): TurboResponse<R>`

Chain operations that return TurboResponse (flatMap/bind).

const result = andThen(
  getUserById('123'),
  (user) => getOrdersByUser(user.id)
);

`andThenAsync<T, R>(r, fn): Promise<TurboResponse<R>>`

Async version of andThen for chaining async operations.

const result = await andThenAsync(
  fetchUser('123'),
  async (user) => fetchOrders(user.id)
);

// Chain multiple async operations
let result = await fetchUser('123');
result = await andThenAsync(result, async (user) => fetchProfile(user.id));
result = await andThenAsync(result, async (profile) => fetchSettings(profile.id));

Error Recovery

`recover<T>(r, fn): TurboResponse<T>`

Attempt to recover from a failure.

const result = recover(
  failedResponse,
  (error) => success(defaultValue)
);

`recoverAsync<T>(r, fn): Promise<TurboResponse<T>>`

Async version of recover.

const result = await recoverAsync(
  failedResponse,
  async (error) => {
    const fallback = await fetchFallbackData();
    return success(fallback);
  }
);

Unwrapping

`unwrap<T>(r): T`

Get the success value or throw the error.

try {
  const value = unwrap(response);
} catch (error) {
  // Handle error
}

`unwrapOr<T>(r, defaultValue): T`

Get the success value or return a default.

const value = unwrapOr(response, defaultUser);

`unwrapOrCompute<T>(r, compute): T`

Get the success value or compute a default lazily.

const value = unwrapOrCompute(response, () => createDefaultUser());

Batch Operations

`traverse<T, R>(items, fn): Promise<TurboResponse<R[]>>`

Apply an async operation to each item, collecting results. Fails fast on first error.

const userIds = ['1', '2', '3'];

const result = await traverse(userIds, async (id) => {
  const user = await fetchUser(id);
  return user ? success(user) : fail(new Error(`User ${id} not found`));
});

if (isSuccess(result)) {
  console.log('All users:', result.result); // User[]
}

`sequence<T>(responses): TurboResponse<T[]>`

Combine an array of responses into a single response. Fails fast on first error.

const responses = [
  success(1),
  success(2),
  success(3),
];

const combined = sequence(responses);
// Success<number[]> with [1, 2, 3]

const withFailure = sequence([
  success(1),
  fail(new Error('oops')),
  success(3),
]);
// Fail - returns the first failure

Validation

`ensure<T>(r, predicate, error): TurboResponse<T>`

Validate the success value against a predicate.

const validated = ensure(
  userResponse,
  (user) => user.age >= 18,
  new Error('Must be 18 or older')
);

Utilities

`swap<T>(r): TurboResponse<T>`

Swap success and fail states.

`getResult<T>(r): T | undefined`

Safely get the result value.

`getError<T>(r): unknown | undefined`

Safely get the error value.

`getTitle<T>(r): string | undefined`

Get the title metadata.

`getMessage<T>(r): string | undefined`

Get the message metadata.

License

MIT