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.

A little bit about promises

Let see a typical Promise use:

``js
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:

`js
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.

`bash
npm install promise-with-state
`

Then import it in your project.

The require way*

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

The import way*

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

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

* in the case it resolves

`js
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

`js
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

`js
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.

`js
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