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.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.