time-queues 1.3.0 → 1.3.2

package/llms.txt

@@ -0,0 +1,95 @@
+# 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
+
+## Install
+
+```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';
+
+// 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 URLs, max 3 at a time
+const results = await batch(
+  urls.map(url => () => fetch(url).then(r => r.json())),
+  3
+);
+```
+
+## Modules
+
+### 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).
+- **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`.
+- **PageWatcher** (`time-queues/PageWatcher.js`) — react to page lifecycle changes (active, passive, hidden, frozen, terminated). Extends ListQueue. Exports: `PageWatcher`, `watchStates(states, fn)`, `pageWatcher` (global instance).
+
+### Utility functions
+
+- **sleep** (`time-queues/sleep.js`) — `sleep(ms | Date): Promise<void>`. Promise-based delay.
+- **defer** (`time-queues/defer.js`) — `defer(fn): void`. Execute on next tick via `requestIdleCallback`/`setImmediate`/`setTimeout`. Also exports `scheduleDefer(fn): Promise`.
+- **throttle** (`time-queues/throttle.js`) — `throttle(fn, ms): fn`. Rate-limit: execute immediately, ignore calls until timeout expires.
+- **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: 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)`.
+- **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)`.
+- **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.
+
+### Random utilities
+
+- **random-dist** (`time-queues/random-dist.js`) — `uniform(min, max)`, `normal(mean, stdDev, skewness?)`, `expo(lambda)`, `pareto(min, alpha)`.
+- **random-sleep** (`time-queues/random-sleep.js`) — `randomUniformSleep(min, max)`, `randomNormalSleep(mean, stdDev)`, `randomExpoSleep(lambda, scale)`, `randomParetoSleep(min, ratio)`, `randomSleep(max)`. Each returns `() => Promise<void>`.
+
+### Page load helpers
+
+- **whenDomLoaded** (`time-queues/when-dom-loaded.js`) — `whenDomLoaded(fn)`. Also exports `scheduleWhenDomLoaded(fn): Promise`, `remove(fn): boolean`.
+- **whenLoaded** (`time-queues/when-loaded.js`) — `whenLoaded(fn)`. Also exports `scheduleWhenLoaded(fn): Promise`, `remove(fn): boolean`.
+
+## Key concepts
+
+- All modules are **ESM** with `import ... from 'time-queues/<module>.js'`.
+- **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`.
+- **Graceful degradation** — feature detection for browser APIs, works in Node.js/Bun/Deno.
+- **TypeScript** — built-in `.d.ts` declarations for all modules.
+
+## Links
+
+- Docs: https://github.com/uhop/time-queues/wiki
+- npm: https://www.npmjs.com/package/time-queues
+- Full LLM reference: https://github.com/uhop/time-queues/blob/master/llms-full.txt

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "time-queues",
-  "version": "1.3.0",
-  "description": "Time queues to organize multitasking and scheduled tasks.",
+  "version": "1.3.2",
+  "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": {
@@ -21,8 +21,14 @@
     "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'",
-    "lint": "prettier --check src/ tests/ wiki/",
-    "lint:fix": "prettier --write src/ tests/ wiki/",
+    "ts-test:proc": "tape6-proc --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:proc:bun": "bun run `tape6-proc --self` --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:proc:deno": "deno run -A `tape6-proc --self` --flags FO -r -A '/ts-tests/test-*.*ts'",
+    "ts-test:seq": "tape6-seq --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:seq:bun": "bun run `tape6-seq --self` --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:seq:deno": "deno run -A `tape6-seq --self` --flags FO '/ts-tests/test-*.*ts'",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write .",
     "start": "tape6-server --trace"
   },
   "repository": {
@@ -30,9 +36,25 @@
     "url": "git+ssh://git@github.com/uhop/time-queues.git"
   },
   "keywords": [
+    "scheduler",
+    "task-queue",
+    "async-queue",
+    "concurrency",
+    "throttle",
+    "debounce",
+    "rate-limit",
+    "batch",
+    "sleep",
+    "defer",
+    "idle-queue",
+    "requestIdleCallback",
+    "requestAnimationFrame",
+    "page-lifecycle",
     "timer",
     "time",
-    "queue"
+    "queue",
+    "esm",
+    "typescript"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "funding": "https://github.com/sponsors/uhop",
@@ -40,15 +62,24 @@
   "bugs": {
     "url": "https://github.com/uhop/time-queues/issues"
   },
+  "github": "https://github.com/uhop/time-queues",
   "homepage": "https://github.com/uhop/time-queues#readme",
+  "llms": "https://raw.githubusercontent.com/uhop/time-queues/master/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/time-queues/master/llms-full.txt",
   "files": [
     "/src",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "tape6": {
     "tests": [
-      "/tests/test-*.*js"
+      "/tests/test-*.js",
+      "/tests/test-*.mjs"
+    ],
+    "cli": [
+      "/tests/test-*.cjs"
     ],
     "importmap": {
       "imports": {
@@ -59,12 +90,13 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.2.3",
-    "tape-six": "^1.7.0",
-    "tape-six-proc": "^1.2.2",
+    "@types/node": "^25.5.0",
+    "prettier": "^3.8.1",
+    "tape-six": "^1.7.12",
+    "tape-six-proc": "^1.2.7",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "list-toolkit": "^2.2.6"
+    "list-toolkit": "^2.3.2"
   }
 }

package/src/CancelTaskError.d.ts

@@ -2,7 +2,8 @@
  * A cancellation error that is thrown when a microtask is canceled.
  */
 export declare class CancelTaskError extends Error {
-  constructor(message: string = 'Task was canceled', options?: ErrorOptions);
+  name: 'CancelTaskError';
+  constructor(message?: string, options?: ErrorOptions);
 }
 
 export default CancelTaskError;

package/src/CancelTaskError.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./CancelTaskError.d.ts"
 
-'use strict';
-
 export class CancelTaskError extends Error {
   constructor(message = 'Task was canceled', options) {
     super(message, options);

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.

package/src/Counter.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./Counter.d.ts"
 
-'use strict';
-
 export class Counter {
   constructor(initial = 0) {
     this.count = initial;

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.
@@ -44,11 +44,11 @@ export declare class FrameQueue extends ListQueue {
 
   /**
    * Schedules a task to run in the next frame.
-   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with function's arguments. Otherwise, it is resolved with the function's return value.
+   * @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: (({timeStamp: number, task: Task, queue: FrameQueue}) => unknown) | null | undefined
+    fn: ((arg: {timeStamp: number; task: Task; queue: FrameQueue}) => unknown) | null | undefined
   ): Task;
 
   /**
@@ -82,4 +82,4 @@ export declare class FrameQueue extends ListQueue {
  */
 export const frameQueue: FrameQueue;
 
-export default FrameQueue;
+export default frameQueue;

package/src/FrameQueue.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./FrameQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 

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.
@@ -51,11 +51,14 @@ export declare class IdleQueue extends ListQueue {
 
   /**
    * Schedules a task to run in the next idle period.
-   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with function's arguments. Otherwise, it is resolved with the function's return value.
+   * @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: (({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown) | null | undefined
+    fn:
+      | ((arg: {deadline: IdleDeadline; task: Task; queue: IdleQueue}) => unknown)
+      | null
+      | undefined
   ): Task;
 
   /**
@@ -93,7 +96,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;
+export default idleQueue;

package/src/IdleQueue.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./IdleQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 

package/src/LimitedQueue.d.ts

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 export {Task};
 
@@ -15,7 +15,7 @@ export declare class LimitedQueue extends ListQueue {
   stopQueue: (() => void) | null;
 
   /**
-   * Creates a new list queue.
+   * Creates a new limited queue.
    * @param limit The maximum number of tasks that can be run in parallel.
    * @param paused Whether the queue should start paused.
    */
@@ -33,7 +33,7 @@ export declare class LimitedQueue extends ListQueue {
 
   /**
    * Set the maximum number of tasks that can be run in parallel.
-   * @param limit The new maximum number of tasks that can be run in parallel. It can dynamically add more tasks if the current number of tasks is less than the new limit.
+   * @param limit The new maximum number of tasks that can be run in parallel. Setting a higher limit may immediately start additional tasks.
    */
   set taskLimit(limit: number);
 
@@ -48,7 +48,7 @@ export declare class LimitedQueue extends ListQueue {
   get isIdle(): boolean;
 
   /**
-   * Wait for queue to become idle.
+   * Waits for the queue to become idle.
    * @returns A promise that resolves when the queue becomes idle. If the queue is already idle, the promise is resolved immediately.
    */
   waitForIdle(): Promise<void>;
@@ -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.
@@ -69,10 +69,10 @@ export declare class LimitedQueue extends ListQueue {
 
   /**
    * Schedules a microtask.
-   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with function's arguments. Otherwise, it is resolved with the function's return value.
+   * @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

@@ -9,7 +9,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 = [];
   }

package/src/ListQueue.d.ts

@@ -1,6 +1,5 @@
-import {MicroTask} from './MicroTask';
-import {MicroTaskQueue} from './MicroTaskQueue';
-import {List} from 'list-toolkit';
+import {MicroTask} from './MicroTask.js';
+import {MicroTaskQueue} from './MicroTaskQueue.js';
 
 /**
  * A list-based queue of microtasks that will be executed when scheduled.
@@ -34,7 +33,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.
@@ -45,10 +44,10 @@ export declare class ListQueue extends MicroTaskQueue {
 
   /**
    * Schedules a microtask.
-   * @param fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with function's arguments. Otherwise, it is resolved with the function's return value.
+   * @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.

package/src/ListQueue.js

@@ -1,14 +1,20 @@
 // @ts-self-types="./ListQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.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
     this.list = new List();
+    // AI-NOTE: stopQueue holds the stop function returned by startQueue(), or null
     this.stopQueue = null;
   }
 
@@ -19,6 +25,7 @@ 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;
@@ -27,6 +34,7 @@ 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();
       }
@@ -37,6 +45,7 @@ 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;
   }
@@ -44,6 +53,7 @@ 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;
@@ -60,7 +70,12 @@ export class ListQueue extends MicroTaskQueue {
     return this;
   }
 
-  // API to be overridden in subclasses
+  /**
+   * 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;
   }

package/src/MicroTask.d.ts

@@ -5,7 +5,7 @@ export declare class MicroTask {
   /**
    * The function to execute when the microtask is scheduled.
    */
-  fn: () => unknown;
+  fn: (...args: any[]) => unknown;
 
   /**
    * Whether the microtask has been canceled.
@@ -16,7 +16,7 @@ export declare class MicroTask {
    * Creates a new microtask.
    * @param fn The function to execute when the microtask is scheduled.
    */
-  constructor(fn: () => unknown);
+  constructor(fn: (...args: any[]) => unknown);
 
   /**
    * Makes a promise that will be resolved when the microtask is executed.
@@ -31,6 +31,11 @@ export declare class MicroTask {
    */
   get promise(): Promise<unknown> | null;
 
+  /**
+   * Whether the microtask has been settled (resolved or canceled).
+   */
+  get settled(): boolean;
+
   /**
    * Resolves the microtask, if a promise is created.
    * @param value The value to resolve the microtask with.

package/src/MicroTask.js

@@ -2,6 +2,11 @@
 
 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;
@@ -9,17 +14,25 @@ export class MicroTask {
   #settled;
   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.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.
+   */
   makePromise() {
     if (this.#promise) return this;
     if (typeof Promise.withResolvers == 'function') {
@@ -45,6 +58,10 @@ 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 (this.#reject) {

package/src/MicroTaskQueue.d.ts

@@ -1,4 +1,4 @@
-import MicroTask from './MicroTask';
+import MicroTask from './MicroTask.js';
 
 /**
  * A queue of microtasks that will be executed when scheduled.
@@ -29,7 +29,7 @@ export declare class 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, ...args: unknown[]): MicroTask;
 
   /**
    * Dequeues a microtask from the queue.
@@ -42,11 +42,11 @@ export declare class MicroTaskQueue {
   /**
    * Schedules a microtask with a promise for execution.
    * This can be overridden in subclasses if more arguments are needed.
-   * @param fn The function to execute when the microtask is scheduled, it can be an async function.
-   * @param args Additional arguments to pass to `enqueue()`. It is there to accommodate custom implementations in subclasses.
+   * @param fn The function to execute when the microtask is scheduled. It can be an async function.
+   * @param args Additional arguments to pass to `enqueue()`. They are there to accommodate custom implementations in subclasses.
    * @returns The scheduled microtask.
    */
-  schedule(fn: (() => unknown) | null | undefined, ...args: unknown[]): MicroTask;
+  schedule(fn: ((...args: any[]) => unknown) | null | undefined, ...args: unknown[]): MicroTask;
 
   /**
    * Clears all tasks from the queue.

package/src/MicroTaskQueue.js

@@ -1,14 +1,19 @@
 // @ts-self-types="./MicroTaskQueue.d.ts"
 
-'use strict';
-
 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
+ */
 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
   get isEmpty() {
     return true;
   }
@@ -20,6 +25,11 @@ 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) {
     const task = new MicroTask(fn);
     return task;
@@ -31,7 +41,11 @@ export class MicroTaskQueue {
   clear() {
     return this;
   }
-  // Generic API
+  /**
+   * 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;
     const task = this.enqueue(