# 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();
```