poll

A simple poll function based on async, await, and an infinite loop.

Links:

• npmjs.com/package/poll
  • on BundlePhobia
• github.com/kleinfreund/poll

Contents

• Installation & usage
• Documentation
• Examples
• Versioning
• Update package version

Installation & usage

npm package

1. Install the poll package.

   npm install poll

2. Import the poll function and use it.

   // “poll” is mapped to “poll/dist/poll.js” by Node.js via the package’s “exports” field.
   import { poll } from 'poll'
   
   function fn() {
     console.log('Hello, beautiful!')
   }
   
   poll(fn, 1000)

Plain file

1. Download the poll module.

   curl -O https://raw.githubusercontent.com/kleinfreund/poll/main/dist/poll.js

2. Import the poll function and use it.

   <script type="module">
     import { poll } from './poll.js'
   
     function fn() {
       console.log('Hello, beautiful!')
     }
   
     poll(fn, 1000)
   </script>

Documentation

Syntax

poll(function, delay[, shouldStopPolling])

Parameters:

• fn: Required. A function to be called every delay milliseconds. No parameters are passed to fn upon calling it.

• delay: Required. The delay (in milliseconds) to wait before calling the function again. If delay is negative, zero will be used instead.

• shouldStopPolling: Optional. A function indicating whether to stop the polling process. The callback function is evaluated twice during one iteration of the internal loop:

  • After the result of the call to fn was successfully awaited. In other words, right before triggering a new delay period.
  • After the delay has passed. In other words, right before calling fn again.

  This guarantees two things:

  • A currently active execution of fn will be completed.
  • No new calls to fn will be triggered.

Return value:

None.

Examples

The poll function expects two parameters: A callback function and a delay. After calling poll with these parameters, the callback function will be called. After it’s done being executed, the poll function will wait for the specified delay. After the delay, the process starts from the beginning.

const pollDelayInMinutes = 10

async function getStatusUpdates() {
  const response = await fetch('/api/status')
  console.log(response)
}

poll(getStatusUpdates, pollDelayInMinutes * 60 * 1000)

Note that poll will not cause a second call to the callback function if the first call is still not finished. For example, it the endpoint /status does not respond and the server doesn’t time out the connection, poll will still be waiting for the callback function to fully resolve. It will not start the delay until the callback function is finished.

Stop polling

You can pass a callback function to poll for its last parameter. Its evaluated before and after calls to the polled function. If it evaluates to true, the poll function’s loop will stop and the function returns.

In the following example, the shouldStopPolling callback function evaluates to true after the setTimeout function called its anonymous callback function which sets stopPolling to true. The next time shouldStopPolling is evaluated, it will cause poll to exit normally.

let stopPolling = false
const shouldStopPolling = () => stopPolling

function fn() {
  console.log('Hello, beautiful!')
}

setTimeout(() => {
  stopPolling = true
}, 1000)

poll(fn, 50, shouldStopPolling)

Versioning

This package uses semantic versioning.

Update package version

1. Make some changes and run the tests and the build script.

   npm test
   npm run build

2. Commit the changes.

3. Verify that you’re authenticated with npm.

   npm whomai

   If you’re not authenticated, do so using npm login.

4. Change the package’s version locally.

   # See `npm version --help` for more options
   npm version minor

   This changes the version number in the package.json file and adds a new git tag matching the new version.

5. Push your changes and the updated git tags separately.

   git push
   git push --tags

6. Publish the package.

   npm publish