guard-timeout

Guard against sleep mode timeouts firing on wake

About

If a process goes into a sleep mode (for instance a laptop hibernates, or a service is put into inspect mode) then timeouts may trigger on wake. Depending on your use case (think distributed systems) you might not want to trigger a timeout if process uptime hasn't actually occurred in that period.

The guard-timeout module will check if there is a significant lag (default 1s) between when the timeout was scheduled to fire and when it actually fired.

Install

$ npm i guard-timeout

Usage

const setTimeout = require('guard-timeout')

// if the timeout is 1 second late, 
// it will be reschedule for another 20 minutes

setTimeout(
  () => { console.log('do something') }, 
  1.2e+6 // 20 minutes
)

Advanced Usage

Configure your own safe timeout:

const setTimeout = require('guard-timeout').create({
  lagMs: 60 * 1000 // 1 minute lag
})

// if the timeout is 1 minute late, 
// it will be reschedule for another 20 minutes

setTimeout(
  () => { console.log('do something') }, 
  1.2e+6 // 20 minutes
)

Await Usage

guard-timeout has util.promisify support:

const { promisify } = require('util')
const timeout = promisify(require('guard-timeout'))

async function run () {
  // if the timeout is 1 second late, 
  // it will be reschedule for another 20 minutes
  await timeout(1.2e+6) // 20 minutes
  console.log('do something')
}

run().catch(console.error)

API

`require('guard-timeout') => setTimeout (cb, time, ...args) => instance`

The default export of guard-timeout a is safe setTimeout function with a default lagMs option of 1000 (one second).

`require('guard-timeout').create(opts) => setTimeout (cb, time, ...args) => instance`

Create a custom safe setTimeout function by passing in options

`instance.close()`

Clears the timeout

`instance.timeout`

A getter property which holds current underlying timeout object (or numerical ID in the browser).

Options

lagMs – Number, default: 1000. The allowable delta between when a timeout should fire and when it actually fires, in milliseconds. If this is exceeded then the timeout is rescheduled.
rescheduler - Function, default: (t, instance) => t. A mapping function to calculate when the timeout should be rescheduled for. It takes two args, the time that the timeout was scheduled for and the timeout instance returned from guard-timeout (which comes Node's native setTimeout). The instance argument can be used to apply specific reschedule times to specific timeouts. The return value should be a number representing milliseconds for the rescheduled timeout.

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue

Author

David Mark Clements

License

Current Tags

2.0.0 ... latest (5 years ago)

4 Versions

2.0.0 ... 5 years ago
1.0.2 ... 5 years ago
1.0.1 ... 5 years ago
1.0.0 ... 5 years ago