Given a collection and a task, return resolved values of the task being ran per value via emitted events.
\nArrayGiven a collection of functions, promises, or basic types 'run' them all at a specified limit
\nBooleanGiven a collection and a task return true if any promise resolves
\nUtility for making optional callbacks easier. If an error param exists, it will throw an error for promises\nor return the error to a callback.
\nPromiseRun the passed function, if it takes longer than the configured time throw an error, otherwise\nreturn the results of the original function execution.
\nOn timeout, this does NOT abort the execution of the function!
\nGiven a collection, run the given asynchronous task in parallel for each value of the collection.
\nBooleanGiven a collection and a task return true if all promises resolve.\nWill bail on first error
\nArrayGiven a collection run a map over it
\nObjectGiven an object of key-value pairs, run the given asynchronous task in parallel for each pair.
\nArrayGiven a function that expects a callback as its last argument, await a promisified version of that function\nand return the arguments sent to the callback as an array.
\n*Given a function that expects a callback as its last argument, await a promisified version of that function\nand return the result.
\n*Retry promise a given number of times at an interval.
\nPromisePromise based wait utility.
\n*Given a condition and function, continuously call the promisified version of that function sequentially\nand return the result once the exiting condition is met.
\nThe condition can access either the parent scoped variables or the results of fn which are passed in\nas the only parameter.
*Given a condition, maximum amount of loop iterations to do, and function, continuously call the promisified\nversion of that function sequentially and return the result once the exiting condition is met or the loop\ncount has been exhausted.
\nThe condition can access either the parent scoped variables or the results of fn which are passed in\nas the only parameter.
Array \\| Object | collection of data to be iterated over |\n| task | function | The async function to be run on each value in the collection. |\n| options | Object | Optional overrides. |\n| options.limit | Number | Optional limit to # of tasks to run in parallel. |\n\n**Example** \n```js\nconst the = require('await-the');\nconst functions = [\n async () => {\n await the.wait(1000);\n return 'waiter';\n },\n () => {\n return 'check please';\n }\n];\nconst limiter = new the.Limiter(functions, { limit: 1 });\n\nlimiter.on('iteration', ({ key, resultValue }) => {\n // resultValue - value of function ran\n // key - key of collection the function was run for\n});\n\nlimiter.on('done', () => {\n return done();\n});\n\nlimiter.on('error', ({error}) => {\n // error - error when running functions\n});\n\n// begin iteration\nlimiter.start();\n```\n\n\n## all ⇒ Array\nGiven a collection of functions, promises, or basic types 'run' them all at a specified limit\n\n**Returns**: Array - array of the resolved promises \n\n| Param | Type | Description |\n| --- | --- | --- |\n| collection | Array \\| Object | Array or object of items to run the asynchronous task with. |\n| options | Object | Optional overrides. |\n| options.limit | Number | Optional limit to # of tasks to run in parallel. |\n\n**Example** \n```js\nconst the = require('await-the');\nawait the.all(\n [\n new Promise(resolve => resolve('hello')),\n 'world',\n () => 'how are you?'\n ],\n { limit: 2 }\n );\n```\n\n\n## any ⇒ Boolean\nGiven a collection and a task return true if any promise resolves\n\n**Returns**: Boolean - true if a promise resolves otherwise throws an error \n\n| Param | Type | Description |\n| --- | --- | --- |\n| collection | Array \\| Object | Array or object of items to run the asynchronous task over. |\n| task | function | The async function to be run on each value in the collection. |\n\n**Example** \n```js\nconst the = require('await-the')\nconst collection = ['item1', 'item2', 'item3'];\nconst task = async (value, index) => {\n if (index === 1) {\n return await new Promise(resolve => resolve());\n } else {\n throw new Error('test error');\n }\n};\nconst result = await the.any(collection, task);\n// result is true\n```\n\n\n## callback\nUtility for making optional callbacks easier. If an error param exists, it will throw an error for promises\nor return the error to a callback.\n\n\n| Param | Type | Description |\n| --- | --- | --- |\n| callback | function | If present will invoke the callback with the err and result; otherwise, return or throw. |\n| err | Object \\| String \\| Number \\| Boolean | Error to throw or return to the caller. |\n| result | \\* | The thrown error or the result to return to the calling function. |\n\n**Example** \n```js\nconst the = require('await-the');\nconst myFunc = async (args, callback) => {\n try {\n const result = await somePromise();\n return the.callback(callback, null, result);\n } catch (e) {\n return the.callback(callback, e);\n }\n};\n\n// call as a promise\nawait myFunc(args);\n// or as a callback\nmyFunc(args, (err, result) => {});\n```\n\n\n## deadline ⇒ Promise\nRun the passed function, if it takes longer than the configured time throw an error, otherwise\nreturn the results of the original function execution.\n\nOn timeout, this does NOT abort the execution of the function!\n\n**Returns**: Promise - A promise \n\n| Param | Type | Description |\n| --- | --- | --- |\n| task | function | The async function to be run. |\n| time | Number | The time in milliseconds this function should be allowed to run. |\n| error | String | Optionally, a custom error message to use. |\n\n**Example** \n```js\nconst the = require('await-the');\nawait the.deadline(someAsyncFunction, 5000);\n// will call `someAsyncFunction` and let it execute for 5000 ms, rejecting if it exceeds that time.\n```\n\n\n## each\nGiven a collection, run the given asynchronous task in parallel for each value of the collection.\n\n\n| Param | Type | Description |\n| --- | --- | --- |\n| collection | Array \\| Object | Array or object of items to run the asynchronous task with. |\n| task | function | The async function to be run on each value in the collection. |\n| options | Object | Optional overrides. |\n| options.limit | Number | Optional limit to # of tasks to run in parallel. |\n\n**Example** \n```js\nconst the = require('await-the');\nawait the.each([1,2,3], someAsyncFunction, { limit: 2 });\n// will call `someAsyncFunction` on each value of the collection, with at most two functions\n// running in parallel at a time.\n```\n\n\n## every ⇒ Boolean\nGiven a collection and a task return true if all promises resolve.\nWill bail on first error\n\n**Returns**: Boolean - true if all promises resolve, otherwise throws the error from the first rejected promise it encounters \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| collection | Array \\| Object | | Array or object of items to run the asynchronous task over. |\n| task | function | | Promise to be awaited for each key, called with (value, key). |\n| options | Object | | Optional overrides. |\n| options.limit | Number | Infinity | Number of concurrently pending promises returned by mapper. |\n\n**Example** \n```js\nconst the = require('await-the')\nconst collection = ['item1', 'item2', 'item3'];\nconst task = async (value, index) => {\n return await new Promise(resolve => resolve());\n};\nconst result = await the.every(collection, task);\n// result is true\n```\n\n\n## map ⇒ Array\nGiven a collection run a map over it\n\n**Returns**: Array - An array containing the results for each index \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| collection | Array | | to iterate over |\n| task | Promise | | Promise to be await for each key, called with (value, key). |\n| options | Object | | Optional overrides. |\n| options.limit | Number | Infinity | Number of concurrently pending promises returned by mapper. |\n\n**Example** \n```js\nconst the = require('await-the');\nconst result = await the.map(['item1'], async (value, key) => {\n return somePromise(value);\n});\n// result is now an object with [Object\nGiven an object of key-value pairs, run the given asynchronous task in parallel for each pair.\n\n**Returns**: Object - An object containing the results for each key. \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| collection | Object | | Key-value pair to be iterated over. |\n| task | Promise | | Promise to be await for each key, called with (value, key). |\n| options | Object | | Optional overrides. |\n| options.limit | Number | Infinity | Number of concurrently pending promises returned by mapper. |\n\n**Example** \n```js\nconst the = require('await-the');\nconst result = await the.mapValues({key1: 'value1'}, async (value, key) => {\n return somePromise(value);\n});\n// result is now an object with {key1: Array\nGiven a function that expects a callback as its last argument, await a promisified version of that function\nand return the arguments sent to the callback as an array.\n\n**Returns**: Array - The arguments sent to the callback, including the error. \n\n| Param | Type | Description |\n| --- | --- | --- |\n| fn | function \\| Array | The async function to promisify and call, or an array of [class, method name]. |\n| ...args | \\* | Variadic arguments to send to the function, _excluding_ the callback. Note that _all_ parameters of the function besides the callback must have values supplied, even if they're optional. |\n\n**Example** \n```js\nconst the = require('await-the');\nconst asyncSum = (x, y, callback) => callback(null, x + y, x * y);\nconst [err, sum, product] = await the.multiResult(asyncSum, 1, 2);\n// will assign null to `err`, 3 to `sum` and 2 to `product`.\n\nawait the.multiResult([someObj, 'someFnName'], 1, 2);\n// equivalent of `await the.multiResult(someObj.someFnName.bind(someObj), 1, 2)`\n\nconst someFnWithOptionalArgs = (x, y = 1, opts = {}, callback) => callback(null, x + y);\nawait the.multiResult(someFnWithOptionalArgs, 2, 1, {});\n// if the function has optional params before the callback, values must be supplied for all\n```\n\n\n## result ⇒ \\*\nGiven a function that expects a callback as its last argument, await a promisified version of that function\nand return the result.\n\n**Returns**: \\* - The thrown error or the result. \n\n| Param | Type | Description |\n| --- | --- | --- |\n| fn | function \\| Array | The async function to promisify and call, or an array of [class, method name]. |\n| ...args | \\* | Variadic arguments to send to the function, _excluding_ the callback. Note that _all_ parameters of the function besides the callback must have values supplied, even if they're optional. |\n\n**Example** \n```js\nconst the = require('await-the');\nconst asyncSum = (x, y, callback) => callback(null, x + y);\nconst sum = await the.result(asyncSum, 1, 2);\n// will assign 3 to `sum`\n\nawait the.result([someObj, 'someFnName'], 1, 2);\n// equivalent of `await the.result(someObj.someFnName.bind(someObj), 1, 2)`\n\nconst someFnWithOptionalArgs = (x, y = 1, opts = {}, callback) => callback(null, x + y);\nawait the.result(someFnWithOptionalArgs, 2, 1, {});\n// if the function has optional params before the callback, values must be supplied for all\n```\n\n\n## retry ⇒ \\*\nRetry promise a given number of times at an interval.\n\n**Returns**: \\* - The last thrown error or the result. \n\n| Param | Type | Description |\n| --- | --- | --- |\n| promise | Promise | The promise to be resolved (or rejected) on the retry cadence. |\n| options | Object | Optional overrides. |\n| options.maxTries | Number | Maximum number of times to retry to promise. |\n| options.interval | Number \\| function | Time to wait in ms between promise executions. |\n| options.errorFilter | Any \\| function \\| Promise | if supplied only retry if Any === error.message or function returns true |\n\n**Example** \n```js\nconst the = require('await-the');\nawait the.retry(myPromise, { maxTries: 10, interval: 100 });\nawait the.retry(myPromise, { maxTries: 10, interval: numTriesSoFar => (numTriesSoFar * 100) });\nawait the.retry(myPromise, { maxTries: 10, interval: errorFilter: 'My Expected Error' });\nawait the.retry(myPromise, { maxTries: 10, interval: errorFilter: err => err.message === 'My Expected Error' });\n```\n\n\n## wait ⇒ Promise\nPromise based wait utility.\n\n\n| Param | Type | Description |\n| --- | --- | --- |\n| time | Number | Time in ms to wait before returning a resolved promise. |\n\n**Example** \n```js\nconst the = require('await-the');\n// wait for 1 second before returning\nawait the.wait(1000);\n```\n\n\n## while ⇒ \\*\nGiven a condition and function, continuously call the promisified version of that function sequentially\nand return the result once the exiting condition is met.\n\nThe `condition` can access either the parent scoped variables or the results of `fn` which are passed in\nas the only parameter.\n\n**Returns**: \\* - The thrown error or the result. \n\n| Param | Type | Description |\n| --- | --- | --- |\n| condition | function | The condition to continue looping. |\n| fn | function \\| Array | The function to be resolved (or rejected) every loop. |\n| ...args | \\* | Variadic arguments to send to the function. |\n\n**Example** \n```js\nconst the = require('await-the');\nlet sum = 0;\nconst condition = previousResult => sum < 10;\nconst asyncFn = x => {\n sum += x;\n return sum * 10;\n}\nconst result = await the.while(condition, asyncFn, 2);\n// will loop while sum < 10, then return the final function result\n// sum === 10\n// result === 100\n```\n\n\n## whileMax ⇒ \\*\nGiven a condition, maximum amount of loop iterations to do, and function, continuously call the promisified\nversion of that function sequentially and return the result once the exiting condition is met or the loop\ncount has been exhausted.\n\nThe `condition` can access either the parent scoped variables or the results of `fn` which are passed in\nas the only parameter.\n\n**Returns**: \\* - The thrown error or the result. \n\n| Param | Type | Description |\n| --- | --- | --- |\n| condition | function | The condition to continue looping. |\n| maxIterations | Number | The maximum amount of loop iterations to be done. |\n| fn | function \\| Array | The function to be resolved (or rejected) every loop. |\n| ...args | \\* | Variadic arguments to send to the function. |\n\n**Example** \n```js\nconst the = require('await-the');\nlet sum = 0;\nconst max = 2;\nconst condition = previousResult => sum < 10;\nconst asyncFn = x => {\n sum += x;\n return sum * 10;\n}\nconst result = await the.whileMax(condition, max, asyncFn, 2);\n// is cut off by hitting the max loops possible\n// sum === 4\n// result === 40\n```\n\n## NPM Options\n\nThe different package NPM options.\n\n### Test\n\nRuns the linter and all Mocha tests in the `test` directory.\n\n```bash\nnpm test\n```\n\n### Lint\n\nAnalyse code for potential errors and styling issues.\n\n```bash\nnpm run lint\n```\n\n### Format\n\nFix issues found during linting.\n\n```bash\nnpm run format\n```\n\n### Build documentation\n\nUpdates this README with the [API Reference](#api-reference).\n\n```bash\nnpm run docs\n```","readmeFilename":"README.md","homepage":"https://github.com/mediafly/await-the#readme","repository":{"type":"git","url":"git+https://github.com/mediafly/await-the.git"},"bugs":{"url":"https://github.com/mediafly/await-the/issues"}}