trashable

A wrapper to make promises cancellable and garbage collectable

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
trashable
8321.0.74 years ago5 years agoMinified + gzip package size for trashable in KB

Readme

Trashable :putlitterinitsplace:
npm NPM file size David CircleCI npm
A wrapper to make promises cancellable and garbage collectable. See how this relates to React below and use trashable-reacttrashable-react to make your React components garbage collectable.

Installation

npm install --save trashable

How to use

import makeTrashable from 'trashable';

let promise = new Promise((resolve) => {
    setTimeout(resolve, 10000);
});

let trashablePromise = makeTrashable(promise);
trashablePromise.then(() => {
    console.log('10 seconds have passed');
});

trashablePromise.trash();

Why you should cancel promises

You wanted a banana but what you got was a gorilla holding the banana and the entire jungle.
— Joe Armstrong

The handlers you pass to promises often reference other objects. These objects can be quick large. This means if the promise is still in flight (not resolved or rejected), these large objects cannot be safely garbage collected even when the promise result has been forgotten and been ignored. That is why canceling promises so that the objects their handlers reference can be freed is so important.

React

In particular, this issue has reared its head in React with the use of isMount() method (now deprecated). This articlereact-ismounted-antipattern gives a good explanation for why using isMount() should be avoided. Simply put, prevents a garbage collector from getting rid of potentially large React Elements.
It recommends to clean up any callbacks in componentWillUnmount so that they won't call setState() after the element has been unmounted and thus continue to reference the Element.
Unfortunately, this is not that easy if promises are used and the solution it provides in that article actually doesn't solve the garbage collection problem. The cancel method does nothing to dereference the handlers and the Element will not be garbage collected (see more in the PROOF).
Use trashable-reacttrashable-react to make your React components garbage collectable.

Why is this any different than other Cancelable Promise libraries

Unlike other cancelable promise libraries, Trashable actually dereferences the promise handlers so that objects that were referenced can be garbaged collected appropriately, freeing up memory.

Gotchas

You need to make your promises trashable before you add your then and catch handlers. Otherwise, you will not get the garbage collection benefits.
// Do this
const trashablePromise = makeTrashable(promise);
trashablePromise.then(() => {});

// NOT this
const handledPromise = promise.then(() => {});
makeTrashable(handledPromise);

Inspiration