pinterval

Advanced setInterval

    npm install --save pinterval

Motivation

pinterval is a small tool that provides an advance mechanism for running an arbitrary code in intervals with flexible and simple API. It's a good fit for small badckground tasks. It supports both sync and async execution of a given function.

API

You can find API here

Features

• Support of async execution
• Graceful error handling
• Customization

Usage

Basic

 
import { Interval } from 'pinterval';
 
const interval = new Interval({
    func: () => console.log('Tick!'),
    time: 1000
});
 
interval.start();
 

Auto stop

If func returns false, the interval automatically stops. The following interval will stop after 10 calls.

 
import { Interval } from 'pinterval';
import sinon from 'sinon';
 
const spy = sinon.spy();
const interval = new Interval({
    func: () => {
        spy();
 
        return spy.calledCount < 10;
    },
    time: 1000
});
 
interval.start();
 

Error handling

 
import { Interval } from 'pinterval';
 
const interval = new Interval({
    func: () => console.log('Tick!'),
    time: 1000,
    onError: (err) => {
        if (err instanceof FatalError) {
            return false; // stop interval and terminate all further execution
        }
 
        return true;
    }
});
 
interval.start();
 

Async

In order to pass async function, it must return a promise on each tick. Each tick is calcualated after async function completion in order to avoid race conditions.

 
import { Interval } from 'pinterval';
 
const interval = new Interval({
    func: () => {
        return fetch('https://github.com/trending')
    },
    time: 1000
});
 
interval.start();
 

Additionally, error handler can be asynchronous too:

 
import { Interval } from 'pinterval';
 
const interval = new Interval({
    func: () => {
        return fetch('https://github.com/trending')
    },
    time: 1000,
    onError: (err: Error) => {
        return fetch('my-service', {
            method: 'POST',
            body: JSON.stringify({
                timerError: err
            })
        })
    }
});
 
interval.start();
 

Dynamic duration

Starting v3.3.0, you can pass a duration factory function into the consutrctor, in order to calculate dynamically interval duration for each tick:

 
import { Interval } from 'pinterval';
 
const minTimeout = 500;
const maxTimeout = 10000;
const interval = new Interval({
    func: () => console.log('Tick!'),
    time: (counter) => {
        const timeout = Math.round(minTimeout * Math.pow(2, counter));
 
        return Math.min(timeout, maxTimeout);
    }
});
 
interval.start();
 

The function receives a number of a tick, so you can use it to write an algorithm more accurately.

Helpers

Polling

poll implements a simple polling mechanism.

 
import { poll } from 'pinterval';
 
await poll(async () => {
    const result = await someProgress();
 
    return result === true;
}, 5000);
 

Until

until is similar to poll but it gives you a possibility to return a value for a polling function.
The polling continues until the predicate returns anything but undefined.

 
import { until } from 'pinterval';
 
const data = await until(async () => {
    const result = await someProgress();
 
    return result.data;
}, 5000);
 

Times

times executes a given function a specific amount of times.

 
import { times } from 'pinterval';
 
await times(async (counter) => {
    await updateSomething(counter);
}, 5, 1000);
 

Pipeline

pipeline sequentially executes a given array of functions with an interval between executions. Each function recieves an output of a previous one. NOTE: Unlike other functions, pipeline executes a first function with 0 timeout time, which means the provided timeout value is used between executions only. If you want to override this behavior, you must provide a function that calculates timeouts.

 
import { pipeline } from 'pinterval';
 
const out = await pipeline([() => 1, (i) => i * 2, (i) => i * 3, (i) => i * 4], 100);
 
console.log(out); // 24