poll

poll

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

Links:

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

Table of contents

• Installation
• Tests
• Documentation
• Usage

Installation

Browser

Download the ES module file …

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

… and import it like this:

import poll from 'poll.mjs';

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

poll(fn, 1000);

Node

Install the node package as a dependency …

npm install --save poll

… and import it like this:

• CommonJS module

  const poll = require('poll').default;
  
  function fn() {
    console.log('Hello, beautiful!');
  };
  
  poll(fn, 1000);
  

• ES module

  import poll from 'poll/dist/esm/poll.mjs';
  
    function fn() {
    console.log('Hello, beautiful!');
  };
  
  poll(fn, 1000);
  

• TypeScript module

  import poll from 'poll/src/poll';
  
  function fn() {
    console.log('Hello, beautiful!');
  };
  
  poll(fn, 1000);
  

Tests

In order to run the tests, clone the repository and run the following commands:

npm install
npm test

Documentation

Syntax

poll(function, delay[, shouldStopPolling])

Parameters:

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

• delay: Required. The delay (in milliseconds) to wait before calling the function again.

• 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 function was successfully awaited. In other words, right before triggering a new delay period.
  • After the delay has passed. In other words, right before calling function again.

  This guarantees two things:

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

Return value:

None.

Changelog

1.0.0 (2019-08-04)

Breaking changes

• Importing the CommonJS module with require('poll') no longer resolves to the poll function. Use require('poll').default instead.

  const poll = require('poll').default;
  

Non-breaking changes:

• The package is now available as an ES module. If you use poll as a dependency, import it like this:

  import poll from 'poll/dist/esm/poll.mjs';
  

• Tests now use Jest instead of Ava.

• Tests are now based on fake timers instead of calling setTimeout in the tests directly. Unfortunately, tests still require a lot of trickery to manually clear out the promise queue. If you know how to test this without sprinkling await Promise.resolve() all over my tests, I’m all ears!