Skip to content

jcoreio/poll

Repository files navigation

poll

Build Status Coverage Status semantic-release Commitizen friendly

yet another promise-based poller (I didn't like the API design of others out there)

Example

npm install --save @jcoreio/poll
const poll = require('@jcoreio/poll')
const superagent = require('superagent')

poll(() => superagent.get('http://google.com'), 1000)
  .timeout(30000)
  .then(() => console.log("You're connected to the internet!"))

poll(fn, interval, [options])

Begins calling fn every interval milliseconds until the condition passes (which defaults to fn didn't throw an Error or return a rejected Promise).

Returns a Promise that resolves when polling finishes or fails, which may be:

  • when fn calls the pass method provided to it
  • when fn calls the fail method provided to it
  • when fn returns/resolves to a value or throws/rejects with an Error that passes the condition
  • when a timeout is specified and poll times out waiting for any of the above

fn will be called with a context object:

{
  attemptNumber: number, // the number of this call (starting from 0)
  elapsedTime: number, // the number of milliseconds since polling started
  pass: (value: any) => void, // makes `poll` resolve immediately with this value
  fail: (error: Error) => void, // makes `poll` reject immediately with this Error
}

You can change the condition by calling .until on the returned Promise:

poll(...).until((error, result) => result > 3)

error will be the Error from the last call to fn (if it rejected or threw) and result will be the value it resolved to or returned otherwise.

You can specify a timeout (in milliseconds) by calling .timeout on the returned Promise:

poll(...).timeout(30000) // time out after 30 seconds

If you call .noWrapError() on the returned Promise, it won't wrap rejection errors.