From 590409d5d8a28aadd3cd90c29dd397ade987dc21 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 03:03:34 +0000 Subject: [PATCH 1/9] Initial plan From 10e262ba70b5d5a83a9164b5930316209fc5e408 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 03:11:48 +0000 Subject: [PATCH 2/9] fix: add explicit TypeScript libs for ES built-in types Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/1f8223a6-705f-4fbc-82d0-c90d803bf965 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- README.md | 5 +++++ lib/test/tsconfig.test.json | 6 +++++- lib/test/tsconfig.test.karma.json | 6 +++++- lib/test/tsconfig.worker.karma.json | 6 +++++- lib/tsconfig.base.json | 6 +++++- 5 files changed, 25 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 635d022..09f69b4 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,11 @@ Install the npm packare: `npm install @nevware21/ts-async --save` > "@nevware21/ts-async": ">= 0.5.5 < 2.x" > ``` +This package still targets ES5 at runtime, but its public TypeScript types use later built-in definitions such as `Promise`, `Iterable`, `AsyncIterable`, and `AggregateError`. If your project currently compiles with only ES5 libs, update your `tsconfig.json` to include a later ES lib, for example: + +- Browser / mixed environments: `"lib": ["ES2021", "DOM"]` +- Node-only environments: `"lib": ["ES2021"]` + And then just import the helpers and use them. ### Simple Examples diff --git a/lib/test/tsconfig.test.json b/lib/test/tsconfig.test.json index aacba0d..cee34ca 100644 --- a/lib/test/tsconfig.test.json +++ b/lib/test/tsconfig.test.json @@ -1,5 +1,9 @@ { "compilerOptions": { + "lib": [ + "es2021", + "dom" + ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -21,4 +25,4 @@ "exclude": [ "node_modules/" ] -} \ No newline at end of file +} diff --git a/lib/test/tsconfig.test.karma.json b/lib/test/tsconfig.test.karma.json index aacba0d..cee34ca 100644 --- a/lib/test/tsconfig.test.karma.json +++ b/lib/test/tsconfig.test.karma.json @@ -1,5 +1,9 @@ { "compilerOptions": { + "lib": [ + "es2021", + "dom" + ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -21,4 +25,4 @@ "exclude": [ "node_modules/" ] -} \ No newline at end of file +} diff --git a/lib/test/tsconfig.worker.karma.json b/lib/test/tsconfig.worker.karma.json index d5f56d3..c8d34a8 100644 --- a/lib/test/tsconfig.worker.karma.json +++ b/lib/test/tsconfig.worker.karma.json @@ -1,5 +1,9 @@ { "compilerOptions": { + "lib": [ + "es2021", + "dom" + ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -22,4 +26,4 @@ "exclude": [ "node_modules/" ] -} \ No newline at end of file +} diff --git a/lib/tsconfig.base.json b/lib/tsconfig.base.json index 2c9a7c4..1ba4889 100644 --- a/lib/tsconfig.base.json +++ b/lib/tsconfig.base.json @@ -1,5 +1,9 @@ { "compilerOptions": { + "lib": [ + "es2021", + "dom" + ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -21,4 +25,4 @@ "exclude": [ "node_modules/" ] -} \ No newline at end of file +} From 29681906dad82cc36e3037954a2e3b7dfcc18510 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 03:33:33 +0000 Subject: [PATCH 3/9] fix: move ES lib update to package tsconfig Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/f6321dc0-0a3d-49a0-941c-47f6a22f2a53 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- CHANGELIST.md | 1 + lib/test/tsconfig.test.json | 6 +----- lib/test/tsconfig.test.karma.json | 6 +----- lib/test/tsconfig.worker.karma.json | 6 +----- lib/tsconfig.base.json | 6 +----- lib/tsconfig.json | 6 +++++- 6 files changed, 10 insertions(+), 21 deletions(-) diff --git a/CHANGELIST.md b/CHANGELIST.md index 11e658c..f581905 100644 --- a/CHANGELIST.md +++ b/CHANGELIST.md @@ -4,6 +4,7 @@ - [#488](https://github.com/nevware21/ts-async/issues/488) [CHORE] Drop Node.js 16 from CI matrix and add Node.js 24 - Node.js 16 is end-of-life and is no longer supported by key tooling dependencies (for example `puppeteer` and `@pnpm/error` require Node.js >= 18) +- [#500](https://github.com/nevware21/ts-async/pull/500) [BUG] Add explicit ES2021 libs to the package tsconfig and document the required consumer TypeScript lib setting # v0.5.5 Jan 5th, 2026 diff --git a/lib/test/tsconfig.test.json b/lib/test/tsconfig.test.json index cee34ca..aacba0d 100644 --- a/lib/test/tsconfig.test.json +++ b/lib/test/tsconfig.test.json @@ -1,9 +1,5 @@ { "compilerOptions": { - "lib": [ - "es2021", - "dom" - ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -25,4 +21,4 @@ "exclude": [ "node_modules/" ] -} +} \ No newline at end of file diff --git a/lib/test/tsconfig.test.karma.json b/lib/test/tsconfig.test.karma.json index cee34ca..aacba0d 100644 --- a/lib/test/tsconfig.test.karma.json +++ b/lib/test/tsconfig.test.karma.json @@ -1,9 +1,5 @@ { "compilerOptions": { - "lib": [ - "es2021", - "dom" - ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -25,4 +21,4 @@ "exclude": [ "node_modules/" ] -} +} \ No newline at end of file diff --git a/lib/test/tsconfig.worker.karma.json b/lib/test/tsconfig.worker.karma.json index c8d34a8..d5f56d3 100644 --- a/lib/test/tsconfig.worker.karma.json +++ b/lib/test/tsconfig.worker.karma.json @@ -1,9 +1,5 @@ { "compilerOptions": { - "lib": [ - "es2021", - "dom" - ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -26,4 +22,4 @@ "exclude": [ "node_modules/" ] -} +} \ No newline at end of file diff --git a/lib/tsconfig.base.json b/lib/tsconfig.base.json index 1ba4889..2c9a7c4 100644 --- a/lib/tsconfig.base.json +++ b/lib/tsconfig.base.json @@ -1,9 +1,5 @@ { "compilerOptions": { - "lib": [ - "es2021", - "dom" - ], "sourceMap": true, "inlineSources": true, "noImplicitAny": true, @@ -25,4 +21,4 @@ "exclude": [ "node_modules/" ] -} +} \ No newline at end of file diff --git a/lib/tsconfig.json b/lib/tsconfig.json index 6b9580d..0665713 100644 --- a/lib/tsconfig.json +++ b/lib/tsconfig.json @@ -1,10 +1,14 @@ { "extends": "./tsconfig.base.json", "compilerOptions": { + "lib": [ + "es2021", + "dom" + ], "target": "es5", "declaration": true, "declarationDir": "./build/types", "removeComments": false, "outDir": "./build/es5" } -} \ No newline at end of file +} From 55b17e6f9c065fc4068371ee3aceba6d84aa0c2d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 03:34:08 +0000 Subject: [PATCH 4/9] docs: correct changelog issue reference Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/f6321dc0-0a3d-49a0-941c-47f6a22f2a53 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- CHANGELIST.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELIST.md b/CHANGELIST.md index f581905..18cc0ad 100644 --- a/CHANGELIST.md +++ b/CHANGELIST.md @@ -4,7 +4,7 @@ - [#488](https://github.com/nevware21/ts-async/issues/488) [CHORE] Drop Node.js 16 from CI matrix and add Node.js 24 - Node.js 16 is end-of-life and is no longer supported by key tooling dependencies (for example `puppeteer` and `@pnpm/error` require Node.js >= 18) -- [#500](https://github.com/nevware21/ts-async/pull/500) [BUG] Add explicit ES2021 libs to the package tsconfig and document the required consumer TypeScript lib setting +- [#499](https://github.com/nevware21/ts-async/issues/499) [BUG] Add explicit ES2021 libs to the package tsconfig and document the required consumer TypeScript lib setting # v0.5.5 Jan 5th, 2026 From a22ca42a61fff78a1582590ade327596b9b9fa4a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 03:55:37 +0000 Subject: [PATCH 5/9] fix: narrow ES lib requirements for typings Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/aa1009c1-0568-4f76-b2a9-d8befbd8c165 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- CHANGELIST.md | 2 +- README.md | 6 +++--- lib/tsconfig.json | 7 +++++-- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CHANGELIST.md b/CHANGELIST.md index 18cc0ad..47a80f5 100644 --- a/CHANGELIST.md +++ b/CHANGELIST.md @@ -4,7 +4,7 @@ - [#488](https://github.com/nevware21/ts-async/issues/488) [CHORE] Drop Node.js 16 from CI matrix and add Node.js 24 - Node.js 16 is end-of-life and is no longer supported by key tooling dependencies (for example `puppeteer` and `@pnpm/error` require Node.js >= 18) -- [#499](https://github.com/nevware21/ts-async/issues/499) [BUG] Add explicit ES2021 libs to the package tsconfig and document the required consumer TypeScript lib setting +- [#499](https://github.com/nevware21/ts-async/issues/499) [BUG] Add the required ES Promise / Iterable / AsyncIterable libs to the package tsconfig and document the consumer ES2018 lib requirement # v0.5.5 Jan 5th, 2026 diff --git a/README.md b/README.md index 09f69b4..3b3a773 100644 --- a/README.md +++ b/README.md @@ -101,10 +101,10 @@ Install the npm packare: `npm install @nevware21/ts-async --save` > "@nevware21/ts-async": ">= 0.5.5 < 2.x" > ``` -This package still targets ES5 at runtime, but its public TypeScript types use later built-in definitions such as `Promise`, `Iterable`, `AsyncIterable`, and `AggregateError`. If your project currently compiles with only ES5 libs, update your `tsconfig.json` to include a later ES lib, for example: +This package still targets ES5 at runtime, but its public TypeScript types use later built-in definitions such as `Promise`, `Iterable`, and `AsyncIterable`. If your project currently compiles with only ES5 libs, update your `tsconfig.json` to include a later ES lib, for example: -- Browser / mixed environments: `"lib": ["ES2021", "DOM"]` -- Node-only environments: `"lib": ["ES2021"]` +- Browser / mixed environments: `"lib": ["ES2018", "DOM"]` +- Node-only environments: `"lib": ["ES2018"]` And then just import the helpers and use them. diff --git a/lib/tsconfig.json b/lib/tsconfig.json index 0665713..10f5e20 100644 --- a/lib/tsconfig.json +++ b/lib/tsconfig.json @@ -2,8 +2,11 @@ "extends": "./tsconfig.base.json", "compilerOptions": { "lib": [ - "es2021", - "dom" + "es5", + "dom", + "es2015.promise", + "es2015.iterable", + "es2018.asynciterable" ], "target": "es5", "declaration": true, From 50e56f12448dff0ebdbe18f594fdcd9af92f426d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 04:04:15 +0000 Subject: [PATCH 6/9] fix: drop redundant es5 lib entry Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/3a8e6886-d1c0-44a5-926f-c707599b2b50 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- lib/tsconfig.json | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/tsconfig.json b/lib/tsconfig.json index 10f5e20..b8f9fe8 100644 --- a/lib/tsconfig.json +++ b/lib/tsconfig.json @@ -2,7 +2,6 @@ "extends": "./tsconfig.base.json", "compilerOptions": { "lib": [ - "es5", "dom", "es2015.promise", "es2015.iterable", From ca9c8e1d175b62dfbcc1cf7a3a29ae76aa015376 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 05:41:13 +0000 Subject: [PATCH 7/9] fix: add async iterable lib to es6 build Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/f4563d82-e957-45c0-ab04-4f4f5c04f7f7 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- lib/tsconfig.es6.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/lib/tsconfig.es6.json b/lib/tsconfig.es6.json index e079dfa..9976723 100644 --- a/lib/tsconfig.es6.json +++ b/lib/tsconfig.es6.json @@ -1,7 +1,12 @@ { "extends": "./tsconfig.base.json", "compilerOptions": { + "lib": [ + "dom", + "es6", + "es2018.asynciterable" + ], "target": "es6", "outDir": "./build/es6" } -} \ No newline at end of file +} From 409d063c13779e1fa11a4ece76247311a9c8fe21 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 15 May 2026 05:37:26 +0000 Subject: [PATCH 8/9] fix: track generated api declaration rollup Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/d55ff4a3-5754-4f2f-b93a-78dd005bd763 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- .gitignore | 5 + lib/dist/types/ts-async.d.ts | 2049 ++++++++++++++++++++++++++++++++++ 2 files changed, 2054 insertions(+) create mode 100644 lib/dist/types/ts-async.d.ts diff --git a/.gitignore b/.gitignore index 2981d33..9b39a90 100644 --- a/.gitignore +++ b/.gitignore @@ -67,6 +67,11 @@ test-esm/ types/ build/ dist/ +!lib/dist/ +lib/dist/** +!lib/dist/types/ +lib/dist/types/** +!lib/dist/types/ts-async.d.ts dist-es**/ docs/typedoc/** diff --git a/lib/dist/types/ts-async.d.ts b/lib/dist/types/ts-async.d.ts new file mode 100644 index 0000000..b3a7abd --- /dev/null +++ b/lib/dist/types/ts-async.d.ts @@ -0,0 +1,2049 @@ +/** + * Calls the provided `callbackFn` function once for each element in an array (or ArratLike) instance in ascending index order. It is not invoked + * for index properties that have been deleted or are uninitialized. And unlike the ES6 forEach() this supports async functions and you CAN stop + * or break the iteration by returning -1 from the `callbackFn` function. + * + * The range (number of elements) processed by arrForEach() is set before the first call to the `callbackFn`. Any elements added beyond the range + * or elements which as assigned to indexes already processed will not be visited by the `callbackFn`. + * + * The `callbackFn` may execute `synchronously` or `asynchronously` and if the `callbackFn` returns a `Promise` then the next iteration will not be + * called until the promise is resolved. If the `callbackFn` returns a `Promise` that is rejected then the iteration will stop and the promise + * returned by arrForEachAsync will be rejected with the same error. + * @since 0.5.0 + * @group Loop + * @group Array + * @group ArrayLike + * @typeParam T - Identifies the element type of the array + * @param theArray - The array or array like object of elements to be searched. + * @param callbackFn - A `asynchronous` or `synchronous` function that accepts up to three arguments. arrForEach calls the callbackfn function one + * time for each element in the array. + * @param thisArg - An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, null or undefined + * the array will be used as the this value. + * @remarks + * arrForEachAsync supports either a `synchronous` or `asynchronous` (returns a `Promise`) callback function. If the callback function returns + * a `Promise` then the next iteration will not be called until the promise is resolved. If the callback function returns a `Promise` that is + * rejected then the iteration will stop and the promise returned by arrForEachAsync will be rejected with the same error. + * @example + * ```ts + * const items = ['item1', 'item2', 'item3', 'item4', 'item5', 'item6', 'item7', 'item8', 'item9', 'item10']; + * const copyItems = []; + * + * arrForEachASync(items, (value, index) => { + * copyItems.push(value); + * if (index === 5) { + * return -1; // Stop the iteration + * } + * }); + * console.log(copyItems); // ['item1', 'item2', 'item3', 'item4', item5'] + * + * // Also supports input as an array like object + * const items = { length: 3, 0: 'item1', 1: 'item2', 2: 'item3' }; + * + * // Asynchronous examples using await + * const items = ['item1', 'item2', 'item3', 'item4', 'item5', 'item6', 'item7', 'item8', 'item9', 'item10']; + * const copyItems = []; + * + * await arrForEachASync(items, (value, index) => { // Note: DO NOT use async here unless you use await within the function + * if (index < 5) { + * // Logs each iteration index + * // Logs each value + * console.log(value); + * // Returning a promise will cause `arrForEachAsync` to return a promise to the caller + * // and wait for the promise to resolve before calling the callback function again. + * return createTimeoutPromise(10, true); + * } + * + * return -1; // Stop the iteration + * }); + * console.log(copyItems); // ['item1', 'item2', 'item3', 'item4', item5'] + * + * ``` + */ +export declare function arrForEachAsync(theArray: ArrayLike, callbackFn: (value: T, index: number, array: T[]) => void | number | IPromise, thisArg?: any): void | number | IPromise; + +/** + * A Simple type which identifies the result of a promise as a single response, it identifies + * if the promise was rejected or resolved along with the resolved value or rejected reason. + * It is a union of the `IPromiseFulfilledResult` and `IPromiseRejectedResult` interfaces the + * response will contain the `rejected` property which will be true if the promise was rejected + * or false if the promise was resolved. The `status` property will be set to either "fulfilled" + * or "rejected" to identify the status of the promise. The `value` or `reason` properties will + * contain the resolved value or rejected reason respectively. + * + * @group Promise + * @typeParam T - The type of the fulfilled value. + * + * @example + * ```ts + * const result: AwaitResponse = { + * status: "fulfilled", + * value: 42 + * }; + * + * const result: AwaitResponse = { + * rejected: true, + * status: "rejected", + * reason: "Hello Darkness" + * }; + * ``` + */ +export declare interface AwaitResponse { + /** + * A string indicating that the promise was rejected. + */ + status: "fulfilled" | "rejected"; + /** + * The value that the promise was fulfilled with. + */ + value?: T; + /** + * The reason that the promise was rejected with. + */ + reason?: R; + /** + * Identifies if the promise was rejected (true) or was resolved (false/undefined) + */ + rejected?: boolean; +} + +/** + * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional + * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. + * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, + * and will reject with this first rejection message / error. + * If the runtime doesn't support the Promise.all it will fallback back to an asynchronous Promise implementation. + * + * @function + * @group Alias + * @group Promise + * @group All + * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + * @returns + *
    + *
  • An already resolved `Promise`, if the input passed is empty. + *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ + * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the + * promises reject. + *
+ */ +export declare const createAllPromise: (input: Iterable>, timeout?: number) => IPromise; + +/** + * Returns a single Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations based on the current + * promise implementation. If the current implementation is synchronous then the chained operations will + * execute __synchronously__ in the same execution cycle as the final operation pending promises have resolved, + * or if the input contains no promises. If the current implementation is asynchronous then the chained + * operations will execute __asynchronously__ using the optional provided timeout value to schedule when the + * chained items will be executed or if the input contains no promises. + * It will resolve only after all of the input promises have either resolved or rejected, and will resolve with an array + * of {@link IPromiseResult } objects that each describe the outcome of each promise. + * @since 0.5.0 + * @group Alias + * @group Promise + * @group AllSettled + * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. + * + * @example + * ```ts + * const promises = [ + * createResolvedPromise(1), + * createResolvedPromise(2), + * createResolvedPromise(3), + * createRejectedPromise("error"), + * ]; + * + * const results = await createAllSettledPromise(promises); + * + * // results is: + * // [ + * // { status: "fulfilled", value: 1 }, + * // { status: "fulfilled", value: 2 }, + * // { status: "fulfilled", value: 3 }, + * // { status: "rejected", reason: "error" } + * // ] + * ``` + */ +export declare function createAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; + +/** + * The `createAnyPromise` method takes an iterable of promises as input and returns a single Promise. + * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. + * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an + * AggregateError containing an array of rejection reasons. + * @since 0.5.0 + * @group Alias + * @group Promise + * @group Any + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A new Promise that is: + * - Already rejected, if the iterable passed is empty. + * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value + * is the fulfillment value of the first promise that was fulfilled. + * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is + * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the + * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but + * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) + * rejected. + */ +export declare function createAnyPromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional + * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. + * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, + * and will reject with this first rejection message / error. + * When resolved or rejected any additional chained operations will execute __asynchronously__ using the optional + * timeout value to schedul when the chained item will be executed (eg. `then()`; `catch()`; `finally()`). + * + * @function + * @group Async + * @group Promise + * @group All + * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + * @returns + *
    + *
  • An already resolved `Promise`, if the input passed is empty. + *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ + * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the + * promises reject. + *
+ */ +export declare const createAsyncAllPromise: (input: Iterable>, timeout?: number) => IPromise; + +/** + * Returns a single Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations based on the + * {@link createAsyncPromise | Asynchronous} promise implementation. Any chained operations will execute + * __asynchronously__ when the final operation pending promises have resolved, or if the input contains + * no promises. It will resolve only after all of the input promises have either resolved or rejected, + * and will resolve with an array of {@link IPromiseResult } objects that each describe the outcome of + * each promise. + * @since 0.5.0 + * @group Async + * @group Promise + * @group AllSettled + * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. + * + * @example + * ```ts + * const promises = [ + * createResolvedPromise(1), + * createResolvedPromise(2), + * createResolvedPromise(3), + * createRejectedPromise("error"), + * ]; + * + * const results = await createAllSettledPromise(promises); + * + * // results is: + * // [ + * // { status: "fulfilled", value: 1 }, + * // { status: "fulfilled", value: 2 }, + * // { status: "fulfilled", value: 3 }, + * // { status: "rejected", reason: "error" } + * // ] + * ``` + */ +export declare function createAsyncAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; + +/** + * The `createAsyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. + * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. + * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an + * AggregateError containing an array of rejection reasons. + * @since 0.5.0 + * @group Async + * @group Promise + * @group Any + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A new Promise that is: + * - Already rejected, if the iterable passed is empty. + * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value + * is the fulfillment value of the first promise that was fulfilled. + * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is + * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the + * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but + * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) + * rejected. + */ +export declare function createAsyncAnyPromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Creates an asynchronous Promise instance that when resolved or rejected will execute it's pending chained operations + * __asynchronously__ using the optional provided timeout value to schedule when the chained items will be ececuted. + * @group Async + * @group Promise + * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will + * cause the promise to be rejected. The return value of the executor is always ignored + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare function createAsyncPromise(executor: PromiseExecutor, timeout?: number): IPromise; + +/** + * The `createAsyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise + * settles with the eventual state of the first promise that settles. + * @description The `createAsyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first + * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). + * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to + * the first of these values found in the iterable. + * @since 0.5.0 + * @group Async + * @group Promise + * @group Race + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the + * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever + * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise is still + * asynchronously settled. + */ +export declare function createAsyncRacePromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Returns a single asynchronous Promise instance that is already rejected with the given reason. + * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule + * when then chained items will be executed. (eg. `catch()`; `finally()`). + * + * @function + * @group Async + * @group Promise + * @group Rejected + * @param reason - The rejection reason + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createAsyncRejectedPromise: (reason: any, timeout?: number) => IPromise; + +/** + * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is + * a promise then that promise is returned instead of creating a new asynchronous promise instance. + * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional + * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). + * + * @function + * @group Async + * @group Promise + * @group Resolved + * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createAsyncResolvedPromise: (value: T, timeout?: number) => IPromise; + +/** + * Returns an idle Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations __asynchronously__ + * using the `requestIdleCallback` API (if available) with the optional provided timeout value to + * schedule when the chained items will be executed. + * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, + * and will reject with this first rejection message / error. + * When resolved or rejected any additional chained operations will execute __asynchronously__ using + * the `requestIdleCallback` API (if available) with the optional provided timeout value to schedule + * when the chained items will be executed. (eg. `then()`; `catch()`; `finally()`). + * + * @function + * @group Idle + * @group Promise + * @group All + * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional deadline timeout to wait before processing the items, defaults to undefined. If the number of + * milliseconds represented by this parameter has elapsed and the callback has not already been called, then a task to execute + * the callback is queued in the event loop (even if doing so risks causing a negative performance impact). timeout must be a + * positive value or it is ignored. + * @returns + *
    + *
  • An already resolved `Promise`, if the input passed is empty. + *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ + * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the + * promises reject. + *
+ */ +export declare const createIdleAllPromise: (input: Iterable>, timeout?: number) => IPromise; + +/** + * Returns a single Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations based on the + * {@link createIdlePromise | idle} promise implementation. Any chained operations will execute + * __asynchronously__ when the environment is idle as the final operation pending promises have resolved, + * or if the input contains no promises. It will resolve only after all of the input promises have either + * resolved or rejected, and will resolve with an array of {@link IPromiseResult } objects that each describe + * the outcome of each promise. + * @since 0.5.0 + * @group Idle + * @group Promise + * @group AllSettled + * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. + * + * @example + * ```ts + * const promises = [ + * createResolvedPromise(1), + * createResolvedPromise(2), + * createResolvedPromise(3), + * createRejectedPromise("error"), + * ]; + * + * const results = await createAllSettledPromise(promises); + * + * // results is: + * // [ + * // { status: "fulfilled", value: 1 }, + * // { status: "fulfilled", value: 2 }, + * // { status: "fulfilled", value: 3 }, + * // { status: "rejected", reason: "error" } + * // ] + * ``` + */ +export declare function createIdleAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; + +/** + * The `createIdleAnyPromise` method takes an iterable of promises as input and returns a single Promise. + * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. + * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an + * AggregateError containing an array of rejection reasons. + * @since 0.5.0 + * @group Idle + * @group Promise + * @group Any + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A new Promise that is: + * - Already rejected, if the iterable passed is empty. + * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value + * is the fulfillment value of the first promise that was fulfilled. + * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is + * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the + * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but + * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) + * rejected. + */ +export declare function createIdleAnyPromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Creates an idle Promise instance that when resolved or rejected will execute it's pending chained operations + * __asynchronously__ using the `requestIdleCallback` API (if available) with the optional provided timeout value to + * schedule when the chained items will be executed. When `requestIdleCallback` is not available this becomes the same as + * `createAsyncPromise` which uses `setTimeout` to schedule executions. + * @group Idle + * @group Promise + * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will + * cause the promise to be rejected. The return value of the executor is always ignored + * @param timeout - Optional deadline timeout to wait before processing the items, defaults to undefined. If the number of + * milliseconds represented by this parameter has elapsed and the callback has not already been called, then a task to execute + * the callback is queued in the event loop (even if doing so risks causing a negative performance impact). timeout must be a + * positive value or it is ignored. + */ +export declare function createIdlePromise(executor: PromiseExecutor, timeout?: number): IPromise; + +/** + * The `createIdleRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise + * settles with the eventual state of the first promise that settles. + * @description The `createIdleRacePromise` method is one of the promise concurrency methods. It's useful when you want the first + * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). + * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to + * the first of these values found in the iterable. + * @since 0.5.0 + * @group Idle + * @group Promise + * @group Race + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the + * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever + * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle + * asynchronously when the system detects that the runtime is idle. + */ +export declare function createIdleRacePromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Returns an idle Promise instance that is already rejected with the given reason. + * Any chained operations will execute __asynchronously__ using the o`requestIdleCallback` API + * (if available) with the optional provided timeout value to schedule when the chained items will + * be executed. (eg. `catch()`; `finally()`). + * + * @function + * @group Idle + * @group Promise + * @group Rejected + * @param reason - The rejection reason + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createIdleRejectedPromise: (reason: any, timeout?: number) => IPromise; + +/** + * Returns an idle Promise instance that is already resolved with the given value. If the value passed is + * a promise then that promise is returned instead of creating a new asynchronous promise instance. + * If a new instance is returned then any chained operations will execute __asynchronously__ using the + * `requestIdleCallback` API (if available) with the optional provided timeout value to schedule when + * the chained items will be executed. (eg. `then()`; `finally()`). + * + * @function + * @group Idle + * @group Promise + * @group Resolved + * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createIdleResolvedPromise: (value: T, timeout?: number) => IPromise; + +/** + * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional + * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. + * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, + * and will reject with this first rejection message / error. + * If the runtime doesn't support the Promise.all it will fallback back to an asynchronous Promise implementation. + * @group Alias + * @group Promise + * @group All + * @group Native + * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + * @returns + *
    + *
  • An already resolved `Promise`, if the input passed is empty. + *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ + * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the + * promises reject. + *
+ */ +export declare function createNativeAllPromise(input: Iterable>, timeout?: number): IPromise; + +/** + * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations using {@link createNativePromise | native} + * environment promise implementation, if the runtime does not provide any native then the optional provided + * timeout value will be used to schedule when the chained items will be executed or if the input contains no promises. + * It will resolve only after all of the input promises have either resolved or rejected, and will resolve with an array + * of {@link IPromiseResult } objects that each describe the outcome of each promise. + * @since 0.5.0 + * @group Alias + * @group Promise + * @group AllSettled + * @group Native + * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. + * + * @example + * ```ts + * const promises = [ + * createNativeResolvedPromise(1), + * createNativeResolvedPromise(2), + * createNativeResolvedPromise(3), + * createNativeRejectedPromise("error"), + * ]; + * + * const results = await createNativeAllSettledPromise(promises); + * + * // results is: + * // [ + * // { status: "fulfilled", value: 1 }, + * // { status: "fulfilled", value: 2 }, + * // { status: "fulfilled", value: 3 }, + * // { status: "rejected", reason: "error" } + * // ] + * ``` + */ +export declare function createNativeAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; + +/** + * The `createNativeAnyPromise` method takes an iterable of promises as input and returns a single Promise. + * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. + * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an + * AggregateError containing an array of rejection reasons. + * @since 0.5.0 + * @group Alias + * @group Promise + * @group Any + * @group Native + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A new Promise that is: + * - Already rejected, if the iterable passed is empty. + * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value + * is the fulfillment value of the first promise that was fulfilled. + * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is + * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the + * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but + * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) + * rejected. + */ +export declare function createNativeAnyPromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Creates a Promise instance that when resolved or rejected will execute it's pending chained operations using the + * available native Promise implementation. + * If runtime does not support native `Promise` class (or no polyfill is available) this function will fallback to using + * `createAsyncPromise` which will resolve them __asynchronously__ using the optional provided timeout value to + * schedule when the chained items will be executed. + * @group Alias + * @group Promise + * @group Native + * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will + * cause the promise to be rejected. The return value of the executor is always ignored + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare function createNativePromise(executor: PromiseExecutor, timeout?: number): IPromise; + +/** + * The `createNativeRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise + * settles with the eventual state of the first promise that settles. + * @description The `createNativeRacePromise` method is one of the promise concurrency methods. It's useful when you want the first + * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). + * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to + * the first of these values found in the iterable. + * @since 0.5.0 + * @group Alias + * @group Promise + * @group Race + * @group Native + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the + * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever + * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle + * asynchronously. + */ +export declare function createNativeRacePromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Returns a single asynchronous Promise instance that is already rejected with the given reason. + * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule + * when then chained items will be executed. (eg. `catch()`; `finally()`). + * + * @function + * @group Alias + * @group Promise + * @group Rejected + * @group Native + * @param reason - The rejection reason + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createNativeRejectedPromise: (reason: any, timeout?: number) => Promise; + +/** + * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is + * a promise then that promise is returned instead of creating a new asynchronous promise instance. + * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional + * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). + * + * @function + * @group Alias + * @group Promise + * @group Resolved + * @group Native + * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createNativeResolvedPromise: (value: T, timeout?: number) => Promise; + +/** + * Creates a Promise instance using the current default promise creator that when resolved or rejected will execute + * it's pending chained operations. + * @group Alias + * @group Promise + * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will + * cause the promise to be rejected. The return value of the executor is always ignored + * @param timeout - [Optional] timeout to wait before processing the items, defaults to zero. + */ +export declare function createPromise(executor: PromiseExecutor, timeout?: number): IPromise; + +/** + * The `createRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise + * settles with the eventual state of the first promise that settles. + * @description The `createRacePromise` method is one of the promise concurrency methods. It's useful when you want the first + * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). + * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to + * the first of these values found in the iterable. + * @since 0.5.0 + * @group Alias + * @group Promise + * @group Race + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the + * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever + * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle + * based on the current promise implementation. + */ +export declare function createRacePromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Returns a single asynchronous Promise instance that is already rejected with the given reason. + * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule + * when then chained items will be executed. (eg. `catch()`; `finally()`). + * + * @function + * @group Alias + * @group Promise + * @group Rejected + * @param reason - The rejection reason + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createRejectedPromise: (reason: any, timeout?: number) => IPromise; + +/** + * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is + * a promise then that promise is returned instead of creating a new asynchronous promise instance. + * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional + * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). + * + * @function + * @group Alias + * @group Promise + * @group Resolved + * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + */ +export declare const createResolvedPromise: (value: T, timeout?: number) => IPromise; + +/** + * Returns a single synchronous Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations __synchronously__ in the same + * execution cycle as the final operation pending promises have resolved, or if the input contains no promises. + * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, + * and will reject with this first rejection message / error. + * When resolved or rejected any additional chained operations will execute __synchronously__ at the point of + * being added (eg. `then()`; `catch()`; `finally()`). + * + * @function + * @group Synchronous + * @group Promise + * @group All + * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @returns + *
    + *
  • An already resolved `Promise`, if the input passed is empty. + *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ + * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the + * promises reject. + *
+ */ +export declare const createSyncAllPromise: (input: Iterable>) => IPromise; + +/** + * Returns a single Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations based on the + * {@link createSyncPromise | synchronous} promise implementation. Any chained operations will execute + * __synchronously__ in the same execution cycle as the final operation pending promises have resolved, + * or if the input contains no promises. It will resolve only after all of the input promises have either + * resolved or rejected, and will resolve with an array of {@link IPromiseResult } objects that each describe + * the outcome of each promise. + * @since 0.5.0 + * @group Synchronous + * @group Promise + * @group AllSettled + * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. + * + * @example + * ```ts + * const promises = [ + * createResolvedPromise(1), + * createResolvedPromise(2), + * createResolvedPromise(3), + * createRejectedPromise("error"), + * ]; + * + * const results = await createAllSettledPromise(promises); + * + * // results is: + * // [ + * // { status: "fulfilled", value: 1 }, + * // { status: "fulfilled", value: 2 }, + * // { status: "fulfilled", value: 3 }, + * // { status: "rejected", reason: "error" } + * // ] + * ``` + */ +export declare function createSyncAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; + +/** + * The `createSyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. + * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. + * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an + * AggregateError containing an array of rejection reasons. + * @since 0.5.0 + * @group Synchronous + * @group Promise + * @group Any + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A new Promise that is: + * - Already rejected, if the iterable passed is empty. + * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value + * is the fulfillment value of the first promise that was fulfilled. + * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is + * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the + * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but + * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) + * rejected. + */ +export declare function createSyncAnyPromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Creates a synchronous Promise instance that when resolved or rejected will execute it's pending chained operations + * __synchronously__ in the same execution cycle as the operation that calls the `executors`, `resolve` or `reject` functions. + * + * @group Synchronous + * @group Promise + * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will + * cause the promise to be rejected. The return value of the executor is always ignored + */ +export declare function createSyncPromise(executor: PromiseExecutor): IPromise; + +/** + * The `createSyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise + * settles with the eventual state of the first promise that settles. + * @description The `createSyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first + * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). + * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to + * the first of these values found in the iterable. + * @since 0.5.0 + * @group Synchronous + * @group Promise + * @group Race + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the + * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever + * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle + * synchronously. + */ +export declare function createSyncRacePromise(values: Iterable>, timeout?: number): IPromise>; + +/** + * Returns a single synchronous Promise instance that is already rejected with the given reason. + * Any chained operations will execute __synchronously__ at the point of being added (eg. `catch()`; `finally()`). + * + * @function + * @group Synchronous + * @group Promise + * @group Rejected + * @param reason - The rejection reason + */ +export declare const createSyncRejectedPromise: (reason: any) => IPromise; + +/** + * Returns a single synchronous Promise instance that is already resolved with the given value. If the value passed is + * a promise then that promise is returned instead of creating a new synchronous promise instance. + * If a new instance is returned then any chained operations will execute __synchronously__ at the point of being + * added (calling `then()`). + * + * @function + * @group Synchronous + * @group Promise + * @group Resolved + * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. + */ +export declare const createSyncResolvedPromise: (value: T) => IPromise; + +/** + * Create a Task Scheduler using the optional promise implementation and scheduler name. + * The newPromise can be any value promise creation function, where the execution of the + * queued tasks will be processed based on how the promise implementation processes it's + * chained promises (asynchrounsly; synchronously; idle processing, etc) + * + * The functions used to start each task my return a result (synchronous execution) or an + * {@link IPromise}, `PromiseLike` or `Promise` result (asynchronous execution). + * + * Each task is executed in the order that it was queued and the provided `startTask` function + * will not be called until all previous tasks have completed (whther they resolve or reject). + * The result from any previous task does not affect and is not passed to any later scheduled + * task, if you need this capability then your `startTask` functions will need to co-operate to + * share any common context. + * + * By default, queued tasks which have either been "waiting" to run or have been running longer + * then 10 minutes will be Auto-Rejected to try and free up resources. If a task is running when + * it rejected then it will continue to "run" based on whatever operation it's `startTask` is + * performing. If a task has not yet had it's `startTask` function called it will never get called. + * In both cases the `IPromise` returned by the call to {@link ITaskScheduler.queue | queue} the + * task will be `rejected`. You can change this default time, including disabling completly via + * the {@link ITaskScheduler.setStaleTimeout | setStaleTimeout} + * function. + * @since 0.2.0 + * @group Scheduler + * @param newPromise - The function to use for creating a new promise when required, if not + * provided this will default to {@link createPromise} which will use the default registered + * promise creation function which defaults to runtime native promises or async Promise if not + * supported by the runtime. + * @param name - The name you want to associated with this scheduler, mostly useful for debugging + * @returns A new ITaskScheduler instance + * @example + * ```ts + * let scheduler = createTaskScheduler(); + * + * // Schedule a task using the ts-async helper promise functions + * scheduler.queue(() => { + * return createPromise((resolve, reject) => { + * scheduleTimeout(() => { + * // Do something after a delay + * }, 100); + * }); + * }); + * + * // Schedule an asynchronous task which uses async/await + * scheduler.queue(async () => { + * // This task will only execute after the previous task has completed + * await performAnotherAsyncTask(); + * }); + * + * // Schedule a synchronous task that executes and completes immediately + * scheduled.queue(() => { + * // Do some synchronous task + * return 42; + * }); + * + * // Schedule an asynchronous task which returns a promise + * scheduled.queue(() => { + * return doAwait(fetch("https://github.com/nevware21/ts-async/blob/main/README.md"), (response) => { + * let theReadMe = response.text(); + * // Do something with the readme + * }); + * }); + * ``` + */ +export declare function createTaskScheduler(newPromise?: (executor: PromiseExecutor, timeout?: number) => IPromise, name?: string): ITaskScheduler; + +/** + * Creates a Promise instance that resolve or reject after the specified timeout. + * @since 0.5.0 + * @group Timeout + * @group Promise + * @param timeout - The timeout in milliseconds to wait before resolving or rejecting the promise. + * @param resolveReject - [Optional] If true the promise will resolve, otherwise it will reject. + * @param message - [Optional] The message to use when rejecting the promise, if not supplied (or + * undefined) the default message will be used. + * @returns A promise that will resolve or reject after the specified timeout. + * @example + * ```ts + * // Rejects after 100ms with default message + * const result = await createTimeoutPromise(100); + * // Throws an Error: Timeout of 100ms exceeded + * + * // Resolves after 100ms with default message + * const result = await createTimeoutPromise(100, true); + * console.log(result); // Timeout of 100ms exceeded + * + * // Rejects after 100ms with default message + * const result = await createTimeoutPromise(100, false); + * // throws an Error: Timeout of 100ms exceeded + * + * // Resolves after 100ms with default message + * const result = await createTimeoutPromise(100, true); + * console.log(result); // Timeout of 100ms exceeded + * + * // Rejects after 100ms with the message "Hello" + * const result = await createTimeoutPromise(100, false, "Hello"); + * // throws an Error: Hello + * + * // Resolves after 100ms with the message "Hello" + * const result = await createTimeoutPromise(100, true, "Hello"); + * console.log(result); // Hello + * + * // Resolves after 100ms with the message "Hello" + * doAwait(createTimeoutPromise(100, true, "Hello"), (result) => { + * console.log(result); // Hello + * }); + * + * // Rejects after 100ms with the message "Hello" + * doAwait(createTimeoutPromise(100, false, "Hello"), (result) => { + * // Not called + * }, (err) => { + * console.log(err); // Hello + * }); + * + * // Rejects after 100ms with the message "Hello" + * doAwaitResult(createTimeoutPromise(100, false, "Hello"), (result) => { + * console.log(result.rejected); // true + * console.log(result.reason); // Hello + * }); + * ``` + */ +export declare function createTimeoutPromise(timeout: number, resolveReject?: boolean, message?: T): IPromise; + +/** + * Wait for the promise to resolve or reject, if resolved the callback function will be called with it's value and if + * rejected the rejectFn will be called with the reason. If the passed promise argument is not a promise the callback + * will be called synchronously with the value. + * @group Await Helper + * @param value - The value or promise like value to wait for + * @param resolveFn - The callback to call on the promise successful resolving. + * @param rejectFn - The callback to call when the promise rejects + * @param finallyFn - The callback to call once the promise has resolved or rejected + * @returns The passed value, if it is a promise and there is either a resolve or reject handler + * then it will return a chained promise with the value from the resolve or reject handler (depending + * whether it resolve or rejects) + * @example + * ```ts + * let promise = createPromise((resolve, reject) => { + * resolve(42); + * }); + * + * // Handle via a chained promise + * let chainedPromise = promise.then((value) => { + * // Do something with the value + * }); + * + * // Handle via doAwait + * doAwait(promise, (value) => { + * // Do something with the value + * }); + * + * // It can also handle the raw value, so you could process the result of either a + * // synchrounous return of the value or a Promise + * doAwait(42, (value) => { + * // Do something with the value + * }); + * ``` + */ +export declare function doAwait(value: T | IPromise | PromiseLike, resolveFn: ResolvedPromiseHandler, rejectFn?: RejectedPromiseHandler, finallyFn?: FinallyPromiseHandler): TResult1 | TResult2 | IPromise; + +/** + * Wait for the promise to resolve or reject, if resolved the callback function will be called with it's value and if + * rejected the rejectFn will be called with the reason. If the passed promise argument is not a promise the callback + * will be called synchronously with the value. + * @group Await Helper + * @param value - The value or promise like value to wait for + * @param resolveFn - The callback to call on the promise successful resolving. + * @param rejectFn - The callback to call when the promise rejects + * @param finallyFn - The callback to call once the promise has resolved or rejected + * @returns The passed value, if it is a promise and there is either a resolve or reject handler + * then it will return a chained promise with the value from the resolve or reject handler (depending + * whether it resolve or rejects) + * @example + * ```ts + * let promise = createPromise((resolve, reject) => { + * resolve(42); + * }); + * + * // Handle via a chained promise + * let chainedPromise = promise.then((value) => { + * // Do something with the value + * }); + * + * // Handle via doAwait + * doAwait(promise, (value) => { + * // Do something with the value + * }); + * + * // It can also handle the raw value, so you could process the result of either a + * // synchrounous return of the value or a Promise + * doAwait(42, (value) => { + * // Do something with the value + * }); + * ``` + */ +export declare function doAwait(value: T | PromiseLike, resolveFn: ResolvedPromiseHandler, rejectFn?: RejectedPromiseHandler, finallyFn?: FinallyPromiseHandler): TResult1 | TResult2 | PromiseLike; + +/** + * Helper to coallesce the promise resolved / reject into a single callback to simplify error handling. + * @group Await Helper + * @param value - The value or promise like value to wait + * @param cb - The callback function to call with the resulting value, if the value is not a + * promise like value then the callback is called synchronously, if the value is a promise then + * the callback will be called once the promise completes the resulting value will be passed as an + * IAwaitResponse instance, it will be called whether any promise resolves or rejects. + * @returns The value returned by the `cb` callback function, if the value is a promise then the return value + * of the callback will be returned as a promise whether the callback returns a promise or not. + * @example + * ```ts + * let promise = createPromise((resolve, reject) => { + * resolve(42); + * }); + * + * // Handle via doAwaitResponse + * doAwaitResponse(promise, (value) => { + * if (!value.rejected) { + * // Do something with the value + * } else { + * // Do something with the reason + * } + * }); + * + * // It can also handle the raw value, so you could process the result of either a + * // synchrounous return of the value or a Promise + * doAwaitResponse(42, (value) => { + * if (!value.rejected) { + * // Do something with the value + * } else { + * // This will never be true as the value is not a promise + * } + * }); + * ``` + */ +export declare function doAwaitResponse(value: T | IPromise | PromiseLike, cb: (response: AwaitResponse) => T | TResult1 | TResult2 | IPromise | PromiseLike): T | TResult1 | TResult2 | IPromise; + +/** + * Helper to coallesce the promise resolved / reject into a single callback to simplify error handling. + * @group Await Helper + * @param value - The value or promise like value to wait for + * @param cb - The callback function to call with the resulting value, if the value is not a + * promise like value then the callback is called synchronously, if the value is a promise then + * the callback will be called once the promise completes the resulting value will be passed as an + * IAwaitResponse instance, it will be called whether any promise resolves or rejects. + * @returns The value returned by the `cb` callback function, if the value is a promise then the return value + * of the callback will be returned as a promise whether the callback returns a promise or not. + * @example + * ```ts + * let promise = createPromise((resolve, reject) => { + * resolve(42); + * }); + * + * // Handle via doAwaitResponse + * doAwaitResponse(promise, (value) => { + * if (!value.rejected) { + * // Do something with the value + * } else { + * // Do something with the reason + * } + * }); + * + * // It can also handle the raw value, so you could process the result of either a + * // synchrounous return of the value or a Promise + * doAwaitResponse(42, (value) => { + * if (!value.rejected) { + * // Do something with the value + * } else { + * // This will never be true as the value is not a promise + * } + * }); + * ``` + */ +export declare function doAwaitResponse(value: T | PromiseLike, cb: (response: AwaitResponse) => T | TResult1 | TResult2 | PromiseLike): T | TResult1 | TResult2 | PromiseLike; + +/** + * Wait for the promise to resolve or reject and then call the finallyFn. If the passed promise argument is not a promise the callback + * will be called synchronously with the value. If the passed promise doesn't implement finally then a finally implementation will be + * simulated using then(..., ...). + * @group Await Helper + * @param value - The value or promise like value to wait for + * @param finallyFn - The finally function to call once the promise has resolved or rejected + */ +export declare function doFinally(value: T | IPromise | PromiseLike, finallyFn: FinallyPromiseHandler): T | IPromise; + +/** + * Wait for the promise to resolve or reject and then call the finallyFn. If the passed promise argument is not a promise the callback + * will be called synchronously with the value. If the passed promise doesn't implement finally then a finally implementation will be + * simulated using then(..., ...). + * @group Await Helper + * @param value - The value or promise like value to wait for + * @param finallyFn - The finally function to call once the promise has resolved or rejected + */ +export declare function doFinally(value: T | PromiseLike, finallyFn: FinallyPromiseHandler): T | PromiseLike; + +/** + * Performs a while loop, calling the provided `callbackFn` function until the `state.isDone` + * property is set to `true` or the optional `isDOneFn` returns `true`. The callback function will + * receive a single {@link IWhileState | state} argument and may return either a value or a promise, + * if a promise is returned the while loop will wait until the promise is resolved before calling + * the callback function again. If the callback function never returns a promise the while loop + * will be executed synchronous and last value returned by the callback will be returned, if the + * callback function returns a promise the while loop will be asynchronous and an {@link IPromise} + * will be returned and resolved with the last value returned by the callback or rejected if the + * callback promise rejects or throws an error. + * @since 0.5.0 + * @group Loop + * @typeParam T - Identifies the element type returned by the callback function. + * @param callbackFn - A function that will be called until the `state.isDone` flag is set to `true` + * the function will receive a single {@link IWhileState | state} argument. The callback function + * may return either a value or a promise, if a promise is returned the while loop will wait + * until the promise is resolved before calling the callback function again. + * @param isDoneFn - An optional function that will be called after the callback function is called, + * that can be used to stop the while loop. The function will receive a single {@link IWhileState | state} + * argument. If the function returns `true` the while loop will stop, otherwise the while loop will continue. + * @param thisArg - An object to which the this keyword can refer in the callbackfn function. + * If thisArg is omitted, null or undefined the array will be used as the this value. + * @remarks + * - If an `isDoneFn` is provided the `state.isDone` property will be set to the provided value and + * is accessible withing the callback function. The callbackFn may overwrite the value of the + * `state.isDone` property within the callback function with a boolean value or another function that + * returns a boolean value. + * - The callback function is called until until the `state.isDone` property is set to `true` or if + * `state.isDone` is a function until the function returns `true`. + * - The callback function will receive a single {@link IWhileState | state} argument that contains + * the following properties: + * - `iter` - The zero-based iteration count, which is incremented after each call to the `callbackFn` + * and any `isDone` function (if provided), the `iter` property is accessible withing the callback + * function and may be overwritten within the callback function. + * - `res` - The last resolved result value returned by the `callbackFn` function. + * - `isDone` - A boolean value or a callback function that will be called to check if the while loop + * should stop, the `isDone` property is accessible withing the callback function and may be + * overwritten within the callback function. + * - The callback function may return either a value or a promise, if a promise is returned the while + * loop will wait until the promise is resolved before calling the callback function again. + * - If the callback function throws an error when executing `synchronously` the exception will + * also be thrown `synchronously` otherwise the returned promise will be rejected with the error. + * @example + * ```ts + * // Synchronous example + * const result = doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function + * if (state.idx < 10) { + * // Logs each iteration index (will be called synchronously) + * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * console.log(state.idx); + * } else { + * state.isDone = true; + * return "Hello"; + * } + * }); + * + * console.log(result); // returns Hello after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * + * // Synchronous example with isDoneFn + * const result = doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function + * if (state.idx < 10) { + * // Logs each iteration index (will be called synchronously) + * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * console.log(state.idx); + * } else { + * return "Hello"; + * } + * }, (state) => state.idx > 10); + * console.log(result); // returns Hello after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * + * // Asynchronous examples + * const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function + * if (state.idx < 10) { + * // Logs each iteration index + * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 calling the callback function synchronously + * console.log(state.idx); + * // Returning a promise will cause `doWhileAsync` to return a promise to the caller + * // and wait for the promise to resolve before calling the callback function again. + * return createTimeoutPromise(10, true, state.idx); + * } + * + * state.isDone = true; + * return createResolvedPromise("Darkness"); + * }); + * console.log(result); // Darkness + * + * // Asynchronous example with isDoneFn + * const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function + * if (state.idx < 10) { + * // Logs each iteration index + * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 calling the callback function synchronously + * console.log(state.idx); + * // Returning a promise will cause `doWhileAsync` to return a promise to the caller + * // and wait for the promise to resolve before calling the callback function again. + * return createTimeoutPromise(10, true, state.idx); + * } + * + * return createResolvedPromise("Darkness"); + * }, (state) => state.idx > 10); + * console.log(result); // returns Darkness after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * + * // Combination Synchronous and Asynchronous example + * const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function + * if (state.idx < 10) { + * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * // Logs each iteration index (will be called synchronously) + * console.log(state.idx); + * } else { + * state.isDone = true; + * // Returning a promise will cause `doWhileAsync` to return a promise to the caller + * // and wait for the promise to resolve before resolving the returned promise. + * return createResolvedPromise("my old friend"); + * } + * }); + * + * console.log(result); // my old friend + * + * // Asynchronous example using await + * const result = await doWhileAsync(async (state) => { + * if (state.idx < 10) { + * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * // Logs each iteration index (will be called synchronously) + * await createTimeoutPromise(10, true, state.idx); + * } else { + * state.isDone = true; + * // Returning a promise will cause `doWhileAsync` to return a promise to the caller + * // and wait for the promise to resolve before resolving the returned promise. + * return await createResolvedPromise("my old friend"); + * } + * }); + * + * console.log(result); // my old friend + * + * // Asynchronous example using await and dynamically setting the isDone function + * const result = await doWhileAsync(async (state) => { + * // dynamically set the isDone function + * if (state.idx < 10) { + * state.isDone = () => return false; + * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * // Logs each iteration index (will be called synchronously) + * await createTimeoutPromise(10, true, state.idx); + * } else { + * state.isDone = () => return true; + * // Returning a promise will cause `doWhileAsync` to return a promise to the caller + * // and wait for the promise to resolve before resolving the returned promise. + * return await createResolvedPromise("my old friend"); + * } + * }); + * + * console.log(result); // my old friend + * ``` + */ +export declare function doWhileAsync(callbackFn: (state: IWhileState) => T | IPromise | PromiseLike, isDoneFn?: (state: IWhileState) => boolean | void | IPromise | PromiseLike, thisArg?: any): T | IPromise; + +/** + * This defines the handler function that is called via the finally when the promise is resolved or rejected + */ +export declare type FinallyPromiseHandler = (() => void) | undefined | null; + +/** + * Create a Promise object that represents the eventual completion (or failure) of an asynchronous operation and its resulting value. + * This interface definition, closely mirrors the typescript / javascript PromiseLike and Promise definitions as well as providing + * simular functions as that provided by jQuery deferred objects. + * + * The returned Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers + * with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous + * methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point + * in the future. + * + * A Promise is in one of these states: + *
    + *
  • pending: initial state, neither fulfilled nor rejected. + *
  • fulfilled: meaning that the operation was completed successfully. + *
  • rejected: meaning that the operation failed. + *
+ * + * A pending promise can either be fulfilled with a value or rejected with a reason (error). When either of these options happens, the + * associated handlers queued up by a promise's then method are called synchronously. If the promise has already been fulfilled or rejected + * when a corresponding handler is attached, the handler will be called synchronously, so there is no race condition between an asynchronous + * operation completing and its handlers being attached. + * + * As the `then()` and `catch()` methods return promises, they can be chained. + * @typeParam T - Identifies the expected return type from the promise + */ +export declare interface IPromise extends PromiseLike, Promise { + /** + * Returns a string representation of the current state of the promise. The promise can be in one of four states. + *
    + *
  • "pending": The promise is not yet in a completed state (neither "rejected"; or "resolved").
    • + *
  • "resolved": The promise is in the resolved state.
    • + *
  • "rejected": The promise is in the rejected state.
    • + *
+ * @example + * ```ts + * let doResolve; + * let promise: IPromise = createSyncPromise((resolve) => { + * doResolve = resolve; + * }); + * + * let state: string = promise.state(); + * console.log("State: " + state); // State: pending + * doResolve(true); // Promise will resolve synchronously as it's a synchronous promise + * console.log("State: " + state); // State: resolved + * ``` + */ + state?: string; + /** + * Attaches callbacks for the resolution and/or rejection of the Promise. + * @param onResolved - The callback to execute when the Promise is resolved. + * @param onRejected - The callback to execute when the Promise is rejected. + * @returns A Promise for the completion of which ever callback is executed. + * @example + * ```ts + * const promise1 = createPromise((resolve, reject) => { + * resolve('Success!'); + * }); + * + * promise1.then((value) => { + * console.log(value); + * // expected output: "Success!" + * }); + * ``` + */ + then(onResolved?: ResolvedPromiseHandler, onRejected?: RejectedPromiseHandler): IPromise; + /** + * Attaches callbacks for the resolution and/or rejection of the Promise. + * @param onResolved - The callback to execute when the Promise is resolved. + * @param onRejected - The callback to execute when the Promise is rejected. + * @returns A Promise for the completion of which ever callback is executed. + * @example + * ```ts + * const promise1 = createPromise((resolve, reject) => { + * resolve('Success!'); + * }); + * + * promise1.then((value) => { + * console.log(value); + * // expected output: "Success!" + * }); + * ``` + */ + then(onResolved?: ResolvedPromiseHandler, onRejected?: RejectedPromiseHandler): PromiseLike; + /** + * Attaches callbacks for the resolution and/or rejection of the Promise. + * @param onResolved - The callback to execute when the Promise is resolved. + * @param onRejected - The callback to execute when the Promise is rejected. + * @returns A Promise for the completion of which ever callback is executed. + * @example + * ```ts + * const promise1 = createPromise((resolve, reject) => { + * resolve('Success!'); + * }); + * + * promise1.then((value) => { + * console.log(value); + * // expected output: "Success!" + * }); + * ``` + */ + then(onResolved?: ResolvedPromiseHandler, onRejected?: RejectedPromiseHandler): IPromise; + /** + * Attaches a callback for only the rejection of the Promise. + * @param onRejected - The callback to execute when the Promise is rejected. + * @returns A Promise for the completion of the callback. + * @example + * ```ts + * const promise1 = createPromise((resolve, reject) => { + * throw 'Uh-oh!'; + * }); + * + * promise1.catch((error) => { + * console.error(error); + * }); + * // expected output: Uh-oh! + * ``` + */ + catch(onRejected?: ((reason: any) => TResult | IPromise) | undefined | null): IPromise; + /** + * Attaches a callback for only the rejection of the Promise. + * @param onRejected - The callback to execute when the Promise is rejected. + * @returns A Promise for the completion of the callback. + * @example + * ```ts + * const promise1 = createPromise((resolve, reject) => { + * throw 'Uh-oh!'; + * }); + * + * promise1.catch((error) => { + * console.error(error); + * }); + * // expected output: Uh-oh! + * ``` + */ + catch(onRejected?: ((reason: any) => TResult | IPromise) | undefined | null): PromiseLike; + /** + * Attaches a callback for only the rejection of the Promise. + * @param onRejected - The callback to execute when the Promise is rejected. + * @returns A Promise for the completion of the callback. + * @example + * ```ts + * const promise1 = createPromise((resolve, reject) => { + * throw 'Uh-oh!'; + * }); + * + * promise1.catch((error) => { + * console.error(error); + * }); + * // expected output: Uh-oh! + * ``` + */ + catch(onRejected?: ((reason: any) => TResult | IPromise) | undefined | null): IPromise; + /** + * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The + * resolved value cannot be modified from the callback. + * @param onfinally - The callback to execute when the Promise is settled (fulfilled or rejected). + * @returns A Promise for the completion of the callback. + * @example + * ```ts + * function doFunction() { + * return createPromise((resolve, reject) => { + * if (Math.random() > 0.5) { + * resolve('Function has completed'); + * } else { + * reject(new Error('Function failed to process')); + * } + * }); + * } + * + * doFunction().then((data) => { + * console.log(data); + * }).catch((err) => { + * console.error(err); + * }).finally(() => { + * console.log('Function processing completed'); + * }); + * ``` + */ + finally(onfinally?: FinallyPromiseHandler): IPromise; +} + +/** + * The result of a promise. It can either be fulfilled with a value, or rejected with a reason. + * @since 0.5.0 + * @group Promise + * @typeParam T - The type of the fulfilled value. + * @typeParam U - The type of the rejected reason. + * + * @example + * ```ts + * const result: IPromiseResult = { + * status: "fulfilled", + * value: 42 + * }; + * + * const result: IPromiseResult = { + * status: "rejected", + * reason: "Hello Darkness" + * }; + * ``` + */ +export declare interface IPromiseResult { + /** + * A string indicating whether the promise was fulfilled or rejected + */ + status: "fulfilled" | "rejected"; + /** + * The value that the promise was fulfilled with. + */ + value?: T; + /** + * The reason that the promise was rejected with. + */ + reason?: any; +} + +/** + * Defines a Task Scheduler that uses IPromise implementations to serialize the execution of the tasks. + * Each added task will not get executed until the previous task has completed. + * @since 0.2.0 + * @group Scheduler + */ +export declare interface ITaskScheduler { + /** + * Identifies if this scheduler is currently idle (`true`) or has waiting or currently processing tasks (`false`). + * @example + * ```ts + * let scheduler = createTaskScheduler(); + * + * // Check idle state + * scheduler.idle; // true + * + * let queuedTask = scheduler.queue(() => { + * // Return a promise + * return createPromise((resolve) => { + * // Wait some time then resolve + * }); + * }); + * + * // Check idle state + * scheduler.idle; // false + * + * // Wait for the queued task to complete + * await queuedTask; + * + * // Check idle state + * scheduler.idle; // true + * ``` + */ + readonly idle: boolean; + /** + * Queue a task to be scheduled for execution, once the task has completed the returned IPromise + * will be resolved / rejected + * @param theTask - The function to call to start the task + * @param taskName - The optional task name for the task, useful for debugging. + * @param timeout - Specify a specific timeout for the task, the timeout will only apply once the task is started. + * @returns A new promise that will be resolved (or rejected) once the task has been executed or aborted. + * @example + * ```ts + * let scheduler = createTaskScheduler(); + * + * // Schedule an async task, where the function returns a Promise or PromiseLike result + * let queuedTask = scheduler.queue(runSomeAsyncTask()); + * + * // Schedule an async task, where the function returns a Promise or PromiseLike result + * let queuedTask2 = scheduler.queue(runAnotherAsyncTask()); + * + * // Both queuedTask and queuedTask2 are Promise implementation (based on the type used by the scheduler) + * // You can now treat these like any promose to wait for them to be resolve / rejected + * // Somewhere else in your code using either `await`, `doAwait`, doAwaitResponse`, `doFinally`, `then`, `catch` + * // or `finally` + * doAwait(queuedTask, (result1) => { + * // queued task 1 is now complete + * // queued task 2 is now scheduled to run (or is already running) + * }); + * + * doAwait(queuedTask2, (result1) => { + * // Both task 1 and 2 have completed + * // As task 2 did not start until task 1 finished + * }); + * + * // This Will also work and will not cause a deadlock + * // But task 2 will still not start until task 1 has completed + * let task2Result = await queuedTask2; + * + * // Now get the task 1 response + * let task1Result = await queuedTask1; + * ``` + */ + queue: (theTask: StartQueuedTaskFn, taskName?: string, timeout?: number) => IPromise; + /** + * Set the timeout to reject and remove any stale running tasks to avoid filling up memory + * with blocked tasks. + * @param staleTimeout - Identifies the maximum that a task can be running or waiting to start, + * defaults to 10 minutes. If the value is set to zero or less the stale timeout will never + * abort waiting tasks. + * @param staleCheckPeriod - Identifes how oftem the queue's should be checked for stale tasks, + * defaults to 1/10th of the staleTimeout when not specified. This directly sets the asynchronous + * timeout value. + * @example + * ```ts + * let secheduler = createTaskScheduler(); + * + * // Set the stale task timeout to 1 second, this will check every 100ms + * // for any long waiting / executing tasks and "reject" them. + * scheduler.setStaleTimeout(1000); + * + * // Set the stale task timeout to 5 minutes (300 seconds), this will check every 1 minute (60 seconds) + * // for any long waiting / executing tasks and "reject" them. + * scheduler.setStaleTimeout(300000, 60000); + * ``` + */ + setStaleTimeout: (staleTimeout: number, staleCheckPeriod?: number) => void; +} + +/** + * Calls the provided `callbackFn` function once for each element in the iterator or iterator returned by + * the iterable and processed in the same order as returned by the iterator. As with the {@link arrForEachAsync} + * you CAN stop or break the iteration by returning -1 from the `callbackFn` function. + * + * The order of processing is not reset if you add or remove elemenets to the iterator, the actual behavior will + * depend on the iterator implementation. + * + * if the passed `iter` is both an Iterable\ and Iterator\ the Iterator\ interface takes precedence. And if + * an iterable and does not have a `Symbol.iterator` property then the `iter` will be used as the iterator. + * + * The `callbackFn` may execute `synchronously` or `asynchronously` and if the `callbackFn` returns a `Promise` + * then the next iteration will not be called until the promise is resolved. If the `callbackFn` returns a `Promise` + * that is rejected then the iteration will stop and the promise returned by iterForEachAsync will be rejected with + * the same error. + * @remarks + * If Symbols are NOT supported then the iterable MUST be using the same polyFill for the well know symbols, as used + * by the library. If the iterable is using a different polyFill then the `iter` MUST be an Iterator\ and not an + * Iterable\. + * If you are targetting a mixed environment you SHOULD either + * - only use the polyfill Symbol's provided by this library + * - ensure that you add any symbol polyfills BEFORE these utilities + * iterForOfAsync + * @since 0.5.0 + * @group Loop + * @group Iterator + * @typeParam T - Identifies the element type of the iterator + * @param iter - The iterator or iterable of elements to be searched. + * @param callbackFn - A `asynchronous` or `synchronous` function that accepts up to three arguments. iterForEach + * calls the callbackfn function one time for each element in the iterator. + * @param thisArg - An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, + * null or undefined the iterator will be used as the this value. + * @example + * ```ts + * const items = ['item1', 'item2', 'item3', 'item4', 'item5', 'item6', 'item7', 'item8', 'item9', 'item10']; + * const copyItems = []; + * + * // using async / await + * let result = await iterForOfAsync(items, async (value, index) => { + * copyItems.push(value); + * if (index === 5) { + * return -1; // Stop the iteration + * } + * + * await createTimeoutPromise(100); // Wait 100ms before processing the next item, you could also just return the promise + * }) + * + * console.log(result); // returns -1 if the loop was stopped, otherwise returns undefined + * + * // using doAwait + * doAwait(iterForOfAsync(items, (value, index) => { + * copyItems.push(value); + * if (index === 5) { + * return -1; // Stop the iteration + * } + * + * return createTimeoutPromise(100); // Wait 100ms before processing the next item, you could also just return the promise + * }), (result) => { + * console.log(result); // returns -1 if the loop was stopped, otherwise returns undefined + * }); + * ``` + */ +export declare function iterForOfAsync(iter: Iterator | Iterable | AsyncIterator | AsyncIterable, callbackFn: (value: T, count: number, iter?: Iterator | AsyncIterator) => void | number | IPromise, thisArg?: any): void | number | IPromise; + +/** + * The current state of the while loop while processing the callback function, this is + * passed to eht callback function. + * @typeParam T - Identifies the element type returned by the callback function. + * @since 0.5.0 + */ +export declare interface IWhileState { + /** + * The number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC, + * at the beginning of the while loop. This value is set at the beginning of the while + * loop via [`utcNow()`](https://nevware21.github.io/ts-utils/typedoc/functions/utcNow.html) + * (`Date.now()`) and is not updated during the execution of while loop. + */ + st: number; + /** + * The zero-based iteration count, which is increased after each call to the callback. + */ + iter: number; + /** + * The resolved result value returned by the callback function. + */ + res?: T; + /** + * Callback to enable the caller stop the while loop. + */ + isDone: boolean | ((state: IWhileState) => boolean | void | IPromise | PromiseLike); +} + +/** + * A full polyfill for the Promise class. + * Represents the completion of an asynchronous operation, and its resulting value. + * @class PolyPromise + * @description The `PolyPromise` class is a polyfill for the native Promise class. It provides a way to work with asynchronous operations in a more manageable way. + * @since 0.5.0 + * @group Polyfill + * @group Promise + */ +export declare let PolyPromise: PolyPromiseConstructor; + +/** + * The PolyPromiseConstructor interface represents the constructor for the polyfill Promise object. + * @since 0.5.0 + * @group Polyfill + */ +export declare interface PolyPromiseConstructor { + /** + * Creates a new Promise. + * @constructor + * @param executor - A callback used to initialize the promise. This callback is passed two arguments: + * a resolve callback used to resolve the promise with a value or the result of another promise, + * and a reject callback used to reject the promise with a provided reason or error. + */ + new (executor: PromiseExecutor): IPromise; + /** + * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional + * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. + * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, + * and will reject with this first rejection message / error. + * When resolved or rejected any additional chained operations will execute __asynchronously__ using the optional + * timeout value to schedul when the chained item will be executed (eg. `then()`; `catch()`; `finally()`). + * @group Polyfill + * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + * @returns + *
    + *
  • An already resolved `Promise`, if the input passed is empty. + *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ + * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the + * promises reject. + *
+ */ + all(input: Iterable>, timeout?: number): IPromise; + /** + * The `createAsyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise + * settles with the eventual state of the first promise that settles. + * @description The `createAsyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first + * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). + * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to + * the first of these values found in the iterable. + * @since 0.5.0 + * @group Polyfill + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the + * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever + * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise is still + * asynchronously settled. + */ + race(values: Iterable>, timeout?: number): IPromise>; + /** + * The `createAsyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise + * settles with the eventual state of the first promise that settles. + * @description The `createAsyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first + * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). + * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to + * the first of these values found in the iterable. + * @since 0.5.0 + * @group Polyfill + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the + * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever + * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise is still + * asynchronously settled. + */ + race(values: T, timeout?: number): IPromise>; + /** + * The `createAsyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. + * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. + * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an + * AggregateError containing an array of rejection reasons. + * @since 0.5.0 + * @group Polyfill + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A new Promise that is: + * - Already rejected, if the iterable passed is empty. + * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value + * is the fulfillment value of the first promise that was fulfilled. + * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is + * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the + * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but + * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) + * rejected. + */ + any(values: Iterable>, timeout?: number): IPromise>; + /** + * The `createAsyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. + * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. + * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an + * AggregateError containing an array of rejection reasons. + * @since 0.5.0 + * @group Polyfill + * @param values - An iterable object of promises. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A new Promise that is: + * - Already rejected, if the iterable passed is empty. + * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value + * is the fulfillment value of the first promise that was fulfilled. + * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is + * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the + * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but + * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) + * rejected. + */ + any(values: T, timeout?: number): IPromise>; + /** + * Returns a single asynchronous Promise instance that is already rejected with the given reason. + * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule + * when then chained items will be executed. (eg. `catch()`; `finally()`). + * @group Polyfill + * @param reason - The rejection reason + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + * @returns A rejected promise. + */ + reject(reason?: any, timeout?: number): IPromise; + /** + * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is + * a promise then that promise is returned instead of creating a new asynchronous promise instance. + * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional + * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). + * @group Polyfill + * @returns A resolved promise. + */ + resolve(): IPromise; + /** + * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is + * a promise then that promise is returned instead of creating a new asynchronous promise instance. + * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional + * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). + * @group Polyfill + * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. + * @param timeout - Optional timeout to wait before processing the items, defaults to zero. + * @returns A resolved promise. + */ + resolve(value: T | PromiseLike, timeout?: number): IPromise; + /** + * Returns a single Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations based on the + * {@link createAsyncPromise | Asynchronous} promise implementation. Any chained operations will execute + * __asynchronously__ when the final operation pending promises have resolved, or if the input contains + * no promises. It will resolve only after all of the input promises have either resolved or rejected, + * and will resolve with an array of {@link IPromiseResult } objects that each describe the outcome of + * each promise. + * @since 0.5.0 + * @group Polyfill + * @param values - An array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. + */ + allSettled(values: T, timeout?: number): IPromise<{ + -readonly [P in keyof T]: IPromiseResult>; + }>; + /** + * Returns a single Promise instance that resolves to an array of the results from the input promises. + * This returned promise will resolve and execute it's pending chained operations based on the + * {@link createAsyncPromise | Asynchronous} promise implementation. Any chained operations will execute + * __asynchronously__ when the final operation pending promises have resolved, or if the input contains + * no promises. It will resolve only after all of the input promises have either resolved or rejected, + * and will resolve with an array of {@link IPromiseResult } objects that each describe the outcome of + * each promise. + * @since 0.5.0 + * @group Polyfill + * @param values - An array of promises to wait to be resolved / rejected before resolving or rejecting the new promise + * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. + * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. + */ + allSettled(values: Iterable>, timeout?: number): IPromise>[]>; +} + +/** + * Defines the signature of a function that creates a Promise. + * @param newExecutor - The executor to run in the context of the promise + * @param extraArgs - Any extra arguments that can be passed to the creator + * @returns A Promise `IPromise` implemenetation + */ +export declare type PromiseCreatorFn = (newExecutor: PromiseExecutor, ...extraArgs: any) => IPromise; + +/** + * A function to be executed during the creation of a promise instance. It receives two functions as parameters: resolve and reject. + * Any errors thrown in the executor will cause the promise to be rejected, and the return value will be neglected. The semantics of executor are detailed below. + * @param resolve - The handler function that should be called when the operation has completed and the promise can continue. + * @param reject - The handler function that should be called to cause the promise to be rejected. + */ +export declare type PromiseExecutor = (resolve: ResolvePromiseHandler, reject: RejectPromiseHandler) => void; + +/** + * This defines the handler function for when a promise is rejected. + * @param value - This is the value passed as part of resolving the Promise + * @return This may return a value, another Promise or void. @see {@link https://nevware21.github.io/ts-async/typedoc/interfaces/IPromise.html#then | IPromise.then} for how the value is handled. + */ +export declare type RejectedPromiseHandler = (((reason: any) => T | IPromise | PromiseLike) | undefined | null); + +/** + * Defines the signature of the reject function passed to the resolverFunc (in the Promise constructor) + * @param reason - The reason to reject the Promise with + * @returns Nothing + */ +export declare type RejectPromiseHandler = (reason?: any) => void; + +/** + * This defines the handler function for when a promise is resolved. + * @param value - This is the value passed as part of resolving the Promise + * @return This may return a value, another Promise or void. @see {@link https://nevware21.github.io/ts-async/typedoc/interfaces/IPromise.html#then | IPromise.then} for how the value is handled. + */ +export declare type ResolvedPromiseHandler = (((value: T) => TResult1 | IPromise | PromiseLike) | undefined | null); + +/** + * Defines the signature of the resolve function passed to the resolverFunc (in the Promise constructor) + * @param value - The value to resolve the Promise with + * @returns Nothing + */ +export declare type ResolvePromiseHandler = (value: T | IPromise | PromiseLike) => void; + +/** + * Set the default promise implementation to use when calling `createPromise`; `createAllPromise`; `createResolvedPromise` + * and `createRejectedPromise`. This is effective a global value and changing this will affect ALL callers of these + * functions, as such these functions should only be used when switching implementations would have not unexpected + * consequences like switching from a `createSyncPromise` to `createIdlePromise` where idle promises have a possibility + * of never getting called during application shutdown or during an expected timeframe. + * @group Alias + * @group Promise + * @param creator - The creator function to call when a new promise is required. + */ +export declare function setCreatePromiseImpl(creator: (executor: PromiseExecutor, timeout?: number) => IPromise): void; + +/** + * Sets the global default idle timeout / deadline to use when no timeout is passed during promise creation. + * @param idleDeadline - Specifies the time in milliseconds to use as the idle timeout / deadline by when any + * outstanding chained items should be executed. + * @group Idle + */ +export declare function setDefaultIdlePromiseTimeout(idleDeadline?: number | undefined): void; + +/** + * @deprecated Use `setDefaultIdlePromiseTimeout` instead + * Sets the global default idle timeout / deadline to use when no timeout is passed during promise creation. + * @param idleDeadline - Specifies the time in milliseconds to use as the idle timeout / deadline by when any + * outstanding chained items should be executed. + * + * @function + * @group Idle + */ +export declare const setDefaultIdleTimeout: typeof setDefaultIdlePromiseTimeout; + +/** + * Debug helper to enable internal debugging of the promise implementations. Disabled by default. + * For the generated packages included in the npm package the `logger` will not be called as the + * `_debugLog` function that uses this logger is removed during packaging. + * + * It is available directly from the repository for unit testing. + * + * @group Debug + * @param enabled - Should debugging be enabled (defaults `false`, when `true` promises will have + * additional debug properties and the `toString` will include extra details. + * @param logger - Optional logger that will log internal state changes, only called in debug + * builds as the calling function is removed is the production artifacts. + * @example + * ```ts + * // The Id is the id of the promise + * // The message is the internal debug message + * function promiseDebugLogger(id: string, message: string) { + * if (console && console.log) { + * console.log(id, message); + * } + * } + * + * setPromiseDebugState(true, promiseDebugLogger); + * + * // While the logger will not be called for the production packages + * // Setting the `enabled` flag to tru will cause each promise to have + * // the following additional properties added + * // [[PromiseState]]; => Same as the `state` property + * // [[PromiseResult]]; => The settled value + * // [[PromiseIsHandled]] => Identifies if the promise has been handled + * // It will also cause the `toString` for the promise to include additional + * // debugging information + * ``` + */ +export declare function setPromiseDebugState(enabled: boolean, logger?: (id: string, message: string) => void): void; + +/** + * Identifies the function to call to start and execute the task when its + * ready to be executed. + * @since 0.2.0 + * @group Scheduler + * @param taskName - The optional task name that was assigned to this task, it is passed by the task scheduler. + * @returns The result or a IPromise that will be resolved / rejected when the task + * was completed. + * @example + * ```ts + * function taskFunc1() { + * return 42; + * } + * + * function taskFunc2(taskName: string) { + * console.log("Running Task: " + taskName); + * return fetch("https://example.com/xxxx").then((response) => { + * // ... + * }); + * } + * + * function taskFunc3() { + * return Promise.all([...]); + * } + * + * function taskFunc4() { + * return createAllPromise([...]); + * } + * + * function taskFunc5(taskName: string) { + * return createPromise(() => { + * scheduleTimeout(() => { + * console.log("Completing task: " + taskName); + * resolve(true); + * }, 100); + * }); + * } + * ``` + */ +export declare type StartQueuedTaskFn = (taskName?: string) => T | IPromise; + +export { } From e9ffebcc14c477d7efdad45e370327e2f8576853 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 15 May 2026 06:25:23 +0000 Subject: [PATCH 9/9] fix: stop tracking generated declaration rollup Agent-Logs-Url: https://github.com/nevware21/ts-async/sessions/3d802913-32a8-43d6-a5fc-e2a0ea496f29 Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com> --- .gitignore | 5 - lib/dist/types/ts-async.d.ts | 2049 ---------------------------------- 2 files changed, 2054 deletions(-) delete mode 100644 lib/dist/types/ts-async.d.ts diff --git a/.gitignore b/.gitignore index 9b39a90..2981d33 100644 --- a/.gitignore +++ b/.gitignore @@ -67,11 +67,6 @@ test-esm/ types/ build/ dist/ -!lib/dist/ -lib/dist/** -!lib/dist/types/ -lib/dist/types/** -!lib/dist/types/ts-async.d.ts dist-es**/ docs/typedoc/** diff --git a/lib/dist/types/ts-async.d.ts b/lib/dist/types/ts-async.d.ts deleted file mode 100644 index b3a7abd..0000000 --- a/lib/dist/types/ts-async.d.ts +++ /dev/null @@ -1,2049 +0,0 @@ -/** - * Calls the provided `callbackFn` function once for each element in an array (or ArratLike) instance in ascending index order. It is not invoked - * for index properties that have been deleted or are uninitialized. And unlike the ES6 forEach() this supports async functions and you CAN stop - * or break the iteration by returning -1 from the `callbackFn` function. - * - * The range (number of elements) processed by arrForEach() is set before the first call to the `callbackFn`. Any elements added beyond the range - * or elements which as assigned to indexes already processed will not be visited by the `callbackFn`. - * - * The `callbackFn` may execute `synchronously` or `asynchronously` and if the `callbackFn` returns a `Promise` then the next iteration will not be - * called until the promise is resolved. If the `callbackFn` returns a `Promise` that is rejected then the iteration will stop and the promise - * returned by arrForEachAsync will be rejected with the same error. - * @since 0.5.0 - * @group Loop - * @group Array - * @group ArrayLike - * @typeParam T - Identifies the element type of the array - * @param theArray - The array or array like object of elements to be searched. - * @param callbackFn - A `asynchronous` or `synchronous` function that accepts up to three arguments. arrForEach calls the callbackfn function one - * time for each element in the array. - * @param thisArg - An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, null or undefined - * the array will be used as the this value. - * @remarks - * arrForEachAsync supports either a `synchronous` or `asynchronous` (returns a `Promise`) callback function. If the callback function returns - * a `Promise` then the next iteration will not be called until the promise is resolved. If the callback function returns a `Promise` that is - * rejected then the iteration will stop and the promise returned by arrForEachAsync will be rejected with the same error. - * @example - * ```ts - * const items = ['item1', 'item2', 'item3', 'item4', 'item5', 'item6', 'item7', 'item8', 'item9', 'item10']; - * const copyItems = []; - * - * arrForEachASync(items, (value, index) => { - * copyItems.push(value); - * if (index === 5) { - * return -1; // Stop the iteration - * } - * }); - * console.log(copyItems); // ['item1', 'item2', 'item3', 'item4', item5'] - * - * // Also supports input as an array like object - * const items = { length: 3, 0: 'item1', 1: 'item2', 2: 'item3' }; - * - * // Asynchronous examples using await - * const items = ['item1', 'item2', 'item3', 'item4', 'item5', 'item6', 'item7', 'item8', 'item9', 'item10']; - * const copyItems = []; - * - * await arrForEachASync(items, (value, index) => { // Note: DO NOT use async here unless you use await within the function - * if (index < 5) { - * // Logs each iteration index - * // Logs each value - * console.log(value); - * // Returning a promise will cause `arrForEachAsync` to return a promise to the caller - * // and wait for the promise to resolve before calling the callback function again. - * return createTimeoutPromise(10, true); - * } - * - * return -1; // Stop the iteration - * }); - * console.log(copyItems); // ['item1', 'item2', 'item3', 'item4', item5'] - * - * ``` - */ -export declare function arrForEachAsync(theArray: ArrayLike, callbackFn: (value: T, index: number, array: T[]) => void | number | IPromise, thisArg?: any): void | number | IPromise; - -/** - * A Simple type which identifies the result of a promise as a single response, it identifies - * if the promise was rejected or resolved along with the resolved value or rejected reason. - * It is a union of the `IPromiseFulfilledResult` and `IPromiseRejectedResult` interfaces the - * response will contain the `rejected` property which will be true if the promise was rejected - * or false if the promise was resolved. The `status` property will be set to either "fulfilled" - * or "rejected" to identify the status of the promise. The `value` or `reason` properties will - * contain the resolved value or rejected reason respectively. - * - * @group Promise - * @typeParam T - The type of the fulfilled value. - * - * @example - * ```ts - * const result: AwaitResponse = { - * status: "fulfilled", - * value: 42 - * }; - * - * const result: AwaitResponse = { - * rejected: true, - * status: "rejected", - * reason: "Hello Darkness" - * }; - * ``` - */ -export declare interface AwaitResponse { - /** - * A string indicating that the promise was rejected. - */ - status: "fulfilled" | "rejected"; - /** - * The value that the promise was fulfilled with. - */ - value?: T; - /** - * The reason that the promise was rejected with. - */ - reason?: R; - /** - * Identifies if the promise was rejected (true) or was resolved (false/undefined) - */ - rejected?: boolean; -} - -/** - * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional - * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. - * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, - * and will reject with this first rejection message / error. - * If the runtime doesn't support the Promise.all it will fallback back to an asynchronous Promise implementation. - * - * @function - * @group Alias - * @group Promise - * @group All - * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - * @returns - *
    - *
  • An already resolved `Promise`, if the input passed is empty. - *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ - * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the - * promises reject. - *
- */ -export declare const createAllPromise: (input: Iterable>, timeout?: number) => IPromise; - -/** - * Returns a single Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations based on the current - * promise implementation. If the current implementation is synchronous then the chained operations will - * execute __synchronously__ in the same execution cycle as the final operation pending promises have resolved, - * or if the input contains no promises. If the current implementation is asynchronous then the chained - * operations will execute __asynchronously__ using the optional provided timeout value to schedule when the - * chained items will be executed or if the input contains no promises. - * It will resolve only after all of the input promises have either resolved or rejected, and will resolve with an array - * of {@link IPromiseResult } objects that each describe the outcome of each promise. - * @since 0.5.0 - * @group Alias - * @group Promise - * @group AllSettled - * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. - * - * @example - * ```ts - * const promises = [ - * createResolvedPromise(1), - * createResolvedPromise(2), - * createResolvedPromise(3), - * createRejectedPromise("error"), - * ]; - * - * const results = await createAllSettledPromise(promises); - * - * // results is: - * // [ - * // { status: "fulfilled", value: 1 }, - * // { status: "fulfilled", value: 2 }, - * // { status: "fulfilled", value: 3 }, - * // { status: "rejected", reason: "error" } - * // ] - * ``` - */ -export declare function createAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; - -/** - * The `createAnyPromise` method takes an iterable of promises as input and returns a single Promise. - * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. - * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an - * AggregateError containing an array of rejection reasons. - * @since 0.5.0 - * @group Alias - * @group Promise - * @group Any - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A new Promise that is: - * - Already rejected, if the iterable passed is empty. - * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value - * is the fulfillment value of the first promise that was fulfilled. - * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is - * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the - * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but - * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) - * rejected. - */ -export declare function createAnyPromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional - * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. - * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, - * and will reject with this first rejection message / error. - * When resolved or rejected any additional chained operations will execute __asynchronously__ using the optional - * timeout value to schedul when the chained item will be executed (eg. `then()`; `catch()`; `finally()`). - * - * @function - * @group Async - * @group Promise - * @group All - * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - * @returns - *
    - *
  • An already resolved `Promise`, if the input passed is empty. - *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ - * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the - * promises reject. - *
- */ -export declare const createAsyncAllPromise: (input: Iterable>, timeout?: number) => IPromise; - -/** - * Returns a single Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations based on the - * {@link createAsyncPromise | Asynchronous} promise implementation. Any chained operations will execute - * __asynchronously__ when the final operation pending promises have resolved, or if the input contains - * no promises. It will resolve only after all of the input promises have either resolved or rejected, - * and will resolve with an array of {@link IPromiseResult } objects that each describe the outcome of - * each promise. - * @since 0.5.0 - * @group Async - * @group Promise - * @group AllSettled - * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. - * - * @example - * ```ts - * const promises = [ - * createResolvedPromise(1), - * createResolvedPromise(2), - * createResolvedPromise(3), - * createRejectedPromise("error"), - * ]; - * - * const results = await createAllSettledPromise(promises); - * - * // results is: - * // [ - * // { status: "fulfilled", value: 1 }, - * // { status: "fulfilled", value: 2 }, - * // { status: "fulfilled", value: 3 }, - * // { status: "rejected", reason: "error" } - * // ] - * ``` - */ -export declare function createAsyncAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; - -/** - * The `createAsyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. - * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. - * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an - * AggregateError containing an array of rejection reasons. - * @since 0.5.0 - * @group Async - * @group Promise - * @group Any - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A new Promise that is: - * - Already rejected, if the iterable passed is empty. - * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value - * is the fulfillment value of the first promise that was fulfilled. - * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is - * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the - * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but - * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) - * rejected. - */ -export declare function createAsyncAnyPromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Creates an asynchronous Promise instance that when resolved or rejected will execute it's pending chained operations - * __asynchronously__ using the optional provided timeout value to schedule when the chained items will be ececuted. - * @group Async - * @group Promise - * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will - * cause the promise to be rejected. The return value of the executor is always ignored - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare function createAsyncPromise(executor: PromiseExecutor, timeout?: number): IPromise; - -/** - * The `createAsyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise - * settles with the eventual state of the first promise that settles. - * @description The `createAsyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first - * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). - * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to - * the first of these values found in the iterable. - * @since 0.5.0 - * @group Async - * @group Promise - * @group Race - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the - * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever - * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise is still - * asynchronously settled. - */ -export declare function createAsyncRacePromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Returns a single asynchronous Promise instance that is already rejected with the given reason. - * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule - * when then chained items will be executed. (eg. `catch()`; `finally()`). - * - * @function - * @group Async - * @group Promise - * @group Rejected - * @param reason - The rejection reason - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createAsyncRejectedPromise: (reason: any, timeout?: number) => IPromise; - -/** - * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is - * a promise then that promise is returned instead of creating a new asynchronous promise instance. - * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional - * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). - * - * @function - * @group Async - * @group Promise - * @group Resolved - * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createAsyncResolvedPromise: (value: T, timeout?: number) => IPromise; - -/** - * Returns an idle Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations __asynchronously__ - * using the `requestIdleCallback` API (if available) with the optional provided timeout value to - * schedule when the chained items will be executed. - * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, - * and will reject with this first rejection message / error. - * When resolved or rejected any additional chained operations will execute __asynchronously__ using - * the `requestIdleCallback` API (if available) with the optional provided timeout value to schedule - * when the chained items will be executed. (eg. `then()`; `catch()`; `finally()`). - * - * @function - * @group Idle - * @group Promise - * @group All - * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional deadline timeout to wait before processing the items, defaults to undefined. If the number of - * milliseconds represented by this parameter has elapsed and the callback has not already been called, then a task to execute - * the callback is queued in the event loop (even if doing so risks causing a negative performance impact). timeout must be a - * positive value or it is ignored. - * @returns - *
    - *
  • An already resolved `Promise`, if the input passed is empty. - *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ - * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the - * promises reject. - *
- */ -export declare const createIdleAllPromise: (input: Iterable>, timeout?: number) => IPromise; - -/** - * Returns a single Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations based on the - * {@link createIdlePromise | idle} promise implementation. Any chained operations will execute - * __asynchronously__ when the environment is idle as the final operation pending promises have resolved, - * or if the input contains no promises. It will resolve only after all of the input promises have either - * resolved or rejected, and will resolve with an array of {@link IPromiseResult } objects that each describe - * the outcome of each promise. - * @since 0.5.0 - * @group Idle - * @group Promise - * @group AllSettled - * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. - * - * @example - * ```ts - * const promises = [ - * createResolvedPromise(1), - * createResolvedPromise(2), - * createResolvedPromise(3), - * createRejectedPromise("error"), - * ]; - * - * const results = await createAllSettledPromise(promises); - * - * // results is: - * // [ - * // { status: "fulfilled", value: 1 }, - * // { status: "fulfilled", value: 2 }, - * // { status: "fulfilled", value: 3 }, - * // { status: "rejected", reason: "error" } - * // ] - * ``` - */ -export declare function createIdleAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; - -/** - * The `createIdleAnyPromise` method takes an iterable of promises as input and returns a single Promise. - * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. - * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an - * AggregateError containing an array of rejection reasons. - * @since 0.5.0 - * @group Idle - * @group Promise - * @group Any - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A new Promise that is: - * - Already rejected, if the iterable passed is empty. - * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value - * is the fulfillment value of the first promise that was fulfilled. - * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is - * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the - * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but - * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) - * rejected. - */ -export declare function createIdleAnyPromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Creates an idle Promise instance that when resolved or rejected will execute it's pending chained operations - * __asynchronously__ using the `requestIdleCallback` API (if available) with the optional provided timeout value to - * schedule when the chained items will be executed. When `requestIdleCallback` is not available this becomes the same as - * `createAsyncPromise` which uses `setTimeout` to schedule executions. - * @group Idle - * @group Promise - * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will - * cause the promise to be rejected. The return value of the executor is always ignored - * @param timeout - Optional deadline timeout to wait before processing the items, defaults to undefined. If the number of - * milliseconds represented by this parameter has elapsed and the callback has not already been called, then a task to execute - * the callback is queued in the event loop (even if doing so risks causing a negative performance impact). timeout must be a - * positive value or it is ignored. - */ -export declare function createIdlePromise(executor: PromiseExecutor, timeout?: number): IPromise; - -/** - * The `createIdleRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise - * settles with the eventual state of the first promise that settles. - * @description The `createIdleRacePromise` method is one of the promise concurrency methods. It's useful when you want the first - * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). - * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to - * the first of these values found in the iterable. - * @since 0.5.0 - * @group Idle - * @group Promise - * @group Race - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the - * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever - * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle - * asynchronously when the system detects that the runtime is idle. - */ -export declare function createIdleRacePromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Returns an idle Promise instance that is already rejected with the given reason. - * Any chained operations will execute __asynchronously__ using the o`requestIdleCallback` API - * (if available) with the optional provided timeout value to schedule when the chained items will - * be executed. (eg. `catch()`; `finally()`). - * - * @function - * @group Idle - * @group Promise - * @group Rejected - * @param reason - The rejection reason - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createIdleRejectedPromise: (reason: any, timeout?: number) => IPromise; - -/** - * Returns an idle Promise instance that is already resolved with the given value. If the value passed is - * a promise then that promise is returned instead of creating a new asynchronous promise instance. - * If a new instance is returned then any chained operations will execute __asynchronously__ using the - * `requestIdleCallback` API (if available) with the optional provided timeout value to schedule when - * the chained items will be executed. (eg. `then()`; `finally()`). - * - * @function - * @group Idle - * @group Promise - * @group Resolved - * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createIdleResolvedPromise: (value: T, timeout?: number) => IPromise; - -/** - * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional - * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. - * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, - * and will reject with this first rejection message / error. - * If the runtime doesn't support the Promise.all it will fallback back to an asynchronous Promise implementation. - * @group Alias - * @group Promise - * @group All - * @group Native - * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - * @returns - *
    - *
  • An already resolved `Promise`, if the input passed is empty. - *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ - * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the - * promises reject. - *
- */ -export declare function createNativeAllPromise(input: Iterable>, timeout?: number): IPromise; - -/** - * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations using {@link createNativePromise | native} - * environment promise implementation, if the runtime does not provide any native then the optional provided - * timeout value will be used to schedule when the chained items will be executed or if the input contains no promises. - * It will resolve only after all of the input promises have either resolved or rejected, and will resolve with an array - * of {@link IPromiseResult } objects that each describe the outcome of each promise. - * @since 0.5.0 - * @group Alias - * @group Promise - * @group AllSettled - * @group Native - * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. - * - * @example - * ```ts - * const promises = [ - * createNativeResolvedPromise(1), - * createNativeResolvedPromise(2), - * createNativeResolvedPromise(3), - * createNativeRejectedPromise("error"), - * ]; - * - * const results = await createNativeAllSettledPromise(promises); - * - * // results is: - * // [ - * // { status: "fulfilled", value: 1 }, - * // { status: "fulfilled", value: 2 }, - * // { status: "fulfilled", value: 3 }, - * // { status: "rejected", reason: "error" } - * // ] - * ``` - */ -export declare function createNativeAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; - -/** - * The `createNativeAnyPromise` method takes an iterable of promises as input and returns a single Promise. - * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. - * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an - * AggregateError containing an array of rejection reasons. - * @since 0.5.0 - * @group Alias - * @group Promise - * @group Any - * @group Native - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A new Promise that is: - * - Already rejected, if the iterable passed is empty. - * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value - * is the fulfillment value of the first promise that was fulfilled. - * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is - * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the - * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but - * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) - * rejected. - */ -export declare function createNativeAnyPromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Creates a Promise instance that when resolved or rejected will execute it's pending chained operations using the - * available native Promise implementation. - * If runtime does not support native `Promise` class (or no polyfill is available) this function will fallback to using - * `createAsyncPromise` which will resolve them __asynchronously__ using the optional provided timeout value to - * schedule when the chained items will be executed. - * @group Alias - * @group Promise - * @group Native - * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will - * cause the promise to be rejected. The return value of the executor is always ignored - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare function createNativePromise(executor: PromiseExecutor, timeout?: number): IPromise; - -/** - * The `createNativeRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise - * settles with the eventual state of the first promise that settles. - * @description The `createNativeRacePromise` method is one of the promise concurrency methods. It's useful when you want the first - * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). - * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to - * the first of these values found in the iterable. - * @since 0.5.0 - * @group Alias - * @group Promise - * @group Race - * @group Native - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the - * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever - * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle - * asynchronously. - */ -export declare function createNativeRacePromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Returns a single asynchronous Promise instance that is already rejected with the given reason. - * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule - * when then chained items will be executed. (eg. `catch()`; `finally()`). - * - * @function - * @group Alias - * @group Promise - * @group Rejected - * @group Native - * @param reason - The rejection reason - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createNativeRejectedPromise: (reason: any, timeout?: number) => Promise; - -/** - * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is - * a promise then that promise is returned instead of creating a new asynchronous promise instance. - * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional - * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). - * - * @function - * @group Alias - * @group Promise - * @group Resolved - * @group Native - * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createNativeResolvedPromise: (value: T, timeout?: number) => Promise; - -/** - * Creates a Promise instance using the current default promise creator that when resolved or rejected will execute - * it's pending chained operations. - * @group Alias - * @group Promise - * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will - * cause the promise to be rejected. The return value of the executor is always ignored - * @param timeout - [Optional] timeout to wait before processing the items, defaults to zero. - */ -export declare function createPromise(executor: PromiseExecutor, timeout?: number): IPromise; - -/** - * The `createRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise - * settles with the eventual state of the first promise that settles. - * @description The `createRacePromise` method is one of the promise concurrency methods. It's useful when you want the first - * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). - * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to - * the first of these values found in the iterable. - * @since 0.5.0 - * @group Alias - * @group Promise - * @group Race - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the - * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever - * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle - * based on the current promise implementation. - */ -export declare function createRacePromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Returns a single asynchronous Promise instance that is already rejected with the given reason. - * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule - * when then chained items will be executed. (eg. `catch()`; `finally()`). - * - * @function - * @group Alias - * @group Promise - * @group Rejected - * @param reason - The rejection reason - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createRejectedPromise: (reason: any, timeout?: number) => IPromise; - -/** - * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is - * a promise then that promise is returned instead of creating a new asynchronous promise instance. - * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional - * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). - * - * @function - * @group Alias - * @group Promise - * @group Resolved - * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - */ -export declare const createResolvedPromise: (value: T, timeout?: number) => IPromise; - -/** - * Returns a single synchronous Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations __synchronously__ in the same - * execution cycle as the final operation pending promises have resolved, or if the input contains no promises. - * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, - * and will reject with this first rejection message / error. - * When resolved or rejected any additional chained operations will execute __synchronously__ at the point of - * being added (eg. `then()`; `catch()`; `finally()`). - * - * @function - * @group Synchronous - * @group Promise - * @group All - * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @returns - *
    - *
  • An already resolved `Promise`, if the input passed is empty. - *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ - * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the - * promises reject. - *
- */ -export declare const createSyncAllPromise: (input: Iterable>) => IPromise; - -/** - * Returns a single Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations based on the - * {@link createSyncPromise | synchronous} promise implementation. Any chained operations will execute - * __synchronously__ in the same execution cycle as the final operation pending promises have resolved, - * or if the input contains no promises. It will resolve only after all of the input promises have either - * resolved or rejected, and will resolve with an array of {@link IPromiseResult } objects that each describe - * the outcome of each promise. - * @since 0.5.0 - * @group Synchronous - * @group Promise - * @group AllSettled - * @param values - The iterator of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. - * - * @example - * ```ts - * const promises = [ - * createResolvedPromise(1), - * createResolvedPromise(2), - * createResolvedPromise(3), - * createRejectedPromise("error"), - * ]; - * - * const results = await createAllSettledPromise(promises); - * - * // results is: - * // [ - * // { status: "fulfilled", value: 1 }, - * // { status: "fulfilled", value: 2 }, - * // { status: "fulfilled", value: 3 }, - * // { status: "rejected", reason: "error" } - * // ] - * ``` - */ -export declare function createSyncAllSettledPromise(values: Iterable>, timeout?: number): IPromise>[]>; - -/** - * The `createSyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. - * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. - * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an - * AggregateError containing an array of rejection reasons. - * @since 0.5.0 - * @group Synchronous - * @group Promise - * @group Any - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A new Promise that is: - * - Already rejected, if the iterable passed is empty. - * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value - * is the fulfillment value of the first promise that was fulfilled. - * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is - * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the - * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but - * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) - * rejected. - */ -export declare function createSyncAnyPromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Creates a synchronous Promise instance that when resolved or rejected will execute it's pending chained operations - * __synchronously__ in the same execution cycle as the operation that calls the `executors`, `resolve` or `reject` functions. - * - * @group Synchronous - * @group Promise - * @param executor - The function to be executed during the creation of the promise. Any errors thrown in the executor will - * cause the promise to be rejected. The return value of the executor is always ignored - */ -export declare function createSyncPromise(executor: PromiseExecutor): IPromise; - -/** - * The `createSyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise - * settles with the eventual state of the first promise that settles. - * @description The `createSyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first - * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). - * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to - * the first of these values found in the iterable. - * @since 0.5.0 - * @group Synchronous - * @group Promise - * @group Race - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the - * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever - * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise will settle - * synchronously. - */ -export declare function createSyncRacePromise(values: Iterable>, timeout?: number): IPromise>; - -/** - * Returns a single synchronous Promise instance that is already rejected with the given reason. - * Any chained operations will execute __synchronously__ at the point of being added (eg. `catch()`; `finally()`). - * - * @function - * @group Synchronous - * @group Promise - * @group Rejected - * @param reason - The rejection reason - */ -export declare const createSyncRejectedPromise: (reason: any) => IPromise; - -/** - * Returns a single synchronous Promise instance that is already resolved with the given value. If the value passed is - * a promise then that promise is returned instead of creating a new synchronous promise instance. - * If a new instance is returned then any chained operations will execute __synchronously__ at the point of being - * added (calling `then()`). - * - * @function - * @group Synchronous - * @group Promise - * @group Resolved - * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. - */ -export declare const createSyncResolvedPromise: (value: T) => IPromise; - -/** - * Create a Task Scheduler using the optional promise implementation and scheduler name. - * The newPromise can be any value promise creation function, where the execution of the - * queued tasks will be processed based on how the promise implementation processes it's - * chained promises (asynchrounsly; synchronously; idle processing, etc) - * - * The functions used to start each task my return a result (synchronous execution) or an - * {@link IPromise}, `PromiseLike` or `Promise` result (asynchronous execution). - * - * Each task is executed in the order that it was queued and the provided `startTask` function - * will not be called until all previous tasks have completed (whther they resolve or reject). - * The result from any previous task does not affect and is not passed to any later scheduled - * task, if you need this capability then your `startTask` functions will need to co-operate to - * share any common context. - * - * By default, queued tasks which have either been "waiting" to run or have been running longer - * then 10 minutes will be Auto-Rejected to try and free up resources. If a task is running when - * it rejected then it will continue to "run" based on whatever operation it's `startTask` is - * performing. If a task has not yet had it's `startTask` function called it will never get called. - * In both cases the `IPromise` returned by the call to {@link ITaskScheduler.queue | queue} the - * task will be `rejected`. You can change this default time, including disabling completly via - * the {@link ITaskScheduler.setStaleTimeout | setStaleTimeout} - * function. - * @since 0.2.0 - * @group Scheduler - * @param newPromise - The function to use for creating a new promise when required, if not - * provided this will default to {@link createPromise} which will use the default registered - * promise creation function which defaults to runtime native promises or async Promise if not - * supported by the runtime. - * @param name - The name you want to associated with this scheduler, mostly useful for debugging - * @returns A new ITaskScheduler instance - * @example - * ```ts - * let scheduler = createTaskScheduler(); - * - * // Schedule a task using the ts-async helper promise functions - * scheduler.queue(() => { - * return createPromise((resolve, reject) => { - * scheduleTimeout(() => { - * // Do something after a delay - * }, 100); - * }); - * }); - * - * // Schedule an asynchronous task which uses async/await - * scheduler.queue(async () => { - * // This task will only execute after the previous task has completed - * await performAnotherAsyncTask(); - * }); - * - * // Schedule a synchronous task that executes and completes immediately - * scheduled.queue(() => { - * // Do some synchronous task - * return 42; - * }); - * - * // Schedule an asynchronous task which returns a promise - * scheduled.queue(() => { - * return doAwait(fetch("https://github.com/nevware21/ts-async/blob/main/README.md"), (response) => { - * let theReadMe = response.text(); - * // Do something with the readme - * }); - * }); - * ``` - */ -export declare function createTaskScheduler(newPromise?: (executor: PromiseExecutor, timeout?: number) => IPromise, name?: string): ITaskScheduler; - -/** - * Creates a Promise instance that resolve or reject after the specified timeout. - * @since 0.5.0 - * @group Timeout - * @group Promise - * @param timeout - The timeout in milliseconds to wait before resolving or rejecting the promise. - * @param resolveReject - [Optional] If true the promise will resolve, otherwise it will reject. - * @param message - [Optional] The message to use when rejecting the promise, if not supplied (or - * undefined) the default message will be used. - * @returns A promise that will resolve or reject after the specified timeout. - * @example - * ```ts - * // Rejects after 100ms with default message - * const result = await createTimeoutPromise(100); - * // Throws an Error: Timeout of 100ms exceeded - * - * // Resolves after 100ms with default message - * const result = await createTimeoutPromise(100, true); - * console.log(result); // Timeout of 100ms exceeded - * - * // Rejects after 100ms with default message - * const result = await createTimeoutPromise(100, false); - * // throws an Error: Timeout of 100ms exceeded - * - * // Resolves after 100ms with default message - * const result = await createTimeoutPromise(100, true); - * console.log(result); // Timeout of 100ms exceeded - * - * // Rejects after 100ms with the message "Hello" - * const result = await createTimeoutPromise(100, false, "Hello"); - * // throws an Error: Hello - * - * // Resolves after 100ms with the message "Hello" - * const result = await createTimeoutPromise(100, true, "Hello"); - * console.log(result); // Hello - * - * // Resolves after 100ms with the message "Hello" - * doAwait(createTimeoutPromise(100, true, "Hello"), (result) => { - * console.log(result); // Hello - * }); - * - * // Rejects after 100ms with the message "Hello" - * doAwait(createTimeoutPromise(100, false, "Hello"), (result) => { - * // Not called - * }, (err) => { - * console.log(err); // Hello - * }); - * - * // Rejects after 100ms with the message "Hello" - * doAwaitResult(createTimeoutPromise(100, false, "Hello"), (result) => { - * console.log(result.rejected); // true - * console.log(result.reason); // Hello - * }); - * ``` - */ -export declare function createTimeoutPromise(timeout: number, resolveReject?: boolean, message?: T): IPromise; - -/** - * Wait for the promise to resolve or reject, if resolved the callback function will be called with it's value and if - * rejected the rejectFn will be called with the reason. If the passed promise argument is not a promise the callback - * will be called synchronously with the value. - * @group Await Helper - * @param value - The value or promise like value to wait for - * @param resolveFn - The callback to call on the promise successful resolving. - * @param rejectFn - The callback to call when the promise rejects - * @param finallyFn - The callback to call once the promise has resolved or rejected - * @returns The passed value, if it is a promise and there is either a resolve or reject handler - * then it will return a chained promise with the value from the resolve or reject handler (depending - * whether it resolve or rejects) - * @example - * ```ts - * let promise = createPromise((resolve, reject) => { - * resolve(42); - * }); - * - * // Handle via a chained promise - * let chainedPromise = promise.then((value) => { - * // Do something with the value - * }); - * - * // Handle via doAwait - * doAwait(promise, (value) => { - * // Do something with the value - * }); - * - * // It can also handle the raw value, so you could process the result of either a - * // synchrounous return of the value or a Promise - * doAwait(42, (value) => { - * // Do something with the value - * }); - * ``` - */ -export declare function doAwait(value: T | IPromise | PromiseLike, resolveFn: ResolvedPromiseHandler, rejectFn?: RejectedPromiseHandler, finallyFn?: FinallyPromiseHandler): TResult1 | TResult2 | IPromise; - -/** - * Wait for the promise to resolve or reject, if resolved the callback function will be called with it's value and if - * rejected the rejectFn will be called with the reason. If the passed promise argument is not a promise the callback - * will be called synchronously with the value. - * @group Await Helper - * @param value - The value or promise like value to wait for - * @param resolveFn - The callback to call on the promise successful resolving. - * @param rejectFn - The callback to call when the promise rejects - * @param finallyFn - The callback to call once the promise has resolved or rejected - * @returns The passed value, if it is a promise and there is either a resolve or reject handler - * then it will return a chained promise with the value from the resolve or reject handler (depending - * whether it resolve or rejects) - * @example - * ```ts - * let promise = createPromise((resolve, reject) => { - * resolve(42); - * }); - * - * // Handle via a chained promise - * let chainedPromise = promise.then((value) => { - * // Do something with the value - * }); - * - * // Handle via doAwait - * doAwait(promise, (value) => { - * // Do something with the value - * }); - * - * // It can also handle the raw value, so you could process the result of either a - * // synchrounous return of the value or a Promise - * doAwait(42, (value) => { - * // Do something with the value - * }); - * ``` - */ -export declare function doAwait(value: T | PromiseLike, resolveFn: ResolvedPromiseHandler, rejectFn?: RejectedPromiseHandler, finallyFn?: FinallyPromiseHandler): TResult1 | TResult2 | PromiseLike; - -/** - * Helper to coallesce the promise resolved / reject into a single callback to simplify error handling. - * @group Await Helper - * @param value - The value or promise like value to wait - * @param cb - The callback function to call with the resulting value, if the value is not a - * promise like value then the callback is called synchronously, if the value is a promise then - * the callback will be called once the promise completes the resulting value will be passed as an - * IAwaitResponse instance, it will be called whether any promise resolves or rejects. - * @returns The value returned by the `cb` callback function, if the value is a promise then the return value - * of the callback will be returned as a promise whether the callback returns a promise or not. - * @example - * ```ts - * let promise = createPromise((resolve, reject) => { - * resolve(42); - * }); - * - * // Handle via doAwaitResponse - * doAwaitResponse(promise, (value) => { - * if (!value.rejected) { - * // Do something with the value - * } else { - * // Do something with the reason - * } - * }); - * - * // It can also handle the raw value, so you could process the result of either a - * // synchrounous return of the value or a Promise - * doAwaitResponse(42, (value) => { - * if (!value.rejected) { - * // Do something with the value - * } else { - * // This will never be true as the value is not a promise - * } - * }); - * ``` - */ -export declare function doAwaitResponse(value: T | IPromise | PromiseLike, cb: (response: AwaitResponse) => T | TResult1 | TResult2 | IPromise | PromiseLike): T | TResult1 | TResult2 | IPromise; - -/** - * Helper to coallesce the promise resolved / reject into a single callback to simplify error handling. - * @group Await Helper - * @param value - The value or promise like value to wait for - * @param cb - The callback function to call with the resulting value, if the value is not a - * promise like value then the callback is called synchronously, if the value is a promise then - * the callback will be called once the promise completes the resulting value will be passed as an - * IAwaitResponse instance, it will be called whether any promise resolves or rejects. - * @returns The value returned by the `cb` callback function, if the value is a promise then the return value - * of the callback will be returned as a promise whether the callback returns a promise or not. - * @example - * ```ts - * let promise = createPromise((resolve, reject) => { - * resolve(42); - * }); - * - * // Handle via doAwaitResponse - * doAwaitResponse(promise, (value) => { - * if (!value.rejected) { - * // Do something with the value - * } else { - * // Do something with the reason - * } - * }); - * - * // It can also handle the raw value, so you could process the result of either a - * // synchrounous return of the value or a Promise - * doAwaitResponse(42, (value) => { - * if (!value.rejected) { - * // Do something with the value - * } else { - * // This will never be true as the value is not a promise - * } - * }); - * ``` - */ -export declare function doAwaitResponse(value: T | PromiseLike, cb: (response: AwaitResponse) => T | TResult1 | TResult2 | PromiseLike): T | TResult1 | TResult2 | PromiseLike; - -/** - * Wait for the promise to resolve or reject and then call the finallyFn. If the passed promise argument is not a promise the callback - * will be called synchronously with the value. If the passed promise doesn't implement finally then a finally implementation will be - * simulated using then(..., ...). - * @group Await Helper - * @param value - The value or promise like value to wait for - * @param finallyFn - The finally function to call once the promise has resolved or rejected - */ -export declare function doFinally(value: T | IPromise | PromiseLike, finallyFn: FinallyPromiseHandler): T | IPromise; - -/** - * Wait for the promise to resolve or reject and then call the finallyFn. If the passed promise argument is not a promise the callback - * will be called synchronously with the value. If the passed promise doesn't implement finally then a finally implementation will be - * simulated using then(..., ...). - * @group Await Helper - * @param value - The value or promise like value to wait for - * @param finallyFn - The finally function to call once the promise has resolved or rejected - */ -export declare function doFinally(value: T | PromiseLike, finallyFn: FinallyPromiseHandler): T | PromiseLike; - -/** - * Performs a while loop, calling the provided `callbackFn` function until the `state.isDone` - * property is set to `true` or the optional `isDOneFn` returns `true`. The callback function will - * receive a single {@link IWhileState | state} argument and may return either a value or a promise, - * if a promise is returned the while loop will wait until the promise is resolved before calling - * the callback function again. If the callback function never returns a promise the while loop - * will be executed synchronous and last value returned by the callback will be returned, if the - * callback function returns a promise the while loop will be asynchronous and an {@link IPromise} - * will be returned and resolved with the last value returned by the callback or rejected if the - * callback promise rejects or throws an error. - * @since 0.5.0 - * @group Loop - * @typeParam T - Identifies the element type returned by the callback function. - * @param callbackFn - A function that will be called until the `state.isDone` flag is set to `true` - * the function will receive a single {@link IWhileState | state} argument. The callback function - * may return either a value or a promise, if a promise is returned the while loop will wait - * until the promise is resolved before calling the callback function again. - * @param isDoneFn - An optional function that will be called after the callback function is called, - * that can be used to stop the while loop. The function will receive a single {@link IWhileState | state} - * argument. If the function returns `true` the while loop will stop, otherwise the while loop will continue. - * @param thisArg - An object to which the this keyword can refer in the callbackfn function. - * If thisArg is omitted, null or undefined the array will be used as the this value. - * @remarks - * - If an `isDoneFn` is provided the `state.isDone` property will be set to the provided value and - * is accessible withing the callback function. The callbackFn may overwrite the value of the - * `state.isDone` property within the callback function with a boolean value or another function that - * returns a boolean value. - * - The callback function is called until until the `state.isDone` property is set to `true` or if - * `state.isDone` is a function until the function returns `true`. - * - The callback function will receive a single {@link IWhileState | state} argument that contains - * the following properties: - * - `iter` - The zero-based iteration count, which is incremented after each call to the `callbackFn` - * and any `isDone` function (if provided), the `iter` property is accessible withing the callback - * function and may be overwritten within the callback function. - * - `res` - The last resolved result value returned by the `callbackFn` function. - * - `isDone` - A boolean value or a callback function that will be called to check if the while loop - * should stop, the `isDone` property is accessible withing the callback function and may be - * overwritten within the callback function. - * - The callback function may return either a value or a promise, if a promise is returned the while - * loop will wait until the promise is resolved before calling the callback function again. - * - If the callback function throws an error when executing `synchronously` the exception will - * also be thrown `synchronously` otherwise the returned promise will be rejected with the error. - * @example - * ```ts - * // Synchronous example - * const result = doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function - * if (state.idx < 10) { - * // Logs each iteration index (will be called synchronously) - * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * console.log(state.idx); - * } else { - * state.isDone = true; - * return "Hello"; - * } - * }); - * - * console.log(result); // returns Hello after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * - * // Synchronous example with isDoneFn - * const result = doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function - * if (state.idx < 10) { - * // Logs each iteration index (will be called synchronously) - * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * console.log(state.idx); - * } else { - * return "Hello"; - * } - * }, (state) => state.idx > 10); - * console.log(result); // returns Hello after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * - * // Asynchronous examples - * const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function - * if (state.idx < 10) { - * // Logs each iteration index - * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 calling the callback function synchronously - * console.log(state.idx); - * // Returning a promise will cause `doWhileAsync` to return a promise to the caller - * // and wait for the promise to resolve before calling the callback function again. - * return createTimeoutPromise(10, true, state.idx); - * } - * - * state.isDone = true; - * return createResolvedPromise("Darkness"); - * }); - * console.log(result); // Darkness - * - * // Asynchronous example with isDoneFn - * const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function - * if (state.idx < 10) { - * // Logs each iteration index - * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 calling the callback function synchronously - * console.log(state.idx); - * // Returning a promise will cause `doWhileAsync` to return a promise to the caller - * // and wait for the promise to resolve before calling the callback function again. - * return createTimeoutPromise(10, true, state.idx); - * } - * - * return createResolvedPromise("Darkness"); - * }, (state) => state.idx > 10); - * console.log(result); // returns Darkness after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * - * // Combination Synchronous and Asynchronous example - * const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function - * if (state.idx < 10) { - * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * // Logs each iteration index (will be called synchronously) - * console.log(state.idx); - * } else { - * state.isDone = true; - * // Returning a promise will cause `doWhileAsync` to return a promise to the caller - * // and wait for the promise to resolve before resolving the returned promise. - * return createResolvedPromise("my old friend"); - * } - * }); - * - * console.log(result); // my old friend - * - * // Asynchronous example using await - * const result = await doWhileAsync(async (state) => { - * if (state.idx < 10) { - * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * // Logs each iteration index (will be called synchronously) - * await createTimeoutPromise(10, true, state.idx); - * } else { - * state.isDone = true; - * // Returning a promise will cause `doWhileAsync` to return a promise to the caller - * // and wait for the promise to resolve before resolving the returned promise. - * return await createResolvedPromise("my old friend"); - * } - * }); - * - * console.log(result); // my old friend - * - * // Asynchronous example using await and dynamically setting the isDone function - * const result = await doWhileAsync(async (state) => { - * // dynamically set the isDone function - * if (state.idx < 10) { - * state.isDone = () => return false; - * // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - * // Logs each iteration index (will be called synchronously) - * await createTimeoutPromise(10, true, state.idx); - * } else { - * state.isDone = () => return true; - * // Returning a promise will cause `doWhileAsync` to return a promise to the caller - * // and wait for the promise to resolve before resolving the returned promise. - * return await createResolvedPromise("my old friend"); - * } - * }); - * - * console.log(result); // my old friend - * ``` - */ -export declare function doWhileAsync(callbackFn: (state: IWhileState) => T | IPromise | PromiseLike, isDoneFn?: (state: IWhileState) => boolean | void | IPromise | PromiseLike, thisArg?: any): T | IPromise; - -/** - * This defines the handler function that is called via the finally when the promise is resolved or rejected - */ -export declare type FinallyPromiseHandler = (() => void) | undefined | null; - -/** - * Create a Promise object that represents the eventual completion (or failure) of an asynchronous operation and its resulting value. - * This interface definition, closely mirrors the typescript / javascript PromiseLike and Promise definitions as well as providing - * simular functions as that provided by jQuery deferred objects. - * - * The returned Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers - * with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous - * methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point - * in the future. - * - * A Promise is in one of these states: - *
    - *
  • pending: initial state, neither fulfilled nor rejected. - *
  • fulfilled: meaning that the operation was completed successfully. - *
  • rejected: meaning that the operation failed. - *
- * - * A pending promise can either be fulfilled with a value or rejected with a reason (error). When either of these options happens, the - * associated handlers queued up by a promise's then method are called synchronously. If the promise has already been fulfilled or rejected - * when a corresponding handler is attached, the handler will be called synchronously, so there is no race condition between an asynchronous - * operation completing and its handlers being attached. - * - * As the `then()` and `catch()` methods return promises, they can be chained. - * @typeParam T - Identifies the expected return type from the promise - */ -export declare interface IPromise extends PromiseLike, Promise { - /** - * Returns a string representation of the current state of the promise. The promise can be in one of four states. - *
    - *
  • "pending": The promise is not yet in a completed state (neither "rejected"; or "resolved").
    • - *
  • "resolved": The promise is in the resolved state.
    • - *
  • "rejected": The promise is in the rejected state.
    • - *
- * @example - * ```ts - * let doResolve; - * let promise: IPromise = createSyncPromise((resolve) => { - * doResolve = resolve; - * }); - * - * let state: string = promise.state(); - * console.log("State: " + state); // State: pending - * doResolve(true); // Promise will resolve synchronously as it's a synchronous promise - * console.log("State: " + state); // State: resolved - * ``` - */ - state?: string; - /** - * Attaches callbacks for the resolution and/or rejection of the Promise. - * @param onResolved - The callback to execute when the Promise is resolved. - * @param onRejected - The callback to execute when the Promise is rejected. - * @returns A Promise for the completion of which ever callback is executed. - * @example - * ```ts - * const promise1 = createPromise((resolve, reject) => { - * resolve('Success!'); - * }); - * - * promise1.then((value) => { - * console.log(value); - * // expected output: "Success!" - * }); - * ``` - */ - then(onResolved?: ResolvedPromiseHandler, onRejected?: RejectedPromiseHandler): IPromise; - /** - * Attaches callbacks for the resolution and/or rejection of the Promise. - * @param onResolved - The callback to execute when the Promise is resolved. - * @param onRejected - The callback to execute when the Promise is rejected. - * @returns A Promise for the completion of which ever callback is executed. - * @example - * ```ts - * const promise1 = createPromise((resolve, reject) => { - * resolve('Success!'); - * }); - * - * promise1.then((value) => { - * console.log(value); - * // expected output: "Success!" - * }); - * ``` - */ - then(onResolved?: ResolvedPromiseHandler, onRejected?: RejectedPromiseHandler): PromiseLike; - /** - * Attaches callbacks for the resolution and/or rejection of the Promise. - * @param onResolved - The callback to execute when the Promise is resolved. - * @param onRejected - The callback to execute when the Promise is rejected. - * @returns A Promise for the completion of which ever callback is executed. - * @example - * ```ts - * const promise1 = createPromise((resolve, reject) => { - * resolve('Success!'); - * }); - * - * promise1.then((value) => { - * console.log(value); - * // expected output: "Success!" - * }); - * ``` - */ - then(onResolved?: ResolvedPromiseHandler, onRejected?: RejectedPromiseHandler): IPromise; - /** - * Attaches a callback for only the rejection of the Promise. - * @param onRejected - The callback to execute when the Promise is rejected. - * @returns A Promise for the completion of the callback. - * @example - * ```ts - * const promise1 = createPromise((resolve, reject) => { - * throw 'Uh-oh!'; - * }); - * - * promise1.catch((error) => { - * console.error(error); - * }); - * // expected output: Uh-oh! - * ``` - */ - catch(onRejected?: ((reason: any) => TResult | IPromise) | undefined | null): IPromise; - /** - * Attaches a callback for only the rejection of the Promise. - * @param onRejected - The callback to execute when the Promise is rejected. - * @returns A Promise for the completion of the callback. - * @example - * ```ts - * const promise1 = createPromise((resolve, reject) => { - * throw 'Uh-oh!'; - * }); - * - * promise1.catch((error) => { - * console.error(error); - * }); - * // expected output: Uh-oh! - * ``` - */ - catch(onRejected?: ((reason: any) => TResult | IPromise) | undefined | null): PromiseLike; - /** - * Attaches a callback for only the rejection of the Promise. - * @param onRejected - The callback to execute when the Promise is rejected. - * @returns A Promise for the completion of the callback. - * @example - * ```ts - * const promise1 = createPromise((resolve, reject) => { - * throw 'Uh-oh!'; - * }); - * - * promise1.catch((error) => { - * console.error(error); - * }); - * // expected output: Uh-oh! - * ``` - */ - catch(onRejected?: ((reason: any) => TResult | IPromise) | undefined | null): IPromise; - /** - * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The - * resolved value cannot be modified from the callback. - * @param onfinally - The callback to execute when the Promise is settled (fulfilled or rejected). - * @returns A Promise for the completion of the callback. - * @example - * ```ts - * function doFunction() { - * return createPromise((resolve, reject) => { - * if (Math.random() > 0.5) { - * resolve('Function has completed'); - * } else { - * reject(new Error('Function failed to process')); - * } - * }); - * } - * - * doFunction().then((data) => { - * console.log(data); - * }).catch((err) => { - * console.error(err); - * }).finally(() => { - * console.log('Function processing completed'); - * }); - * ``` - */ - finally(onfinally?: FinallyPromiseHandler): IPromise; -} - -/** - * The result of a promise. It can either be fulfilled with a value, or rejected with a reason. - * @since 0.5.0 - * @group Promise - * @typeParam T - The type of the fulfilled value. - * @typeParam U - The type of the rejected reason. - * - * @example - * ```ts - * const result: IPromiseResult = { - * status: "fulfilled", - * value: 42 - * }; - * - * const result: IPromiseResult = { - * status: "rejected", - * reason: "Hello Darkness" - * }; - * ``` - */ -export declare interface IPromiseResult { - /** - * A string indicating whether the promise was fulfilled or rejected - */ - status: "fulfilled" | "rejected"; - /** - * The value that the promise was fulfilled with. - */ - value?: T; - /** - * The reason that the promise was rejected with. - */ - reason?: any; -} - -/** - * Defines a Task Scheduler that uses IPromise implementations to serialize the execution of the tasks. - * Each added task will not get executed until the previous task has completed. - * @since 0.2.0 - * @group Scheduler - */ -export declare interface ITaskScheduler { - /** - * Identifies if this scheduler is currently idle (`true`) or has waiting or currently processing tasks (`false`). - * @example - * ```ts - * let scheduler = createTaskScheduler(); - * - * // Check idle state - * scheduler.idle; // true - * - * let queuedTask = scheduler.queue(() => { - * // Return a promise - * return createPromise((resolve) => { - * // Wait some time then resolve - * }); - * }); - * - * // Check idle state - * scheduler.idle; // false - * - * // Wait for the queued task to complete - * await queuedTask; - * - * // Check idle state - * scheduler.idle; // true - * ``` - */ - readonly idle: boolean; - /** - * Queue a task to be scheduled for execution, once the task has completed the returned IPromise - * will be resolved / rejected - * @param theTask - The function to call to start the task - * @param taskName - The optional task name for the task, useful for debugging. - * @param timeout - Specify a specific timeout for the task, the timeout will only apply once the task is started. - * @returns A new promise that will be resolved (or rejected) once the task has been executed or aborted. - * @example - * ```ts - * let scheduler = createTaskScheduler(); - * - * // Schedule an async task, where the function returns a Promise or PromiseLike result - * let queuedTask = scheduler.queue(runSomeAsyncTask()); - * - * // Schedule an async task, where the function returns a Promise or PromiseLike result - * let queuedTask2 = scheduler.queue(runAnotherAsyncTask()); - * - * // Both queuedTask and queuedTask2 are Promise implementation (based on the type used by the scheduler) - * // You can now treat these like any promose to wait for them to be resolve / rejected - * // Somewhere else in your code using either `await`, `doAwait`, doAwaitResponse`, `doFinally`, `then`, `catch` - * // or `finally` - * doAwait(queuedTask, (result1) => { - * // queued task 1 is now complete - * // queued task 2 is now scheduled to run (or is already running) - * }); - * - * doAwait(queuedTask2, (result1) => { - * // Both task 1 and 2 have completed - * // As task 2 did not start until task 1 finished - * }); - * - * // This Will also work and will not cause a deadlock - * // But task 2 will still not start until task 1 has completed - * let task2Result = await queuedTask2; - * - * // Now get the task 1 response - * let task1Result = await queuedTask1; - * ``` - */ - queue: (theTask: StartQueuedTaskFn, taskName?: string, timeout?: number) => IPromise; - /** - * Set the timeout to reject and remove any stale running tasks to avoid filling up memory - * with blocked tasks. - * @param staleTimeout - Identifies the maximum that a task can be running or waiting to start, - * defaults to 10 minutes. If the value is set to zero or less the stale timeout will never - * abort waiting tasks. - * @param staleCheckPeriod - Identifes how oftem the queue's should be checked for stale tasks, - * defaults to 1/10th of the staleTimeout when not specified. This directly sets the asynchronous - * timeout value. - * @example - * ```ts - * let secheduler = createTaskScheduler(); - * - * // Set the stale task timeout to 1 second, this will check every 100ms - * // for any long waiting / executing tasks and "reject" them. - * scheduler.setStaleTimeout(1000); - * - * // Set the stale task timeout to 5 minutes (300 seconds), this will check every 1 minute (60 seconds) - * // for any long waiting / executing tasks and "reject" them. - * scheduler.setStaleTimeout(300000, 60000); - * ``` - */ - setStaleTimeout: (staleTimeout: number, staleCheckPeriod?: number) => void; -} - -/** - * Calls the provided `callbackFn` function once for each element in the iterator or iterator returned by - * the iterable and processed in the same order as returned by the iterator. As with the {@link arrForEachAsync} - * you CAN stop or break the iteration by returning -1 from the `callbackFn` function. - * - * The order of processing is not reset if you add or remove elemenets to the iterator, the actual behavior will - * depend on the iterator implementation. - * - * if the passed `iter` is both an Iterable\ and Iterator\ the Iterator\ interface takes precedence. And if - * an iterable and does not have a `Symbol.iterator` property then the `iter` will be used as the iterator. - * - * The `callbackFn` may execute `synchronously` or `asynchronously` and if the `callbackFn` returns a `Promise` - * then the next iteration will not be called until the promise is resolved. If the `callbackFn` returns a `Promise` - * that is rejected then the iteration will stop and the promise returned by iterForEachAsync will be rejected with - * the same error. - * @remarks - * If Symbols are NOT supported then the iterable MUST be using the same polyFill for the well know symbols, as used - * by the library. If the iterable is using a different polyFill then the `iter` MUST be an Iterator\ and not an - * Iterable\. - * If you are targetting a mixed environment you SHOULD either - * - only use the polyfill Symbol's provided by this library - * - ensure that you add any symbol polyfills BEFORE these utilities - * iterForOfAsync - * @since 0.5.0 - * @group Loop - * @group Iterator - * @typeParam T - Identifies the element type of the iterator - * @param iter - The iterator or iterable of elements to be searched. - * @param callbackFn - A `asynchronous` or `synchronous` function that accepts up to three arguments. iterForEach - * calls the callbackfn function one time for each element in the iterator. - * @param thisArg - An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, - * null or undefined the iterator will be used as the this value. - * @example - * ```ts - * const items = ['item1', 'item2', 'item3', 'item4', 'item5', 'item6', 'item7', 'item8', 'item9', 'item10']; - * const copyItems = []; - * - * // using async / await - * let result = await iterForOfAsync(items, async (value, index) => { - * copyItems.push(value); - * if (index === 5) { - * return -1; // Stop the iteration - * } - * - * await createTimeoutPromise(100); // Wait 100ms before processing the next item, you could also just return the promise - * }) - * - * console.log(result); // returns -1 if the loop was stopped, otherwise returns undefined - * - * // using doAwait - * doAwait(iterForOfAsync(items, (value, index) => { - * copyItems.push(value); - * if (index === 5) { - * return -1; // Stop the iteration - * } - * - * return createTimeoutPromise(100); // Wait 100ms before processing the next item, you could also just return the promise - * }), (result) => { - * console.log(result); // returns -1 if the loop was stopped, otherwise returns undefined - * }); - * ``` - */ -export declare function iterForOfAsync(iter: Iterator | Iterable | AsyncIterator | AsyncIterable, callbackFn: (value: T, count: number, iter?: Iterator | AsyncIterator) => void | number | IPromise, thisArg?: any): void | number | IPromise; - -/** - * The current state of the while loop while processing the callback function, this is - * passed to eht callback function. - * @typeParam T - Identifies the element type returned by the callback function. - * @since 0.5.0 - */ -export declare interface IWhileState { - /** - * The number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC, - * at the beginning of the while loop. This value is set at the beginning of the while - * loop via [`utcNow()`](https://nevware21.github.io/ts-utils/typedoc/functions/utcNow.html) - * (`Date.now()`) and is not updated during the execution of while loop. - */ - st: number; - /** - * The zero-based iteration count, which is increased after each call to the callback. - */ - iter: number; - /** - * The resolved result value returned by the callback function. - */ - res?: T; - /** - * Callback to enable the caller stop the while loop. - */ - isDone: boolean | ((state: IWhileState) => boolean | void | IPromise | PromiseLike); -} - -/** - * A full polyfill for the Promise class. - * Represents the completion of an asynchronous operation, and its resulting value. - * @class PolyPromise - * @description The `PolyPromise` class is a polyfill for the native Promise class. It provides a way to work with asynchronous operations in a more manageable way. - * @since 0.5.0 - * @group Polyfill - * @group Promise - */ -export declare let PolyPromise: PolyPromiseConstructor; - -/** - * The PolyPromiseConstructor interface represents the constructor for the polyfill Promise object. - * @since 0.5.0 - * @group Polyfill - */ -export declare interface PolyPromiseConstructor { - /** - * Creates a new Promise. - * @constructor - * @param executor - A callback used to initialize the promise. This callback is passed two arguments: - * a resolve callback used to resolve the promise with a value or the result of another promise, - * and a reject callback used to reject the promise with a provided reason or error. - */ - new (executor: PromiseExecutor): IPromise; - /** - * Returns a single asynchronous Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations __asynchronously__ using the optional - * provided timeout value to schedule when the chained items will be executed, or if the input contains no promises. - * It rejects immediately upon any of the input promises rejected or non-promises throwing an error, - * and will reject with this first rejection message / error. - * When resolved or rejected any additional chained operations will execute __asynchronously__ using the optional - * timeout value to schedul when the chained item will be executed (eg. `then()`; `catch()`; `finally()`). - * @group Polyfill - * @param input - The array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - * @returns - *
    - *
  • An already resolved `Promise`, if the input passed is empty. - *
  • A pending `Promise` in all other cases. This returned promise is then resolved/rejected __synchronously__ - * (as soon as the pending items is empty) when all the promises in the given input have resolved, or if any of the - * promises reject. - *
- */ - all(input: Iterable>, timeout?: number): IPromise; - /** - * The `createAsyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise - * settles with the eventual state of the first promise that settles. - * @description The `createAsyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first - * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). - * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to - * the first of these values found in the iterable. - * @since 0.5.0 - * @group Polyfill - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the - * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever - * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise is still - * asynchronously settled. - */ - race(values: Iterable>, timeout?: number): IPromise>; - /** - * The `createAsyncRacePromise` method takes an array of promises as input and returns a single Promise. This returned promise - * settles with the eventual state of the first promise that settles. - * @description The `createAsyncRacePromise` method is one of the promise concurrency methods. It's useful when you want the first - * async task to complete, but do not care about its eventual state (i.e. it can either succeed or fail). - * If the iterable contains one or more non-promise values and/or an already settled promise, then Promise.race() will settle to - * the first of these values found in the iterable. - * @since 0.5.0 - * @group Polyfill - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A Promise that settles with the eventual state of the first promise in the iterable to settle. In other words, it fulfills if the - * first promise to settle is fulfilled, and rejects if the first promise to settle is rejected. The returned promise remains pending forever - * if the iterable passed is empty. If the iterable passed is non-empty but contains no pending promises, the returned promise is still - * asynchronously settled. - */ - race(values: T, timeout?: number): IPromise>; - /** - * The `createAsyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. - * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. - * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an - * AggregateError containing an array of rejection reasons. - * @since 0.5.0 - * @group Polyfill - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A new Promise that is: - * - Already rejected, if the iterable passed is empty. - * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value - * is the fulfillment value of the first promise that was fulfilled. - * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is - * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the - * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but - * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) - * rejected. - */ - any(values: Iterable>, timeout?: number): IPromise>; - /** - * The `createAsyncAnyPromise` method takes an iterable of promises as input and returns a single Promise. - * This returned promise fulfills when any of the input's promises fulfills, with this first fulfillment value. - * It rejects when all of the input's promises reject (including when an empty iterable is passed), with an - * AggregateError containing an array of rejection reasons. - * @since 0.5.0 - * @group Polyfill - * @param values - An iterable object of promises. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A new Promise that is: - * - Already rejected, if the iterable passed is empty. - * - Asynchronously fulfilled, when any of the promises in the given iterable fulfills. The fulfillment value - * is the fulfillment value of the first promise that was fulfilled. - * - Asynchronously rejected, when all of the promises in the given iterable reject. The rejection reason is - * an AggregateError containing an array of rejection reasons in its errors property. The errors are in the - * order of the promises passed, regardless of completion order. If the iterable passed is non-empty but - * contains no pending promises, the returned promise is still asynchronously (instead of synchronously) - * rejected. - */ - any(values: T, timeout?: number): IPromise>; - /** - * Returns a single asynchronous Promise instance that is already rejected with the given reason. - * Any chained operations will execute __asynchronously__ using the optional timeout value to schedule - * when then chained items will be executed. (eg. `catch()`; `finally()`). - * @group Polyfill - * @param reason - The rejection reason - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - * @returns A rejected promise. - */ - reject(reason?: any, timeout?: number): IPromise; - /** - * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is - * a promise then that promise is returned instead of creating a new asynchronous promise instance. - * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional - * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). - * @group Polyfill - * @returns A resolved promise. - */ - resolve(): IPromise; - /** - * Returns a single asynchronous Promise instance that is already resolved with the given value. If the value passed is - * a promise then that promise is returned instead of creating a new asynchronous promise instance. - * If a new instance is returned then any chained operations will execute __asynchronously__ using the optional - * timeout value to schedule when the chained items will be executed.(eg. `then()`; `finally()`). - * @group Polyfill - * @param value - The value to be used by this `Promise`. Can also be a `Promise` or a thenable to resolve. - * @param timeout - Optional timeout to wait before processing the items, defaults to zero. - * @returns A resolved promise. - */ - resolve(value: T | PromiseLike, timeout?: number): IPromise; - /** - * Returns a single Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations based on the - * {@link createAsyncPromise | Asynchronous} promise implementation. Any chained operations will execute - * __asynchronously__ when the final operation pending promises have resolved, or if the input contains - * no promises. It will resolve only after all of the input promises have either resolved or rejected, - * and will resolve with an array of {@link IPromiseResult } objects that each describe the outcome of - * each promise. - * @since 0.5.0 - * @group Polyfill - * @param values - An array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. - */ - allSettled(values: T, timeout?: number): IPromise<{ - -readonly [P in keyof T]: IPromiseResult>; - }>; - /** - * Returns a single Promise instance that resolves to an array of the results from the input promises. - * This returned promise will resolve and execute it's pending chained operations based on the - * {@link createAsyncPromise | Asynchronous} promise implementation. Any chained operations will execute - * __asynchronously__ when the final operation pending promises have resolved, or if the input contains - * no promises. It will resolve only after all of the input promises have either resolved or rejected, - * and will resolve with an array of {@link IPromiseResult } objects that each describe the outcome of - * each promise. - * @since 0.5.0 - * @group Polyfill - * @param values - An array of promises to wait to be resolved / rejected before resolving or rejecting the new promise - * @param timeout - Optional timeout to wait before processing the items, defaults to zero, only used when Native promises are not available. - * @returns A pending `Promise` that will resolve to an array of {@link IPromiseResult } objects that each describe the outcome of each promise. - */ - allSettled(values: Iterable>, timeout?: number): IPromise>[]>; -} - -/** - * Defines the signature of a function that creates a Promise. - * @param newExecutor - The executor to run in the context of the promise - * @param extraArgs - Any extra arguments that can be passed to the creator - * @returns A Promise `IPromise` implemenetation - */ -export declare type PromiseCreatorFn = (newExecutor: PromiseExecutor, ...extraArgs: any) => IPromise; - -/** - * A function to be executed during the creation of a promise instance. It receives two functions as parameters: resolve and reject. - * Any errors thrown in the executor will cause the promise to be rejected, and the return value will be neglected. The semantics of executor are detailed below. - * @param resolve - The handler function that should be called when the operation has completed and the promise can continue. - * @param reject - The handler function that should be called to cause the promise to be rejected. - */ -export declare type PromiseExecutor = (resolve: ResolvePromiseHandler, reject: RejectPromiseHandler) => void; - -/** - * This defines the handler function for when a promise is rejected. - * @param value - This is the value passed as part of resolving the Promise - * @return This may return a value, another Promise or void. @see {@link https://nevware21.github.io/ts-async/typedoc/interfaces/IPromise.html#then | IPromise.then} for how the value is handled. - */ -export declare type RejectedPromiseHandler = (((reason: any) => T | IPromise | PromiseLike) | undefined | null); - -/** - * Defines the signature of the reject function passed to the resolverFunc (in the Promise constructor) - * @param reason - The reason to reject the Promise with - * @returns Nothing - */ -export declare type RejectPromiseHandler = (reason?: any) => void; - -/** - * This defines the handler function for when a promise is resolved. - * @param value - This is the value passed as part of resolving the Promise - * @return This may return a value, another Promise or void. @see {@link https://nevware21.github.io/ts-async/typedoc/interfaces/IPromise.html#then | IPromise.then} for how the value is handled. - */ -export declare type ResolvedPromiseHandler = (((value: T) => TResult1 | IPromise | PromiseLike) | undefined | null); - -/** - * Defines the signature of the resolve function passed to the resolverFunc (in the Promise constructor) - * @param value - The value to resolve the Promise with - * @returns Nothing - */ -export declare type ResolvePromiseHandler = (value: T | IPromise | PromiseLike) => void; - -/** - * Set the default promise implementation to use when calling `createPromise`; `createAllPromise`; `createResolvedPromise` - * and `createRejectedPromise`. This is effective a global value and changing this will affect ALL callers of these - * functions, as such these functions should only be used when switching implementations would have not unexpected - * consequences like switching from a `createSyncPromise` to `createIdlePromise` where idle promises have a possibility - * of never getting called during application shutdown or during an expected timeframe. - * @group Alias - * @group Promise - * @param creator - The creator function to call when a new promise is required. - */ -export declare function setCreatePromiseImpl(creator: (executor: PromiseExecutor, timeout?: number) => IPromise): void; - -/** - * Sets the global default idle timeout / deadline to use when no timeout is passed during promise creation. - * @param idleDeadline - Specifies the time in milliseconds to use as the idle timeout / deadline by when any - * outstanding chained items should be executed. - * @group Idle - */ -export declare function setDefaultIdlePromiseTimeout(idleDeadline?: number | undefined): void; - -/** - * @deprecated Use `setDefaultIdlePromiseTimeout` instead - * Sets the global default idle timeout / deadline to use when no timeout is passed during promise creation. - * @param idleDeadline - Specifies the time in milliseconds to use as the idle timeout / deadline by when any - * outstanding chained items should be executed. - * - * @function - * @group Idle - */ -export declare const setDefaultIdleTimeout: typeof setDefaultIdlePromiseTimeout; - -/** - * Debug helper to enable internal debugging of the promise implementations. Disabled by default. - * For the generated packages included in the npm package the `logger` will not be called as the - * `_debugLog` function that uses this logger is removed during packaging. - * - * It is available directly from the repository for unit testing. - * - * @group Debug - * @param enabled - Should debugging be enabled (defaults `false`, when `true` promises will have - * additional debug properties and the `toString` will include extra details. - * @param logger - Optional logger that will log internal state changes, only called in debug - * builds as the calling function is removed is the production artifacts. - * @example - * ```ts - * // The Id is the id of the promise - * // The message is the internal debug message - * function promiseDebugLogger(id: string, message: string) { - * if (console && console.log) { - * console.log(id, message); - * } - * } - * - * setPromiseDebugState(true, promiseDebugLogger); - * - * // While the logger will not be called for the production packages - * // Setting the `enabled` flag to tru will cause each promise to have - * // the following additional properties added - * // [[PromiseState]]; => Same as the `state` property - * // [[PromiseResult]]; => The settled value - * // [[PromiseIsHandled]] => Identifies if the promise has been handled - * // It will also cause the `toString` for the promise to include additional - * // debugging information - * ``` - */ -export declare function setPromiseDebugState(enabled: boolean, logger?: (id: string, message: string) => void): void; - -/** - * Identifies the function to call to start and execute the task when its - * ready to be executed. - * @since 0.2.0 - * @group Scheduler - * @param taskName - The optional task name that was assigned to this task, it is passed by the task scheduler. - * @returns The result or a IPromise that will be resolved / rejected when the task - * was completed. - * @example - * ```ts - * function taskFunc1() { - * return 42; - * } - * - * function taskFunc2(taskName: string) { - * console.log("Running Task: " + taskName); - * return fetch("https://example.com/xxxx").then((response) => { - * // ... - * }); - * } - * - * function taskFunc3() { - * return Promise.all([...]); - * } - * - * function taskFunc4() { - * return createAllPromise([...]); - * } - * - * function taskFunc5(taskName: string) { - * return createPromise(() => { - * scheduleTimeout(() => { - * console.log("Completing task: " + taskName); - * resolve(true); - * }, 100); - * }); - * } - * ``` - */ -export declare type StartQueuedTaskFn = (taskName?: string) => T | IPromise; - -export { }