{"_id":"@abecodes/promise-helper","_rev":"1-6b00839b9a9c56213d5b265f47a7792e","name":"@abecodes/promise-helper","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@abecodes/promise-helper","version":"1.0.0","description":"A useful, zero dependencies toolbox to handle different situations like trigerring sequential Promises, a sequence with pause in between, parallel execution and limited parallel execution","main":"index.js","scripts":{"test":"nyc --cache --reporter=text-summary --reporter=html mocha -R tap -R nyan ./**/**/__tests__/*.test.js"},"repository":{"type":"git","url":"git+https://github.com/abecodes/promise-helper.git"},"private":false,"keywords":["promise","cancel","cancelable","abort","callback","timeout","sleep","sequence","parallel","limit","task","queue","async","await","chain","vanilla","zero dependencies"],"author":{"name":"abe.codes","email":"me@abe.codes","url":"http://abe.codes/"},"license":"UNLICENSED","devDependencies":{"chai":"^4.2.0","mocha":"^6.2.0","nyc":"^14.1.1"},"gitHead":"dd65448d0b041c25cf8149c5d06534827d189c79","bugs":{"url":"https://github.com/abecodes/promise-helper/issues"},"homepage":"https://github.com/abecodes/promise-helper#readme","_id":"@abecodes/promise-helper@1.0.0","_nodeVersion":"12.7.0","_npmVersion":"6.11.3","dist":{"integrity":"sha512-+jnSt1J6iIMmeBlS7a0l2KuM4yizTRKOD6YQxq5++inOix5VhUkeVmfvvWXrJGt5ZNQtyikDtPvMOMH7WoQ47A==","shasum":"f0681420fbc2360dc624b03d525c155e506e3442","tarball":"https://registry.npmjs.org/@abecodes/promise-helper/-/promise-helper-1.0.0.tgz","fileCount":27,"unpackedSize":26825,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdj7HiCRA9TVsSAnZWagAAZAgP/03kDTSnyWUjS64/X9Ue\np8WnsEbR9LUuzYrjSA28oX9reCohISK0y7OZx7HJ5INCdp6i6kUXGeAlUCAv\nQC6zv1Mo7yjqkZqmNmy1pmIMB/4oGNa0VDXQXIUnDOK/nGHAjhI9INgPLPeY\n/WJPIF1hw9mR4z5OYE85viC0zdWeKNGyCnAOuPN9NI5wXwW0kfA9QR7OEYDm\nTxc7BXmwRY5OpPS2h5SnaGzId3uG5foXfuFdX/t6IpjOX6rCZ0bZnuR/4H7F\nFWXaVbSL09x/xIAITOR6XT57qPmeUkKB2Fm7Koqmhivk+rFcpheb7LVYq5be\nFGt1Isef9qZuTbNY1YSeUfMkhQaf/vIDdM3Vh6r7BJdUKsXdHLnqgr+GJfh2\nxEoCL5d+sfwAEgt1kcHP3xfwxRgX3JiXAFUGEyhNcrfdK9uQNDSUAUaRHbeh\n6lyrSs3o/IDdL6TYNNa6jtB2IK9+Z/e6T+pmv3KK9rxCMAr+1uads2PsBerT\nKCODFWeVIDiGFHRweb+kkyDRHP0GdiDyd1OLcA5pao8HDHj7d6M88W29Dx3b\nit/d81lL2LTBoCV97Ie+CKndIoT4J8GNdkKWi48DaYWQ418TIC/smXkZpTZe\nFoCyG15320z7Z9A0LAMc5ZKVLyFRZL2wqHx/JHM8AhDxzGZqCE7UgXoCBYhu\nd/ME\r\n=S/Gi\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD8UDPxlYbWpEvruvNJJsy+2qv9w355I+DHbZA9bzuqgAIhALjY9xP6SXONo2JwBl3ESnbyy78ETN+ABqPe0n1a5bM8"}]},"maintainers":[{"name":"abecodes","email":"me@abe.codes"}],"_npmUser":{"name":"abecodes","email":"me@abe.codes"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/promise-helper_1.0.0_1569698273399_0.6162029994284848"},"_hasShrinkwrap":false}},"time":{"created":"2019-09-28T19:17:53.182Z","1.0.0":"2019-09-28T19:17:53.590Z","modified":"2022-04-04T10:58:50.238Z"},"maintainers":[{"name":"abecodes","email":"me@abe.codes"}],"description":"A useful, zero dependencies toolbox to handle different situations like trigerring sequential Promises, a sequence with pause in between, parallel execution and limited parallel execution","homepage":"https://github.com/abecodes/promise-helper#readme","keywords":["promise","cancel","cancelable","abort","callback","timeout","sleep","sequence","parallel","limit","task","queue","async","await","chain","vanilla","zero dependencies"],"repository":{"type":"git","url":"git+https://github.com/abecodes/promise-helper.git"},"author":{"name":"abe.codes","email":"me@abe.codes","url":"http://abe.codes/"},"bugs":{"url":"https://github.com/abecodes/promise-helper/issues"},"license":"UNLICENSED","readme":"# promise-helper\n\npromise-helper is a simple toolbelt that aims to help with the more complex tasks of using promises.\nIt supports operations like handling promises in sequence, sequences with sleeps,\nparallel execution or limited parallel execution, promises with timeout and cancelable promises.\n\nIt is released under the [UNLICENSE](https://unlicense.org/) & supports modern environments.\n\n## Installation\n\nUsing npm:\n\n```bash\n# global\n$ npm i -g @abecodes/promise-helper\n\n# dependency\n$ npm i -S @abecodes/promise-helper\n\n# dev dependecy\n$ npm i -D @abecodes/promise-helper\n```\n\nIn Node.js:\n\n```js\n// Require the package.\nconst ph = require(\"@abecodes/promise-helper\");\n```\n\n## API\n\n### sequence\n\n```javascript\n// Default\nph.sequence(taskArray: [() => Promise<any>], cb?: (err, result) => any) => Promise<any>\n\n// Adding timeout between each task\nph.sequence.withSleep(taskArray: [() => Promise<any>], timeout: number,cb?: (err, result) => any) => Promise<any>\n\n// Adding a random timeout inbetween a given range between each task\nph.sequence.withSleepRange(taskArray: [() => Promise<any>], minTime: number, maxTime: number, cb?: (err, result) => any) => Promise<any>\n```\n\nThe _sequence_ method takes an array of HOFs that return a promise an runs them in sequence. If _sequence.withSleep_ or _sequence.withSleepRange_ is called, the sequence will sleep after each task.\n\n_Sequence_ can be used as Promise or with a callback.\nIf one task fails, the whole sequence will fail.\nIn case of an error, all previous results will be accessable (if not falsy).\n\nIf used as promise, they will be passed in the error object as result property.\n\nIf used with a callback, they are passed as the result parameter.\n\n```javascript\n// Example\nconst p = ph.sequence.withSleep(\n\t[\n\t\t() =>\n\t\t\tnew Promise((resolve, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tresolve(\"Hello\");\n\t\t\t\t}, 200);\n\t\t\t}),\n\t\t() =>\n\t\t\tnew Promise((resolve, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tresolve(\"World\");\n\t\t\t\t}, 200);\n\t\t\t}),\n\t],\n\t2000\n);\np.then(res => console.log(res)).catch(err => console.log(err, err.result));\n```\n\n### parallel\n\n```javascript\n// Default\nph.parallel(taskArray: [() => Promise<any>], cb?: (err, result) => any) => Promise<any>\n\n// Triggering limited execution\nph.parallel.limited(taskArray: [() => Promise<any>], limit: number) => void\n```\n\nThe _parallel_ method takes an array of HOFs that return a promise an runs them in parallel.\n\nIf _parallel.limited_ is called,\nonly the given number of tasks will run in parallel.\n\n_Parallel_ can be used as Promise or with a callback.\nIf one task fails, the whole sequence will fail.\n\n_Parallel.limited_ returns void, so each task must be handled by itself during initialization.\n\n```javascript\n// Example\nph.parallel.limited(\n\t[\n\t\t() =>\n\t\t\tnew Promise((resolve, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tresolve(\"Hello\");\n\t\t\t\t}, 200);\n\t\t\t}).then(res => console.log(res)),\n\t\t() =>\n\t\t\tnew Promise((resolve, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tresolve(\"World\");\n\t\t\t\t}, 200);\n\t\t\t}).then(res => console.log(res)),\n\t\t() =>\n\t\t\tnew Promise((resolve, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\treject(new Error(\"oO\"));\n\t\t\t\t}, 200);\n\t\t\t}).catch(res => console.log(res)),\n\t\t() =>\n\t\t\tnew Promise((resolve, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\tresolve(\"working limited\");\n\t\t\t\t}, 200);\n\t\t\t}).then(res => console.log(res)),\n\t],\n\t2\n);\n```\n\n### timeout\n\n```javascript\n// Default (throws timeout)\nph.timeout((executor: (resolve: (value?: any) => void, reject: (reason?: any)) => void) => void, timeout: number, onTimeout?: () => any) => Promise<any>\n\n// Instead of throwing an error, withNull will resolve with null on timeout\nph.timeout.withNull((executor: (resolve: (value?: any) => void, reject: (reason?: any)) => void) => void, timeout: number, onTimeout?: () => any) => Promise<any>\n```\n\nThe _timeout_ method creates a promise that is bound to a timeout.\n\nIf the promise fails to respond in time, it will throw an error. If _timeout.withNull_ is used, it will resolve with null instead of throwing.\n\nDue to how promises work, the original promise will still execute, but if the operation offers a abort function, it can be triggered with the _onTimeout_ callback.\n\n```javascript\n// Example\nconst p = ph.timeout(\n\t(resolve, reject) => {\n\t\treq = https.get(\"https://www.google.de\", res => resolve(res));\n\t\treq.on(\"error\", err => reject(err));\n\t\treq.on(\"abort\", () => reject());\n\t},\n\t20,\n\t() => req.abort()\n);\np.then(res => console.log(res)).catch(err => console.log(err));\n```\n\n### cancelable\n\n```javascript\n// Invocation\nconst p = ph.cancelable((executor: (resolve: (value?: any) => void, reject: (reason?: any)) => void) => void) => Promise<any>\n\n// cancel (throws canceled)\np.cancel(onCancel?: () => void)\n\n// cancelWithNull resolves with null\np.cancelWithNull(onCancel?: () => void)\n```\n\nThe _cancelable_ method creates a promise that could be canceled at will.\n\nIf canceled, it will throw an error. If _cancelable.cancelWithNull_ is used, it will resolve with null instead of throwing.\n\nDue to how promises work, the original promise will still execute, but if the operation offers a abort function, it can be triggered with the _onCancel_ callback.\n\n```javascript\n// Example\nlet req;\n\nconst p = ph.cancelable((resolve, reject) => {\n\treq = https.get(\"https://www.google.de\", res => resolve(res));\n\treq.on(\"error\", err => reject(err));\n\treq.on(\"abort\", () => reject());\n});\np.then(res => console.log(res)).catch(err => console.log(err));\n\nsetTimeout(() => p.cancel(() => req.abort()), 20);\n```\n\n## Greetings\n\nMay you enjoy using this piece of software as much as I enjoyed writing it. Stay bug free and have an awesome day <3\n","readmeFilename":"README.md"}