Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/magynhard/fire-once
Javascript library that ensures that an irregularly but frequently event triggered function is fired only once at the given period
https://github.com/magynhard/fire-once
Last synced: 3 days ago
JSON representation
Javascript library that ensures that an irregularly but frequently event triggered function is fired only once at the given period
- Host: GitHub
- URL: https://github.com/magynhard/fire-once
- Owner: magynhard
- License: mit
- Created: 2024-06-18T11:26:33.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2024-07-17T16:06:54.000Z (4 months ago)
- Last Synced: 2024-09-18T03:47:36.932Z (about 2 months ago)
- Language: JavaScript
- Size: 43 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fire-once
[](https://www.npmjs.com/package/fire-once)
[](https://github.com/magynhard/fire-once/releases)
[](LICENSE)
> Javascript library that ensures that an irregularly but frequently event triggered function is fired only once at the
> given period
>
> Can also fire at the end of the defined period of time again, if the function was called at least twice. This can be
> very helpful to improve performance by
> ignoring superfluous, too frequent events but always processing the last call of the event.
>
> Available for node js and browser!
# Contents
* [Examples](#examples)
* [Installation](#installation)
* [Documentation](#documentation)
* [Contributing](#contributing)
## Examples
### Demonstration
If the `fire` function was called 50 times within one second (period: 1000),
it will actually called only two times: It will be immediately be called at the first call and then once again after
1000ms.
```javascript
const helloWorld = (name, number) => {
console.log(`Hello ${name}, you are number ${number}!`);
}
for (let i = 1; i <= 50; ++i) {
FireOnce.fire("hello_world_unique_id", () => {
helloWorld("Peter", i);
}, {period: 1000, fire_after: true});
}
// 0ms => Hello Peter, you are number 1!
// 1000ms => Hello Peter, you are number 50!
```
### Scroll event
In this example we want to limit the scroll event to be only fired a maximum of twice per second.
```javascript
addEventListener("scroll", (event) => {
FireOnce.fire("scroll_limiter", () => {
console.log("Scrolling ...");
}, {period: 500});
});
// 0ms => Scrolling ...
// 500ms => Scrolling ...
```
### Several event sources
By specifying a unique identifier, you can also combine several event sources.
```javascript
const myEventTriggeredFun = () => {
console.log("Triggered!");
};
element.on("click", (event) => {
FireOnce.fire("my_event_limiter", myEventTriggeredFun, {period: 500});
});
WebSocket.on("push", (event) => {
FireOnce.fire("my_event_limiter", myEventTriggeredFun, {period: 500});
});
```
## Installation
### Option 1: node js - yarn
In your project root directory execute the following command:
```bash
yarn add fire-once
```
### Option 2: node js - npm
In your project root directory execute the following command:
```bash
npm install fire-once
```
### Option 3: Browser
`fire-once` is available in normal and minified version.
If you are unsure, us the normal version, that includes jsdocs and improves developer experience. The minified version
is only intended for productive use.
Download the `fire-once.js` or `fire-once.min.js` at
the [release page](https://github.com/magynhard/fire-once/releases) and
put it in an appropriate folder, e.g. `js/lib`
and reference it with an script tag in your project:
```html
```
If you are using a packager, you should add the source file to your build pipeline.
## Documentation
```javascript
FireOnce.fire(identifier, func, options)
```
### Options
| Option | Type | Default | Description |
|----------|--------|---------|------------------------------------------------------------------------------------------------------|
| `period` | number | 1000 | In which period should the given function fired once |
| `type` | string | 'both' | 'both' Call the first and last call (if at least 2 calls) of the period at the beginning and the end. |
| TODO: | | | 'start' Call only the first of the period at the beginning end surpress all calls until the end. |
| TODO: | | | 'end' Call only the last call of the period at the end of the period. |
### jsdoc
Check out the *jsdoc* documentation [here](doc/fire-once.jsdoc.md).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/magynhard/fire-once. This project is intended
to be a safe, welcoming space for collaboration, and contributors are expected to adhere to
the [Contributor Covenant](http://contributor-covenant.org) code of conduct.