Cleanup + fixing more edge cases.

Author: uhop

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;
     }
   }
 }

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();
   }
 }

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();
   }
 }

src/ListQueue.d.ts

@@ -80,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;
 }
 
 /**

src/ListQueue.js

@@ -7,10 +7,8 @@ import MicroTaskQueue from './MicroTaskQueue.js';
 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;
   }
 
@@ -21,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;
@@ -30,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();
       }
@@ -41,15 +37,13 @@ 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;
   }
 
   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;
@@ -69,6 +63,27 @@ export class ListQueue extends MicroTaskQueue {
   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;

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;
@@ -36,6 +40,13 @@ export declare class MicroTask {
    */
   get settled(): boolean;
 
+  /**
+   * 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
@@ -52,9 +63,10 @@ export declare class MicroTask {
    * Cancels the microtask. Always sets `isCanceled = true` so queues skip the task.
    * Additionally rejects the promise with a `CancelTaskError` if `makePromise()`
    * has been called.
-   * Note: when called pre-`makePromise()`, the optional `error` argument is dropped
-   * (no promise rejection to attach `cause` to). Pass `error` only after the
-   * promise has been created if you need it preserved.
+   * 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.

src/MicroTask.js

@@ -7,22 +7,25 @@ export class MicroTask {
   #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;
   }
+  get cancelError() {
+    return this.#cancelError;
+  }
   makePromise() {
     if (this.#promise) return this;
     if (typeof Promise.withResolvers == 'function') {
@@ -37,6 +40,14 @@ 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) {
@@ -53,8 +64,13 @@ export class MicroTask {
   }
   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;

src/MicroTaskQueue.js

@@ -2,12 +2,13 @@
 
 import MicroTask from './MicroTask.js';
 
+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;
   }
@@ -30,26 +31,23 @@ export class MicroTaskQueue {
   clear() {
     return this;
   }
-  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;

src/PageWatcher.js

@@ -46,6 +46,11 @@ export class PageWatcher extends ListQueue {
     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();

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.