A library to use queryable promises or make native promise A+ queryable.
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.
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
First you need to install it to your project.
npm install promise-with-stateThen 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)
// trueNative 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
Additional JSDOC info
Takes a native Promise and returns a QueryablePromise with state and query methods.
-
fnExecutorFunction 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.
describes what a promise executor should look like
Type: function (fulfill: function (value: (T | PromiseLike<T>)): void, reject: function (reason: any): void): void
Contains queryable promise states
Promise state PENDING for queryable promise
Type: PromiseState
Promise state FULFILLED for queryable promise
Type: PromiseState
Promise state REJECTED for queryable promise
Type: PromiseState
-
fnExecutorFunction The native Promise or function which contains fulfill and reject callbacks
then method refers to promise method.
-
onFulfilledFunction callback function to run on fulfilled -
onRejectedFunction callback function to run on rejected
Returns QueryablePromise returns class instance
catch method refers to promise method.
-
onRejectedFunction callback function to run on rejected
Returns QueryablePromise returns class instance
finally method refers to promise method.
-
onFinallyFunction callback function that can run after fulfilled or rejected states
Returns QueryablePromise returns class instance
Getter for queryable promise state.
Type: PromiseState
Returns PromiseState contains current promise state
a function that retrieves if queried state is the actual queryable promise state.
Returns boolean a boolean whether a queryable promise state is PENDING
a function that retrieves if queried state is the actual queryable promise state.
Returns boolean a boolean whether a queryable promise state is FULFILLED
a function that retrieves if queried state is the actual queryable promise state.
Returns boolean a boolean whether a queryable promise state is REJECTED