Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mkloubert/js-promises
Helpers for promises, which work in Node and the browser.
https://github.com/mkloubert/js-promises
browser function helper javascript nodejs promise
Last synced: about 2 months ago
JSON representation
Helpers for promises, which work in Node and the browser.
- Host: GitHub
- URL: https://github.com/mkloubert/js-promises
- Owner: mkloubert
- License: mit
- Created: 2022-04-29T04:00:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-05-02T02:22:14.000Z (over 2 years ago)
- Last Synced: 2024-10-06T23:35:29.231Z (3 months ago)
- Topics: browser, function, helper, javascript, nodejs, promise
- Language: TypeScript
- Homepage: https://mkloubert.github.io/js-promises/
- Size: 181 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/@marcelkloubert/promises)
[](https://github.com/mkloubert/js-promises/actions?query=workflow%3APublish)
[](https://github.com/mkloubert/js-promises/pulls)
# @marcelkloubert/promises
> Helpers for promises, which work in Node and the browser.
## Install
Execute the following command from your project folder, where your `package.json` file is stored:
```bash
npm i @marcelkloubert/promises
```
## Usage
### doRepeat(action: DoRepeatAction, countOrCondition: number | DoRepeatCondition, ...args: any[]): Promise
> Repeats an action or promise.
```typescript
import assert from "assert";
import { doRepeat, DoRepeatActionContext } from "@marcelkloubert/promises";
const repeatCount = 5979;
const counter = 0;
const results = await doRepeat(async (context: DoRepeatActionContext) => {
console.log("context.state", String(context.state));
context.state = context.index * 2;
++counter;
// do some work here
}, repeatCount);
assert.strictEqual(results.length, repeatCount);
assert.strictEqual(counter, results.length);
```
### isPromise(value: any): boolean
> Checks if a value is a Promise.
```typescript
import { isPromise } from "@marcelkloubert/promises";
import Bluebird from "bluebird";
// all are (true)
isPromise(Promise.resolve("Foo"));
isPromise(Bluebird.resolve("Foo"));
isPromise({
then: (onfulfilled?: Function, onrejected?: Function): any => {},
catch: (onrejected?: Function) => {},
});
// all are (false)
isPromise("Foo");
isPromise({
then: (onfulfilled?: Function, onrejected?: Function): any => {},
});
isPromise(null);
```
### isPromiseLike(value: any): boolean
> Checks if a value is a PromiseLike.
```typescript
import { isPromiseLike } from "@marcelkloubert/promises";
import Bluebird from "bluebird";
// all are (true)
isPromiseLike(Promise.resolve("Foo"));
isPromiseLike(Bluebird.resolve("Foo"));
isPromiseLike({
then: (onfulfilled?: Function, onrejected?: Function): any => {},
});
// all are (false)
isPromiseLike("Foo");
isPromiseLike({});
isPromiseLike(null);
```
### PromiseQueue
> A promise queue.
```typescript
import assert from "assert";
import { PromiseQueue } from "@marcelkloubert/promises";
// create and start the queue
const queue = new PromiseQueue({
autoStart: true,
concurrency: 10, // maximum 10 actions at the same time
});
const promises: Promise[] = [];
let counter = 0;
// lets create 100 actions and
// add them to queue
const actionCount = 100;
for (let i = 0; i < actionCount; i++) {
promises.push(
queue.enqueue(async () => {
// do some (long) work here ...
++counter;
})
);
}
// wait until all actions have been executed
await Promise.all(promises);
// stop the queue
queue.stop();
// counter should now be the number of
// enqueued actions
assert.strictEqual(counter, promises.length);
```
### waitFor(action: WaitForAction, condition: WaitForCondition, ...args: any[]): Promise
> Invokes an action or promise, but waits for a condition.
```typescript
import {
waitFor,
WaitForActionContext,
WaitForCondition,
} from "@marcelkloubert/promises";
import fs from "fs";
const waitForFile: WaitForCondition = async (context) => {
// use context.cancel() function
// to cancel the operation
// maybe for a timeout
// setup 'state' value for upcoming
// action
context.state = "Foo Bar BUZZ"; // (s. below in action)
// return a truthy value to keep waiting
// otherwise falsy to start execution of action
return !fs.existsSync("/path/to/my/file.xlsx");
};
const result = await waitFor(async ({ state }: WaitForActionContext) => {
// state === "Foo Bar BUZZ" (s. above)
}, waitForFile);
```
### withCancellation(action: WithCancellationAction, ...args: any[]): Promise
> Invokes an action or promise, which can be cancelled.
```typescript
import {
CancellationError,
withCancellation,
WithCancellationActionContext,
} from "@marcelkloubert/promises";
const promise = withCancellation(
async (context: WithCancellationActionContext) => {
let hasBeenFinished = false;
while (!context.cancellationRequested && !hasBeenFinished) {
// do some long work here
}
}
);
setTimeout(() => {
promise.cancel("Promise action takes too long");
}, 10000);
try {
await promise;
} catch (ex) {
if (ex instanceof CancellationError) {
// has been cancelled
} else {
// other error
}
}
```
### withRetries(action: WithRetriesAction, optionsOrMaxRetries: WithRetriesOptions | number, ...args: any[]): Promise
> Invokes an action or promise and throws an error if a maximum number of tries has been reached.
```typescript
import {
MaximumTriesReachedError,
withRetries,
} from "@marcelkloubert/promises";
const myAsyncAction = async () => {
// do something here
};
try {
// try this action
await withTimeout(myAsyncAction, {
maxRetries: 9, // try invoke the myLongAction
// with a maximum of 10 times
// (first invocation + maxRetries)
waitBeforeRetry: 10000, // wait 10 seconds, before retry
});
} catch (error) {
// error should be a MaximumTriesReachedError instance
console.error("Invokation of myLongAction failed", error);
}
```
### withTimeout(action: WithTimeoutAction, timeout: number, ...args: any[]): Promise
> Invokes an action or promise and throws an error on a timeout.
```typescript
import { TimeoutError, withTimeout } from "@marcelkloubert/promises";
const action = () => {
return new Promise((resolve) => {
setTimeout(() => result("FOO"), 1000);
});
};
// submit action as function
// should NOT throw a TimeoutError
const fooResult1 = await withTimeout(action, 10000);
// submit action as Promise
// this should throw a TimeoutError
const fooResult2 = await withTimeout(action(), 100);
```
### withWorker(workerFileOrUrl: string | URL, options?: WithWorkerOptions): Promise
> Wraps the execution of a worker into a Promise.
```typescript
import { withWorker } from "@marcelkloubert/promises";
// this is code for Node.js
// in a browser 'exitCode' will not exist
const { exitCode, lastMessage } = await withWorker("/path/to/worker_script.js");
```
## Documentation
The API documentation can be found [here](https://mkloubert.github.io/js-promises/).
## License
MIT © [Marcel Joachim Kloubert](https://github.com/mkloubert)
## Support
Or visit https://marcel.coffee/