fun-promises

A library for making Promises more friendly, fluent, and fun(ctional).

Install

Yarn

yarn add fun-promises

npm

npm install --save fun-promises

CDN for Browsers

The following URL contains a script which will set the FunPromises global to be an object containing the various exports of index.ts.

https://unpkg.com/browse/fun-promises@latest/dist/browser/index.js

Usage

ES Modules

import FunPromise from "fun-promises";

CJS

const { FunPromise } = require("fun-promises");

What This Is Not

This is not an implementation of Promises/A+. It is not a polyfill or a ponyfill. In fact, it assumes that you have Promise available as a global, either through a polyfill or natively.

This is a library that extends the native Promise implementation with a number of useful utilities, so that your code is faster and easier. It is inspired by libraries like bluebird and rsvp.js, except without the overhead of providing its own Promise implementation. Native promises have been competitive in performance since Node 10 (even bluebird says so) but there's a lot of functionality which native Promises don't supply. Fun Promises gives you that better API without the overhead.

API

You also may want to check out the BDD spec, which gives an overview of how we expect these things to work.

Some Highlights

`settle` / `settleAll`

This changes a promise of a value into a promise of an object describing the result. The finally resolved object has a status property that is either "fulfilled" or "rejected", and also provides access to the reason or value.

`Deferral` class

This is an inside-out promise: it gives you access to the resolve and reject methods of the promise so that you can perform operations on them later, as well as having accessor to query the state of promise.

`try`

FunPromise.try(() => doSomething(explosivelyFailingParamCalculation()));
FunPromise.try(async () => {
    /* do stuff */ await something; /* do more stuff */
});

Wrap your execution in a promise, so that even its invocation won't release Zalgo, or as a convinent way to build a FunPromise off of an async function.

`tap`

someExpensiveOperation()
    .tap((value) => debug("Value from someExpensiveOperation", value))
    .then(/* ... */);

This lets you take a look at a resolved value without risking changing it. This is extremely useful for debugging log messages.

`race`

getRelatedShows().race((someShow) => renderSuggestedShow(someShow));

Fire off a bunch of promises and return whichever one resolves first. (The results of any later-resolving promises are discarded.)

`coalesce`

FunPromise.coalesce([
    lookupUserInMemoryCache,
    lookupUserInRedisCache,
    lookupUserInDB,
]).then((data) => renderUserData(data));

Given a bunch of functions that return either values or promises of values, execute them sequentially and return the first one what resolves.

Types

There are types that represent unwrapped promise values (Unpromise), things that may be promises or values (Promisable), and a few others that are a lot more esoteric.

NOTE: Compiling these types requires a recent version of TypeScript (4.1 or greater) due to conditional recursive types being unavailable in 3.x and buggy in 4.0.x.

Distributions

By default, your packager should automatically grab the appropriate distribution through the package.json configuration within this library. If you're curious or if you have a weird use case, then each distribution has a few different flavors of the codebase to choose from. These all live under the ./dist directory.

ESNext

Within ./dist/esnext is the result of the Typescript compilation with the "ESNext" module setting and the "ESNext" target setting. Note that it is subject to change as new ECMAScript standards are put out and Typescript's JavaScript generation continues to catch up to them, and mostly exists for developers to see code that results from compilation.

ES6

Within ./dist/es6 are the folders amd, umd, cjs (CommonJS), and esm (ECMAScript Modules). These contain the result of the Typescript compilation with the corresponding module setting and the "ES6" target setting.

The only single-file distribution is the es6/amd distribution.

Node

Within ./dist/node are the folders v10, v12, v14, each of which containing the Typescript compilation based on the recommended tsconfig.json configs. for those environments. All the versions are the exact same code as of this writing, so we default Node to using node/v14.

Browser

The file at ./dist/browser/index.js is the result of transpiling the result of the ESNext code above using Parcel. The result is a single minified file, appropriate for use in a CDN. It exposes the module under the global FunPromise namespace.

React Native

Within ./dist/react-native is the result of transpiling the result with the recommended tsconfig.json configs for React Native. The distribution is specified in package.json under the "reactNative" key, which you can configure Metro to prefer.

Documentation

The full documentation (including this content) is available on GitHub Pages.

Specifications

Our test specs are published here.