Protected constructorConstructor accepts a normal Promise executor function like new Unpromise((resolve, reject) => {...}) or accepts a pre-existing Promise
like new Unpromise(existingPromise). Adds .then() and .catch()
handlers to the Promise. These handlers pass fulfilment and rejection
notifications to downstream subscribers and maintains records of value
or error if the Promise ever settles.
Readonly [toTOSTRING SUPPORT
Protected Readonly promiseThe promise shadowed by this Unpromise
Protected settlementThe Promise's settlement (recorded when it fulfils or rejects). This is consulted when calling .subscribe() .then() .catch() .finally() to see if an immediately-resolving Promise can be returned, and therefore subscription can be bypassed.
Protected subscribersPromises expecting eventual settlement (unless unsubscribed first). This list is deleted after the original promise settles - no further notifications will be issued.
Optional onfinally: null | (() => void)Create a promise that mitigates uncontrolled subscription to a long-lived Promise via .then() and .catch() - otherwise a source of memory leaks.
The returned promise has an unsubscribe() method which can be called when
the Promise is no longer being tracked by application logic, and which
ensures that there is no reference chain from the original promise to the
new one, and therefore no memory leak.
If original promise has not yet settled, this adds a new unique promise
that listens to then/catch events, along with an unsubscribe() method to
detach it.
If original promise has settled, then creates a new Promise.resolve() or Promise.reject() and provided unsubscribe is a noop.
If you call unsubscribe() before the returned Promise has settled, it
will never settle.
STANDARD PROMISE METHODS (but returning a SubscribedPromise)
Static anyPerform Promise.any() via SubscribedPromises, then unsubscribe them. Equivalent to Promise.any but eliminates memory leaks from long-lived promises accumulating .then() and .catch() subscribers.
Protected Static createProtected Static getRetrieve a previously-created Unpromise keyed by an original Promise.
Static proxyCreate or Retrieve the proxy Unpromise (a re-used Unpromise for the VM lifetime of the provided Promise reference)
Static racePerform Promise.race via SubscribedPromises, then unsubscribe them. Equivalent to Promise.race but eliminates memory leaks from long-lived promises accumulating .then() and .catch() subscribers.
Static raceCreate a race of SubscribedPromises that will fulfil to a single winning Promise (in a 1-Tuple). Eliminates memory leaks from long-lived promises accumulating .then() and .catch() subscribers. Allows simple logic to consume the result, like...
const [ winner ] = await Unpromise.race([ promiseA, promiseB ]);
if(winner === promiseB){
const result = await promiseB;
// do the thing
}
Static resolveLookup the Unpromise for this promise, and derive a SubscribedPromise from it (that can be later unsubscribed to eliminate Memory leaks)
Every
Promise<T>can be shadowed by a singleProxyPromise<T>. It is created once, cached and reused throughout the lifetime of the Promise. Get a Promise's ProxyPromise usingUnpromise.proxy(promise).The
ProxyPromise<T>attaches handlers to the originalPromise<T>.then()and.catch()just once. Promises derived from it use a subscription- (and unsubscription-) based mechanism that monitors these handlers.Every time you call
.subscribe(),.then().catch()or.finally()on aProxyPromise<T>it returns aSubscribedPromise<T>having an additionalunsubscribe()method. Callingunsubscribe()detaches reference chains from the original, potentially long-lived Promise, eliminating memory leaks.This approach can eliminate the memory leaks that otherwise come about from repeated
race()orany()calls invoking.then()and.catch()multiple times on the same long-lived native Promise (subscriptions which can never be cleaned up).Unpromise.race(promises)is a reference implementation ofPromise.raceavoiding memory leaks when using long-lived unsettled Promises.Unpromise.any(promises)is a reference implementation ofPromise.anyavoiding memory leaks when using long-lived unsettled Promises.Unpromise.resolve(promise)returns an ephemeralSubscribedPromise<T>for any givenPromise<T>facilitating arbitrary async/await patterns. Behind the scenes,resolveis implemented simply asUnpromise.proxy(promise).subscribe(). Don't forget to call.unsubscribe()to tidy up!