result-box v0.4.2

result-box

Because throw/catch is not always best.

Install

npm install result-box

Usage

A result is a plain object with fields success and data. Type definitions for different kinds of result are provided, as well as some creation, operation, and consumption conveniency functions:

• Result: result type definitions.
• Create: creation utility functions.
• Operate: operation utility functions.
• Consume: consumption utility functions.

Result

Type definitions are provided for a successful result, a failed result, and a combination of them:

• Result.Box: a successful or failed result.
• Result.Break: a successful result, a failed result, or null.
• Result.Success: a successful result.
• Result.Failure: a failed result.

import { Result } from 'result-box';

const success: Result.Success<string> = {
  success: true,
  data: 'foo'
};

const failure: Result.Failure<Error> = {
  success: false,
  data: new Error('foo')
};

const successBox: Result.Box<string, Error> = success;
const failureBox: Result.Box<string, Error> = failure;

const successBreak: Result.Break<string, Error> = success;
const failureBreak: Result.Break<string, Error> = failure;
const nullBreak: Result.Break<string, Error> = null;

Create

Creation utility functions:

• Create.success: creates a successful result.
• Create.failure: creates a failed result.
• Create.execute: creates a result from a function.
• Create.promise: returns a Promise of a result from an input Promise.
• Create.observable: returns an Observable of result from an input Observable.
• Create.combine: combines a record or array of result.

import { Create } from 'result-box';

// Returns: `{ success: true, data: { foo: 'bar' } }`
const success = Create.success({ foo: 'bar' });

// Returns: `{ success: false, data: { reason: Error, code: 500 } }`
const failure = Create.failure({ reason: new Error('...'), code: 500 });

// Returns: `{ success: true, data: { foo: 'bar' } }`
const executeSuccess = Create.execute(() => ({ foo: 'bar' }));

// Returns: `{ success: false, data: Error }`
const executeFailure = Create.execute(() => { throw new Error('...'); });

Operate

All operations return a unary function taking a result as an argument. You can straightforwardly pipe them with a pipe function such as the ones provided by the pipettes package.

• Operate.fallback: creates a successful result when null.
• Operate.transform: transforms a result into its data.
• Operate.map: maps a result data.
• Operate.flip: optionally converts a successful result into a failed result and vice-versa.
• Operate.tap: allows for the execution of side effects.

import { Operate, Result } from 'result-box';
import { into } from 'pipettes';

const none = null as Result.Break<number, string>;

// Return type: `Result.Box<number | boolean, string>`
const box = into(none, Operate.fallback(true));

// Return type: `number | boolean | string[]`
const transformed = into(
  box,
  Operate.transform(null, (data: string) => [data])
);

// Return type: `Result.Box<boolean, string>`
const mapped = into(
  box,
  Operate.map((data: number | boolean) => data === 5, null)
);

// Return type: `Result.Box<never, number | boolean | string>`
const flipped = into(box, Operate.flip(true, false));

// Return type: `Result.Box<number | boolean, string>`
const tapped = into(box, Operate.tap(null, console.log));

Consume

Consumption utility functions:

• Consume.result: consumes a result.
• Consume.promise: consumes a Promise of a result.
• Consume.observable: consumes an Observable of result.

import { Consume, Create } from 'result-box';
import { into } from 'pipettes';

// Returns: `'foo'`
const data = Consume.result(Create.success('foo'));

// Throws error
into(Create.failure('bar'), Consume.result);