Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/onury/tasktimer
An accurate timer utility for running periodic tasks on the given interval ticks or dates. (Node and Browser)
https://github.com/onury/tasktimer
Last synced: 13 days ago
JSON representation
An accurate timer utility for running periodic tasks on the given interval ticks or dates. (Node and Browser)
- Host: GitHub
- URL: https://github.com/onury/tasktimer
- Owner: onury
- License: mit
- Created: 2016-08-16T18:27:33.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-01-04T09:54:55.000Z (almost 2 years ago)
- Last Synced: 2024-10-16T04:06:19.509Z (28 days ago)
- Language: TypeScript
- Homepage: https://onury.io/tasktimer
- Size: 2.28 MB
- Stars: 123
- Watchers: 8
- Forks: 12
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
© 2021, Onur Yıldırım (@onury).
An accurate timer utility for running periodic tasks on the given interval ticks or dates.
## Why `TaskTimer`?
Because of the single-threaded, asynchronous [nature of JavaScript][how-timers-work], each execution takes a piece of CPU time, and the time they have to wait will vary, depending on the load. This creates a latency and cumulative difference in asynchronous timers; that gradually increase the inacuraccy. `TaskTimer` claims to be the best timer that overcomes this problem as much as possible.
Secondly, I needed a task manager that can handle multiple tasks on different intervals, with a single timer instance.
## Features
- **Precission & Accuracy**: With the `precision` option (enabled by default);
- The delay between each tick is **auto-adjusted** when it's off due to task/CPU loads or [clock drifts][clock-drift].
- In Node.js, `TaskTimer` also makes use of `process.hrtime()` **high-resolution real-time**. The time is relative to an arbitrary time in the past (not related to the time of day) and therefore not subject to clock drifts.
- The timer may hit a synchronous / blocking task; or detect significant time drift (longer than the base interval) due to JS event queue, which cannot be recovered by simply adjusting the next delay. In this case, right from the next tick onward; it will auto-recover as much as possible by running "immediate" tasks until it reaches the proper time vs tick/run balance.
- Run or schedule **multiple tasks** (on a single timer instance).
- Ability to run **sync** or **async** tasks that return a promise (or use callbacks).
- Ability to **balance task-loads** via distributing executions by tick intervals.
- Ability to **limit total runs** of a task.
- **Stateful tasks**: i.e. ability to auto-stop when all tasks complete.
- `TaskTimer` is also an **`EventEmitter`**.
- **Universal** module. Works in both Node and Browser.
- Small size (4.5kB minified, gzipped).
- Completely **re-written** in **TypeScript**. (version 2.0.0+)
## Installation
```sh
npm i tasktimer
```
## Usage
In Node/CommonJS environments:
```js
const { TaskTimer } = require('tasktimer');
```
With transpilers (TypeScript, Babel):
```js
import { TaskTimer } from 'tasktimer';
```
In (Modern) Browsers:
```html
const { TaskTimer } = tasktimer;
```
### Simplest Example
```js
const timer = new TaskTimer(1000);
timer.add(task => console.log(`Current runs: ${task.currentRuns}`)).start();
```
### Regular Timer (without Task Management)
```js
const timer = new TaskTimer(5000);
timer.on('tick', () => console.log(`Tick count: ${timer.tickCount}`));
timer.start();
```
### Detailed Example
```js
// Timer with 1000ms (1 second) base interval resolution.
const timer = new TaskTimer(1000);
// interval can be updated anytime by setting the `timer.interval` property.
// Add multiple tasks (at once) based on tick intervals.
timer.add([
{
id: 'task-1', // unique ID of the task
tickInterval: 5, // run every 5 ticks (5 x interval = 5000 ms)
totalRuns: 10, // run 10 times only. (set to 0 for unlimited times)
callback(task) {
// code to be executed on each run
console.log(`${task.id} task has run ${task.currentRuns} times.`);
}
},
{
id: 'task-2', // unique ID of the task
tickDelay: 1, // 1 tick delay before first run
tickInterval: 10, // run every 10 ticks (10 x interval = 10000 ms)
totalRuns: 2, // run 2 times only. (set to 0 for unlimited times)
callback(task) {
// code to be executed on each run
console.log(`${task.id} task has run ${task.currentRuns} times.`);
}
}
]);
// You can also execute some code on each tick... (every 1000 ms)
timer.on('tick', () => {
console.log('tick count: ' + timer.tickCount);
console.log('elapsed time: ' + timer.time.elapsed + ' ms.');
// stop timer (and all tasks) after 1 hour
if (timer.tickCount >= 3600000) timer.stop();
});
// Start the timer
timer.start();
```
## How it works
- When you create a timer; you set a **time**-interval (e.g. `1000` milliseconds), to be used as **base** resolution (tick) for the tasks.
- Then add task(s) to be executed on **tick**-intervals.
*(e.g. task1 runs on every 10th tick, task2 runs on every 30th)*
- You can optionally define:
- The number of **total runs**,
- An initial **delay**,
- Start/end **dates** for each task...
- In addition to task callbacks; event listeners can be added to execute some other code on each `tick` (base interval) or `task` run, etc...
- You can add, remove, reset, disable individual tasks at any time, without having to stop or re-create the timer.
- Pause and resume the timer at any time; which effects all current tasks.
### Documentation
See [**API reference**][docs] and examples [here][docs].
## Changelog
See [CHANGELOG.md][changelog].
*If you're migrating from TaskTimer v1 to v2+, there are various **breaking changes**!..*
## Contributing
Clone original project:
```sh
git clone https://github.com/onury/tasktimer.git
```
Install dependencies:
```sh
npm install
```
Add tests into [test/node](test/node) and [test/browser](test/browser) and run:
```sh
npm run test! # builds and runs tests
npm test # runs tests without building
```
Use included `tslint.json` and `editorconfig` for style and linting.
Travis build should pass, coverage should not degrade.
## License
[MIT](LICENSE).
[docs]:https://onury.io/tasktimer/api
[changelog]:CHANGELOG.md
[how-timers-work]:https://johnresig.com/blog/how-javascript-timers-work/
[clock-drift]:https://en.wikipedia.org/wiki/Clock_drift