81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
|
# Safe Timers
|
||
|
|
||
|
## About
|
||
|
|
||
|
Q: What's this all about? Aren't JavaScript timers safe?
|
||
|
A: Long story short: they're a bit broken. This module unbreaks them.
|
||
|
|
||
|
Whether it's by spec, or by accident, **all** major browsers and Node.js limit the interval a setTimeout can accept to a
|
||
|
32 bit signed integer. What that means in essence is that a timeout can never last longer than 24.85 days. Long enough,
|
||
|
right?
|
||
|
|
||
|
The problem is that:
|
||
|
|
||
|
- In human (non-binary) terms, this is a really arbitrary number.
|
||
|
- In long running processes (whether on the web, or in Node), you are limited.
|
||
|
- If the interval you provide overflows this limit, **the timer fires immediately**!
|
||
|
|
||
|
All the arguments about "you shouldn't need intervals this big anyway" go out the window the moment you provide a big
|
||
|
one and instead of never firing, it fires immediately. This is a real problem. And so here we are, Safe Timers solves
|
||
|
this for you.
|
||
|
|
||
|
Does that mean you should forego the browser native setTimeout and setInterval altogether? Absolutely not. Most of the
|
||
|
time, we pass constant short intervals, in which case Safe Timers are overkill. But when your interval comes from some
|
||
|
variable that depends on state or user input, using Safe Timers is a good idea.
|
||
|
|
||
|
## API
|
||
|
|
||
|
**Timer setTimeout(Function callback, number interval, mixed arg1, mixed arg2, ...)**
|
||
|
|
||
|
Calls `callback` after at least `interval` milliseconds have passed. All arguments passed after the `interval` will be
|
||
|
passed to the callback once it gets invoked. Returns a `Timer` instance.
|
||
|
|
||
|
```js
|
||
|
const setTimeout = require('safe-timers').setTimeout;
|
||
|
|
||
|
setTimeout(function (msg) {
|
||
|
console.log(msg);
|
||
|
}, 5000, 'Hello world');
|
||
|
```
|
||
|
|
||
|
**Timer setTimeoutAt(Function callback, number timestamp, mixed arg1, mixed arg2, ...)**
|
||
|
|
||
|
Calls `callback` when our clock reaches the given `timestamp` (in milliseconds). All arguments passed after the
|
||
|
`interval` will be passed to the callback once it gets invoked. Returns a `Timer` instance.
|
||
|
|
||
|
```js
|
||
|
const setTimeoutAt = require('safe-timers').setTimeoutAt;
|
||
|
|
||
|
setTimeoutAt(function (msg) {
|
||
|
console.log(msg);
|
||
|
}, Date.now() + 5000, 'Hello world');
|
||
|
```
|
||
|
|
||
|
**Interval setInterval(Function callback, number interval, mixed arg1, mixed arg2, ...)**
|
||
|
|
||
|
Calls `callback` after at least every `interval` milliseconds. All arguments passed after the `interval` will be passed
|
||
|
to the callback when it gets invoked. Returns an `Interval` instance.
|
||
|
|
||
|
```js
|
||
|
const setInterval = require('safe-timers').setInterval;
|
||
|
|
||
|
setInterval(function (msg) {
|
||
|
console.log(msg);
|
||
|
}, 5000, 'Hello world');
|
||
|
```
|
||
|
|
||
|
**timer.clear() / interval.clear()**
|
||
|
|
||
|
The response from `safetimers.setTimeout[At]` and `safetimers.setInterval` are `Timer` and `Interval` objects
|
||
|
respectively. To cancel a timer or interval, you can call `clear` on it.
|
||
|
|
||
|
```js
|
||
|
const setTimeout = require('safe-timers').setTimeout;
|
||
|
|
||
|
const timer = setTimeout(function (msg) {
|
||
|
console.log(msg); // this will never show
|
||
|
}, 5000, 'Hello world');
|
||
|
|
||
|
timer.clear();
|
||
|
```
|