time-queues 1.3.1 → 1.4.0

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

@@ -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,10 +16,14 @@ 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.
+   * 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.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.
@@ -46,7 +46,7 @@ export declare class MicroTaskQueue {
    * @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

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

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 /**
  * A page state.
@@ -82,7 +82,7 @@ export declare class PageWatcher extends ListQueue {
  */
 export declare const watchStates: (
   queue: ListQueue,
-  resumeStatesList: PageState[] = ['active']
+  resumeStatesList?: PageState[]
 ) => (state: PageState) => void;
 
 /**

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';
 };
 
@@ -27,7 +24,6 @@ export class PageWatcher extends ListQueue {
   }
 
   pause() {
-    this.paused = true;
     watchedEvents.forEach(type => removeEventListener(type, this, eventHandlerOptions));
     return super.pause();
   }
@@ -45,12 +41,21 @@ 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() {
-    this.list.clear();
+    while (!this.list.isEmpty) {
+      const task = this.list.popFront();
+      task.cancel();
+    }
     return this;
   }
 

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,42 +1,54 @@
 // @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(async () => {
-      const value = this.value;
-      this.value = null;
-      this.handle = null;
+    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,19 +1,17 @@
-import MicroTask from './MicroTask';
-import MicroTaskQueue from './MicroTaskQueue';
+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: ({task: Task, scheduler: Scheduler}) => unknown;
-
-  /**
-   * Whether the task has been canceled.
-   */
-  isCanceled: boolean;
+  fn: (arg: {task: Task; scheduler: Scheduler}) => unknown;
 
   /**
    * The time in milliseconds (Unix timestamp) when the task is scheduled to run.
@@ -30,46 +28,37 @@ export declare class Task extends MicroTask {
    * @param delay The delay before the task is executed. It can be a number of milliseconds or a `Date` object as an absolute time.
    * @param fn The function to execute.
    */
-  constructor(delay: number | Date, fn: ({task: Task, scheduler: Scheduler}) => unknown);
-
-  /**
-   * Makes a promise that will be resolved when the microtask is executed.
-   * @returns The microtask.
-   */
-  makePromise(): this;
+  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 {
   /**
-   * 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.
@@ -102,14 +91,14 @@ export declare class Scheduler extends MicroTaskQueue {
    * @param delay The delay before the task is executed. It can be a number of milliseconds or a `Date` object as an absolute time.
    * @returns The task object that was enqueued.
    */
-  enqueue(fn: ({task: Task, scheduler: Scheduler}) => unknown, delay: number | Date): Task;
+  enqueue(fn: (arg: {task: Task; scheduler: Scheduler}) => unknown, delay: number | Date): Task;
 
   /**
    * Removes a task from the scheduler.
    * @param task The task to remove.
    * @returns The scheduler object for chaining.
    */
-  dequeue(task: Task): this;
+  dequeue(task: MicroTask): this;
 
   /**
    * Schedules a task to run in the future.
@@ -118,7 +107,7 @@ export declare class Scheduler extends MicroTaskQueue {
    * @returns The task object that was scheduled.
    */
   schedule(
-    fn: (({task: Task, scheduler: Scheduler}) => unknown) | null | undefined,
+    fn: ((arg: {task: Task; scheduler: Scheduler}) => unknown) | null | undefined,
     delay: number | Date
   ): Task;
 
@@ -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;
 }
 
 /**
@@ -150,9 +152,9 @@ export declare class Scheduler extends MicroTaskQueue {
  * @returns A function that can be used to enqueue the task to the scheduler.
  */
 export declare const repeat: (
-  fn: ({task: Task, scheduler: Scheduler}) => void,
+  fn: (arg: {task: Task; scheduler: Scheduler}) => void,
   delay: number | Date
-) => ({task: Task, scheduler: Scheduler}) => void;
+) => (arg: {task: Task; scheduler: Scheduler}) => void;
 
 /**
  * A scheduler instance usually used as a global scheduler.

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() {
@@ -71,6 +74,7 @@ export class Scheduler extends MicroTaskQueue {
     task.cancel();
     if (this.queue.isEmpty) 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;
     }
@@ -108,7 +112,19 @@ export class Scheduler extends MicroTaskQueue {
       this.queue.top.time <= Date.now() + this.tolerance
     ) {
       const task = this.queue.pop();
-      task.fn({task, scheduler: this});
+      if (task.isCanceled) continue;
+      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();
@@ -118,7 +134,9 @@ export class Scheduler extends MicroTaskQueue {
 export const repeat = (fn, delay) => {
   const repeatableFunction = ({task, scheduler}) => {
     fn({task, scheduler});
-    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;
 };