README.md

Deferred Promise

The DeferredPromise class is a Promise-compatible abstraction that defers resolving/rejecting promises to another closure. This class is primarily useful when one part of your system establishes as promise but another part of your system fulfills it.

This class is conceptually inspired by the createDeferredPromise() internal utility in Node.js. Unlike the Node.js implementation, however, DeferredProimse extends a native Promise, allowing the consumer to handle deferred promises like regular promises (no .promise instance nesting).

Getting started

npm install @open-draft/deferred-promise

Documentation

• createDeferredExecutor()
  • DeferredExecutor.state
  • DeferredExecutor.resolve()
  • DeferredExecutor.reject()
  • DeferredExecutor.rejectionReason
• Class: DeferredPromise
  • new DeferredPromise()
  • deferredPromise.state
  • deferredPromise.resolve()
  • deferredPromise.reject()
  • deferredPromise.rejectionReason

---

createDeferredExecutor()

Creates a Promise executor function that delegates its resolution to the current scope.

import { createDeferredExecutor } from '@open-draft/deferred-promise'

const executor = createDeferredExecutor()
const promise = new Promise(executor)

executor.resolve('hello')
// executor.reject(new Error('Reason'))

Deferred executor allows you to control any promise remotely and doesn't affect the Promise instance in any way. Similar to the DeferredPromise instance, the deferred executor exposes additional promise properties like state, rejectionReason, resolve, and reject. In fact, the DeferredPromise class is implemented on top of the deferred executor.

const executor = createDeferredExecutor()
const promise = new Promise(executor)

executor.reject('reason')

nextTick(() => {
  console.log(executor.rejectionReason) // "reason"
})

DeferredExecutor.state

• <"pending" | "fulfilled" | "rejected"> Default: "pending"

const executor = createDeferredExecutor()
const promise = new Promise(executor)

console.log(executor.state) // "pending"

Calling resolve() and reject() methods of the executor transitions the state to "fulfilled" and "rejected" respectively.

DeferredExecutor.resolve()

Resolves the promise with a given value.

const executor = createDeferredExecutor()
const promise = new Promise(executor)

console.log(executor.state) // "pending"

executor.resolve()

// The promise state is still "pending"
// because promises are settled in the next microtask.
console.log(executor.state) // "pending"

nextTick(() => {
  // In the next microtask, the promise's state is resolved.
  console.log(executor.state) // "fulfilled"
})

DeferredExecutor.reject()

Rejects the promise with a given reason.

const executor = createDeferredExecutor()
const promise = new Promise(executor)

executor.reject(new Error('Failed to fetch'))

nextTick(() => {
  console.log(executor.state) // "rejected"
  console.log(executor.rejectionReason) // Error("Failed to fetch")
})

You can access the rejection reason of the promise at any time by the rejectionReason property of the deferred executor.

DeferredExecutor.rejectionReason

Returns the reason of the promise rejection. If no reason has been provided to the reject() call, undefined is returned instead.

const executor = createDeferredExecutor()
const promise = new Promise(executor)

promise.reject(new Error('Internal Server Error'))

nextTick(() => {
  console.log(promise.rejectionReason) // Error("Internal Server Error")
})

---

Class: DeferredPromise

new DefferedPromise()

Creates a new instance of a deferred promise.

import { DeferredPromise } from '@open-draft/deferred-promise'

const promise = new DeferredPromise()

A deferred promise is a Promise-compatible class that constructs a regular Promise instance under the hood, controlling it via the deferred executor.

A deferred promise is fully compatible with the regular Promise, both type- and runtime-wise, e.g. a deferred promise can be chained and awaited normally.

const promise = new DefferredPromise()
  .then((value) => value.toUpperCase())
  .then((value) => value.substring(0, 2))
  .catch((error) => console.error(error))

await promise

Unlike the regular Promise, however, a deferred promise doesn't accept the executor function as the constructor argument. Instead, the resolution of the deferred promise is deferred to the current scope (thus the name).

function getPort() {
  // Notice that you don't provide any executor function
  // when constructing a deferred promise.
  const portPromise = new DeferredPromise()

  port.on('open', (port) => {
    // Resolve the deferred promise whenever necessary.
    portPromise.resolve(port)
  })

  // Return the deferred promise immediately.
  return portPromise
}

Use the resolve() and reject() methods of the deferred promise instance to resolve and reject that promise respectively.

deferredPromise.state

See DeferredExecutor.state

deferredPromise.resolve()

See DeferredExecutor.resolve()

deferredPromise.reject()

See DeferredExecutor.reject()

deferredPromise.rejectionReason

See DeferredExecutor.rejectionReason

---

Mentions

• Jonas Kuske for the phenomenal work around improving Promise-compliance.