handy promised-based polling API

Downloads in past


1192.3.25 months ago5 years agoMinified + gzip package size for @jcoreio/poll in KB


Build Status Coverage Status semantic-release Commitizen friendly
yet another promise-based poller (I didn't like the API design of others out there)


npm install --save @jcoreio/poll

const poll = require('@jcoreio/poll')
const superagent = require('superagent')

poll(() => superagent.get('http://google.com'), 1000)
  .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.