Promise with state

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.

How to use it?

First you need to import it in your project.

The require way

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

The import way

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

Then you can instantiate QueryablePromise to create Promises that are queryable for its state.

• 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 queryableWithRejection = new QueryablePromise((resolve, reject) => {
    // YOUR OWN CODE AND STUFF
    reject()
  })

  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(() => {
    console.log(queryableWithRejection.state)
    // REJECTED
    console.log(queryableWithRejection.isPending())
    // false
    console.log(queryableWithRejection.isRejected())
    // true
  })

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

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

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

  console.log(queryablePromise.state)
  // PENDING
  console.log(queryablePromise.isPending())
  // true
  console.log(queryablePromise.state === QueryablePromiseState.PENDING)
  // true
  console.log(queryablePromise.isFulfilled())
  // false
  console.log(queryablePromise.isRejected())
  // false

Native thenables can be transformed into queryable promises with makeQueryablePromise.

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

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

  const queryableTextPromise = makeQueryablePromise(processTextPromise)

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

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

Powered by https://xisco.dev

Additional JSDOC info

JSDOC

Table of Contents

• makeQueryablePromise
  • Parameters
  • isPending
  • isFulfilled
  • isRejected
• QueryablePromise
  • Parameters
  • resolve
    • Parameters
  • reject
    • Parameters
  • toStringTag
  • then
    • Parameters
  • catch
    • Parameters
  • finally
    • Parameters
  • state
  • isPending
  • isFulfilled
  • isRejected
• QueryablePromiseState
  • PENDING
  • FULFILLED
  • REJECTED

makeQueryablePromise

Transform any promise to queryable promise.

Parameters

• thenable Promise the promise to be transformed

Returns any a promise enhanced with state query methods

isPending

retrieves true if queried state is actual queryable promise state.

Returns boolean true when queryable promise state is PENDING

isFulfilled

retrieves true if queried state is actual queryable promise state.

Returns boolean true when queryable promise state is FULFILLED

isRejected

retrieves true if queried state is actual queryable promise state.

Returns boolean true when queryable promise state is REJECTED

QueryablePromise

Parameters

• fnExecutor Function function which contains fulfill and reject resolvers for Promise

resolve

then method refers to promise method

Parameters

• x any the result value of resolve

Returns QueryablePromise the resolve instance of the class

reject

then method refers to promise method

Parameters

• y any the reason or message error

Returns QueryablePromise the reject instance of the class

toStringTag

the property [Symbol.toStringTag] included in Promise

Type: string

Returns QueryablePromise returns class instance

then

then method refers to promise method

Parameters

• fn any method accepts a callback function

Returns QueryablePromise returns class instance

catch

catch method refers to promise method

Parameters

• fn any method accepts a callback function

Returns QueryablePromise returns class instance

finally

catch method refers to promise method

Parameters

• fn any method accepts a callback function

Returns QueryablePromise returns class instance

state

Getter for queryable promise state.

Type: QueryablePromiseState

Returns QueryablePromiseState contains current promise state

isPending

retrieves true if queried state is actual queryable promise state.

Returns boolean true when queryable promise state is PENDING

isFulfilled

retrieves true if queried state is actual queryable promise state.

Returns boolean true when queryable promise state is FULFILLED

isRejected

retrieves true if queried state is actual queryable promise state.

Returns boolean true when queryable promise state is REJECTED

QueryablePromiseState

Contains queryable promise states

Type: object

PENDING

Promise state PENDING for queryable

Type: QueryablePromiseState

FULFILLED

Promise state FULFILLED for queryable

Type: QueryablePromiseState

REJECTED

Promise state REJECTED for queryable

Type: QueryablePromiseState