What is this?

A library to use queryable promises or make native promise A+ queryable.

Why?

According to Promises/A+ standard definition, a Promise is a "thenable" object, which sets itself into 3 different states: PENDING, FULFILLED, or REJECTED. However, there is no way to ask a promise which state it is only know it has fulfilled or rejected. With this library you can create queryable promise or make native promise queryable.

A little bit about promises

Let see a typical Promise use:

new Promise((resolve, reject) => {
  if (condition) {
    resolve(result)
  } else {
    reject(err)
  }
})

A promise is built to fulfill or reject whatever its executor function defines, so a promise and its executor callback can look like this:

const functionExecutor = (resolve, reject) => {
  if (condition) {
    resolve(result)
  } else {
    reject(err)
  }
}

new Promise(functionExecutor)

This package was made to handle both cases, when a Promise instance is handled or if an executor callback is instead

Feel free to look the source code on the github repository of this project

How to use it?

First you need to install it to your project.

npm install promise-with-state

Then import it in your project.

• The require way

let { QueryablePromise } = require("promise-with-state");

• The import way

import { QueryablePromise } from "promise-with-state";

Use it so you can instantiate QueryablePromise to create Promises that are queryable.

• in the case it resolves

  import { QueryablePromise } from "promise-with-state";

  const queryableWithResolution = new QueryablePromise((resolve, reject) => {
    // YOUR OWN CODE AND STUFF
    resolve()
  })

  console.log(queryableWithResolution.state)
  // PENDING
  console.log(queryableWithResolution.isPending())
  // true
  console.log(queryableWithResolution.isFulfilled())
  // false
  console.log(queryableWithResolution.isRejected())
  // false

  queryableWithResolution
  .then(() => {
    console.log(queryableWithResolution.state)
    // FULFILLED
    console.log(queryableWithResolution.isPending())
    // false
    console.log(queryableWithResolution.isFulfilled())
    // true
  })
  .catch()

• in the case it rejects

  import { QueryablePromise } from "promise-with-state";
  const promiseExecutor = (resolve, reject) => {
    // YOUR OWN CODE AND STUFF
    reject()
  }

  const queryableWithRejection = new QueryablePromise(promiseExecutor)

  console.log(queryableWithRejection.state)
  // PENDING
  console.log(queryableWithRejection.isPending())
  // true
  console.log(queryableWithRejection.isFulfilled())
  // false
  console.log(queryableWithRejection.isRejected())
  // false

  queryableWithRejection
  .then() // promises always should has thenable
  .catch((err) => {
    console.log(queryableWithRejection.state)
    // REJECTED
    console.log(queryableWithRejection.isPending())
    // false
    console.log(queryableWithRejection.isRejected())
    // true
    handleError(err)
  })

The states for queryable promises are grouped in a constant called PromiseState

  import { PromiseState } from "promise-with-state";

  console.log(PromiseState)
  // {
  //   "PENDING": "PENDING",
  //   "FULFILLED": "FULFILLED",
  //   "REJECTED": "REJECTED"
  // }

  const queryableWithResolution = new QueryablePromise((resolve, reject) => {
    // YOUR OWN CODE AND STUFF
    resolve(foo)
  })

  console.log(queryableWithResolution.state === PromiseState.PENDING)
  // true

Native thenables can be transformed into queryable promises with makeQueryablePromise.

  import { makeQueryablePromise } from "promise-with-state";

  const promiseExecutor = (resolve, reject) => {
    // YOUR OWN CODE AND STUFF
    if (condition) {
      resolve()
    } else {
      reject()
    }
  }

  const processTextPromise = new Promise(promiseExecutor)
  const queryableTextPromise = makeQueryablePromise(processTextPromise)

  queryableTextPromise
    // if resolves
    .then(() => {
      console.log(queryableTextPromise.state)
      // FULFILLED
      console.log(queryableTextPromise.isPending())
      // false
      console.log(queryableTextPromise.isFulfilled())
      // true
    })
    // if rejects
    .catch(() => {
      console.log(queryableTextPromise.state)
      // REJECTED
      console.log(queryableTextPromise.isPending())
      // false
      console.log(queryableTextPromise.isRejected())
      // true
    })
    // whatever happens here
    .finally(() => {
      console.log(queryableTextPromise.isPending())
      // false
    })

Powered by https://xisco.dev

JSDOC

Table of Contents

• makeQueryablePromise
  • Parameters
• PromiseExecutor
• PromiseState
  • PENDING
  • FULFILLED
  • REJECTED
• QueryablePromise
  • Parameters
  • then
    • Parameters
  • catch
    • Parameters
  • finally
    • Parameters
  • state
  • isPending
  • isFulfilled
  • isRejected

makeQueryablePromise

Takes a native Promise and returns a QueryablePromise with state and query methods.

Parameters

• fnExecutor Function The native Promise or function which contains fulfill and reject callbacks

• Throws Error if the fnExecutor is invalid

Returns QueryablePromise A QueryablePromise instance with state and query methods.

PromiseExecutor

describes what a promise executor should look like

Type: function (fulfill: function (value: (T | PromiseLike<T>)): void, reject: function (reason: any): void): void

PromiseState

Contains queryable promise states

PENDING

Promise state PENDING for queryable promise

Type: PromiseState

FULFILLED

Promise state FULFILLED for queryable promise

Type: PromiseState

REJECTED

Promise state REJECTED for queryable promise

Type: PromiseState

QueryablePromise

Parameters

• fnExecutor Function The native Promise or function which contains fulfill and reject callbacks

then

then method refers to promise method.

Parameters

• onFulfilled Function callback function to run on fulfilled
• onRejected Function callback function to run on rejected

Returns QueryablePromise returns class instance

catch

catch method refers to promise method.

Parameters

• onRejected Function callback function to run on rejected

Returns QueryablePromise returns class instance

finally

finally method refers to promise method.

Parameters

• onFinally Function callback function that can run after fulfilled or rejected states

Returns QueryablePromise returns class instance

state

Getter for queryable promise state.

Type: PromiseState

Returns PromiseState contains current promise state

isPending

a function that retrieves if queried state is the actual queryable promise state.

Returns boolean a boolean whether a queryable promise state is PENDING

isFulfilled

a function that retrieves if queried state is the actual queryable promise state.

Returns boolean a boolean whether a queryable promise state is FULFILLED

isRejected

a function that retrieves if queried state is the actual queryable promise state.

Returns boolean a boolean whether a queryable promise state is REJECTED