@expo/results

An efficient, standards-compliant library for representing results of successful or failed operations. A result object represents the result of an operation that can either return a value successfully or fail. Typically we'd simply either return a value or throw an error, but sometimes we perform multiple operations as a batch, some of which may succeed and others fail. Since we can't simultaneously return values and throw errors, we instead return collections of result objects. This allows a batch operation to return values for successful operations and errors for failed ones without loss of information, namely the errors. (In contrast, sometimes it is appropriate for a batch operation to return just successful values and omit values for failed operations.)

Usage

Using Results

import { Result, result } from '@expo/results';

const results = await fetchWebPages(['https://expo.dev', 'http://example.com']);
for (const result of results) {
  if (result.ok) {
    console.log(result.value);
  } else {
    console.error(result.reason);
  }
}

Creating Results

import { Result, result } from '@expo/results';

/**
 * The purpose of this result API is to let you write functions that can
 * partially succeed and partially fail and return all of that information to
 * the caller.
 */
function fetchWebPages(urls: string[]): Promise<Result<string>[]> {
  return Promise.all(urls.map(fetchWebPage));
}

function fetchWebPage(url: string): Promise<Result<string>> {
  try {
    const response = await fetch(url);
    const text = await response.text();
    return result(text);
  } catch (e) {
    return result(e);
  }
}

Changelog

1.0.0

• Remove official Node 8.x compatibility (support 10.x and up). The package still will run on Node 8 LTS (with async functions), though.

0.3.0

Additions

• Export Success and Failure types in TypeScript declarations.

0.2.0

Breaking changes

• Calling Result#enforceValue() on a failure result now throws the failure reason instead of throwing a new TypeError. This helps propagate underlying errors up the call stack instead of masking them with TypeError instances that don't specify what caused the failure.

Additions

• enforceAsyncResult, a function to convert promises that return results into promises that return unwrapped values or throw. This is the inverse of asyncResult.

0.1.1

Initial version of the Results API.