{"id":17473747,"url":"https://github.com/xiscodev/promise-with-state","last_synced_at":"2025-04-22T10:39:08.251Z","repository":{"id":48074749,"uuid":"388599087","full_name":"xiscodev/promise-with-state","owner":"xiscodev","description":"A library to use queryable promises or make native promise A+ queryable","archived":false,"fork":false,"pushed_at":"2024-05-13T08:56:15.000Z","size":1081,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-22T10:38:02.089Z","etag":null,"topics":["browser","javascript-library","promise"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/promise-with-state","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xiscodev.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-22T21:15:15.000Z","updated_at":"2024-05-13T08:41:17.000Z","dependencies_parsed_at":"2024-05-13T09:50:01.077Z","dependency_job_id":"d8c19172-5390-4df8-b057-b891c0475456","html_url":"https://github.com/xiscodev/promise-with-state","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiscodev%2Fpromise-with-state","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiscodev%2Fpromise-with-state/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiscodev%2Fpromise-with-state/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiscodev%2Fpromise-with-state/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiscodev","download_url":"https://codeload.github.com/xiscodev/promise-with-state/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250222062,"owners_count":21394809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","javascript-library","promise"],"created_at":"2024-10-18T18:06:54.617Z","updated_at":"2025-04-22T10:39:08.035Z","avatar_url":"https://github.com/xiscodev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv style=\"display: -ms-flexbox; display: -webkit-flex; display: flex; -webkit-flex-direction: row; -ms-flex-direction: row; flex-direction: row; -webkit-flex-wrap: wrap; -ms-flex-wrap: wrap; flex-wrap: wrap; -webkit-justify-content: center; -ms-flex-pack: center; justify-content: center; -webkit-align-content: center; -ms-flex-line-pack: center; align-content: center; -webkit-align-items: center; -ms-flex-align: center; align-items: center;\"\u003e\n  \u003cimg style=\"-webkit-order: 0; -ms-flex-order: 0; order: 0; -webkit-flex: 0 1 auto; -ms-flex: 0 1 auto; flex: 0 1 auto; -webkit-align-self: auto; -ms-flex-item-align: auto; align-self: auto;\" src=\"icon.png\" /\u003e\n\u003c/div\u003e\n\n\u003ch1 style=\"text-align:center;\"\u003ePromise with state\u003c/h1\u003e\n\n## What is this?\n\nA library to use queryable promises or make native promise A+ queryable.\n\n## Why?\n\nAccording to [Promises/A+](https://promisesaplus.com) standard definition, a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) is a \"thenable\" object, which sets itself into 3 different states: [PENDING](#pending), [FULFILLED](#fulfilled), or [REJECTED](#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.\n\n## A little bit about promises\n\nLet see a typical Promise use:\n\n```js\nnew Promise((resolve, reject) =\u003e {\n  if (condition) {\n    resolve(result)\n  } else {\n    reject(err)\n  }\n})\n```\n\nA promise is built to fulfill or reject whatever its executor function defines, so a promise and its executor callback can look like this:\n\n```js\nconst functionExecutor = (resolve, reject) =\u003e {\n  if (condition) {\n    resolve(result)\n  } else {\n    reject(err)\n  }\n}\n\nnew Promise(functionExecutor)\n```\n\nThis package was made to handle both cases, when a Promise instance is handled or if an executor callback is instead\n\nFeel free to look the source code on the [github repository](https://github.com/xiscodev/promise-with-state/) of this project\n\n## How to use it?\n\nFirst you need to install it to your project.\n\n```bash\nnpm install promise-with-state\n```\n\nThen import it in your project.\n\n*   *The require way*\n\n```js\nlet { QueryablePromise } = require(\"promise-with-state\");\n```\n\n*   *The import way*\n\n```js\nimport { QueryablePromise } from \"promise-with-state\";\n```\n\nUse it so you can instantiate [QueryablePromise](#queryablepromise) to create Promises that are queryable.\n\n*   in the case it resolves\n\n```js\n  import { QueryablePromise } from \"promise-with-state\";\n\n  const queryableWithResolution = new QueryablePromise((resolve, reject) =\u003e {\n    // YOUR OWN CODE AND STUFF\n    resolve()\n  })\n\n  console.log(queryableWithResolution.state)\n  // PENDING\n  console.log(queryableWithResolution.isPending())\n  // true\n  console.log(queryableWithResolution.isFulfilled())\n  // false\n  console.log(queryableWithResolution.isRejected())\n  // false\n\n  queryableWithResolution\n  .then(() =\u003e {\n    console.log(queryableWithResolution.state)\n    // FULFILLED\n    console.log(queryableWithResolution.isPending())\n    // false\n    console.log(queryableWithResolution.isFulfilled())\n    // true\n  })\n  .catch()\n```\n\n*   in the case it rejects\n\n```js\n  import { QueryablePromise } from \"promise-with-state\";\n  const promiseExecutor = (resolve, reject) =\u003e {\n    // YOUR OWN CODE AND STUFF\n    reject()\n  }\n\n  const queryableWithRejection = new QueryablePromise(promiseExecutor)\n\n  console.log(queryableWithRejection.state)\n  // PENDING\n  console.log(queryableWithRejection.isPending())\n  // true\n  console.log(queryableWithRejection.isFulfilled())\n  // false\n  console.log(queryableWithRejection.isRejected())\n  // false\n\n  queryableWithRejection\n  .then() // promises always should has thenable\n  .catch((err) =\u003e {\n    console.log(queryableWithRejection.state)\n    // REJECTED\n    console.log(queryableWithRejection.isPending())\n    // false\n    console.log(queryableWithRejection.isRejected())\n    // true\n    handleError(err)\n  })\n```\n\nThe states for queryable promises are grouped in a constant called [PromiseState](#promisestate)\n\n```js\n  import { PromiseState } from \"promise-with-state\";\n\n  console.log(PromiseState)\n  // {\n  //   \"PENDING\": \"PENDING\",\n  //   \"FULFILLED\": \"FULFILLED\",\n  //   \"REJECTED\": \"REJECTED\"\n  // }\n\n  const queryableWithResolution = new QueryablePromise((resolve, reject) =\u003e {\n    // YOUR OWN CODE AND STUFF\n    resolve(foo)\n  })\n\n  console.log(queryableWithResolution.state === PromiseState.PENDING)\n  // true\n```\n\nNative thenables can be transformed into queryable promises with [makeQueryablePromise](#makequeryablepromise).\n\n```js\n  import { makeQueryablePromise } from \"promise-with-state\";\n\n  const promiseExecutor = (resolve, reject) =\u003e {\n    // YOUR OWN CODE AND STUFF\n    if (condition) {\n      resolve()\n    } else {\n      reject()\n    }\n  }\n\n  const processTextPromise = new Promise(promiseExecutor)\n  const queryableTextPromise = makeQueryablePromise(processTextPromise)\n\n  queryableTextPromise\n    // if resolves\n    .then(() =\u003e {\n      console.log(queryableTextPromise.state)\n      // FULFILLED\n      console.log(queryableTextPromise.isPending())\n      // false\n      console.log(queryableTextPromise.isFulfilled())\n      // true\n    })\n    // if rejects\n    .catch(() =\u003e {\n      console.log(queryableTextPromise.state)\n      // REJECTED\n      console.log(queryableTextPromise.isPending())\n      // false\n      console.log(queryableTextPromise.isRejected())\n      // true\n    })\n    // whatever happens here\n    .finally(() =\u003e {\n      console.log(queryableTextPromise.isPending())\n      // false\n    })\n```\n\nPowered by \u003chttps://xisco.dev\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAdditional JSDOC info\u003c/summary\u003e\n\n### JSDOC\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n##### Table of Contents\n\n*   [makeQueryablePromise](#makequeryablepromise)\n    *   [Parameters](#parameters)\n*   [PromiseExecutor](#promiseexecutor)\n*   [PromiseState](#promisestate)\n    *   [PENDING](#pending)\n    *   [FULFILLED](#fulfilled)\n    *   [REJECTED](#rejected)\n*   [QueryablePromise](#queryablepromise)\n    *   [Parameters](#parameters-1)\n    *   [then](#then)\n        *   [Parameters](#parameters-2)\n    *   [catch](#catch)\n        *   [Parameters](#parameters-3)\n    *   [finally](#finally)\n        *   [Parameters](#parameters-4)\n    *   [state](#state)\n    *   [isPending](#ispending)\n    *   [isFulfilled](#isfulfilled)\n    *   [isRejected](#isrejected)\n\n#### makeQueryablePromise\n\nTakes a native Promise and returns a QueryablePromise with state and query methods.\n\n##### Parameters\n\n*   `fnExecutor` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The native Promise or function which contains fulfill and reject callbacks\n\n\u003c!----\u003e\n\n*   Throws **[Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)** if the fnExecutor is invalid\n\nReturns **[QueryablePromise](#queryablepromise)** A QueryablePromise instance with state and query methods.\n\n#### PromiseExecutor\n\ndescribes what a promise executor should look like\n\nType: function (fulfill: function (value: (T | PromiseLike\\\u003cT\u003e)): void, reject: function (reason: any): void): void\n\n#### PromiseState\n\nContains queryable promise states\n\n##### PENDING\n\nPromise state PENDING for queryable promise\n\nType: [PromiseState](#promisestate)\n\n##### FULFILLED\n\nPromise state FULFILLED for queryable promise\n\nType: [PromiseState](#promisestate)\n\n##### REJECTED\n\nPromise state REJECTED for queryable promise\n\nType: [PromiseState](#promisestate)\n\n#### QueryablePromise\n\n##### Parameters\n\n*   `fnExecutor` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The native Promise or function which contains fulfill and reject callbacks\n\n##### then\n\nthen method refers to promise method.\n\n###### Parameters\n\n*   `onFulfilled` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** callback function to run on fulfilled\n*   `onRejected` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** callback function to run on rejected\n\nReturns **[QueryablePromise](#queryablepromise)** returns class instance\n\n##### catch\n\ncatch method refers to promise method.\n\n###### Parameters\n\n*   `onRejected` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** callback function to run on rejected\n\nReturns **[QueryablePromise](#queryablepromise)** returns class instance\n\n##### finally\n\nfinally method refers to promise method.\n\n###### Parameters\n\n*   `onFinally` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** callback function that can run after fulfilled or rejected states\n\nReturns **[QueryablePromise](#queryablepromise)** returns class instance\n\n##### state\n\nGetter for queryable promise state.\n\nType: [PromiseState](#promisestate)\n\nReturns **[PromiseState](#promisestate)** contains current promise state\n\n##### isPending\n\na function that retrieves if queried state is the actual queryable promise state.\n\nReturns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** a boolean whether a queryable promise state is PENDING\n\n##### isFulfilled\n\na function that retrieves if queried state is the actual queryable promise state.\n\nReturns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** a boolean whether a queryable promise state is FULFILLED\n\n##### isRejected\n\na function that retrieves if queried state is the actual queryable promise state.\n\nReturns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** a boolean whether a queryable promise state is REJECTED\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiscodev%2Fpromise-with-state","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiscodev%2Fpromise-with-state","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiscodev%2Fpromise-with-state/lists"}