time-queues 1.3.0 → 1.3.1

package/README.md

@@ -3,17 +3,18 @@
 [npm-img]: https://img.shields.io/npm/v/time-queues.svg
 [npm-url]: https://npmjs.org/package/time-queues
 
-`time-queues` is an efficient, lightweight library for organizing asynchronous multitasking and scheduled tasks in JavaScript applications. It works seamlessly in browsers and server-side environments like Node.js, Deno, and Bun.
+Lightweight library for asynchronous task scheduling and concurrency control in JavaScript. Works in browsers, Node.js, Deno, and Bun.
 
-The library provides elegant solutions for common timing and scheduling challenges, helping developers create responsive, efficient applications that follow best practices for resource management and user experience.
+## Why time-queues?
 
-## Key Features
+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:
 
-- **Efficient Task Scheduling**: Schedule tasks to run at specific times or after delays
-- **Browser Performance Optimization**: Execute tasks during idle periods or animation frames
-- **Page Lifecycle Management**: Respond intelligently to page visibility and focus changes
-- **Resource Management**: Control execution rates with throttling and debouncing
-- **Minimal Dependencies**: Relies only on [list-toolkit](https://www.npmjs.com/package/list-toolkit), a zero-dependency library
+- **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](https://www.npmjs.com/package/list-toolkit), zero-dep)
 
 ## Installation
 
@@ -21,127 +22,137 @@ The library provides elegant solutions for common timing and scheduling challeng
 npm install time-queues
 ```
 
-If you want to check out the source code, you can use the following command:
+## Quick Start
 
-```sh
-git clone --recurse-submodules https://github.com/uhop/time-queues.git
-cd time-queues
-npm install
+```js
+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
+);
 ```
 
-## Documentation
-
-The [project wiki](https://github.com/uhop/time-queues/wiki) provides comprehensive information about the `time-queues` library.
-
-### Core Task Queue Classes
-
-- [MicroTask](https://github.com/uhop/time-queues/wiki/MicroTask): Base class for deferred execution
-- [MicroTaskQueue](https://github.com/uhop/time-queues/wiki/MicroTaskQueue): Base class for task queues
-- [ListQueue](https://github.com/uhop/time-queues/wiki/ListQueue): List-based queue implementation
-
-### Concurrency Control
-
-- [LimitedQueue](https://github.com/uhop/time-queues/wiki/LimitedQueue): Queue with controlled concurrency
-- [Throttler](https://github.com/uhop/time-queues/wiki/Throttler): Control execution rate based on keys
-- [Counter](https://github.com/uhop/time-queues/wiki/Counter): Track pending task counts
-
-### Browser-Specific Components
-
-- [IdleQueue](https://github.com/uhop/time-queues/wiki/IdleQueue): Execute tasks during browser idle periods
-- [FrameQueue](https://github.com/uhop/time-queues/wiki/FrameQueue): Execute tasks during animation frames
-- [PageWatcher](https://github.com/uhop/time-queues/wiki/PageWatcher): Monitor and respond to page lifecycle changes
-
-### Scheduling & Timing
+See the [wiki](https://github.com/uhop/time-queues/wiki) for more use cases.
 
-- [Scheduler](https://github.com/uhop/time-queues/wiki/Scheduler): Time-based task scheduling
-- [Retainer](https://github.com/uhop/time-queues/wiki/Retainer): Resource lifecycle management
+## Documentation
 
-### Utility Functions
+The [project wiki](https://github.com/uhop/time-queues/wiki) has detailed docs for every component.
 
-- [defer()](<https://github.com/uhop/time-queues/wiki/defer()>): Execute tasks in the next tick
-- [sleep()](<https://github.com/uhop/time-queues/wiki/sleep()>): Promise-based delay function
-- [throttle()](<https://github.com/uhop/time-queues/wiki/throttle()>): Limit function execution rate
-- [debounce()](<https://github.com/uhop/time-queues/wiki/debounce()>): Delay function execution until input stabilizes
-- [sample()](<https://github.com/uhop/time-queues/wiki/sample()>): Execute function at regular intervals
-- [audit()](<https://github.com/uhop/time-queues/wiki/audit()>): Execute function after specified delay
-- [batch()](<https://github.com/uhop/time-queues/wiki/batch()>): Execute async operations with controlled concurrency
+### Queues
 
-### Random Distribution Utilities
+| Component                                                             | Purpose                                             |
+| --------------------------------------------------------------------- | --------------------------------------------------- |
+| [Scheduler](https://github.com/uhop/time-queues/wiki/Scheduler)       | Time-based task scheduling (delays, dates, repeats) |
+| [IdleQueue](https://github.com/uhop/time-queues/wiki/IdleQueue)       | Run tasks during browser idle periods               |
+| [FrameQueue](https://github.com/uhop/time-queues/wiki/FrameQueue)     | Run tasks in animation frames                       |
+| [LimitedQueue](https://github.com/uhop/time-queues/wiki/LimitedQueue) | Concurrency-controlled async queue                  |
+| [PageWatcher](https://github.com/uhop/time-queues/wiki/PageWatcher)   | React to page lifecycle changes                     |
 
-- [random-dist](https://github.com/uhop/time-queues/wiki/random-dist): Generate random numbers from various probability distributions
-- [random-sleep](https://github.com/uhop/time-queues/wiki/random-sleep): Create randomized delays with various probability distributions
+### Utilities
 
-## Getting Started
+| Function                                                            | Purpose                                 |
+| ------------------------------------------------------------------- | --------------------------------------- |
+| [sleep()](<https://github.com/uhop/time-queues/wiki/sleep()>)       | Promise-based delay                     |
+| [defer()](<https://github.com/uhop/time-queues/wiki/defer()>)       | Execute on next tick                    |
+| [throttle()](<https://github.com/uhop/time-queues/wiki/throttle()>) | Rate-limit a function (first call wins) |
+| [debounce()](<https://github.com/uhop/time-queues/wiki/debounce()>) | Delay until input stabilizes            |
+| [sample()](<https://github.com/uhop/time-queues/wiki/sample()>)     | Sample at regular intervals             |
+| [audit()](<https://github.com/uhop/time-queues/wiki/audit()>)       | Collect then execute after delay        |
+| [batch()](<https://github.com/uhop/time-queues/wiki/batch()>)       | Run async ops with concurrency limit    |
 
-To get started with `time-queues`, install it via npm:
+### Supporting Classes
 
-```sh
-npm install time-queues
-```
+| Component                                                                 | Purpose                         |
+| ------------------------------------------------------------------------- | ------------------------------- |
+| [Throttler](https://github.com/uhop/time-queues/wiki/Throttler)           | Key-based rate limiting         |
+| [Retainer](https://github.com/uhop/time-queues/wiki/Retainer)             | Resource lifecycle management   |
+| [Counter](https://github.com/uhop/time-queues/wiki/Counter)               | Track pending task counts       |
+| [MicroTask](https://github.com/uhop/time-queues/wiki/MicroTask)           | Base task unit                  |
+| [MicroTaskQueue](https://github.com/uhop/time-queues/wiki/MicroTaskQueue) | Base queue class                |
+| [ListQueue](https://github.com/uhop/time-queues/wiki/ListQueue)           | List-based queue implementation |
 
-Then import the components you need in your project:
+### Random Utilities
 
-```js
-// Import specific components
-import {Scheduler, repeat} from 'time-queues/Scheduler.js';
-import idleQueue from 'time-queues/IdleQueue.js';
-import defer from 'time-queues/defer.js';
+| Module                                                                | Purpose                                               |
+| --------------------------------------------------------------------- | ----------------------------------------------------- |
+| [random-dist](https://github.com/uhop/time-queues/wiki/random-dist)   | Random numbers (uniform, normal, exponential, Pareto) |
+| [random-sleep](https://github.com/uhop/time-queues/wiki/random-sleep) | Randomized delays from various distributions          |
 
-// Use the components in your application
-```
+### Page Load Helpers
 
-For more information, see the documentation for each component in the wiki.
+| Function                                                                      | Purpose                            |
+| ----------------------------------------------------------------------------- | ---------------------------------- |
+| [whenDomLoaded()](<https://github.com/uhop/time-queues/wiki/whenDomLoaded()>) | Run code when DOM is ready         |
+| [whenLoaded()](<https://github.com/uhop/time-queues/wiki/whenLoaded()>)       | Run code when page is fully loaded |
 
-## Browser-related notes
+## Browser Notes
 
-Internally it uses `list-toolkit` and leverages the following browser APIs:
+The library leverages these browser APIs where available:
 
 - [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback)
 - [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
 - [queueMicrotask()](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)
-- [setTimeout()](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout)
-- Various events and properties.
+- [Page Lifecycle API](https://developer.chrome.com/docs/web-platform/page-lifecycle-api)
 
-There are many articles on the subject that detail how to leverage the APIs writing efficient applications.
-Some of them are:
+For background reading:
 
 - [Background Tasks API](https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API)
 - [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
-- [Page Lifecycle API](https://developer.chrome.com/docs/web-platform/page-lifecycle-api)
 
-This package eliminates the need to write code that you'll write anyway following best practices.
+### Test web app
+
+Run `npm start` and open [http://localhost:3000/tests/web/](http://localhost:3000/tests/web/) &mdash;
+open the console, switch tabs, navigate away and back to see queues in action.
+Source: [tests/web/test.js](https://github.com/uhop/time-queues/blob/main/tests/web/test.js).
 
-### Running a test web application
+## AI Integration
 
-Don't forget to look at a test web application that uses the library. For that you should start a server:
+This project ships [llms.txt](llms.txt) and [llms-full.txt](llms-full.txt) for AI agents and LLMs. Contributors and AI coding assistants should see [AGENTS.md](AGENTS.md) for project conventions.
+
+## Development
 
 ```sh
-npm start
+git clone --recurse-submodules https://github.com/uhop/time-queues.git
+cd time-queues
+npm install
+npm test
 ```
 
-And navigate to [http://localhost:3000/tests/web/](http://localhost:3000/tests/web/) &mdash;
-don't forget to open the console and play around: switch tabs, make other window active,
-navigate away and come back, and so on.
-See how queues work in [tests/web/test.js](https://github.com/uhop/time-queues/blob/main/tests/web/test.js).
-
 ## License
 
-This project is licensed under the BSD-3-Clause License.
+BSD-3-Clause
 
 ## Release History
 
-- 1.3.0 _Added `batch()` and `LimitedQueue` to run asynchronous operations with controlled concurrency, random distribuitions and random sleep functions, updated dependencies, minor improvements._
+- 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`. Updated dev dependencies._
-- 1.1.2 _Updated dev dependencies. No need to upgrade._
+- 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. No need to upgrade._
+- 1.0.1 _Minor update in README._
 - 1.0.0 _Initial release._

package/llms-full.txt

@@ -0,0 +1,430 @@
+# time-queues
+
+> Lightweight async task scheduling and concurrency control for JavaScript: schedulers, idle/frame/limited queues, throttle, debounce, batch, page lifecycle, random delays.
+
+- NPM: https://npmjs.org/package/time-queues
+- GitHub: https://github.com/uhop/time-queues
+- Wiki: https://github.com/uhop/time-queues/wiki
+- License: BSD-3-Clause
+- Runtime: browsers, Node.js, Bun, Deno
+- Module system: ESM (`"type": "module"`)
+- TypeScript: built-in `.d.ts` declarations for all modules
+- Dependency: [list-toolkit](https://npmjs.org/package/list-toolkit) (zero-dep)
+
+## Installation
+
+```bash
+npm install time-queues
+```
+
+## Quick start
+
+```js
+import sleep from 'time-queues/sleep.js';
+import {Scheduler, repeat} from 'time-queues/Scheduler.js';
+import {batch} from 'time-queues/batch.js';
+
+await sleep(1000);
+
+const scheduler = new Scheduler();
+scheduler.enqueue(repeat(({task, scheduler}) => {
+  console.log('tick');
+}, 5000), 5000);
+
+const results = await batch(
+  urls.map(url => () => fetch(url).then(r => r.json())),
+  3
+);
+```
+
+## Architecture
+
+```
+MicroTask (single task with promise support)
+  └─ Task (Scheduler-specific, adds delay/time)
+
+MicroTaskQueue (abstract queue base)
+  ├─ Scheduler (time-based, uses min-heap)
+  └─ ListQueue (linked-list storage)
+       ├─ IdleQueue (requestIdleCallback)
+       ├─ FrameQueue (requestAnimationFrame)
+       ├─ LimitedQueue (concurrency control)
+       └─ PageWatcher (page lifecycle events)
+
+Standalone: Counter, Throttler, Retainer, CancelTaskError
+```
+
+All modules are ESM. Import as `import X from 'time-queues/<module>.js'`.
+
+## API Reference
+
+### CancelTaskError (`time-queues/CancelTaskError.js`)
+
+Error subclass for task cancellation signals.
+
+```ts
+class CancelTaskError extends Error {
+  constructor(message?: string, options?: ErrorOptions);
+}
+export default CancelTaskError;
+```
+
+### MicroTask (`time-queues/MicroTask.js`)
+
+Base task unit with lazy promise creation.
+
+```ts
+class MicroTask {
+  fn: () => unknown;
+  isCanceled: boolean;
+  get promise(): Promise<unknown> | null;
+  constructor(fn: () => unknown);
+  makePromise(): this;
+  resolve(value: unknown): this;
+  cancel(error?: Error): this;
+}
+export default MicroTask;
+```
+
+### MicroTaskQueue (`time-queues/MicroTaskQueue.js`)
+
+Abstract queue base class.
+
+```ts
+class MicroTaskQueue {
+  paused: boolean;
+  constructor(paused?: boolean);
+  get isEmpty(): boolean;
+  enqueue(fn: () => unknown): MicroTask;
+  dequeue(task: MicroTask): this;
+  schedule(fn: (() => unknown) | null | undefined, ...args: unknown[]): MicroTask;
+  clear(): this;
+  pause(): this;
+  resume(): this;
+}
+export default MicroTaskQueue;
+```
+
+### ListQueue (`time-queues/ListQueue.js`)
+
+Linked-list queue implementation. Extends `MicroTaskQueue`.
+
+```ts
+class ListQueue extends MicroTaskQueue {
+  paused: boolean;
+  stopQueue: (() => void) | null;
+  constructor(paused?: boolean);
+  get isEmpty(): boolean;
+  enqueue(fn: () => unknown): MicroTask;
+  dequeue(task: MicroTask): this;
+  schedule(fn: (() => unknown) | null | undefined): MicroTask;
+  clear(): this;
+  pause(): this;
+  resume(): this;
+  startQueue(): (() => void) | null;  // override in subclasses
+}
+export type Task = MicroTask;
+export default ListQueue;
+```
+
+### Scheduler (`time-queues/Scheduler.js`)
+
+Time-based task scheduling with min-heap. Extends `MicroTaskQueue`.
+
+```ts
+class Task extends MicroTask {
+  time: number;
+  delay: number;
+  constructor(delay: number | Date, fn: ({task: Task, scheduler: Scheduler}) => unknown);
+}
+
+class Scheduler extends MicroTaskQueue {
+  paused: boolean;
+  tolerance: number;
+  constructor(paused?: boolean, tolerance?: number);
+  get isEmpty(): boolean;
+  get nextTime(): number;
+  enqueue(fn: ({task: Task, scheduler: Scheduler}) => unknown, delay: number | Date): Task;
+  dequeue(task: Task): this;
+  schedule(fn: (({task: Task, scheduler: Scheduler}) => unknown) | null | undefined, delay: number | Date): Task;
+  clear(): this;
+  pause(): this;
+  resume(): this;
+}
+
+const repeat: (fn: ({task: Task, scheduler: Scheduler}) => void, delay: number | Date) => ({task: Task, scheduler: Scheduler}) => void;
+const scheduler: Scheduler;  // global instance
+export default scheduler;
+```
+
+Callback receives `{task, scheduler}` as a destructured object.
+
+### IdleQueue (`time-queues/IdleQueue.js`)
+
+Run tasks during browser idle periods via `requestIdleCallback()`. Extends `ListQueue`.
+
+```ts
+class IdleQueue extends ListQueue {
+  timeoutBatch: number | undefined;
+  options: IdleCallbackOptions | undefined;
+  constructor(paused?: boolean, timeoutBatchInMs?: number, options?: IdleCallbackOptions);
+  enqueue(fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown): Task;
+  schedule(fn: (({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown) | null | undefined): Task;
+}
+
+const idleQueue: IdleQueue;   // global instance
+const defer: (fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown) => Task;
+export default IdleQueue;
+```
+
+### FrameQueue (`time-queues/FrameQueue.js`)
+
+Run tasks in animation frames via `requestAnimationFrame()`. Extends `ListQueue`.
+
+```ts
+class FrameQueue extends ListQueue {
+  batch: number | undefined;
+  constructor(paused?: boolean, batchInMs?: number);
+  enqueue(fn: ({timeStamp: number, task: Task, queue: FrameQueue}) => unknown): Task;
+  schedule(fn: (({timeStamp: number, task: Task, queue: FrameQueue}) => unknown) | null | undefined): Task;
+}
+
+const frameQueue: FrameQueue;  // global instance
+export default FrameQueue;
+```
+
+### LimitedQueue (`time-queues/LimitedQueue.js`)
+
+Concurrency-controlled async queue. Extends `ListQueue`.
+
+```ts
+class LimitedQueue extends ListQueue {
+  constructor(limit: number, paused?: boolean);
+  get taskLimit(): number;
+  set taskLimit(limit: number);
+  get activeTasks(): number;
+  get isIdle(): boolean;
+  waitForIdle(): Promise<void>;
+  enqueue(fn: () => unknown): Task;
+  schedule(fn: (() => unknown) | null | undefined): Task;
+}
+export { Task };
+export default LimitedQueue;
+```
+
+### PageWatcher (`time-queues/PageWatcher.js`)
+
+React to page lifecycle changes. Extends `ListQueue`.
+
+```ts
+type PageState = 'active' | 'passive' | 'hidden' | 'frozen' | 'terminated';
+
+class PageWatcher extends ListQueue {
+  currentState: PageState;
+  constructor(started?: boolean);
+  enqueue(fn: (state: PageState, previousState: PageState, task: Task, queue: ListQueue) => void, initialize?: boolean): Task;
+  schedule(): never;  // always throws
+}
+
+const watchStates: (queue: ListQueue, resumeStatesList?: PageState[]) => (state: PageState) => void;
+const pageWatcher: PageWatcher;  // global instance
+export default PageWatcher;
+```
+
+### Counter (`time-queues/Counter.js`)
+
+Numeric counter with async waiting.
+
+```ts
+class Counter {
+  count: number;
+  constructor(initial?: number);
+  get value(): number;
+  set value(value: number);
+  increment(): void;
+  decrement(): void;
+  advance(amount?: number): void;
+  waitForZero(): Promise<number>;
+  waitFor(fn: (count: number) => boolean): Promise<number>;
+  clearWaiters(): void;
+}
+export default Counter;
+```
+
+### Throttler (`time-queues/Throttler.js`)
+
+Key-based rate limiting with vacuum cleanup.
+
+```ts
+type ThrottlerOptions = {
+  throttleTimeout?: number;   // default: 1000
+  neverSeenTimeout?: number;  // default: 0
+  vacuumPeriod?: number;      // default: throttleTimeout * 3
+};
+
+class Throttler implements ThrottlerOptions {
+  throttleTimeout: number;
+  neverSeenTimeout: number;
+  vacuumPeriod: number;
+  lastSeen: Map<unknown, number>;
+  constructor(options?: ThrottlerOptions);
+  getLastSeen(key: unknown): number;
+  getDelay(key: unknown): number;
+  wait(key: unknown): Promise<void>;
+  get isVacuuming(): boolean;
+  startVacuum(): this;
+  stopVacuum(): this;
+}
+export default Throttler;
+```
+
+### Retainer (`time-queues/Retainer.js`)
+
+Resource lifecycle management with reference counting.
+
+```ts
+interface RetainerOptions<T = unknown> {
+  create: () => Promise<T> | T;
+  destroy: (value: T) => Promise<void> | void;
+  retentionPeriod: number;
+}
+
+class Retainer<T = unknown> implements RetainerOptions<T> {
+  counter: number;
+  value: T | null;
+  create: () => Promise<T> | T;
+  destroy: (value: T) => Promise<void> | void;
+  retentionPeriod: number;
+  constructor(options: RetainerOptions<T>);
+  async get(): Promise<T>;
+  async release(immediately?: boolean): Promise<this>;
+}
+export default Retainer;
+```
+
+### sleep (`time-queues/sleep.js`)
+
+```ts
+function sleep(ms: number | Date): Promise<void>;
+export default sleep;
+```
+
+### defer (`time-queues/defer.js`)
+
+Next-tick execution via `requestIdleCallback` / `setImmediate` / `setTimeout`.
+
+```ts
+function defer<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+function scheduleDefer<R>(fn: () => R): Promise<Awaited<R>>;
+function scheduleDefer(fn: null | undefined): Promise<void>;
+export default defer;
+```
+
+### throttle (`time-queues/throttle.js`)
+
+Execute immediately, ignore calls until timeout expires. Uses first seen args.
+
+```ts
+function throttle<A extends unknown[]>(fn: (...args: A) => void, ms: number): (...args: A) => void;
+export default throttle;
+```
+
+### debounce (`time-queues/debounce.js`)
+
+Delay until input stabilizes. Each call resets the timeout. Uses last seen args.
+
+```ts
+function debounce<A extends unknown[]>(fn: (...args: A) => void, ms: number): (...args: A) => void;
+export default debounce;
+```
+
+### sample (`time-queues/sample.js`)
+
+Execute at regular intervals with last seen args. Intervals never reset and never stop.
+
+```ts
+function sample<A extends unknown[]>(fn: (...args: A) => void, ms: number): (...args: A) => void;
+export default sample;
+```
+
+### audit (`time-queues/audit.js`)
+
+First call starts timeout, then executes with last seen args. Similar to throttle but uses last args.
+
+```ts
+function audit<A extends unknown[]>(fn: (...args: A) => void, ms: number): (...args: A) => void;
+export default audit;
+```
+
+### batch (`time-queues/batch.js`)
+
+Run async operations with concurrency limit. Modeled after `Promise.all()`.
+
+```ts
+function batch(
+  fns: ((() => PromiseLike<unknown>) | PromiseLike<unknown> | unknown)[],
+  limit?: number  // default: 4
+): Promise<unknown[]>;
+export default batch;
+```
+
+### random-dist (`time-queues/random-dist.js`)
+
+Random number distributions.
+
+```ts
+function uniform(min: number, max: number): number;
+function normal(mean: number, stdDev: number, skewness?: number): number;
+function expo(lambda: number): number;
+function pareto(min: number, alpha: number): number;
+```
+
+### random-sleep (`time-queues/random-sleep.js`)
+
+Randomized delays from various distributions. Each factory returns `() => Promise<void>`.
+
+```ts
+type RandomSleepFunction = () => Promise<void>;
+
+function randomUniformSleep(min: number, max: number): RandomSleepFunction;
+function randomNormalSleep(mean: number, stdDev: number, skewness?: number): RandomSleepFunction;
+function randomExpoSleep(rate: number, range: number, base?: number): RandomSleepFunction;
+function randomParetoSleep(min: number, ratio?: number): RandomSleepFunction;
+function randomSleep(max: number, min?: number): Promise<void>;
+export default randomSleep;
+```
+
+### whenDomLoaded (`time-queues/when-dom-loaded.js`)
+
+```ts
+function whenDomLoaded(fn: () => void): void;
+function remove(fn: () => void): boolean;
+function scheduleWhenDomLoaded<R>(fn: () => R): Promise<Awaited<R>>;
+function scheduleWhenDomLoaded(fn?: null): Promise<void>;
+export default whenDomLoaded;
+```
+
+### whenLoaded (`time-queues/when-loaded.js`)
+
+```ts
+function whenLoaded(fn: () => void): void;
+function remove(fn: () => void): boolean;
+function scheduleWhenLoaded<R>(fn: () => R): Promise<Awaited<R>>;
+function scheduleWhenLoaded(fn?: null): Promise<void>;
+export default whenLoaded;
+```
+
+## Key concepts
+
+- All modules are **ESM** with `import ... from 'time-queues/<module>.js'`.
+- **Inheritance**: `MicroTaskQueue` → `ListQueue` → specialized queues. `Scheduler` extends `MicroTaskQueue` directly (uses min-heap, not linked list).
+- **Lazy promises** — only created when `.makePromise()` is called or via `schedule()`.
+- **Clean cancellation** — all tasks support cancellation via `CancelTaskError`.
+- **Graceful degradation** — feature detection for browser APIs, works in Node.js/Bun/Deno.
+- **Callback signatures** — queue callbacks receive a destructured context object: `({task, scheduler})` for Scheduler, `({deadline, task, queue})` for IdleQueue, `({timeStamp, task, queue})` for FrameQueue, `(state, prevState, task, queue)` for PageWatcher.
+
+## Links
+
+- Docs: https://github.com/uhop/time-queues/wiki
+- npm: https://www.npmjs.com/package/time-queues
+- Summary: https://github.com/uhop/time-queues/blob/master/llms.txt