Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/martinsbicudo/promise-with-events
Simple lib to use promises with events :pager:
https://github.com/martinsbicudo/promise-with-events
events javascript promise promise-with-events typescript
Last synced: about 1 month ago
JSON representation
Simple lib to use promises with events :pager:
- Host: GitHub
- URL: https://github.com/martinsbicudo/promise-with-events
- Owner: martinsbicudo
- License: mit
- Created: 2024-04-02T18:11:36.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-04-03T14:22:44.000Z (9 months ago)
- Last Synced: 2024-11-07T23:43:34.851Z (about 2 months ago)
- Topics: events, javascript, promise, promise-with-events, typescript
- Language: HTML
- Homepage: https://www.npmjs.com/package/promise-with-events
- Size: 363 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
Simple lib to use promises with events
# Compatibility
[check here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#browser_compatibility)
# Bundle Analyzer
- [main](https://htmlpreview.github.io/?https://github.com/martinsbicudo/promise-with-events/blob/main/parcel-bundle-reports/main.html)
- [types](https://htmlpreview.github.io/?https://github.com/martinsbicudo/promise-with-events/blob/main/parcel-bundle-reports/types.html)
# Quick Menu
- [how to use](#how-to-use)
- [documentation](#documentation)
- [how to contribute](#how-to-contribute)
- [license](#license)
# How to use
### Install
```shell
npm i promise-with-events
#or
yarn add promise-with-events
#or
pnpm add promise-with-events
```
### Simple example
```ts
import { createWatchEvent, onResolveEvents } from "promise-with-events";
const promiseExample1 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example1");
});
};
createWatchEvent(promiseExample1, {
eventName: "key1",
autoStart: true,
});
onResolveEvents(
(error, resolve1) => {
console.log(resolve1); //output = "example1"
},
["key1"]
);
```
# Documentation
- [watch events](#watch-events)
- [single promise](#single-promise)
- [multi promises](#multi-promises)
- [multi events](#multi-events)
- [auto start](#auto-start)
- [promise method](#promise-method)
- [start events](#start-events)
- [events](#events)
- [onStartEvents](#onstartevents)
- [onResolveEvents](#onresolveevents)
- [onRejectEvents](#onrejectevents)
- [onFinallyEvents](#onfinallyevents)
- [advanced]
- [reuse watched events](#reuse-watched-events)
## Watch Events
`createWatchEvent` receive 2 params:
1. `promises`: (() => promises)[]
2. `key`: that is the event name `OR` `config`:
```ts
type TConfig = {
eventName: string;
autoStart?: boolean;
promiseMethod?: "all" | "allSettled" | "any" | "race";
};
```
Quick Examples
```ts
...
createWatchEvent(promise1, "key1")
```
```ts
...
createWatchEvent(promise1, {
eventName: "key1",
autoStart: true,
promiseMethod: 'race',
})
```
```ts
...
createWatchEvent([promise1, promise2], "key2")
```
```ts
...
createWatchEvent([promise1, promise2], {
eventName: "key2",
autoStart: true,
promiseMethod: 'race',
})
```
### Single Promise
Example
```ts
import {
createWatchEvent,
startEvents,
onResolveEvents,
} from "promise-with-events";
const promiseExample1 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example1");
});
};
createWatchEvent(promiseExample1, "key1");
startEvents(["key1"]);
onResolveEvents(
(error, resolve1) => {
console.log(resolve1); //output = "example1"
},
["key1"]
);
```
### Multi Promises
Example
```ts
import {
createWatchEvent,
startEvents,
onResolveEvents,
} from "promise-with-events";
const promiseExample1 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example1");
});
};
const promiseExample2 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 2000, "example2");
});
};
createWatchEvent([promiseExample1, promiseExample2], "key1");
startEvents(["key1"]);
onResolveEvents(
(error, resolve1) => {
console.log(resolve1); //output = ["example1", "example2"]
},
["key1"]
);
```
### Multi Events
Example
```ts
import {
createWatchEvent,
startEvents,
onResolveEvents,
} from "promise-with-events";
const promiseExample1 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example1");
});
};
const promiseExample2 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 2000, "example2");
});
};
const promiseExample3 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example3");
});
};
const promiseExample4 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 2000, "example4");
});
};
createWatchEvent([promiseExample1, promiseExample2], "key1");
createWatchEvent([promiseExample3, promiseExample4], "key2");
startEvents(["key1", "key2"]);
onResolveEvents(
(error, resolve1, resolve2) => {
console.log(resolve1); //output = ["example1", "example2"]
console.log(resolve2); //output = ["example3", "example4"]
},
["key1", "key2"]
);
```
### Auto Start
**Note**: `startEvents` doesn't works with `autoStart` active
**Possible values**: `true` | `false` (**default value** = `true`)
Example
```ts
import { createWatchEvent, onResolveEvents } from "promise-with-events";
const promiseExample1 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example1");
});
};
const promiseExample2 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 2000, "example2");
});
};
createWatchEvent([promiseExample1, promiseExample2], {
eventName: "key1",
autoStart: true,
});
onResolveEvents(
(error, resolve1) => {
console.log(resolve1); //output = ["example1", "example2"]
},
["key1"]
);
```
### Promise Method
**Note**: `promiseMethod` doesn't works with `single promise`
**Possible values**: `all` | `allSettled` | `any` | `race` (**default value** = `all`)
Example
```ts
import { createWatchEvent, onResolveEvents } from "promise-with-events";
const promiseExample1 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example1");
});
};
const promiseExample2 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 2000, "example2");
});
};
createWatchEvent([promiseExample1, promiseExample2], {
eventName: "key1",
autoStart: true,
promiseMethod: "any",
});
onResolveEvents(
(error, resolve1) => {
console.log(resolve1); //output = "example1"
},
["key1"]
);
```
## Start Events
**Note**: Doesn't works with `autoStart: true`
Example
```ts
import { startEvents } from "promise-with-events";
startEvents(["key1"]);
startEvents(["key1", "key2"]);
```
## Events
All `events` receive 2 params:
1. `callback`: returns error, ...responses `(response for each key)`
2. `keys`: string[]
**Note**: `error` on callback its about code errors
### onStartEvents
Calls `callback` param when all promises are resolved
**Note**: Doesn't works with `autoStart: true`
Quick Examples
```ts
...
onStartEvents((error) => {
console.log('ok')
}, ["key1"])
```
```ts
...
onStartEvents((error) => {
console.log('ok')
}, ["key1", "key2"])
```
### onResolveEvents
Calls `callback` param when all promises are resolved
Quick Examples
```ts
...
onResolveEvents((error, resolve1) => {
console.log(resolve1)
}, ["key1"])
```
```ts
...
onResolveEvents((error, resolve1, resolve2) => {
console.log(resolve1)
console.log(resolve2)
}, ["key1", "key2"])
```
### onRejectEvents
Calls `callback` param when all promises are rejected
Quick Examples
```ts
...
onRejectEvents((error, reject1) => {
console.log(reject1)
}, ["key1"])
```
```ts
...
onResolveEvents((error, reject1, reject2) => {
console.log(reject1)
console.log(reject2)
}, ["key1", "key2"])
```
### onFinallyEvents
Calls `callback` param when all promises are finished
Quick Examples
```ts
...
onFinallyEvents((error, finally1) => {
console.log(finally1.response) //could be undefined, according promise result
console.log(finally1.error) //could be undefined, according promise result
}, ["key1"])
```
```ts
...
onFinallyEvents((error, finally1, finally2) => {
console.log(finally1.response)
console.log(finally1.error)
console.log(finally2.response)
console.log(finally2.rerror)
}, ["key1", "key2"])
```
## Advanced
### Reuse Watched Events
Example
```ts
import { createWatchEvent, onResolveEvents } from "promise-with-events";
const promiseExample1 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example1");
});
};
const promiseExample2 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 2000, "example2");
});
};
const promiseExample3 = () => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, "example3");
});
};
const watchedPromise1 = createWatchEvent([promiseExample1, promiseExample2], {
eventName: "key1",
autoStart: true,
promiseMethod: "any",
});
const watchedPromise2 = createWatchEvent([watchedPromise1, promiseExample3], {
eventName: "key2",
autoStart: true,
});
createWatchEvent([watchedPromise1, watchedPromise2], {
eventName: "key3",
autoStart: true,
promiseMethod: "all",
});
onResolveEvents(
(error, resolve1) => {
console.log(resolve1); //output = "example1"
},
["key1"]
);
onResolveEvents(
(error, resolve2) => {
console.log(resolve2); //output = ["example1", "example3"]
},
["key2"]
);
onResolveEvents(
(error, resolve3) => {
console.log(resolve3); //output = ["example1", ["example1", "example3"]]
},
["key3"]
);
```
# How to contribute
To contribute, make sure to follow the steps bellow:
1. Create a new branch:
```shell
git checkout -b feat/your-new-feature
```
2. Make your changes, add unit tests (with `jest`) and test with `npm link`
On promise-with-events project:
```shell
npm link
```
On your app/project:
```shell
npm link promise-with-events
```
This will create a symlink into your `node_modules` app, and you can test iteratively. You can check more about npm-link [here](https://docs.npmjs.com/cli/v9/commands/npm-link)
3. Before to push your changes to origin, open your pull request and fill all required fields.
1. Make sure to fill the **Release** section with what your pull request changes. **This section is required to merge pull request.**
4. Set a _required_ `semver` label according to your change:
1. `semver:patch`: used when you submit a fix to a bug, enhance performance, etc;
2. `semver:minor`: used when you submit a new component, new feature, etc;
3. `semver:major`: used when you submit some breaking change, etc;
4. `semver:prerelease`: used when you submit a prerelease (ex: `1.0.0-beta.1`);
5. `semver:bypass`: used to update docs, or something that doesn’t affect the build.
> Info: Once you have merged your pull request, with all required fields, GitHub Actions will be responsible to create a new build and publish.
# License
MIT License