time-queues 1.3.1 → 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,8 @@ 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._
@@ -156,3 +158,5 @@ BSD-3-Clause
 - 1.0.2 _Updated deps (`list-toolkit`)._
 - 1.0.1 _Minor update in README._
 - 1.0.0 _Initial release._
+
+See [release notes](wiki/Release-notes) for more details and history.

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;
@@ -205,8 +214,8 @@ class LimitedQueue extends ListQueue {
   get activeTasks(): number;
   get isIdle(): boolean;
   waitForIdle(): Promise<void>;
-  enqueue(fn: () => unknown): Task;
-  schedule(fn: (() => unknown) | null | undefined): Task;
+  enqueue(fn: (arg: {task: Task, queue: LimitedQueue}) => unknown): Task;
+  schedule(fn: ((arg: {task: Task, queue: LimitedQueue}) => unknown) | null | undefined): Task;
 }
 export { Task };
 export default LimitedQueue;
@@ -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`.
@@ -54,18 +58,18 @@ const results = await batch(
 - **debounce** (`time-queues/debounce.js`) — `debounce(fn, ms): fn`. Delay until input stabilizes.
 - **sample** (`time-queues/sample.js`) — `sample(fn, ms): fn`. Execute at regular intervals with last seen args.
 - **audit** (`time-queues/audit.js`) — `audit(fn, ms): fn`. Collect then execute after delay with last seen args.
-- **batch** (`time-queues/batch.js`) — `batch(fns, limit?): Promise<results[]>`. Run async operations with concurrency limit (default: 5).
+- **batch** (`time-queues/batch.js`) — `batch(fns, limit?): Promise<results[]>`. Run async operations with concurrency limit (default: 4).
 
 ### Supporting classes
 
 - **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.1",
+  "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"
   },
@@ -75,7 +83,11 @@
   ],
   "tape6": {
     "tests": [
-      "/tests/test-*.*js"
+      "/tests/test-*.js",
+      "/tests/test-*.mjs"
+    ],
+    "cli": [
+      "/tests/test-*.cjs"
     ],
     "importmap": {
       "imports": {
@@ -86,13 +98,13 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.3.0",
-    "prettier": "^3.8.1",
-    "tape-six": "^1.7.2",
-    "tape-six-proc": "^1.2.3",
-    "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.0"
+    "list-toolkit": "^2.3.2"
   }
 }

package/src/Counter.d.ts

@@ -22,7 +22,7 @@ export declare class Counter {
    * Sets the counter to a specific value.
    * @param value The new value for the counter.
    */
-  set value(value: number): void;
+  set value(value: number);
 
   /**
    * Increments the counter.
@@ -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

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 /**
  * A queue based on [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame).
@@ -33,7 +33,7 @@ export declare class FrameQueue extends ListQueue {
    * @param fn The function to execute.
    * @returns The task object.
    */
-  enqueue(fn: ({timeStamp: number, task: Task, queue: FrameQueue}) => unknown): Task;
+  enqueue(fn: (arg: {timeStamp: number; task: Task; queue: FrameQueue}) => unknown): Task;
 
   /**
    * Dequeues a task.
@@ -48,7 +48,7 @@ export declare class FrameQueue extends ListQueue {
    * @returns The task object.
    */
   schedule(
-    fn: (({timeStamp: number, task: Task, queue: FrameQueue}) => unknown) | null | undefined
+    fn: ((arg: {timeStamp: number; task: Task; queue: FrameQueue}) => unknown) | null | undefined
   ): Task;
 
   /**
@@ -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

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 /**
  * A queue based on [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback).
@@ -20,7 +20,7 @@ export declare class IdleQueue extends ListQueue {
   /**
    * The options passed to `requestIdleCallback()`.
    */
-  options: IdleCallbackOptions | undefined;
+  options: IdleRequestOptions | undefined;
 
   /**
    * Creates a new idle queue.
@@ -28,7 +28,7 @@ export declare class IdleQueue extends ListQueue {
    * @param timeoutBatchInMs The timeout batch size in milliseconds.
    * @param options The options passed to `requestIdleCallback()`.
    */
-  constructor(paused?: boolean, timeoutBatchInMs?: number, options?: IdleCallbackOptions);
+  constructor(paused?: boolean, timeoutBatchInMs?: number, options?: IdleRequestOptions);
 
   /**
    * Whether the queue is empty.
@@ -40,7 +40,7 @@ export declare class IdleQueue extends ListQueue {
    * @param fn The function to execute.
    * @returns The task object.
    */
-  enqueue(fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown): Task;
+  enqueue(fn: (arg: {deadline: IdleDeadline; task: Task; queue: IdleQueue}) => unknown): Task;
 
   /**
    * Dequeues a task.
@@ -55,7 +55,10 @@ export declare class IdleQueue extends ListQueue {
    * @returns The task object.
    */
   schedule(
-    fn: (({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown) | null | undefined
+    fn:
+      | ((arg: {deadline: IdleDeadline; task: Task; queue: IdleQueue}) => unknown)
+      | null
+      | undefined
   ): Task;
 
   /**
@@ -82,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;
 }
 
 /**
@@ -93,7 +103,7 @@ export const idleQueue: IdleQueue;
  * A function that schedules a task to run in the next idle period.
  */
 export const defer: (
-  fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown
+  fn: (arg: {deadline: IdleDeadline; task: Task; queue: IdleQueue}) => unknown
 ) => Task;
 
 export default idleQueue;

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

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 export {Task};
 
@@ -58,7 +58,7 @@ export declare class LimitedQueue extends ListQueue {
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
-  enqueue(fn: () => unknown): Task;
+  enqueue(fn: (arg: {task: Task; queue: LimitedQueue}) => unknown): Task;
 
   /**
    * Dequeues a microtask.
@@ -72,7 +72,7 @@ export declare class LimitedQueue extends ListQueue {
    * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with the function's arguments. Otherwise, it is resolved with the function's return value.
    * @returns The task object.
    */
-  schedule(fn: (() => unknown) | null | undefined): Task;
+  schedule(fn: ((arg: {task: Task; queue: LimitedQueue}) => unknown) | null | undefined): Task;
 
   /**
    * Clears the queue.

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;
@@ -9,7 +18,7 @@ export class LimitedQueue extends ListQueue {
 
   constructor(limit, paused) {
     super(paused);
-    this.#taskLimit = limit;
+    this.#taskLimit = Math.max(1, limit);
     this.#activeTasks = 0;
     this.#idleWaiters = [];
   }
@@ -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,6 +1,6 @@
-import {MicroTask} from './MicroTask';
-import {MicroTaskQueue} from './MicroTaskQueue';
-import {List} from 'list-toolkit';
+import List from 'list-toolkit/list.js';
+import {MicroTask} from './MicroTask.js';
+import {MicroTaskQueue} from './MicroTaskQueue.js';
 
 /**
  * A list-based queue of microtasks that will be executed when scheduled.
@@ -12,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()`.
@@ -34,7 +39,7 @@ export declare class ListQueue extends MicroTaskQueue {
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
-  enqueue(fn: () => unknown): MicroTask;
+  enqueue(fn: (...args: any[]) => unknown): MicroTask;
 
   /**
    * Dequeues a microtask.
@@ -48,7 +53,7 @@ export declare class ListQueue extends MicroTaskQueue {
    * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with the function's arguments. Otherwise, it is resolved with the function's return value.
    * @returns The task object.
    */
-  schedule(fn: (() => unknown) | null | undefined): MicroTask;
+  schedule(fn: ((...args: any[]) => unknown) | null | undefined): MicroTask;
 
   /**
    * Clears the queue.
@@ -75,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;
 }
 
 /**