RxJS Polling Operator

A flexible RxJS operator library that enables polling on any completed observable source with advanced timing and retry strategies.

🚀 Features

- Two polling types: repeat and interval to suit different use cases
- Timing strategies: constant, linear, exponential, random and dynamic (custom logic)
- Auto-pause: Automatically pause/resume polling based on page visibility (browser only)
- Reliable execution: First and in-flight cycles (poll or retry) guaranteed
- Flexible retries: Control retry attempts with consecutive or total counting modes
- Input validation: Guards against unexpected input time values
- Cross-platform: Works in both browser and Node.js environments
- Modern compatibility: Compatible with RxJS v7+
- Module formats: Supports CJS, ESM, and UMD

📦 Installation

``shell
npm install rxjs-poll --save
`

🎯 Purpose & Process

Polling is essential when you need to repeatedly check for updates from sources that don't provide real-time notifications. Common scenarios include monitoring HTTP API endpoints for status changes, watching DOM elements for state updates, or periodically sampling data streams.

This operator cleanly separates polling concerns from your core observable logic. It waits for your source observable to complete per polling type, then schedules the next poll based on your configuration. The architecture distinguishes between normal polling delays and error retry scenarios, giving you precise control over both success and failure timing strategies.

🧪 Usage Examples

$3

▶️ Live Demo

Plug and play - just add the operator to your pipe and start polling.

`typescript
import { poll } from 'rxjs-poll';
import { takeWhile } from 'rxjs';

request$
.pipe(
poll(), // Poll every second with exponential retry strategy (7s max)
takeWhile(({ status }) => status !== 'done', true)
)
.subscribe({ next: console.log });
`

$3

▶️ Live Demo

Use built-in strategies for easy timing control.

`typescript
import { poll } from 'rxjs-poll';
import { takeWhile } from 'rxjs';

request$
.pipe(
poll({
type: 'interval', // Drops uncompleted source after delay
delay: {
strategy: 'random',
time: [1000, 3000], // Random delay between 1 and 3 seconds
},
retry: {
limit: Infinity, // Will never throw
},
}),
takeWhile(({ status }) => status !== 'done', true)
)
.subscribe({ next: console.log });
`

$3

▶️ Live Demo

Implement complex polling strategies with dynamic timing based on poll state.

`typescript
import { poll } from 'rxjs-poll';
import { takeWhile } from 'rxjs';

request$
.pipe(
poll({
delay: {
/* Adaptive polling based on response data /
strategy: 'dynamic',
time: ({ value }) => (value?.items.length ? 1000 : 500),
},
retry: {
/* Custom exponential backoff with jitter /
strategy: 'dynamic',
time: ({ consecutiveRetryCount }) => {
const exponential = Math.pow(2, consecutiveRetryCount - 1) * 1000;
const jitter = Math.random() * 200;

return exponential + jitter;
},
limit: 6,
},
}),
takeWhile(({ status }) => status !== 'done', true)
)
.subscribe({ next: console.log });
`

📋 API Reference

$3

Creates a polling operator that will begin polling once the source observable completes.

#### PollConfig

`typescript
interface PollConfig {
/**
* Defines the polling behavior:
* - 'repeat': Polls after current source completes
* - 'interval': Polls in intervals, dropping any ongoing source operations
* @default 'repeat'
*/
type?: 'repeat' | 'interval';

/**
* Configuration for polling delays (between successful operations)
*/
delay?: {
/**
* Strategy type for delay timing. Built-in strategies (except dynamic)
* calculate time per state's pollCount.
* @default 'constant'
*/
strategy: 'constant' | 'linear' | 'exponential' | 'random' | 'dynamic';

/**
* Time (ms) depending on strategy:
* - constant: number
* - linear: number
* - exponential: number
* - random: [min, max]
* - dynamic: (state) => number | [min, max]
* @default 1000
*/
time:
| number
| [min: number, max: number]
| (state: PollState) => number | [min: number, max: number];
};

/**
* Configuration for retry behavior (on errors)
*/
retry?: {
/**
* Strategy type for retry timing. Built-in strategies (except dynamic)
* calculate time per state:
* - consecutiveOnly: true → uses consecutiveRetryCount
* - consecutiveOnly: false → uses retryCount
* @default 'exponential'
* @note Required if time is provided, otherwise uses default
*/
strategy: 'constant' | 'linear' | 'exponential' | 'random' | 'dynamic';

/**
* Time (ms) depending on strategy:
* - constant: number
* - linear: number
* - exponential: number
* - random: [min, max]
* - dynamic: (state) => number | [min, max]
* @default 1000
* @note Required if strategy is provided, otherwise uses default
*/
time:
| number
| [min: number, max: number]
| (state: PollState) => number | [min: number, max: number];

/**
* Maximum number of retry attempts before throwing an error.
* Use Infinity to keep retrying indefinitely.
* @default 3
*/
limit?: number;

/**
* Controls how retries are counted:
* - true: Only consecutive errors count toward retry limit
* (resets counter on success)
* - false: All errors count toward retry limit regardless of
* successful responses between them
* @default true
*/
consecutiveOnly?: boolean;
};

/**
* [Browser only] Controls polling behavior when page isn't visible
* - true: Pause polling when tab isn't active, and resume on active
* - false: Poll even when tab isn't focused
* @default true
* @note Every started cycle (poll or retry) finishes before pausing
*/
pauseWhenHidden?: boolean;
}
`

$3

State object passed to delay/retry time producer functions:

`typescript
interface PollState {
/** Latest value from the source. For interval polling type,
first emission is undefined. /
value: T | undefined;

/* Latest error when retrying /
error: any | undefined;

/* Total number of successful poll operations /
pollCount: number;

/* Total number of retry attempts /
retryCount: number;

/* Current number of consecutive retry attempts /
consecutiveRetryCount: number;
}

/* Note: pollCount + retryCount = total attempts /
``

📚 Additional Resources

- Troubleshooting Guide - Common issues and solutions
- V2 Changes - Overview of the changes and migration steps

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Have a question? Check out GitHub Discussions to ask questions, share ideas, or get help from the community.

🙌 Credits

This library is inspired by rx-polling, which creates an Observable for polling.

📄 License

MIT