time-queues 1.3.2 → 1.4.0

package/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2005-2024, Eugene Lazutkin
+Copyright (c) 2005-2026, Eugene Lazutkin
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

package/README.md

@@ -140,6 +140,7 @@ 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._

package/llms-full.txt

@@ -20,6 +20,10 @@ npm install time-queues
 ## Quick start
 
 ```js
+// Bare imports work as a barrel:
+import {sleep, Scheduler, repeat, batch} from 'time-queues';
+
+// Or subpath imports for tree-shaking-friendly use:
 import sleep from 'time-queues/sleep.js';
 import {Scheduler, repeat} from 'time-queues/Scheduler.js';
 import {batch} from 'time-queues/batch.js';
@@ -54,7 +58,7 @@ MicroTaskQueue (abstract queue base)
 Standalone: Counter, Throttler, Retainer, CancelTaskError
 ```
 
-All modules are ESM. Import as `import X from 'time-queues/<module>.js'`.
+All modules are ESM. Bare imports (`from 'time-queues'`) and subpath imports (`from 'time-queues/<module>.js'`) are both supported.
 
 ## API Reference
 
@@ -78,10 +82,12 @@ class MicroTask {
   fn: () => unknown;
   isCanceled: boolean;
   get promise(): Promise<unknown> | null;
+  get settled(): boolean;
+  get cancelError(): Error | null;
   constructor(fn: () => unknown);
-  makePromise(): this;
-  resolve(value: unknown): this;
-  cancel(error?: Error): this;
+  makePromise(): this;          // idempotent; if already canceled, fresh promise settles immediately as CancelTaskError
+  resolve(value: unknown): this; // throws if makePromise() has not been called
+  cancel(error?: Error): this;   // stores first error reason; replayed on later makePromise() if no promise yet
 }
 export default MicroTask;
 ```
@@ -141,6 +147,9 @@ class Task extends MicroTask {
 class Scheduler extends MicroTaskQueue {
   paused: boolean;
   tolerance: number;
+  queue: MinHeap<Task>;                          // pending tasks ordered by `time`
+  stopQueue: (() => void) | null;
+  onError: ((error: unknown, task: Task) => void) | null;  // optional per-task error handler; default null surfaces via unhandled-rejection
   constructor(paused?: boolean, tolerance?: number);
   get isEmpty(): boolean;
   get nextTime(): number;
@@ -244,9 +253,10 @@ class Counter {
   increment(): void;
   decrement(): void;
   advance(amount?: number): void;
-  waitForZero(): Promise<number>;
+  waitForZero(): Promise<number>;                       // resolves with NaN if clearWaiters() called first
   waitFor(fn: (count: number) => boolean): Promise<number>;
   clearWaiters(): void;
+  notify(): void;                                       // call after direct `count` mutation
 }
 export default Counter;
 ```
@@ -291,12 +301,12 @@ interface RetainerOptions<T = unknown> {
 
 class Retainer<T = unknown> implements RetainerOptions<T> {
   counter: number;
-  value: T | null;
+  readonly value: T | null;
   create: () => Promise<T> | T;
   destroy: (value: T) => Promise<void> | void;
   retentionPeriod: number;
   constructor(options: RetainerOptions<T>);
-  async get(): Promise<T>;
+  async get(): Promise<T>;                          // concurrent get() calls share one create()
   async release(immediately?: boolean): Promise<this>;
 }
 export default Retainer;

package/llms.txt

@@ -16,6 +16,10 @@ npm install time-queues
 ## Quick start
 
 ```js
+// Bare imports work as a barrel:
+import {sleep, Scheduler, repeat, batch} from 'time-queues';
+
+// Or subpath imports for tree-shaking-friendly use:
 import sleep from 'time-queues/sleep.js';
 import {Scheduler, repeat} from 'time-queues/Scheduler.js';
 import {batch} from 'time-queues/batch.js';
@@ -40,7 +44,7 @@ const results = await batch(
 
 ### Queues
 
-- **Scheduler** (`time-queues/Scheduler.js`) — time-based task scheduling with delays, dates, and repeats. Extends MicroTaskQueue. Uses a min-heap. Exports: `Scheduler`, `Task`, `repeat(fn, delay)`, `scheduler` (global instance).
+- **Scheduler** (`time-queues/Scheduler.js`) — time-based task scheduling with delays, dates, and repeats. Extends MicroTaskQueue. Uses a min-heap. Exports: `Scheduler`, `Task`, `repeat(fn, delay)`, `scheduler` (global instance). Optional `scheduler.onError(error, task)` callback handles per-task exceptions; loop continues regardless.
 - **IdleQueue** (`time-queues/IdleQueue.js`) — run tasks during browser idle periods via `requestIdleCallback()`. Extends ListQueue. Exports: `IdleQueue`, `idleQueue` (global instance), `defer(fn)`.
 - **FrameQueue** (`time-queues/FrameQueue.js`) — run tasks in animation frames via `requestAnimationFrame()`. Extends ListQueue. Exports: `FrameQueue`, `frameQueue` (global instance).
 - **LimitedQueue** (`time-queues/LimitedQueue.js`) — concurrency-controlled async queue. Extends ListQueue. Exports: `LimitedQueue`, `Task`.
@@ -60,12 +64,12 @@ const results = await batch(
 
 - **Throttler** (`time-queues/Throttler.js`) — key-based rate limiting with vacuum cleanup. Methods: `getDelay(key)`, `wait(key)`, `startVacuum()`, `stopVacuum()`.
 - **Retainer** (`time-queues/Retainer.js`) — resource lifecycle management with reference counting. Methods: `get(): Promise<value>`, `release(): Promise<void>`.
-- **Counter** (`time-queues/Counter.js`) — numeric counter with async waiting. Methods: `increment()`, `decrement()`, `advance(delta)`, `waitForZero()`, `waitFor(target)`.
+- **Counter** (`time-queues/Counter.js`) — numeric counter with async waiting. Methods: `increment()`, `decrement()`, `advance(delta)`, `waitForZero()`, `waitFor(predicate)`, `clearWaiters()` (resolves pending with `NaN`), `notify()` (call after direct `count` mutation).
 - **CancelTaskError** (`time-queues/CancelTaskError.js`) — `Error` subclass for task cancellation signals.
 
 ### Base classes
 
-- **MicroTask** (`time-queues/MicroTask.js`) — base task unit with lazy promise creation. Methods: `makePromise()`, `resolve(value)`, `cancel(error)`.
+- **MicroTask** (`time-queues/MicroTask.js`) — base task unit with lazy promise creation. Methods: `makePromise()`, `resolve(value)` (throws if no promise yet), `cancel(error)` (stores `error`, replays as `cause` on later `makePromise()`). Getters: `promise`, `settled`, `cancelError`.
 - **MicroTaskQueue** (`time-queues/MicroTaskQueue.js`) — abstract queue base class. Methods: `enqueue(fn)`, `dequeue(task)`, `schedule(fn)`, `clear()`, `pause()`, `resume()`.
 - **ListQueue** (`time-queues/ListQueue.js`) — linked-list queue implementation extending MicroTaskQueue. Adds `startQueue()` lifecycle.
 
@@ -81,7 +85,7 @@ const results = await batch(
 
 ## Key concepts
 
-- All modules are **ESM** with `import ... from 'time-queues/<module>.js'`.
+- All modules are **ESM**. Bare imports (`from 'time-queues'`) and subpath imports (`from 'time-queues/<module>.js'`) both work.
 - **Inheritance**: `MicroTaskQueue` → `ListQueue` → `IdleQueue`/`FrameQueue`/`LimitedQueue`/`PageWatcher`. `Scheduler` extends `MicroTaskQueue` directly.
 - **Lazy promises** — only created when `.makePromise()` is called or via `schedule()`.
 - **Clean cancellation** — all tasks support cancellation via `CancelTaskError`.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "time-queues",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Lightweight async task scheduling and concurrency control: schedulers, idle/frame/limited queues, throttle, debounce, batch, page lifecycle, random delays. Browsers, Node.js, Deno, Bun.",
   "type": "module",
   "types": "./src/index.d.ts",
   "exports": {
+    ".": "./src/index.js",
     "./*": "./src/*"
   },
   "scripts": {
@@ -18,6 +19,7 @@
     "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
     "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO",
     "ts-check": "tsc --noEmit",
+    "js-check": "tsc --project tsconfig.check.json",
     "ts-test": "tape6 --flags FO '/ts-tests/test-*.*ts'",
     "ts-test:bun": "tape6-bun --flags FO '/ts-tests/test-*.*ts'",
     "ts-test:deno": "tape6-deno --flags FO '/ts-tests/test-*.*ts'",
@@ -33,7 +35,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/uhop/time-queues.git"
+    "url": "git+https://github.com/uhop/time-queues.git"
   },
   "keywords": [
     "scheduler",
@@ -41,17 +43,20 @@
     "async-queue",
     "concurrency",
     "throttle",
+    "throttler",
     "debounce",
     "rate-limit",
     "batch",
     "sleep",
     "defer",
     "idle-queue",
+    "frame-queue",
+    "limited-queue",
     "requestIdleCallback",
     "requestAnimationFrame",
     "page-lifecycle",
-    "timer",
-    "time",
+    "microtask",
+    "retainer",
     "queue",
     "esm",
     "typescript"
@@ -59,6 +64,9 @@
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "funding": "https://github.com/sponsors/uhop",
   "license": "BSD-3-Clause",
+  "engines": {
+    "node": ">=22"
+  },
   "bugs": {
     "url": "https://github.com/uhop/time-queues/issues"
   },
@@ -90,11 +98,11 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "prettier": "^3.8.1",
-    "tape-six": "^1.7.12",
-    "tape-six-proc": "^1.2.7",
-    "typescript": "^5.9.3"
+    "@types/node": "^25.6.1",
+    "prettier": "^3.8.3",
+    "tape-six": "^1.9.0",
+    "tape-six-proc": "^1.2.9",
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "list-toolkit": "^2.3.2"

package/src/Counter.d.ts

@@ -42,21 +42,35 @@ export declare class Counter {
 
   /**
    * Waits for the counter to reach zero. If the counter is already zero, the promise is resolved immediately.
+   * Resolves with `0` on a normal wait, or with `NaN` if `clearWaiters()` is called before the counter reaches zero.
    * @returns A promise that resolves when the counter reaches zero.
    */
   waitForZero(): Promise<number>;
 
   /**
    * Waits for the counter to reach a specific value. If the counter is already at the desired value, the promise is resolved immediately.
+   * Resolves with the matching count, or with `NaN` if `clearWaiters()` is called before the predicate matches.
    * @param fn A function that returns `true` when the counter reaches the desired value.
    * @returns A promise that resolves when the counter reaches the desired value.
    */
   waitFor(fn: (count: number) => boolean): Promise<number>;
 
   /**
-   * Clears all waiters.
+   * Clears all pending waiters by resolving them with `NaN`.
+   * Use `Number.isNaN(value)` to distinguish "queue cleared" from a real count of zero.
+   * Most consumers `await` the result without inspecting it; checking is only needed
+   * when you both clear waiters during teardown and have downstream arithmetic that
+   * shouldn't be NaN-poisoned.
    */
   clearWaiters(): void;
+
+  /**
+   * Re-evaluates pending waiters against the current `count` and resolves any
+   * whose predicate now matches. Called automatically by `value`, `increment`,
+   * `decrement`, and `advance`. Call manually only when mutating `count`
+   * directly (which bypasses the setter).
+   */
+  notify(): void;
 }
 
 export default Counter;

package/src/Counter.js

@@ -4,15 +4,15 @@ export class Counter {
   constructor(initial = 0) {
     this.count = initial;
     this.zeroWaiters = [];
-    this.functionWaiters = new Set();
+    this.functionWaiters = [];
   }
 
   get value() {
     return this.count;
   }
 
-  set value(value) {
-    this.count = value;
+  set value(newValue) {
+    this.count = newValue;
     this.notify();
   }
 
@@ -38,7 +38,7 @@ export class Counter {
 
   waitFor(fn) {
     if (fn(this.count)) return Promise.resolve(this.count);
-    return new Promise(resolve => this.functionWaiters.add({fn, resolve}));
+    return new Promise(resolve => this.functionWaiters.push({fn, resolve}));
   }
 
   clearWaiters() {
@@ -49,9 +49,9 @@ export class Counter {
         resolve(NaN);
       }
     }
-    if (this.functionWaiters.size > 0) {
+    if (this.functionWaiters.length > 0) {
       const functionWaiters = this.functionWaiters;
-      this.functionWaiters = new Set();
+      this.functionWaiters = [];
       for (const {resolve} of functionWaiters) {
         resolve(NaN);
       }
@@ -66,17 +66,16 @@ export class Counter {
         resolve(0);
       }
     }
-    if (this.functionWaiters.size > 0) {
-      const ready = [];
+    if (this.functionWaiters.length > 0) {
+      const remaining = [];
       for (const waiter of this.functionWaiters) {
-        if (waiter.fn(this.count)) ready.push(waiter);
-      }
-      if (ready.length > 0) {
-        for (const waiter of ready) {
+        if (waiter.fn(this.count)) {
           waiter.resolve(this.count);
-          this.functionWaiters.delete(waiter);
+        } else {
+          remaining.push(waiter);
         }
       }
+      this.functionWaiters = remaining;
     }
   }
 }

package/src/FrameQueue.d.ts

@@ -75,6 +75,13 @@ export declare class FrameQueue extends ListQueue {
    * @returns The function that stops the queue.
    */
   startQueue(): (() => void) | null;
+
+  /**
+   * Processes pending tasks. Called by `requestAnimationFrame()` — not part of
+   * the typical user surface; documented for subclasses that need to override.
+   * @param timeStamp The high-resolution timestamp from the rAF callback.
+   */
+  processTasks(timeStamp: number): void;
 }
 
 /**

package/src/FrameQueue.js

@@ -1,6 +1,5 @@
 // @ts-self-types="./FrameQueue.d.ts"
 
-import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 
 export class FrameQueue extends ListQueue {
@@ -19,22 +18,7 @@ export class FrameQueue extends ListQueue {
       this.stopQueue();
       this.stopQueue = null;
     }
-
-    if (!isNaN(this.batch)) {
-      const start = Date.now();
-      while (Date.now() - start < this.batch && !this.list.isEmpty) {
-        const task = this.list.popFront();
-        task.fn({timeStamp, task, queue: this});
-      }
-    } else {
-      const list = this.list;
-      this.list = new List();
-      while (!list.isEmpty) {
-        const task = list.popFront();
-        task.fn({timeStamp, task, queue: this});
-      }
-    }
-
+    this._drainBatch(this.batch, {timeStamp});
     if (!this.list.isEmpty) this.stopQueue = this.startQueue();
   }
 }

package/src/IdleQueue.d.ts

@@ -85,6 +85,13 @@ export declare class IdleQueue extends ListQueue {
    * @returns The function that stops the queue.
    */
   startQueue(): (() => void) | null;
+
+  /**
+   * Processes pending tasks. Called by `requestIdleCallback()` — not part of
+   * the typical user surface; documented for subclasses that need to override.
+   * @param deadline The `IdleDeadline` from the rIC callback.
+   */
+  processTasks(deadline: IdleDeadline): void;
 }
 
 /**

package/src/IdleQueue.js

@@ -1,6 +1,5 @@
 // @ts-self-types="./IdleQueue.d.ts"
 
-import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 
 // Based on information from https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API
@@ -22,29 +21,14 @@ export class IdleQueue extends ListQueue {
       this.stopQueue();
       this.stopQueue = null;
     }
-
     if (deadline.didTimeout) {
-      if (!isNaN(this.timeoutBatch)) {
-        const start = Date.now();
-        while (Date.now() - start < this.timeoutBatch && !this.list.isEmpty) {
-          const task = this.list.popFront();
-          task.fn({deadline, task, queue: this});
-        }
-      } else {
-        const list = this.list;
-        this.list = new List();
-        while (!list.isEmpty) {
-          const task = list.popFront();
-          task.fn({deadline, task, queue: this});
-        }
-      }
+      this._drainBatch(this.timeoutBatch, {deadline});
     } else {
       while (deadline.timeRemaining() > 0 && !this.list.isEmpty) {
         const task = this.list.popFront();
         task.fn({deadline, task, queue: this});
       }
     }
-
     if (!this.list.isEmpty) this.stopQueue = this.startQueue();
   }
 }

package/src/LimitedQueue.js

@@ -2,6 +2,15 @@
 
 import ListQueue from './ListQueue.js';
 
+const wrap = fn =>
+  new Promise((resolve, reject) => {
+    try {
+      resolve(fn());
+    } catch (error) {
+      reject(error);
+    }
+  });
+
 export class LimitedQueue extends ListQueue {
   #taskLimit;
   #activeTasks;
@@ -57,22 +66,12 @@ export class LimitedQueue extends ListQueue {
     while (this.#activeTasks < this.#taskLimit && !this.list.isEmpty) {
       const task = this.list.popFront();
       ++this.#activeTasks;
-      LimitedQueue.wrap(() => task.fn({task, queue: this})).finally(() => {
+      wrap(() => task.fn({task, queue: this})).finally(() => {
         --this.#activeTasks;
         this.#processTasks();
       });
     }
   }
-
-  static wrap(fn) {
-    return new Promise((resolve, reject) => {
-      try {
-        resolve(fn());
-      } catch (error) {
-        reject(error);
-      }
-    });
-  }
 }
 
 export default LimitedQueue;

package/src/ListQueue.d.ts

@@ -1,3 +1,4 @@
+import List from 'list-toolkit/list.js';
 import {MicroTask} from './MicroTask.js';
 import {MicroTaskQueue} from './MicroTaskQueue.js';
 
@@ -11,6 +12,11 @@ export declare class ListQueue extends MicroTaskQueue {
    */
   paused: boolean;
 
+  /**
+   * The linked list of pending microtasks.
+   */
+  list: List<MicroTask>;
+
   /**
    * The function that stops the queue.
    * It is used internally by `pause()` and `resume()`.
@@ -74,6 +80,15 @@ export declare class ListQueue extends MicroTaskQueue {
    * @returns The function that stops the queue.
    */
   startQueue(): (() => void) | null;
+
+  /**
+   * Internal helper used by subclasses (FrameQueue, IdleQueue) to drain pending
+   * tasks. If `batchMs` is finite, runs tasks until that many milliseconds have
+   * elapsed; otherwise swaps in a fresh list and drains the captured one
+   * entirely.
+   * @internal
+   */
+  _drainBatch(batchMs: number, taskContext: object): void;
 }
 
 /**

package/src/ListQueue.js

@@ -1,20 +1,14 @@
 // @ts-self-types="./ListQueue.d.ts"
 
 import List from 'list-toolkit/list.js';
+import MicroTask from './MicroTask.js';
 import MicroTaskQueue from './MicroTaskQueue.js';
 
-/**
- * ListQueue extends MicroTaskQueue with linked-list task storage.
- * AI-NOTE: This is the concrete base class most specialized queues extend.
- * Key pattern: startQueue() returns a stop function (or null if not started).
- * @see IdleQueue, FrameQueue, LimitedQueue, Scheduler - All extend ListQueue
- */
 export class ListQueue extends MicroTaskQueue {
   constructor(paused) {
     super(paused);
-    // AI-NOTE: Using list-toolkit List for O(1) push/pop operations
+    /** @type {List<MicroTask>} */
     this.list = new List();
-    // AI-NOTE: stopQueue holds the stop function returned by startQueue(), or null
     this.stopQueue = null;
   }
 
@@ -25,7 +19,6 @@ export class ListQueue extends MicroTaskQueue {
   pause() {
     if (!this.paused) {
       super.pause();
-      // AI-NOTE: Pattern: call stop function, then null it
       if (this.stopQueue) this.stopQueue = (this.stopQueue(), null);
     }
     return this;
@@ -34,7 +27,6 @@ export class ListQueue extends MicroTaskQueue {
   resume() {
     if (this.paused) {
       super.resume();
-      // AI-NOTE: Auto-start processing if tasks exist and not already running
       if (!this.list.isEmpty) {
         this.stopQueue = this.startQueue();
       }
@@ -45,7 +37,6 @@ export class ListQueue extends MicroTaskQueue {
   enqueue(fn) {
     const task = super.enqueue(fn);
     this.list.pushBack(task);
-    // AI-NOTE: Auto-start queue on first task if not paused and not running
     if (!this.paused && !this.stopQueue) this.stopQueue = this.startQueue();
     return task;
   }
@@ -53,7 +44,6 @@ export class ListQueue extends MicroTaskQueue {
   dequeue(task) {
     task.cancel();
     this.list.removeNode(task);
-    // AI-NOTE: Auto-stop queue when empty (unless paused)
     if (!this.paused && this.list.isEmpty && this.stopQueue)
       this.stopQueue = (this.stopQueue(), null);
     return this;
@@ -70,15 +60,30 @@ export class ListQueue extends MicroTaskQueue {
     return this;
   }
 
-  /**
-   * Start processing the queue - MUST be overridden by subclasses.
-   * AI-NOTE: This is the abstract method pattern - base returns null.
-   * Subclasses return a function that stops the processing.
-   * @returns {Function|null} Stop function or null if not started
-   */
   startQueue() {
     return null;
   }
+
+  // Drains pending tasks. If batchMs is a finite number, runs tasks until that
+  // many milliseconds have elapsed; otherwise swaps in a fresh list and drains
+  // the captured one entirely (so tasks enqueued during draining run on the
+  // next tick rather than this one).
+  _drainBatch(batchMs, taskContext) {
+    if (!isNaN(batchMs)) {
+      const start = Date.now();
+      while (Date.now() - start < batchMs && !this.list.isEmpty) {
+        const task = this.list.popFront();
+        task.fn({...taskContext, task, queue: this});
+      }
+    } else {
+      const list = this.list;
+      this.list = new List();
+      while (!list.isEmpty) {
+        const task = list.popFront();
+        task.fn({...taskContext, task, queue: this});
+      }
+    }
+  }
 }
 
 export default ListQueue;

package/src/MicroTask.d.ts

@@ -19,7 +19,11 @@ export declare class MicroTask {
   constructor(fn: (...args: any[]) => unknown);
 
   /**
-   * Makes a promise that will be resolved when the microtask is executed.
+   * Creates the promise lazily. Idempotent — subsequent calls return `this`
+   * without changing state. If the task was already canceled (via `cancel()`
+   * before `makePromise()` ran), the freshly-created promise is settled
+   * immediately as a `CancelTaskError` rejection, carrying any `cancelError`
+   * stored from the earlier `cancel()` call as `cause`.
    * @returns The microtask.
    */
   makePromise(): this;
@@ -37,15 +41,32 @@ export declare class MicroTask {
   get settled(): boolean;
 
   /**
-   * Resolves the microtask, if a promise is created.
+   * The error supplied to the first `cancel(error)` call, or `null` if the task
+   * has not been canceled with a reason. Useful for inspecting why a non-promised
+   * task was canceled (when there is no rejection to carry the cause).
+   */
+  get cancelError(): Error | null;
+
+  /**
+   * Resolves the microtask. The promise must already exist — call `makePromise()`
+   * first, or invoke this only from inside a `schedule()`-wrapped callback (which
+   * makes the promise eagerly).
    * @param value The value to resolve the microtask with.
    * @returns The microtask.
+   * @throws If `makePromise()` has not been called — without a promise to resolve,
+   *   the value would be silently dropped, which previously caused subscribers to
+   *   hang on `task.makePromise().promise` calls made afterwards.
    */
   resolve(value: unknown): this;
 
   /**
-   * Cancels the microtask, if a promise is created.
-   * If the microtask is canceled, the promise will be rejected with a CancelTaskError.
+   * Cancels the microtask. Always sets `isCanceled = true` so queues skip the task.
+   * Additionally rejects the promise with a `CancelTaskError` if `makePromise()`
+   * has been called.
+   * The first `error` passed is stored on the instance and accessible via
+   * `cancelError`. If `cancel(error)` runs before `makePromise()`, the stored
+   * error is replayed when the promise is later created — `makePromise()` will
+   * settle the fresh promise with `CancelTaskError(cause: error)` immediately.
    * It can be overridden in subclasses.
    * @param error The optional error to use as the cause of the cancellation.
    * @returns The microtask.

package/src/MicroTask.js

@@ -2,37 +2,30 @@
 
 import CancelTaskError from './CancelTaskError.js';
 
-/**
- * Base class for deferred task execution with lazy promise creation.
- * AI-NOTE: Promises are created lazily via makePromise() - not in constructor.
- * This allows tasks to be created without immediate promise overhead.
- */
 export class MicroTask {
   #promise;
   #resolve;
   #reject;
   #settled;
+  #cancelError;
   constructor(fn) {
     this.fn = fn;
-    // AI-NOTE: Private fields initialized to null - lazy initialization pattern
     this.#promise = null;
     this.#resolve = null;
     this.#reject = null;
     this.#settled = false;
+    this.#cancelError = null;
     this.isCanceled = false;
   }
-  // AI-NOTE: Returns null until makePromise() is called - this is intentional
   get promise() {
     return this.#promise;
   }
   get settled() {
     return this.#settled;
   }
-  /**
-   * Creates the promise and resolution functions.
-   * AI-NOTE: Uses Promise.withResolvers() when available (modern environments),
-   * falls back to manual Promise constructor for broader compatibility.
-   */
+  get cancelError() {
+    return this.#cancelError;
+  }
   makePromise() {
     if (this.#promise) return this;
     if (typeof Promise.withResolvers == 'function') {
@@ -47,9 +40,20 @@ export class MicroTask {
         this.#reject = reject;
       });
     }
+    if (this.isCanceled) {
+      this.#reject(
+        new CancelTaskError(undefined, this.#cancelError ? {cause: this.#cancelError} : undefined)
+      );
+      this.#resolve = null;
+      this.#reject = null;
+      this.#settled = true;
+    }
     return this;
   }
   resolve(value) {
+    if (!this.#promise) {
+      throw new Error('MicroTask: resolve() called before makePromise()');
+    }
     if (this.#resolve) {
       this.#resolve(value);
       this.#resolve = null;
@@ -58,14 +62,15 @@ export class MicroTask {
     }
     return this;
   }
-  /**
-   * Cancel the task with optional error cause.
-   * AI-NOTE: Always rejects with CancelTaskError to distinguish from other errors.
-   */
   cancel(error) {
     this.isCanceled = true;
+    if (error !== undefined && this.#cancelError === null) {
+      this.#cancelError = error;
+    }
     if (this.#reject) {
-      this.#reject(new CancelTaskError(undefined, error ? {cause: error} : undefined));
+      this.#reject(
+        new CancelTaskError(undefined, this.#cancelError ? {cause: this.#cancelError} : undefined)
+      );
       this.#resolve = null;
       this.#reject = null;
       this.#settled = true;

package/src/MicroTaskQueue.js

@@ -2,18 +2,13 @@
 
 import MicroTask from './MicroTask.js';
 
-/**
- * Base queue class for managing task lifecycle.
- * AI-NOTE: This is an abstract base class - concrete implementations should extend
- * ListQueue for actual task storage and processing.
- * @see ListQueue - The primary class for queue implementations
- */
+const returnArgs = (...args) => args;
+
 export class MicroTaskQueue {
   constructor(paused) {
     this.paused = Boolean(paused);
   }
-  // API to be overridden in subclasses
-  // AI-NOTE: Base implementation returns true - subclasses override with actual logic
+  // overridden in subclasses
   get isEmpty() {
     return true;
   }
@@ -25,12 +20,7 @@ export class MicroTaskQueue {
     this.paused = false;
     return this;
   }
-  /**
-   * Enqueue a function for execution.
-   * AI-NOTE: Creates MicroTask but does NOT create promise automatically.
-   * Call task.makePromise() if promise access is needed.
-   */
-  enqueue(fn) {
+  enqueue(fn, ..._args) {
     const task = new MicroTask(fn);
     return task;
   }
@@ -41,31 +31,23 @@ export class MicroTaskQueue {
   clear() {
     return this;
   }
-  /**
-   * Schedule a function with automatic promise creation.
-   * AI-NOTE: This is the convenience method - it calls both enqueue() and makePromise().
-   * Returns a MicroTask with an active promise.
-   */
-  schedule(fn, ...args) {
-    fn ||= MicroTaskQueue.returnArgs;
+  schedule(fn, ...scheduleArgs) {
+    fn ||= returnArgs;
     const task = this.enqueue(
-      function (...args) {
+      function (...invocationArgs) {
         this.makePromise();
         try {
-          this.resolve(fn(...args));
+          this.resolve(fn(...invocationArgs));
         } catch (error) {
           this.cancel(error);
         }
         return this.promise;
       },
-      ...args
+      ...scheduleArgs
     );
     task.makePromise();
     return task;
   }
-  static returnArgs(...args) {
-    return args;
-  }
 }
 
 export default MicroTaskQueue;

package/src/PageWatcher.js

@@ -10,12 +10,9 @@ const eventHandlerOptions = {capture: true},
 // valid states: active, passive, hidden, frozen, terminated
 
 const getState = () => {
-  if (document.visibilityState === 'hidden') {
-    return 'hidden';
-  }
-  if (document.hasFocus()) {
-    return 'active';
-  }
+  if (typeof document == 'undefined') return 'active';
+  if (document.visibilityState === 'hidden') return 'hidden';
+  if (document.hasFocus()) return 'active';
   return 'passive';
 };
 
@@ -44,10 +41,16 @@ export class PageWatcher extends ListQueue {
 
   // Implemented in ListQueue: dequeue()
 
-  schedule() {
+  /** @returns {never} */
+  schedule(_fn) {
     throw new Error('Not implemented');
   }
 
+  // Override of ListQueue.clear() that skips the parent's pause/resume cycle.
+  // PageWatcher.pause/resume add and remove DOM event listeners on every call,
+  // so bouncing them around an internal clear() just to drain the task list
+  // would thrash listeners for no reason. The watching state is independent
+  // of whether tasks are pending.
   clear() {
     while (!this.list.isEmpty) {
       const task = this.list.popFront();

package/src/Retainer.d.ts

@@ -26,9 +26,11 @@ export declare class Retainer<T = unknown> implements RetainerOptions<T> {
   counter: number;
 
   /**
-   * The value currently retained.
+   * The value currently retained. Read-only — managed internally by `get()`
+   * and `release()`. Reads return the live value or `null` when nothing is
+   * currently held.
    */
-  value: T | null;
+  readonly value: T | null;
 
   /**
    * The function to create a value.

package/src/Retainer.js

@@ -1,45 +1,55 @@
 // @ts-self-types="./Retainer.d.ts"
 
 export class Retainer {
+  #value = null;
+  #handle = null;
+  /** @type {Promise<*> | null} */
+  #creating = null;
+
   constructor({create, destroy, retentionPeriod = 1_000}) {
     if (!create || !destroy) throw new Error('Retainer: create and destroy are required');
     this.create = create;
     this.destroy = destroy;
     this.retentionPeriod = retentionPeriod;
     this.counter = 0;
-    this.handle = null;
-    this.value = null;
+  }
+
+  get value() {
+    return this.#value;
   }
 
   async get() {
     if (!this.counter) {
-      if (this.handle) {
-        clearTimeout(this.handle);
-        this.handle = null;
+      if (this.#handle) {
+        clearTimeout(this.#handle);
+        this.#handle = null;
       } else {
-        this.value = await this.create();
+        if (!this.#creating) this.#creating = this.create();
+        try {
+          this.#value = await this.#creating;
+        } finally {
+          this.#creating = null;
+        }
       }
     }
     ++this.counter;
-    return this.value;
+    return this.#value;
   }
 
   async release(immediately) {
     if (this.counter <= 0) throw new Error('Retainer: counter is already zero');
     if (--this.counter) return this;
     if (immediately) {
-      const value = this.value;
-      this.value = null;
+      const value = this.#value;
+      this.#value = null;
       await this.destroy(value);
       return this;
     }
-    this.handle = setTimeout(() => {
-      const value = this.value;
-      this.value = null;
-      this.handle = null;
-      Promise.resolve()
-        .then(() => this.destroy(value))
-        .catch(() => {});
+    this.#handle = setTimeout(async () => {
+      const value = this.#value;
+      this.#value = null;
+      this.#handle = null;
+      await this.destroy(value);
     }, this.retentionPeriod);
     return this;
   }

package/src/Scheduler.d.ts

@@ -1,20 +1,18 @@
+import MinHeap from 'list-toolkit/heap.js';
 import MicroTask from './MicroTask.js';
 import MicroTaskQueue from './MicroTaskQueue.js';
 
 /**
  * A task that will be executed at a later time by `Scheduler`.
+ * Inherits `makePromise()`, `promise`, `settled`, `cancelError`, `resolve()`,
+ * and `cancel()` from `MicroTask` — see `MicroTask.d.ts` for their contracts.
  */
 export declare class Task extends MicroTask {
   /**
-   * The function to execute.
+   * The function to execute. Narrower signature than `MicroTask.fn`.
    */
   fn: (arg: {task: Task; scheduler: Scheduler}) => unknown;
 
-  /**
-   * Whether the task has been canceled.
-   */
-  isCanceled: boolean;
-
   /**
    * The time in milliseconds (Unix timestamp) when the task is scheduled to run.
    */
@@ -31,45 +29,36 @@ export declare class Task extends MicroTask {
    * @param fn The function to execute.
    */
   constructor(delay: number | Date, fn: (arg: {task: Task; scheduler: Scheduler}) => unknown);
+}
 
+/**
+ * A scheduler that manages tasks to be executed at a later time.
+ */
+export declare class Scheduler extends MicroTaskQueue {
   /**
-   * Makes a promise that will be resolved when the microtask is executed.
-   * @returns The microtask.
-   */
-  makePromise(): this;
-
-  /**
-   * The promise that could be resolved when the microtask is executed.
-   * This is a queue-specific promise. It may be created when there is an associated asynchronous task.
-   * If the microtask is canceled, the promise will be rejected with a CancelTaskError.
+   * Whether the scheduler is paused.
+   * When paused, new tasks are queued but not executed immediately.
    */
-  get promise(): Promise<unknown> | null;
+  paused: boolean;
 
   /**
-   * Resolves the microtask, if a promise is created.
-   * @param value The value to resolve the microtask with.
-   * @returns The microtask.
+   * The min-heap of pending tasks ordered by `time`.
    */
-  resolve(value: unknown): this;
+  queue: MinHeap<Task>;
 
   /**
-   * Cancels the microtask, if a promise is created.
-   * If the microtask is canceled, the promise will be rejected with a CancelTaskError.
-   * @param error The optional error to use as the cause of the cancellation.
-   * @returns The microtask.
+   * The function that stops the scheduler loop.
+   * It is used internally by `pause()` and `resume()`.
    */
-  cancel(error?: Error): this;
-}
+  stopQueue: (() => void) | null;
 
-/**
- * A scheduler that manages tasks to be executed at a later time.
- */
-export declare class Scheduler extends MicroTaskQueue {
   /**
-   * Whether the scheduler is paused.
-   * When paused, new tasks are queued but not executed immediately.
+   * Optional handler invoked when a scheduled `task.fn` throws.
+   * If unset, exceptions are surfaced via `Promise.reject(error)` so they
+   * fire the standard unhandled-rejection channel; the scheduler loop
+   * always continues regardless.
    */
-  paused: boolean;
+  onError: ((error: unknown, task: Task) => void) | null;
 
   /**
    * The tolerance for comparing starting times of tasks.
@@ -141,6 +130,19 @@ export declare class Scheduler extends MicroTaskQueue {
    * @returns The scheduler instance for chaining.
    */
   resume(): this;
+
+  /**
+   * Starts the scheduler loop by arming a `setTimeout` for the next-due task.
+   * Used internally by `enqueue()` and `resume()`.
+   * @returns The function that stops the scheduler loop.
+   */
+  startQueue(): (() => void) | null;
+
+  /**
+   * Processes due tasks. Called by the scheduler's internal `setTimeout`
+   * timer — not part of the typical user surface.
+   */
+  processTasks(): void;
 }
 
 /**

package/src/Scheduler.js

@@ -20,9 +20,12 @@ export class Task extends MicroTask {
 export class Scheduler extends MicroTaskQueue {
   constructor(paused, tolerance = 4) {
     super(paused);
-    this.queue = new MinHeap({less: (a, b) => a.time < b.time});
+    /** @type {(a: Task, b: Task) => boolean} */
+    const less = (a, b) => a.time < b.time;
+    this.queue = new MinHeap({less});
     this.tolerance = tolerance;
     this.stopQueue = null;
+    this.onError = null;
   }
 
   get isEmpty() {
@@ -70,8 +73,8 @@ export class Scheduler extends MicroTaskQueue {
   dequeue(task) {
     task.cancel();
     if (this.queue.isEmpty) return this;
-    if (!this.queue.has(task)) return this;
     if (this.paused || this.queue.top !== task) {
+      // MinHeap.remove no-ops on missing items, so no pre-check needed
       this.queue.remove(task);
       return this;
     }
@@ -110,7 +113,18 @@ export class Scheduler extends MicroTaskQueue {
     ) {
       const task = this.queue.pop();
       if (task.isCanceled) continue;
-      task.fn({task, scheduler: this});
+      try {
+        task.fn({task, scheduler: this});
+      } catch (error) {
+        // keep the loop alive; surface via onError callback or unhandled-rejection channel
+        if (this.onError) {
+          try {
+            this.onError(error, task);
+          } catch {}
+        } else {
+          Promise.reject(error);
+        }
+      }
     }
 
     if (!this.paused && !this.queue.isEmpty) this.stopQueue = this.startQueue();
@@ -120,7 +134,9 @@ export class Scheduler extends MicroTaskQueue {
 export const repeat = (fn, delay) => {
   const repeatableFunction = ({task, scheduler}) => {
     fn({task, scheduler});
-    if (!task.isCanceled) scheduler.enqueue(repeatableFunction, isNaN(delay) ? task.delay : delay);
+    if (task.isCanceled) return;
+    const next = isNaN(delay) ? task.delay : delay;
+    scheduler.enqueue(repeatableFunction, typeof next == 'number' && next < 1 ? 1 : next);
   };
   return repeatableFunction;
 };

package/src/Throttler.d.ts

@@ -17,7 +17,20 @@ export declare type ThrottlerOptions = {
 };
 
 /**
- * A throttler that throttles the execution of tasks based on a key.
+ * A throttler that paces the execution of work based on a key.
+ *
+ * Despite the name, this is **rate-limiting / pacing**, not classical
+ * "drop excess" throttle. `Throttler` does not execute functions; it
+ * exposes `wait(key)` and the caller decides what to do once awaited.
+ * Because there is nothing for `Throttler` to drop, every call is honored
+ * — N rapid calls produce delays roughly `0, throttleTimeout,
+ * 2*throttleTimeout, …`, spacing the work out across time. Use it when
+ * you need every operation to run but no faster than `throttleTimeout`
+ * apart per key.
+ *
+ * If you want React/Lodash-style "fire-leading-edge-only-then-drop"
+ * semantics, wrap your callback with `throttle()` from this package
+ * instead.
  */
 export declare class Throttler implements ThrottlerOptions {
   /**
@@ -54,16 +67,20 @@ export declare class Throttler implements ThrottlerOptions {
   getLastSeen(key: unknown): number;
 
   /**
-   * Retrieves the delay for a key.
+   * Retrieves the delay for a key and reserves the next slot.
+   * Each call extends the per-key queue: stored state advances by the returned
+   * delay, so the next call for the same key waits at least `throttleTimeout`
+   * past the slot just allocated. Returns the delay in milliseconds.
    * @param key The key to retrieve the delay for.
-   * @returns The delay for the key in milliseconds.
+   * @returns The delay before this caller's slot opens, in milliseconds.
    */
   getDelay(key: unknown): number;
 
   /**
-   * Waits for a key to be available.
+   * Waits until this caller's slot for `key` opens. See class docs for the
+   * pacing semantics — every call is queued, none are dropped.
    * @param key The key to wait for.
-   * @returns A promise that resolves when the key is available.
+   * @returns A promise that resolves when the slot is available.
    */
   wait(key: unknown): Promise<void>;
 

package/src/Throttler.js

@@ -3,6 +3,8 @@
 import sleep from './sleep.js';
 
 export class Throttler {
+  #handle = null;
+
   constructor({
     throttleTimeout = 1_000,
     neverSeenTimeout = 0,
@@ -12,7 +14,6 @@ export class Throttler {
     this.neverSeenTimeout = neverSeenTimeout;
     this.vacuumPeriod = vacuumPeriod;
     this.lastSeen = new Map();
-    this.handle = null;
     if (this.vacuumPeriod) this.startVacuum();
   }
 
@@ -38,7 +39,7 @@ export class Throttler {
   }
 
   get isVacuuming() {
-    return !!this.handle;
+    return !!this.#handle;
   }
 
   vacuum() {
@@ -51,18 +52,18 @@ export class Throttler {
   }
 
   startVacuum() {
-    if (this.handle) return this;
-    this.handle = setInterval(() => {
+    if (this.#handle) return this;
+    this.#handle = setInterval(() => {
       this.vacuum();
     }, this.vacuumPeriod);
-    if (this.handle.unref) this.handle.unref();
+    if (this.#handle.unref) this.#handle.unref();
     return this;
   }
 
   stopVacuum() {
-    if (!this.handle) return this;
-    clearInterval(this.handle);
-    this.handle = null;
+    if (!this.#handle) return this;
+    clearInterval(this.#handle);
+    this.#handle = null;
     return this;
   }
 }

package/src/audit.js

@@ -4,7 +4,7 @@ export const audit = (fn, ms) => {
   let handle = null,
     lastSeenArgs = null;
   return (...args) => {
-    lastSeenArgs = [...args];
+    lastSeenArgs = args;
     if (handle) return;
     handle = setTimeout(() => {
       handle = null;

package/src/defer.js

@@ -1,5 +1,6 @@
 // @ts-self-types="./defer.d.ts"
 
+/** @type {(...args: any[]) => any} */
 let deferImplementation = setTimeout;
 
 if (typeof requestIdleCallback == 'function') {

package/src/index.js

@@ -0,0 +1,29 @@
+// @ts-self-types="./index.d.ts"
+
+export * from './audit.js';
+export * from './batch.js';
+export * from './debounce.js';
+export * from './defer.js';
+export * from './sample.js';
+export * from './sleep.js';
+export * from './throttle.js';
+
+export * from './CancelTaskError.js';
+export * from './MicroTask.js';
+export * from './MicroTaskQueue.js';
+export * from './LimitedQueue.js';
+export * from './ListQueue.js';
+export * from './FrameQueue.js';
+export {IdleQueue, idleQueue} from './IdleQueue.js';
+
+export * from './Counter.js';
+export * from './PageWatcher.js';
+export * from './Retainer.js';
+export {Task as SchedulerTask, Scheduler, repeat, scheduler} from './Scheduler.js';
+export * from './Throttler.js';
+
+export * from './random-dist.js';
+export * from './random-sleep.js';
+
+export * from './when-dom-loaded.js';
+export {whenLoaded, scheduleWhenLoaded} from './when-loaded.js';

package/src/random-dist.js

@@ -10,12 +10,15 @@ export const normal = (mean, stdDev, skewness = 0) => {
     v = 0;
   while (!u) u = Math.random(); // Converting [0,1) to (0,1)
   while (!v) v = Math.random();
-  let z = Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
-  if (!skewness) return z * stdDev + mean;
-  const delta = skewness / Math.sqrt(1 + skewness * skewness),
-    x = delta * z + Math.sqrt(1 - delta * delta) * v;
-  z = z >= 0 ? x : -x;
-  return z * stdDev + mean;
+  const r = Math.sqrt(-2.0 * Math.log(u)),
+    theta = 2.0 * Math.PI * v,
+    z1 = r * Math.cos(theta);
+  if (!skewness) return z1 * stdDev + mean;
+  // Box-Muller yields two independent N(0,1) samples per (u, v) pair; use both for skew-normal.
+  const z2 = r * Math.sin(theta),
+    delta = skewness / Math.sqrt(1 + skewness * skewness),
+    x = delta * z1 + Math.sqrt(1 - delta * delta) * z2;
+  return (z1 >= 0 ? x : -x) * stdDev + mean;
 };
 
 export const expo = lambda => {

package/src/sample.js

@@ -6,7 +6,7 @@ export const sample = (fn, ms) => {
     lastSeenArgs = null,
     timeout = ms;
   return (...args) => {
-    lastSeenArgs = [...args];
+    lastSeenArgs = args;
     if (handle) return;
     const diff = (Date.now() - started) % ms,
       delay = diff ? ms - diff : timeout;

package/src/when-dom-loaded.js

@@ -2,10 +2,11 @@
 
 import ValueList from 'list-toolkit/value-list.js';
 
+/** @type {ValueList<() => void>} */
 const waitingForDom = new ValueList();
 
 export const remove = fn => {
-  for (const node of waitingForDom.getNodeIterable()) {
+  for (const node of waitingForDom.getNodeIterator()) {
     if (node.value === fn) {
       waitingForDom.removeNode(node);
       return true;

package/src/when-loaded.js

@@ -2,10 +2,11 @@
 
 import ValueList from 'list-toolkit/value-list.js';
 
+/** @type {ValueList<() => void>} */
 const waitingForLoad = new ValueList();
 
 export const remove = fn => {
-  for (const node of waitingForLoad.getNodeIterable()) {
+  for (const node of waitingForLoad.getNodeIterator()) {
     if (node.value === fn) {
       waitingForLoad.removeNode(node);
       return true;