@figliolia/promises

Promises

A small wrapper library around the native Promise API that provides two core utilities - Cancellable Promises and Timed Promises.

A Cancellable Promise is simply a Promise with a cancel method attached to it. Using it you can stop promises mid-flight and even cancel in progress network requests.

A Timed Promise is niche utility that allows a promises pending duration to be measured against a provided threshold. If the promise resolves or rejects, it'll do so yielding the result as well as the remaining milliseconds of the threshold.

Installation

npm i @figliolia/promises
# or
yarn add @figliolia/promises

Basic Usage

Cancellable Promise

import { CancellablePromise } from "@figliolia/promises";

const myAsyncWork = (signal: AbortSignal) => {
  return fetch("/some-data", { signal });
}

const CP = new CancellablePromise(myAsyncWork);
await CP.run();
// To cancel:
CP.cancel()

In the above example, we've wrapped our asynchronous task in a function accepting an AbortSignal. The CancellablePromise interface will provide your asynchronous task with a signal that you can pass down into further asynchronous work - yielding you the ability to cancel any number of asynchronous tasks at once with a call to cancel().

Timed Promise

import { TimedPromise } from "@figliolia/promises";

const myAsyncWork = () => {
  // trigger a loading spinner or something
  return fetch("/some-data", { signal });
}

const TP = new TimedPromise(myAsyncWork, 1000);
const { result, remainingMS } = await TP.run();
if(remainingMS > 0) {
  // Defer hiding the loading state so soon that
  // it may be a jarring visual to some users
  setTimeout(/* hide loading state */, remainingMS);
} else {
  // Carry about your business
}

Composing them Together

import { 
  TimedPromise,
  CancellablePromise
} from "@figliolia/promises";

const myAsyncWork = () => {
  // trigger a loading spinner or something
  return fetch("/some-data", { signal });
}

const CP = new CancellablePromise(myAsyncWork);
const TP = new TimedPromise(() => CP.run(), 1000);
const { result, remainingMS } = await TP.run();
// or
CP.cancel() // which would cancel your TP and CP at once!

Background and Contributions

I often find myself spinning up utilities such as these on fly, then kicking myself when I have to write them again in a new project or company. If you find yourself in my shoes, please feel free to PR this repository with your utilities and polyfills and I'll review promptly!