extendPromise

Extend a Promise by injecting custom properties using a Proxy. The custom properties will be available on the promise chain no matter how many thens, catchs or finallys are added.

Example

This function can be used with any kind of promises, but the example focuses on requests because, nowadays, they are the most common context for promises.

Let's say you have a function that makes a request and you want to be able to return a way to abort it at any point. You can use fetch and an AbortController to do it, but you can't return just the promise, you need to return the controller or at least its abort method:

const makeTheRequest = () => {
  const controller = new AbortController();
  const req = fetch('https://...', {
    signal: controller.signal,
  });

  return { req, controller };
};

It looks good, but if the function is called from a service or somewhere that is not the actual implementation, you'll need to keep track of both the Promise and the controller.

You could monkey patch the abort method to the Promise:

const makeTheRequest = () => {
  const controller = new AbortController();
  const req = fetch('https://...', {
    signal: controller.signal,
  });
  req.abort = controller.abort.bind(this);
  return req;
};

But there's a problem: the moment a .then/.catch/.finally is added to that Promise, a new one is generated, and the patch goes away.

This is where extendPromise can help you. Either the controller or the abort method can be added to the chain and the customization will be available no matter how many .thens are added:

const { extendPromise } = require('wootils/shared');

const makeTheRequest = () => {
  const controller = new AbortController();
  const req = fetch('https://...', {
    signal: controller.signal,
  });

  return extendPromise(req, {
    abort: controller.abort.bind(this),
  });
};

And there you go! You can now receive the request Promise and abort it if needed:

// Make the request
const req = makeTheRequest()
.then((response) => response.json())
.catch((error) => {
  if (error.name === 'AbortError') {
    console.log('to late...');
  }
  ...
});

// Abort it if takes more than one second.
setTimeout(() => req.abort(), 1000);

ES Modules

If you are using ESM, you can import the function from the /esm sub path:

import extendPromise from 'wootils/esm/shared/extendPromise';

// or

import { extendPromise } from 'wootils/esm/shared';

Technical documentation

• Function: extendPromise
• Helper class: PromiseExtender

If you are reading this form the markdown document, you can go to the online version; or you can generate the documentation site yourself by running the docs command:

# You can either use npm or yarn, it doesn't matter
npm run docs && open ./docs/index.html;