time-queues

Lightweight library for asynchronous task scheduling and concurrency control in JavaScript. Works in browsers, Node.js, Deno, and Bun.

Why time-queues?

Modern web apps need to schedule work without blocking the main thread, respect page lifecycle events, and limit concurrency — but the platform APIs are low-level and tedious to use correctly. time-queues wraps them in a small, composable toolkit:

• Schedule tasks to run after a delay, at a specific time, or on a recurring interval
• Optimize browser performance by running work during idle periods or animation frames
• React to page lifecycle changes (hidden, frozen, terminated) automatically
• Control concurrency with throttling, debouncing, batching, and rate limiting
• Manage resources with reference-counted creation/destruction
• Minimal footprint — one dependency (list-toolkit, zero-dep)

Installation

npm install time-queues

Quick Start

import sleep from 'time-queues/sleep.js';
import {Scheduler, repeat} from 'time-queues/Scheduler.js';
import {batch} from 'time-queues/batch.js';

// Simple delay
await sleep(1000);

// Run a task every 5 seconds
const scheduler = new Scheduler();
scheduler.enqueue(
  repeat(({task, scheduler}) => {
    console.log('tick');
  }, 5000),
  5000
);

// Fetch 10 URLs, max 3 at a time
const results = await batch(
  urls.map(url => () => fetch(url).then(r => r.json())),
  3
);

See the wiki for more use cases.

Documentation

The project wiki has detailed docs for every component.

Queues

Component	Purpose
Scheduler	Time-based task scheduling (delays, dates, repeats)
IdleQueue	Run tasks during browser idle periods
FrameQueue	Run tasks in animation frames
LimitedQueue	Concurrency-controlled async queue
PageWatcher	React to page lifecycle changes

Utilities

Function	Purpose
sleep()	Promise-based delay
defer()	Execute on next tick
throttle()	Rate-limit a function (first call wins)
debounce()	Delay until input stabilizes
sample()	Sample at regular intervals
audit()	Collect then execute after delay
batch()	Run async ops with concurrency limit

Supporting Classes

Component	Purpose
Throttler	Key-based rate limiting
Retainer	Resource lifecycle management
Counter	Track pending task counts
MicroTask	Base task unit
MicroTaskQueue	Base queue class
ListQueue	List-based queue implementation

Random Utilities

Module	Purpose
random-dist	Random numbers (uniform, normal, exponential, Pareto)
random-sleep	Randomized delays from various distributions

Page Load Helpers

Function	Purpose
whenDomLoaded()	Run code when DOM is ready
whenLoaded()	Run code when page is fully loaded

Browser Notes

The library leverages these browser APIs where available:

• requestIdleCallback()
• requestAnimationFrame()
• queueMicrotask()
• Page Lifecycle API

For background reading:

• Background Tasks API
• Page Visibility API

Test web app

Run npm start and open http://localhost:3000/tests/web/ — open the console, switch tabs, navigate away and back to see queues in action. Source: tests/web/test.js.

AI Integration

This project ships llms.txt and llms-full.txt for AI agents and LLMs. Contributors and AI coding assistants should see AGENTS.md for project conventions.

Development

git clone --recurse-submodules https://github.com/uhop/time-queues.git
cd time-queues
npm install
npm test

License

BSD-3-Clause

Release History

• 1.4.0 Multiple fixes that improve edge cases, minor additive API changes for edge cases.
• 1.3.2 Bug fixes (Scheduler, LimitedQueue, PageWatcher, Retainer), corrected .d.ts declarations, expanded tests, documentation fixes.
• 1.3.1 Fixed .d.ts declarations, consolidated TS typing tests, improved documentation.
• 1.3.0 Added batch(), LimitedQueue, random distributions and random sleep functions.
• 1.2.4 Updated dependencies.
• 1.2.3 Updated dependencies.
• 1.2.2 Counter: separated old waiter from new waiters before notifying them.
• 1.2.1 Minor release: updated formal TS dependencies in index.d.ts.
• 1.2.0 Added Counter.
• 1.1.2 Updated dev dependencies.
• 1.1.1 Updates to TS typings.
• 1.1.0 Added Throttler, Retainer, promise-based convenience time methods.
• 1.0.5 Technical release: updated deps, more tests.
• 1.0.4 Bug fixes and code simplifications.
• 1.0.3 Updated deps (list-toolkit) to fix a minor bug.
• 1.0.2 Updated deps (list-toolkit).
• 1.0.1 Minor update in README.
• 1.0.0 Initial release.

See release notes for more details and history.