Advanced interval management for JavaScript/TypeScript
A powerful and flexible interval management library that goes beyond JavaScript's native setInterval. Perfect for background tasks, polling, retries, and complex scheduling scenarios with built-in support for async/await, error handling, and dynamic timing strategies.
AbortSignal support and total-lifetime limitsInstall using your preferred package manager:
# npm
npm install --save pinterval
# yarn
yarn add pinterval
# pnpm
pnpm add pinterval
import { Interval } from 'pinterval';
// Create a simple interval
const interval = new Interval({
func: () => console.log('Tick!'),
time: 1000
});
// Start the interval
interval.start();
// Stop when needed
setTimeout(() => interval.stop(), 5000);
// Observe normal completion, stop, cancellation, or failure
await interval.done;
JavaScript's native setInterval has several limitations:
pinterval solves all these problems with a modern, Promise-based API that's perfect for:
Full API documentation is available at http://ziflex.github.io/pinterval
The Interval class is the core building block of pinterval. It provides a flexible way to execute functions repeatedly with configurable timing and error handling.
import { Interval } from 'pinterval';
const interval = new Interval({
func: () => console.log('Tick!'),
time: 1000
});
interval.start();
// Stop when needed
interval.stop();
interface Params {
func: (context: IntervalContext) => boolean | void | Promise<boolean | void>;
time: number | ((counter: number) => number);
start?: 'immediate' | 'delayed';
onError?: (err: Error) => boolean | void;
signal?: AbortSignal;
}
'delayed' (default) waits for the first delay, 'immediate' executes immediatelytrue to continue, false to stopstop() and rejects on cancellation or an unhandled error.'idle', 'running', 'paused', or 'stopped'.state === 'running'.start() remains synchronous and fluent. Read done after starting to await that specific run:
const interval = new Interval({
time: 1000,
func: async ({ iteration, elapsed, signal }) => {
console.log(`Execution ${iteration} after ${elapsed}ms`);
await fetch('/api/refresh', { signal });
}
});
interval.start();
const firstRun = interval.done;
// Pausing cancels the pending delay but preserves this run and its iteration count.
interval.pause();
interval.resume(); // The pending/next execution waits one normal interval duration.
setTimeout(() => interval.stop(), 5000);
await firstRun;
iteration is 1-based. elapsed is wall-clock time since start(), including paused time. signal is owned by the run: it reflects the supplied external signal and also aborts when stop() is called, allowing signal-aware callback work to stop cooperatively.
Before the first start, done is already resolved. Each subsequent start() creates a new promise and signal; an old done promise can never be settled by a later run. Calling resume() after a final stop is a no-op—use start() to begin a new run.
In v5, Interval callbacks receive this context object instead of a numeric counter:
// v4
func: (counter) => counter < 10
// v5
func: ({ iteration }) => iteration < 10
Duration functions retain their existing 1-based numeric counters. Finite-helper callbacks receive IntervalContext or RetryContext in v5.
Control when your interval executes for the first time:
// Delayed start (default): waits for time before first execution
const delayedInterval = new Interval({
func: () => console.log('First execution after 1 second'),
time: 1000,
start: 'delayed' // or omit this, it's the default
});
// Immediate start: executes immediately, then waits for timeout
const immediateInterval = new Interval({
func: () => console.log('Executes immediately!'),
time: 1000,
start: 'immediate'
});
If your function returns false, the interval automatically stops. This is useful for self-terminating intervals.
import { Interval } from 'pinterval';
let counter = 0;
const interval = new Interval({
func: () => {
counter++;
console.log(`Tick ${counter}`);
// Stop after 10 ticks
return counter < 10;
},
time: 1000
});
interval.start();
// Will automatically stop after 10 executions
Comprehensive error handling with both synchronous and asynchronous error handlers:
import { Interval } from 'pinterval';
// Synchronous error handler
const interval = new Interval({
func: () => {
// This might throw
riskyOperation();
},
time: 1000,
onError: (err) => {
console.error('Error occurred:', err);
// Return false to stop, true to continue
if (err instanceof FatalError) {
return false; // Stop interval
}
return true; // Continue with next tick
}
});
// Asynchronous error handler
const asyncInterval = new Interval({
func: async () => {
const response = await fetch('https://api.example.com/data');
return response.ok;
},
time: 5000,
onError: async (err: Error) => {
// Log error to remote service
await fetch('https://logging-service.com/log', {
method: 'POST',
body: JSON.stringify({ error: err.message })
});
// Decide whether to continue
return err.message !== 'FATAL';
}
});
Error Handler Return Values:
true - Continue interval execution (schedules next tick)false - Stop interval execution and resolve doneundefined or no return - Stop interval execution and resolve donedone rejects with the callback errordone rejects with the handler errorNative support for asynchronous functions with proper race condition prevention:
import { Interval } from 'pinterval';
const interval = new Interval({
func: async () => {
// The next tick won't start until this Promise resolves
const data = await fetch('https://api.example.com/status');
const json = await data.json();
console.log('Status:', json.status);
// Can return false to stop
return json.status !== 'completed';
},
time: 2000
});
interval.start();
Key Points:
false from async function to stop the intervalInterval, sleep, and every finite helper accept an optional standard AbortSignal. Aborting clears a pending scheduling timer immediately and prevents future executions. For Interval, it also rejects the current done promise with the external signal's exact reason.
import { Interval, until } from 'pinterval';
const intervalController = new AbortController();
const interval = new Interval({
time: 1000,
signal: intervalController.signal,
func: async ({ signal }) => {
await refreshData({ signal });
}
});
interval.start();
intervalController.abort();
try {
await interval.done;
} catch (err) {
console.log(err === intervalController.signal.reason); // true
}
const controller = new AbortController();
await until(readState, {
predicate: state => state.ready,
time: 500,
signal: controller.signal
});
For finite helpers, time and timeout have distinct meanings:
Every concrete duration passed to a timer follows the same validation contract: interval delays, sleep durations, and
finite-helper timeout values must be finite and between 0 and 2_147_483_647 milliseconds inclusive. Zero-duration
timers remain valid. Invalid values fail explicitly instead of relying on host-specific setTimeout coercion.
import { retry } from 'pinterval';
await retry(loadData, {
attempts: 10,
time: 250,
timeout: 10_000
});
AbortError and TimeoutError are exported classes that extend the standard Error type in both Node and browser environments. pinterval creates an AbortError when it needs its own cancellation reason (for example, when stop() aborts an interval's effective signal) and a TimeoutError when an overall helper timeout expires.
External cancellation still rejects with the exact signal.reason. That value belongs to the caller or host runtime and is not normalized, so it may be any value or host-provided error type. Neither cancellation nor timeout can forcibly interrupt arbitrary callback code already executing; it stops the operation promptly and prevents another iteration. Finite-helper callbacks receive the effective signal through IntervalContext or RetryContext; pass it to APIs such as fetch when callback work should also be interruptible.
Calculate interval duration dynamically based on the iteration count:
import { Interval } from 'pinterval';
// Exponential backoff
const interval = new Interval({
func: () => console.log('Tick!'),
time: (counter) => {
const minTimeout = 500;
const maxTimeout = 10000;
const timeout = Math.round(minTimeout * Math.pow(2, counter - 1));
return Math.min(timeout, maxTimeout);
}
});
interval.start();
// Executions at: 500ms, 1000ms, 2000ms, 4000ms, 8000ms, 10000ms, 10000ms...
Counter Parameter:
1 for the first executionFor complex timing strategies, see the Duration Functions section.
pinterval provides focused Promise-based helpers for four distinct finite-execution patterns:
poll waits for a boolean condition.until waits for a returned value accepted by a predicate.retry repeats an operation only when it throws or rejects.times executes an operation a fixed number of times.Every helper accepts positional scheduling arguments and object options. Its callback receives the same elapsed-time and effective-signal context used by Interval:
interface ExecutionOptions {
time: number | ((counter: number) => number); // Delay between executions
start?: 'immediate' | 'delayed'; // Defaults to 'immediate'
signal?: AbortSignal; // External cancellation
timeout?: number; // Maximum total lifetime
}
interface RetryContext {
attempt: number; // One-based execution number
elapsed: number; // Milliseconds elapsed at attempt start
signal: AbortSignal; // Effective cancellation signal
}
type RetryDecision = boolean | void;
type OnRetry = (
error: unknown,
context: RetryContext
) => RetryDecision | Promise<RetryDecision>;
interface RetryOptions extends ExecutionOptions {
attempts: number;
onRetry?: OnRetry;
}
interface TimesOptions extends ExecutionOptions {
amount: number;
}
time, attempts, and amount are required. attempts is the maximum total number of executions, including the first attempt.
Repeatedly checks a condition until it returns true. It resolves with void; errors propagate unchanged. By default, the first check happens immediately.
import { poll } from 'pinterval';
// Keep polling until the status becomes ready
await poll(async () => {
const status = await checkStatus();
return status === 'ready';
}, 1000);
console.log('Condition met!');
Signature:
function poll(
condition: (context: IntervalContext) => boolean | Promise<boolean>,
time: number | ((counter: number) => number),
start?: 'immediate' | 'delayed'
): Promise<void>
function poll(
condition: (context: IntervalContext) => boolean | Promise<boolean>,
options: ExecutionOptions
): Promise<void>
Parameters:
true to complete and false to keep polling'immediate' (default) or 'delayed'Example with immediate start:
// Check immediately, then every 5 seconds (default behavior)
await poll(
async () => (await fetch('/api/status')).ok,
5000
);
Example with delayed start:
// Wait 5 seconds before first check, then every 5 seconds
await poll(
async () => (await fetch('/api/status')).ok,
5000,
'delayed'
);
Repeatedly evaluates a value source and returns the first value accepted by an explicit predicate. The predicate sees every result, including undefined, null, and other falsy values. Source and predicate errors propagate unchanged.
import { until } from 'pinterval';
// Wait until the returned state is ready
const state = await until(async ({ signal }) => {
const response = await fetch('/api/data', { signal });
return await response.json();
}, value => value.ready, 2000);
console.log('State ready:', state);
Signature:
function until<T>(
source: (context: IntervalContext) => T | Promise<T>,
predicate: (value: T, context: IntervalContext) => boolean | Promise<boolean>,
time: number | ((counter: number) => number),
start?: 'immediate' | 'delayed'
): Promise<T>
function until<T>(
source: (context: IntervalContext) => T | Promise<T>,
options: ExecutionOptions & {
predicate: (value: T, context: IntervalContext) => boolean | Promise<boolean>
}
): Promise<T>
Parameters:
true when that value should be returned'immediate' (default) or 'delayed'Key Difference from poll:
poll - Waits for a boolean condition and returns voiduntil - Applies a predicate to produced values and returns the qualifying valueExecutes an operation until it returns normally or the maximum total attempt count is reached. Any returned value is success; only thrown or rejected failures are retried.
import { retry } from 'pinterval';
// Retry up to 5 times with 2 second intervals
const result = await retry(
async ({ attempt, signal }) => {
const response = await fetch('/api/resource', { signal });
if (!response.ok) throw new Error(`Attempt ${attempt} failed`);
return await response.json();
},
5, // max attempts
2000 // interval between attempts
);
Signature:
function retry<T>(
operation: (context: RetryContext) => T | Promise<T>,
attempts: number,
time: number | ((counter: number) => number),
start?: 'immediate' | 'delayed'
): Promise<T>
function retry<T>(
operation: (context: RetryContext) => T | Promise<T>,
options: RetryOptions
): Promise<T>
Parameters:
'immediate' (default) or 'delayed'Use object options to combine retry limits, delay, external cancellation, and an overall timeout:
await retry(loadData, {
attempts: 10,
time: 250,
timeout: 10_000
});
Observe failures and decide whether to retry with the same callback:
const result = await retry(loadData, {
attempts: 5,
time: 500,
onRetry: (error, { attempt }) => {
console.warn(`Attempt ${attempt} failed`, error);
return error instanceof HttpError && error.status >= 500;
}
});
onRetry runs after an attempt fails, only when another attempt is available, and before the retry delay begins. Returning false stops and rethrows the current operation error unchanged. Returning true, returning undefined, or omitting a return continues with the retry, so observation-only callbacks do not accidentally disable retries:
// Observation only: the missing return continues retrying.
onRetry: (error, { attempt }) => {
logger.warn(`Attempt ${attempt} failed`, error);
}
// Decision only.
onRetry: error => isTransient(error)
The callback may be asynchronous. It is awaited before the retry delay, receives the effective cancellation signal through RetryContext, and may combine asynchronous observation with a decision:
onRetry: async (error, context) => {
await recordFailure(error, context);
return shouldContinue(error);
}
If onRetry throws or rejects, its error is terminal and propagates unchanged. Exhaustion still rejects with the final operation error without invoking onRetry again.
With exponential backoff:
import { retry, duration } from 'pinterval';
const result = await retry(
async () => await fetchData(),
10,
duration.exponential(1000, 30000)
);
With the default immediate start, the first execution has no delay and the first retry uses duration index 2. Pass start: 'delayed' when the first execution should wait for duration index 1.
Executes a function sequentially exactly amount times with a delay between executions. amount must be a non-negative integer, and zero resolves without executing.
import { times } from 'pinterval';
// Execute immediately, then 4 more times with 1 second between executions
await times(
async ({ iteration, signal }) => {
console.log(`Execution ${iteration}`);
await updateMetrics(iteration, { signal });
},
5,
1000
);
console.log('All executions completed!');
Signature:
function times(
operation: (context: IntervalContext) => void | Promise<void>,
amount: number,
time: number | ((counter: number) => number),
start?: 'immediate' | 'delayed'
): Promise<void>
function times(
operation: (context: IntervalContext) => void | Promise<void>,
options: TimesOptions
): Promise<void>
Parameters:
iteration, elapsed, and the effective signal'immediate' (default) or 'delayed'v5 intentionally removes result-sentinel retry behavior and makes helper conditions positive:
// v4: true meant continue
await poll(() => !isReady(), 500);
// v5: true means satisfied
await poll(() => isReady(), 500);
// v4: undefined meant continue
await until(readState, 500);
// v5: the predicate owns acceptance
await until(readState, state => state.ready, 500);
// v4: undefined meant retry
await retry(async attempt => tryLoad(attempt), 5, 500);
// v5: failures retry; every normal return succeeds
await retry(async ({ attempt }) => await load(attempt), 5, 500);
Finite-helper callbacks now receive IntervalContext or RetryContext instead of a numeric counter. Duration functions keep their existing indices: immediate helpers skip index 1, while delayed helpers use it for the initial delay.
Sequentially executes an array of functions with intervals between them. Each function receives the output of the previous one.
import { pipeline } from 'pinterval';
const result = await pipeline([
() => 1,
(x) => x * 2, // receives 1, returns 2
(x) => x + 3, // receives 2, returns 5
(x) => x * 4 // receives 5, returns 20
], 100);
console.log(result); // 20
Signature:
function pipeline(
predicates: Array<(data: any) => any | Promise<any>>,
time: number | ((counter: number) => number),
start?: 'immediate' | 'delayed'
): Promise<any>
function pipeline(
predicates: Array<(data: any) => any | Promise<any>>,
options: ExecutionOptions
): Promise<any>
Important Notes:
start: 'immediate' (default)timeAsync pipeline example:
import { pipeline } from 'pinterval';
const result = await pipeline([
async () => await fetch('/api/users'),
async (response) => await response.json(),
async (users) => users.filter(u => u.active),
async (activeUsers) => {
await saveToDatabase(activeUsers);
return activeUsers.length;
}
], 500);
console.log(`Processed ${result} active users`);
Simple utility to pause execution for a specified duration.
import { sleep } from 'pinterval';
console.log('Starting...');
await sleep(2000);
console.log('2 seconds later...');
const controller = new AbortController();
const pendingSleep = sleep(5000, { signal: controller.signal });
controller.abort();
try {
await pendingSleep;
} catch (err) {
console.log(err === controller.signal.reason); // true
}
Signature:
function sleep(time: number, options?: { signal?: AbortSignal }): Promise<void>
time follows the common timer validation contract: it must be finite and between 0 and 2_147_483_647 milliseconds
inclusive, and zero is valid.
Durations use one common model: either a constant number of milliseconds or a function of the scheduling counter.
type DurationFunction = (counter: number) => number;
type Duration = number | DurationFunction;
All built-in functions are available under the duration namespace:
constant, linear, exponential, fibonacci, and stepscap, floor, jitter, and mapjittered convenience strategy and stateful decorrelatedJitterTransformations accept either form of Duration, so constants, built-ins, and custom functions compose in the same way. They evaluate from the inside out, and order remains observable.
The counter is one-based and retains the existing scheduling semantics. A delayed interval resolves counter 1 before its first execution. An immediate interval executes first without a delay, so its first resolved duration receives counter 2.
Resolved delays may be fractional, but must be finite and between 0 and 2_147_483_647 milliseconds inclusive. The
same range applies to sleep durations and finite-helper timeouts. Invalid values fail explicitly instead of relying on
host-specific setTimeout coercion.
Returns the same duration for every execution. Useful for fixed intervals.
import { Interval, duration } from 'pinterval';
const interval = new Interval({
func: () => console.log('Tick!'),
time: duration.constant(1000)
});
interval.start();
// Executes every 1000ms: 1000, 1000, 1000, 1000...
Signature:
function constant(ms: number): DurationFunction
Use Cases:
Increases duration linearly by a fixed increment on each iteration.
import { Interval, duration } from 'pinterval';
const interval = new Interval({
func: () => console.log('Tick!'),
time: duration.linear(100, 50)
});
interval.start();
// Executes at: 100ms, 150ms, 200ms, 250ms, 300ms...
Signature:
function linear(initial: number, increment: number): DurationFunction
Parameters:
Use Cases:
Decreasing intervals:
// Start fast, get slower by 100ms each time
const decreasing = duration.linear(2000, -100);
// Executes at: 2000ms, 1900ms, 1800ms, 1700ms...
Doubles the duration on each iteration with an optional maximum cap. This is the standard backoff strategy used in many systems.
import { retry, duration } from 'pinterval';
// Exponential backoff for retries
const result = await retry(
async () => await fetchData(),
10,
duration.exponential(100, 10000)
);
// Immediate first attempt, then retry delays: 200ms, 400ms, 800ms, 1600ms, ...
Signature:
function exponential(initial: number, max?: number): DurationFunction
Parameters:
Use Cases:
Without cap:
// Unbounded exponential growth
const uncapped = duration.exponential(100);
// Executes at: 100ms, 200ms, 400ms, 800ms, 1600ms, 3200ms, 6400ms...
Uses the Fibonacci sequence for duration calculation. Provides gentler growth than exponential backoff.
import { Interval, duration } from 'pinterval';
const interval = new Interval({
func: () => console.log('Tick!'),
time: duration.fibonacci(100)
});
interval.start();
// Executes at: 100ms, 100ms, 200ms, 300ms, 500ms, 800ms, 1300ms...
Signature:
function fibonacci(initial: number): DurationFunction
Parameters:
Use Cases:
Adds randomness to exponential backoff to prevent the "thundering herd" problem where multiple clients retry simultaneously.
This convenience strategy is equivalent to applying jitter to exponential. Its optional maximum caps the exponential value before jitter is applied, so the final jittered value can exceed that maximum by the selected factor. Use an outer duration.cap when the final value must have an absolute ceiling.
import { retry, duration } from 'pinterval';
// Add ±10% randomness to prevent synchronized retries
const result = await retry(
async () => await fetchData(),
10,
duration.jittered(1000, 30000, 0.1)
);
// Immediate first attempt, then retry delays (with ±10% jitter):
// ~2000ms (1800-2200), ~4000ms (3600-4400), ~8000ms (7200-8800)...
Signature:
function jittered(
initial: number,
max?: number,
jitterFactor?: number
): DurationFunction
Parameters:
Use Cases:
Custom jitter:
// ±25% randomness
const highJitter = duration.jittered(1000, 10000, 0.25);
// ±5% randomness
const lowJitter = duration.jittered(1000, 10000, 0.05);
AWS-style decorrelated jitter where each delay is based on the previous generated delay, not the iteration count. The initial duration is the lower bound, and the strategy is stateful.
import { retry, duration } from 'pinterval';
// AWS-style decorrelated jitter
const result = await retry(
async () => await fetchData(),
10,
duration.decorrelatedJitter(100, 10000)
);
// Each delay is random(initial, previous_delay * 3), capped at max
// Provides excellent distribution for distributed systems
Signature:
function decorrelatedJitter(initial: number, max: number): DurationFunction
Parameters:
initial)Use Cases:
Important Note:
Each generated and capped delay becomes the previous value used to calculate the next range. Each instance maintains its own internal state, so create a new instance for each interval:
// ✅ Correct: new instance per interval
const interval1 = new Interval({
func: task1,
time: duration.decorrelatedJitter(100, 5000)
});
const interval2 = new Interval({
func: task2,
time: duration.decorrelatedJitter(100, 5000)
});
// ❌ Wrong: sharing instance causes unexpected behavior
const sharedDuration = duration.decorrelatedJitter(100, 5000);
const interval3 = new Interval({ func: task1, time: sharedDuration });
const interval4 = new Interval({ func: task2, time: sharedDuration });
Returns different durations based on counter thresholds. Perfect for phase-based intervals that change behavior over time.
import { Interval, duration } from 'pinterval';
const interval = new Interval({
func: () => console.log('Tick!'),
time: duration.steps([
{ threshold: 0, duration: 100 }, // Fast for first 5
{ threshold: 5, duration: 500 }, // Medium for 5-10
{ threshold: 10, duration: 2000 } // Slow after 10
])
});
interval.start();
// Counter 1-4: 100ms
// Counter 5-9: 500ms
// Counter 10+: 2000ms
Signature:
function steps(
thresholds: Array<{ threshold: number; duration: number }>
): DurationFunction
Parameters:
Use Cases:
Complex example:
import { retry, duration } from 'pinterval';
// Aggressive at first, then back off
const result = await retry(
async () => await fetchData(),
20,
duration.steps([
{ threshold: 0, duration: 100 }, // First 3 attempts: fast (100ms)
{ threshold: 3, duration: 500 }, // Attempts 3-6: medium (500ms)
{ threshold: 6, duration: 2000 }, // Attempts 6-10: slow (2s)
{ threshold: 10, duration: 5000 } // Attempts 10+: very slow (5s)
])
);
Transformations resolve their source and return another DurationFunction, so they can be nested without special support from Interval, retry, poll, until, or times.
Limits a constant or calculated duration to a maximum value:
const capped = duration.cap(
duration.exponential(100),
30_000
);
capped(1); // 100
capped(20); // 30_000
function cap(source: Duration, maximum: number): DurationFunction
Raises a constant or calculated duration to a minimum value:
const floored = duration.floor(
duration.linear(100, 100),
500
);
floored(1); // 500
floored(6); // 600
function floor(source: Duration, minimum: number): DurationFunction
Applies symmetric randomness to any duration. A factor of 0.2 means a variation from -20% through +20%; factors must be between 0 and 1.
const jittered = duration.jitter(
duration.fibonacci(100),
0.2
);
function jitter(source: Duration, factor: number): DurationFunction
Transforms a resolved value and receives the unchanged scheduling counter as its second argument:
const rounded = duration.map(
duration.exponential(100),
(value, counter) => {
console.log(`Resolving duration ${counter}`);
return Math.round(value / 100) * 100;
}
);
function map(
source: Duration,
transform: (value: number, counter: number) => number
): DurationFunction
Combinators evaluate from the inside out. Capping after jitter guarantees an absolute maximum; jittering after a cap may exceed that cap:
duration.cap(duration.jitter(source, 0.2), 1000);
duration.jitter(duration.cap(source, 1000), 0.2);
A realistic retry strategy can combine the primitives and transformations directly:
import { duration, retry } from 'pinterval';
const result = await retry(loadData, {
attempts: 10,
time: duration.cap(
duration.jitter(
duration.exponential(100),
0.2
),
5000
)
});
Monitor a service health endpoint with intelligent backoff when failures occur:
import { Interval, duration } from 'pinterval';
let consecutiveFailures = 0;
const healthCheck = new Interval({
func: async () => {
try {
const response = await fetch('https://api.example.com/health');
if (response.ok) {
consecutiveFailures = 0;
console.log('✓ Service is healthy');
return true;
}
consecutiveFailures++;
console.log(`✗ Service unhealthy (${consecutiveFailures} failures)`);
return true;
} catch (error) {
consecutiveFailures++;
console.error(`✗ Health check failed: ${error.message}`);
return consecutiveFailures < 10; // Stop after 10 failures
}
},
time: (counter) => {
// Normal polling: 5s, on failure: exponential backoff up to 60s
if (consecutiveFailures === 0) return 5000;
return Math.min(5000 * Math.pow(2, consecutiveFailures - 1), 60000);
},
start: 'immediate'
});
healthCheck.start();
Poll an API until a specific condition is met:
import { poll } from 'pinterval';
async function waitForJobCompletion(jobId: string) {
console.log(`Waiting for job ${jobId} to complete...`);
await poll(async () => {
const response = await fetch(`/api/jobs/${jobId}`);
const job = await response.json();
console.log(`Job status: ${job.status}`);
if (job.status === 'completed') {
console.log('Job completed successfully!');
return true;
}
if (job.status === 'failed') {
throw new Error('Job failed!');
}
return false; // Keep polling
}, 2000, 'immediate');
}
// Usage
await waitForJobCompletion('job-123');
Implement sophisticated retry logic with multiple strategies:
import { retry, duration } from 'pinterval';
async function fetchWithRetry(url: string) {
// Try primary endpoint with exponential backoff
try {
return await retry(
async ({ signal }) => {
const response = await fetch(url, { signal });
if (!response.ok) throw new Error(`Primary request failed: ${response.status}`);
return await response.json();
},
5,
duration.exponential(1000, 10000),
'immediate'
);
} catch (primaryError) {
console.warn('Primary endpoint failed, trying backup...');
// Fall back to backup endpoint with linear backoff
return await retry(
async ({ signal }) => {
const response = await fetch(url.replace('api', 'api-backup'), { signal });
if (!response.ok) throw new Error(`Backup request failed: ${response.status}`);
return await response.json();
},
3,
duration.linear(2000, 1000),
'immediate'
);
}
}
Implement a rate-limited API client that respects API limits:
import { Interval } from 'pinterval';
class RateLimitedClient {
private queue: Array<() => Promise<any>> = [];
private interval: Interval;
constructor(requestsPerSecond: number) {
const delay = 1000 / requestsPerSecond;
this.interval = new Interval({
func: async () => {
if (this.queue.length === 0) {
return true; // Keep running
}
const task = this.queue.shift();
if (task) {
await task();
}
return true;
},
time: delay,
start: 'immediate'
});
this.interval.start();
}
async request(url: string): Promise<Response> {
return new Promise((resolve, reject) => {
this.queue.push(async () => {
try {
const response = await fetch(url);
resolve(response);
} catch (error) {
reject(error);
}
});
});
}
stop() {
this.interval.stop();
}
}
// Usage: max 10 requests per second
const client = new RateLimitedClient(10);
// All requests are automatically rate-limited
const responses = await Promise.all([
client.request('/api/users/1'),
client.request('/api/users/2'),
client.request('/api/users/3'),
// ... more requests
]);
Prevent thundering herd when multiple services try to reconnect to a database:
import { retry, duration } from 'pinterval';
async function connectToDatabase(config: DbConfig) {
console.log('Attempting to connect to database...');
return await retry(async () => {
const connection = await createConnection(config);
await connection.ping();
console.log('✓ Database connected');
return connection;
}, {
attempts: 10,
time: duration.jittered(1000, 30000, 0.2), // ±20% jitter
onRetry: (error, { attempt }) => {
console.log(`✗ Connection failed (attempt ${attempt}): ${error}, retrying...`);
}
});
}
Process data through multiple stages with delays:
import { pipeline } from 'pinterval';
async function processUserData(userId: string) {
const result = await pipeline([
// Stage 1: Fetch user data
async () => {
console.log('Stage 1: Fetching user data...');
const response = await fetch(`/api/users/${userId}`);
return await response.json();
},
// Stage 2: Enrich with additional data
async (user) => {
console.log('Stage 2: Enriching data...');
const orders = await fetch(`/api/users/${userId}/orders`);
return { ...user, orders: await orders.json() };
},
// Stage 3: Calculate analytics
async (userData) => {
console.log('Stage 3: Computing analytics...');
return {
...userData,
analytics: {
totalOrders: userData.orders.length,
totalSpent: userData.orders.reduce((sum, o) => sum + o.amount, 0)
}
};
},
// Stage 4: Save to cache
async (enrichedData) => {
console.log('Stage 4: Caching results...');
await saveToCache(`user:${userId}`, enrichedData);
return enrichedData;
}
], 500); // 500ms between stages
console.log('Pipeline completed!');
return result;
}
Run a background cleanup task with dynamic timing:
import { Interval, duration } from 'pinterval';
const cleanupTask = new Interval({
func: async ({ iteration }) => {
console.log(`Running cleanup task (iteration ${iteration})...`);
try {
// Clean up old records
const deleted = await deleteOldRecords();
console.log(`✓ Cleaned up ${deleted} old records`);
// Clean up temporary files
await cleanupTempFiles();
console.log('✓ Temporary files cleaned');
return true; // Continue running
} catch (error) {
console.error(`✗ Cleanup failed: ${error.message}`);
return true; // Continue despite errors
}
},
time: duration.steps([
{ threshold: 0, duration: 60000 }, // First hour: every minute
{ threshold: 60, duration: 300000 }, // Hours 1-5: every 5 minutes
{ threshold: 300, duration: 3600000 } // After 5 hours: every hour
]),
start: 'delayed',
onError: async (err) => {
// Log error to monitoring service
await logError('cleanup-task', err);
return true; // Continue running
}
});
cleanupTask.start();
pinterval is written in TypeScript and provides full type definitions out of the box. No need for @types/* packages!
import { Interval, Params, IntervalFunction } from 'pinterval';
// Type-safe interval function
const myFunction: IntervalFunction = ({ iteration, elapsed, signal }) => {
console.log(`Tick ${iteration} after ${elapsed}ms`, signal.aborted);
return iteration < 10;
};
// Type-safe parameters
const params: Params = {
func: myFunction,
time: 1000,
start: 'immediate',
onError: (err: Error) => {
console.error(err);
return false;
}
};
const interval = new Interval(params);
Helper functions support generic types for type-safe return values:
import { until, retry } from 'pinterval';
interface User {
id: string;
name: string;
email: string;
}
// Type-safe until
const user = await until<User>(async () => {
const response = await fetch('/api/user');
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
return await response.json(); // Typed as User
}, user => user.id.length > 0, 1000);
// user is typed as User
console.log(user.email);
// Type-safe retry
interface ApiResponse {
success: boolean;
data: any;
}
const result = await retry<ApiResponse>(
async ({ signal }) => {
const response = await fetch('/api/data', { signal });
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
return await response.json();
},
5,
2000
);
Create type-safe duration functions:
import { DurationFunction, Interval } from 'pinterval';
// Custom duration function with full type safety
const customDuration: DurationFunction = (counter: number): number => {
if (counter <= 3) return 1000;
if (counter <= 6) return 2000;
return 5000;
};
const interval = new Interval({
func: () => console.log('Tick!'),
time: customDuration
});
Here's why you might choose pinterval over native setInterval:
| Feature | Native setInterval | pinterval |
|---|---|---|
| Async/Await Support | ❌ No native support | ✅ Built-in Promise support |
| Error Handling | ❌ Errors crash the interval | ✅ Graceful error handling with recovery |
| Dynamic Intervals | ❌ Fixed interval only | ✅ Calculate interval per iteration |
| Auto-Stop | ❌ Manual management only | ✅ Automatic stop on conditions |
| Backoff Strategies | ❌ Not supported | ✅ Multiple built-in strategies |
| Race Conditions | ❌ Can overlap with async code | ✅ Prevents overlapping execution |
| Helper Functions | ❌ Build your own | ✅ poll, retry, until, times, pipeline |
| TypeScript | ⚠️ Basic types only | ✅ Full TypeScript support |
| API | ⚠️ Callback-based | ✅ Modern Promise-based API |
Before (native setInterval):
let intervalId;
let attempts = 0;
intervalId = setInterval(async () => {
try {
attempts++;
const response = await fetch('/api/status');
const data = await response.json();
if (data.ready) {
clearInterval(intervalId);
console.log('Ready!');
}
if (attempts >= 10) {
clearInterval(intervalId);
throw new Error('Max attempts reached');
}
} catch (error) {
clearInterval(intervalId);
console.error('Error:', error);
}
}, 2000);
After (pinterval):
import { until } from 'pinterval';
try {
await until(async ({ signal }) => {
const response = await fetch('/api/status', { signal });
return await response.json();
}, {
predicate: data => data.ready,
time: 2000,
timeout: 20_000
});
console.log('Ready!');
} catch (error) {
console.error('Error:', error);
}
poll when waiting for a boolean conditionuntil when you need to return a valueretry for operations with a maximum attempt limittimes for a fixed number of executionspipeline for sequential multi-stage processingInterval class for complex custom scenariosAlways provide an error handler for production code:
const interval = new Interval({
func: async () => {
await riskyOperation();
},
time: 5000,
onError: async (err) => {
// Log to monitoring service
await logError(err);
// Decide based on error type
if (err instanceof NetworkError) {
return true; // Retry on network errors
}
return false; // Stop on other errors
}
});
Always stop intervals when they're no longer needed:
class MyComponent {
private interval: Interval;
start() {
this.interval = new Interval({
func: () => this.updateData(),
time: 5000
});
this.interval.start();
}
// Clean up when component unmounts
cleanup() {
this.interval?.stop();
}
}
The default start mode is now 'immediate' for most helper functions, which is ideal for most use cases:
// ✅ Default behavior: check immediately, then resolve when the condition is true
await poll(() => checkStatus(), 1000); // Immediate by default
// Use 'delayed' when you specifically want to wait before the first execution
await poll(() => checkStatus(), 1000, 'delayed'); // Wait 1s before first check
When to use 'delayed' mode:
Use shorter timeouts during testing:
const timeout = process.env.NODE_ENV === 'test' ? 100 : 5000;
const interval = new Interval({
func: myFunction,
time: timeout
});
// Wait for service to be ready, then start processing
await poll(async () => await isServiceReady(), 1000);
// Now run the main task with retries
await times(async ({ iteration }) => {
await retry(async () => await processItem(iteration), 3, 1000);
}, 10, 5000);
# Install dependencies
npm install
# Build the project
npm run build
# The compiled JavaScript will be in the lib/ directory
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Lint the code
npm run lint
# Format code
npm run fmt
# Generate TypeDoc documentation
npm run doc
# Documentation will be generated in docs/ directory
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
Created and maintained by Tim Voronov