get-promisable-result 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# get-promisable-result
+
+A very small JavaScript utility to check and retry a function a limited number of times abstracting it in a Promise
+
+[![Deployment Status](https://github.com/elchininet/get-promisable-result/actions/workflows/deploy.yaml/badge.svg)](https://github.com/elchininet/get-promisable-result/actions/workflows/deploy.yaml)
+[![Tests](https://github.com/elchininet/get-promisable-result/actions/workflows/tests.yaml/badge.svg)](https://github.com/elchininet/get-promisable-result/actions/workflows/tests.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/elchininet/get-promisable-result/badge.svg?branch=master)](https://coveralls.io/github/elchininet/get-promisable-result?branch=master)
+[![npm version](https://badge.fury.io/js/get-promisable-result.svg)](https://badge.fury.io/js/get-promisable-result)
+
+## Install
+
+#### npm
+
+```bash
+npm install get-promisable-result
+```
+
+#### yarn
+
+```bash
+yarn add get-promisable-result
+```
+
+#### PNPM
+
+```bash
+pnpm add get-promisable-result
+```
+
+## API
+
+```typescript
+getPromisableResult(
+  getResultFunction: () => T,
+  checkResult: (result: T) => boolean,
+  options: PromisableOptions = {}
+): Promise<T>
+```
+
+`getResultFunction` should be a function that returns something. This something is what you expect when the promise gets resolved.
+
+`checkResult` is a function that will have as a parameter the result of the `getResultFunction` and it should return a `boolean` to validate that the result is OK. If this function returns `false`, the `getResultFunction` will be executed a limited number of times (consult the [options](#options) section) until its result pass the check or until it reached the `retries` (consult the [options](#options) section).
+
+### Options
+
+| Parameter      | Type          | Default | Description                                                         |
+| -------------- | ------------- | ------- | ------------------------------------------------------------------- |
+| retries        | number        | 10      | number of retries that will be performed before the promise rejects |
+| delay          | number        | 10      | delay between the retries                                           |
+| shouldReject   | boolean       | true    | indicates if the promise should be rejected when the number of retries reached the limit. If this parameter is set to `false` and the number of retries is reached the Promise will be resolved with the last value returned by `getResultFunction` |
+| rejectMessage  | string        | \*\*    | custom error message. It can contain the substring `{{ retries }}` and it will be replaced with the number of `retries` |
+
+>\*\* The default `rejectMessage` will be `Could not get the result after {{ retries }} retries`
+
+## Example
+
+Querying a DOM element that is rendered asynchronously with a custom `retries`, `delay` and `rejectMessage`
+
+```typescript
+getPromisableResult(
+  () => document.getElementById('my-element'),
+  (element) => element !== null,
+  {
+    retries: 50,
+    delay: 100,
+    rejectMessage: 'My element could not be retrieved after {{ restries }} retries'
+  }
+)
+  .then((element) => {
+    // Do something with the element
+  })
+  .catch((error) => {
+    // Do something if the promise is rejected
+    // My element could not be retrieved after 50 retries
+  });
+```

package/dist/esm/index.d.ts

@@ -0,0 +1,10 @@
+declare const DEFAULT_RETRIES = 10;
+declare const DEFAULT_DELAY = 10;
+interface PromisableOptions {
+    retries?: number;
+    delay?: number;
+    shouldReject?: boolean;
+    rejectMessage?: string;
+}
+declare const getPromisableResult: <T>(getResultFunction: () => T, checkResult: (result: T) => boolean, options?: PromisableOptions) => Promise<T>;
+export { DEFAULT_RETRIES, DEFAULT_DELAY, getPromisableResult };

package/dist/esm/index.js

@@ -0,0 +1 @@
+var e=10,r=10,t=function(e,r,t){var o;void 0===t&&(t={});var i=t.retries,n=void 0===i?10:i,s=t.delay,a=void 0===s?10:s,v=t.shouldReject,u=void 0===v||v,c=null!==(o=t.rejectMessage)&&void 0!==o?o:"Could not get the result after {{ retries }} retries";return new Promise((function(t,o){var i=0,s=function(){var v=e();r(v)?t(v):++i<n?setTimeout(s,a):u?o(new Error(c.replace(/\{\{\s*retries\s*\}\}/g,"".concat(n)))):t(v)};s()}))};export{r as DEFAULT_DELAY,e as DEFAULT_RETRIES,t as getPromisableResult};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+declare const DEFAULT_RETRIES = 10;
+declare const DEFAULT_DELAY = 10;
+interface PromisableOptions {
+    retries?: number;
+    delay?: number;
+    shouldReject?: boolean;
+    rejectMessage?: string;
+}
+declare const getPromisableResult: <T>(getResultFunction: () => T, checkResult: (result: T) => boolean, options?: PromisableOptions) => Promise<T>;
+export { DEFAULT_RETRIES, DEFAULT_DELAY, getPromisableResult };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";exports.DEFAULT_DELAY=10,exports.DEFAULT_RETRIES=10,exports.getPromisableResult=function(e,r,t){var o;void 0===t&&(t={});var s=t.retries,i=void 0===s?10:s,n=t.delay,u=void 0===n?10:n,a=t.shouldReject,c=void 0===a||a,l=null!==(o=t.rejectMessage)&&void 0!==o?o:"Could not get the result after {{ retries }} retries";return new Promise((function(t,o){var s=0,n=function(){var a=e();r(a)?t(a):++s<i?setTimeout(n,u):c?o(new Error(l.replace(/\{\{\s*retries\s*\}\}/g,"".concat(i)))):t(a)};n()}))};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "get-promisable-result",
+  "version": "1.0.0",
+  "description": "A very small JavaScript utility to check and retry a function a limited number of times abstracting it in a Promise",
+  "keywords": [
+    "promise",
+    "promisable",
+    "async",
+    "promisable-result",
+    "javascript",
+    "utility",
+    "javascript-utility",
+    "retry",
+    "check-and-retry"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "author": "ElChiniNet",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elchininet/get-promisable-result"
+  },
+  "scripts": {
+    "build": "rollup --config rollup.config.js --bundleConfigAsCjs",
+    "test:ts": "tsc --noEmit",
+    "test:lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test:unit": "jest --clearCache && jest --verbose --coverage",
+    "test:all": "pnpm test:ts && pnpm test:lint && pnpm test:unit",
+    "prepare": "pnpm build",
+    "prepublishOnly": "pnpm test:all",
+    "version": "git add .",
+    "postversion": "git push && git push --tags"
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/eslint": "^9.6.1",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.5.4",
+    "eslint": "^9.10.0",
+    "globals": "^15.9.0",
+    "jest": "^29.7.0",
+    "rollup": "4.21.2",
+    "rollup-plugin-ts": "^3.4.5",
+    "ts-jest": "^29.2.5",
+    "tslib": "^2.7.0",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.4.0"
+  }
+}