time-queues 1.2.2 → 1.2.4

package/README.md

@@ -61,6 +61,8 @@ This project is licensed under the BSD-3-Clause License.
 
 ## Release History
 
+- 1.2.4 _Updated dependencies._
+- 1.2.3 _Updated dependencies._
 - 1.2.2 _`Counter`: separated old waiter from new waiters before notifying them._
 - 1.2.1 _Minor release: updated formal TS dependencies in `index.d.ts`._
 - 1.2.0 _Added `Counter`. Updated dev dependencies._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "time-queues",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Time queues to organize multitasking and scheduled tasks.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -56,12 +56,12 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.14.1",
-    "tape-six": "^1.1.1",
-    "tape-six-proc": "^1.0.1",
-    "typescript": "^5.8.3"
+    "@types/node": "^25.0.10",
+    "tape-six": "^1.4.5",
+    "tape-six-proc": "^1.1.6",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "list-toolkit": "^2.2.1"
+    "list-toolkit": "^2.2.5"
   }
 }

package/src/CancelTaskError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A cancellation error that is thrown when a microtask is canceled.
+ */
+export declare class CancelTaskError extends Error {
+  constructor();
+}
+
+export default CancelTaskError;

package/src/CancelTaskError.js

@@ -0,0 +1,15 @@
+// @ts-self-types="./CancelTaskError.d.ts"
+
+'use strict';
+
+export class CancelTaskError extends Error {
+  constructor() {
+    super('Task was canceled');
+    this.name = 'CancelTaskError';
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CancelTaskError);
+    }
+  }
+}
+
+export default CancelTaskError;

package/src/FrameQueue.d.ts

@@ -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) => void): Task;
+  enqueue(fn: ({timeStamp: number, task: Task, queue: FrameQueue}) => unknown): Task;
 
   /**
    * Dequeues a task.
@@ -42,6 +42,15 @@ export declare class FrameQueue extends ListQueue {
    */
   dequeue(task: Task): this;
 
+  /**
+   * 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.
+   * @returns The task object.
+   */
+  schedule(
+    fn: (({timeStamp: number, task: Task, queue: FrameQueue}) => unknown) | null | undefined
+  ): Task;
+
   /**
    * Clears the queue.
    * @returns The queue.

package/src/FrameQueue.js

@@ -26,14 +26,14 @@ export class FrameQueue extends ListQueue {
       const start = Date.now();
       while (Date.now() - start < this.batch && !this.list.isEmpty) {
         const task = this.list.popFront();
-        task.fn(timeStamp, task, this);
+        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, this);
+        task.fn({timeStamp, task, queue: this});
       }
     }
 

package/src/IdleQueue.d.ts

@@ -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) => void): Task;
+  enqueue(fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown): Task;
 
   /**
    * Dequeues a task.
@@ -49,6 +49,15 @@ export declare class IdleQueue extends ListQueue {
    */
   dequeue(task: Task): this;
 
+  /**
+   * 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.
+   * @returns The task object.
+   */
+  schedule(
+    fn: (({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown) | null | undefined
+  ): Task;
+
   /**
    * Clears the queue.
    * @returns The queue.
@@ -83,6 +92,8 @@ 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) => void) => Task;
+export const defer: (
+  fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown
+) => Task;
 
 export default IdleQueue;

package/src/IdleQueue.js

@@ -30,20 +30,20 @@ export class IdleQueue extends ListQueue {
         const start = Date.now();
         while (Date.now() - start < this.timeoutBatch && !this.list.isEmpty) {
           const task = this.list.popFront();
-          task.fn(deadline, task, this);
+          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, this);
+          task.fn({deadline, task, queue: this});
         }
       }
     } else {
       while (deadline.timeRemaining() > 0 && !this.list.isEmpty) {
         const task = this.list.popFront();
-        task.fn(deadline, task, this);
+        task.fn({deadline, task, queue: this});
       }
     }
 

package/src/ListQueue.d.ts

@@ -1,4 +1,5 @@
 import {MicroTask} from './MicroTask';
+import {MicroTaskQueue} from './MicroTaskQueue';
 import {List} from 'list-toolkit';
 
 /**
@@ -33,7 +34,7 @@ export declare class ListQueue extends MicroTaskQueue {
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
-  enqueue(fn: () => void): MicroTask;
+  enqueue(fn: () => unknown): MicroTask;
 
   /**
    * Dequeues a microtask.
@@ -42,6 +43,13 @@ export declare class ListQueue extends MicroTaskQueue {
    */
   dequeue(task: MicroTask): this;
 
+  /**
+   * 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.
+   * @returns The task object.
+   */
+  schedule(fn: (() => unknown) | null | undefined): MicroTask;
+
   /**
    * Clears the queue.
    * @returns The queue.
@@ -74,4 +82,9 @@ export declare class ListQueue extends MicroTaskQueue {
  */
 export declare type Task = MicroTask;
 
+/**
+ * A task for list queues with a promise.
+ */
+export declare type TaskWithPromise = MicroTaskWithPromise;
+
 export default ListQueue;

package/src/ListQueue.js

@@ -42,6 +42,7 @@ export class ListQueue extends MicroTaskQueue {
   }
 
   dequeue(task) {
+    task.cancel();
     this.list.removeNode(task);
     if (!this.paused && this.list.isEmpty && this.stopQueue)
       this.stopQueue = (this.stopQueue(), null);
@@ -51,7 +52,10 @@ export class ListQueue extends MicroTaskQueue {
   clear() {
     const paused = this.paused;
     if (!paused) this.pause();
-    this.list.clear();
+    while (!this.list.isEmpty) {
+      const task = this.list.popFront();
+      task.cancel();
+    }
     if (!paused) this.resume();
     return this;
   }

package/src/MicroTask.d.ts

@@ -5,13 +5,46 @@ export declare class MicroTask {
   /**
    * The function to execute when the microtask is scheduled.
    */
-  fn: () => void;
+  fn: () => unknown;
+
+  /**
+   * Whether the microtask has been canceled.
+   */
+  isCanceled: boolean;
 
   /**
    * Creates a new microtask.
    * @param fn The function to execute when the microtask is scheduled.
    */
-  constructor(fn: () => void);
+  constructor(fn: () => unknown);
+
+  /**
+   * 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.
+   */
+  get promise(): Promise<unknown> | null;
+
+  /**
+   * Resolves the microtask, if a promise is created.
+   * @param value The value to resolve the microtask with.
+   * @returns The microtask.
+   */
+  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.
+   * It can be overridden in subclasses.
+   * @returns The microtask.
+   */
+  cancel(): this;
 }
 
 export default MicroTask;

package/src/MicroTask.js

@@ -2,9 +2,43 @@
 
 'use strict';
 
+import CancelTaskError from './CancelTaskError.js';
+
 export class MicroTask {
+  #promise;
+  #resolve;
+  #reject;
   constructor(fn) {
     this.fn = fn;
+    this.#promise = null;
+    this.#resolve = null;
+    this.#reject = null;
+    this.isCanceled = false;
+  }
+  get promise() {
+    return this.#promise;
+  }
+  makePromise() {
+    this.#promise = new Promise((resolve, reject) => {
+      this.#resolve = resolve;
+      this.#reject = reject;
+    });
+    return this;
+  }
+  resolve(value) {
+    if (!this.#resolve) return;
+    this.#resolve(value);
+    this.#resolve = null;
+    this.#reject = null;
+    return this;
+  }
+  cancel() {
+    if (!this.#reject) return;
+    this.isCanceled = true;
+    this.#reject(new CancelTaskError());
+    this.#resolve = null;
+    this.#reject = null;
+    return this;
   }
 }
 

package/src/MicroTaskQueue.d.ts

@@ -1,4 +1,4 @@
-import {MicroTask} from './MicroTask';
+import MicroTask from './MicroTask';
 
 /**
  * A queue of microtasks that will be executed when scheduled.
@@ -28,7 +28,7 @@ export declare class MicroTaskQueue {
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
-  enqueue(fn: () => void): MicroTask;
+  enqueue(fn: () => unknown): MicroTask;
 
   /**
    * Dequeues a microtask.
@@ -38,6 +38,14 @@ export declare class MicroTaskQueue {
    */
   dequeue(task: MicroTask): this;
 
+  /**
+   * Schedules a microtask with a promise.
+   * It 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.
+   * @returns The scheduled microtask.
+   */
+  schedule(fn: (() => unknown) | null | undefined): MicroTask;
+
   /**
    * Clears the queue.
    * It is meant to be overridden in subclasses.

package/src/MicroTaskQueue.js

@@ -25,11 +25,32 @@ export class MicroTaskQueue {
     return task;
   }
   dequeue(task) {
+    task.cancel();
     return this;
   }
   clear() {
     return this;
   }
+  // Generic API
+  schedule(fn, ...args) {
+    fn ||= MicroTaskQueue.returnArgs;
+    const task = this.enqueue(
+      (...args) => {
+        try {
+          task.resolve(fn(...args));
+        } catch (error) {
+          task.cancel();
+        }
+      },
+      ...args
+    );
+    task.makePromise();
+    task.fn = fn;
+    return task;
+  }
+  static returnArgs(...args) {
+    return args;
+  }
 }
 
 export default MicroTaskQueue;

package/src/PageWatcher.d.ts

@@ -48,6 +48,12 @@ export declare class PageWatcher extends ListQueue {
    */
   dequeue(task: Task): this;
 
+  /**
+   * Schedules a task to be executed when the page state changes.
+   * @throws Always throws an error.
+   */
+  schedule(): never;
+
   /**
    * Clears the queue.
    * @returns The queue.

package/src/PageWatcher.js

@@ -47,6 +47,10 @@ export class PageWatcher extends ListQueue {
 
   // Implemented in ListQueue: dequeue()
 
+  schedule() {
+    throw new Error('Not implemented');
+  }
+
   clear() {
     this.list.clear();
     return this;

package/src/Scheduler.d.ts

@@ -8,7 +8,12 @@ export declare class Task extends MicroTask {
   /**
    * The function to execute.
    */
-  fn: (task: Task, scheduler: Scheduler) => void;
+  fn: ({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.
@@ -25,7 +30,35 @@ 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) => void);
+  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;
+
+  /**
+   * 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.
+   */
+  get promise(): Promise<unknown> | null;
+
+  /**
+   * Resolves the microtask, if a promise is created.
+   * @param value The value to resolve the microtask with.
+   * @returns The microtask.
+   */
+  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.
+   * It can be overridden in subclasses.
+   * @returns The microtask.
+   */
+  cancel(): this;
 }
 
 /**
@@ -65,7 +98,7 @@ 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.
    */
-  enqueue(fn: (task: Task, scheduler: Scheduler) => void, delay: number | Date): Task;
+  enqueue(fn: ({task: Task, scheduler: Scheduler}) => unknown, delay: number | Date): Task;
 
   /**
    * Removes a task from the scheduler.
@@ -75,11 +108,15 @@ export declare class Scheduler extends MicroTaskQueue {
   dequeue(task: Task): this;
 
   /**
-   * Creates a promise that resolves after a delay.
+   * Schedules a task to run in the future.
+   * @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 delay The delay before the task is executed. It can be a number of milliseconds or a `Date` object as an absolute time.
-   * @returns A promise that resolves after the delay.
+   * @returns The task object.
    */
-  schedule(delay: number | Date): Promise<{task: Task; scheduler: Scheduler}>;
+  schedule(
+    fn: (({task: Task, scheduler: Scheduler}) => unknown) | null | undefined,
+    delay: number | Date
+  ): Task;
 
   /**
    * Clears the queue.
@@ -107,9 +144,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: ({task: Task, scheduler: Scheduler}) => void,
   delay: number | Date
-) => (task: Task, scheduler: Scheduler) => void;
+) => ({task: Task, scheduler: Scheduler}) => void;
 
 /**
  * A scheduler instance usually used as a global scheduler.

package/src/Scheduler.js

@@ -70,6 +70,7 @@ export class Scheduler extends MicroTaskQueue {
   }
 
   dequeue(task) {
+    task.cancel();
     if (this.queue.isEmpty) return this;
     if (this.paused || this.queue.top !== task) {
       this.queue.remove(task);
@@ -83,15 +84,10 @@ export class Scheduler extends MicroTaskQueue {
     return this;
   }
 
-  schedule(delay) {
-    return new Promise(resolve =>
-      this.enqueue((task, scheduler) => resolve({task, scheduler}), delay)
-    );
-  }
-
   clear() {
     const paused = this.paused;
     if (!paused) this.pause();
+    this.queue.array.forEach(task => task.cancel());
     this.queue.clear();
     if (!paused) this.resume();
   }
@@ -113,7 +109,7 @@ export class Scheduler extends MicroTaskQueue {
       this.queue.top.time <= Date.now() + this.tolerance
     ) {
       const task = this.queue.pop();
-      task.fn(task, this);
+      task.fn({task, scheduler: this});
     }
 
     if (!this.paused && !this.queue.isEmpty) this.stopQueue = this.startQueue();
@@ -121,8 +117,8 @@ export class Scheduler extends MicroTaskQueue {
 }
 
 export const repeat = (fn, delay) => {
-  const repeatableFunction = (task, scheduler) => {
-    fn(task, scheduler);
+  const repeatableFunction = ({task, scheduler}) => {
+    fn({task, scheduler});
     scheduler.enqueue(repeatableFunction, isNaN(delay) ? task.delay : delay);
   };
   return repeatableFunction;

package/src/audit.d.ts

@@ -7,9 +7,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns An audited version of the function.
  */
-export declare function audit<T extends (...args: any[]) => void>(
-  fn: T,
+export declare function audit<A extends unknown[]>(
+  fn: (...args: A) => void,
   ms: number
-): (...args: Parameters<T>) => void;
+): (...args: A) => void;
 
 export default audit;

package/src/debounce.d.ts

@@ -6,9 +6,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns A debounced version of the function.
  */
-export declare function debounce<T extends (...args: any[]) => void>(
-  fn: T,
+export declare function debounce<A extends unknown[]>(
+  fn: (...args: A) => void,
   ms: number
-): (...args: Parameters<T>) => void;
+): (...args: A) => void;
 
 export default debounce;

package/src/defer.d.ts

@@ -8,6 +8,22 @@
  * @param fn The function to delay.
  * @returns A function that, when called, will execute the provided function.
  */
-export declare function defer(fn: () => void): () => void;
+export declare function defer<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+
+/**
+ * Schedules a function to be called when the next available time.
+ *
+ * @param fn The function to schedule.
+ * @returns A promise that resolves when the function is called.
+ */
+export declare function scheduleDefer<R extends unknown>(fn: () => R): Promise<Awaited<R>>;
+
+/**
+ * Schedules a function to be called when the next available time.
+ *
+ * @param fn The function to schedule.
+ * @returns A promise that resolves when the function is called.
+ */
+export declare function scheduleDefer(fn: null | undefined): Promise<void>;
 
 export default defer;

package/src/defer.js

@@ -12,4 +12,19 @@ if (typeof requestIdleCallback == 'function') {
 
 export const defer = fn => void deferImplementation(() => fn());
 
+const returnArgs = (...args) => args;
+
+export const scheduleDefer = fn => {
+  fn ||= returnArgs;
+  return new Promise((resolve, reject) => {
+    defer(() => {
+      try {
+        resolve(fn());
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+};
+
 export default defer;

package/src/index.d.ts

@@ -6,6 +6,7 @@ declare module 'time-queues' {
   export * from './sleep';
   export * from './throttle';
 
+  export * from './CancelTaskError';
   export * from './MicroTask';
   export * from './MicroTaskQueue';
   export * from './ListQueue';

package/src/sample.d.ts

@@ -9,9 +9,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns A sampled version of the function.
  */
-export declare function sample<T extends (...args: any[]) => void>(
-  fn: T,
+export declare function sample<A extends unknown[]>(
+  fn: (...args: A) => void,
   ms: number
-): (...args: Parameters<T>) => void;
+): (...args: A) => void;
 
 export default sample;

package/src/throttle.d.ts

@@ -7,9 +7,9 @@
  * @param ms The minimum time interval between function calls, in milliseconds.
  * @returns A throttled version of the function.
  */
-export declare function throttle<T extends (...args: any[]) => void>(
-  fn: T,
+export declare function throttle<A extends unknown[]>(
+  fn: (...args: A) => void,
   ms: number
-): (...args: Parameters<T>) => void;
+): (...args: A) => void;
 
 export default throttle;

package/src/when-dom-loaded.d.ts

@@ -14,4 +14,24 @@ export declare function whenDomLoaded(fn: () => void): void;
  */
 export declare function remove(fn: () => void): boolean;
 
+/**
+ * Schedules a function to be called when the DOM is loaded.
+ *
+ * @param fn The function to schedule.
+ * @returns A promise that resolves when the DOM is loaded.
+ */
+export declare function scheduleWhenDomLoaded<R extends unknown>(
+  fn: () => R
+): Promise<Awaited<R>>;
+
+/**
+ * Schedules a function to be called when the DOM is loaded.
+ *
+ * @param fn The function to schedule.
+ * @returns A promise that resolves when the DOM is loaded.
+ */
+export declare function scheduleWhenDomLoaded(
+  fn: null | undefined
+): Promise<void>;
+
 export default whenDomLoaded;

package/src/when-dom-loaded.js

@@ -34,4 +34,19 @@ export const whenDomLoaded = fn => {
   if (wasEmpty) document.addEventListener('DOMContentLoaded', handleDomLoaded);
 };
 
+const returnArgs = (...args) => args;
+
+export const scheduleWhenDomLoaded = fn => {
+  fn ||= returnArgs;
+  return new Promise((resolve, reject) => {
+    whenDomLoaded(() => {
+      try {
+        resolve(fn());
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+};
+
 export default whenDomLoaded;

package/src/when-loaded.d.ts

@@ -14,4 +14,24 @@ export declare function whenLoaded(fn: () => void): void;
  */
 export declare function remove(fn: () => void): boolean;
 
+/**
+ * Schedules a function to be called when the document is loaded.
+ *
+ * @param fn The function to schedule.
+ * @returns A promise that resolves when the document is loaded.
+ */
+export declare function scheduleWhenLoaded<R extends unknown>(
+  fn: () => R
+): Promise<Awaited<R>>;
+
+/**
+ * Schedules a function to be called when the document is loaded.
+ *
+ * @param fn The function to schedule.
+ * @returns A promise that resolves when the document is loaded.
+ */
+export declare function scheduleWhenLoaded(
+  fn: null | undefined
+): Promise<void>;
+
 export default whenLoaded;

package/src/when-loaded.js

@@ -32,4 +32,19 @@ export const whenLoaded = fn => {
   if (wasEmpty) window.addEventListener('load', handleLoaded);
 };
 
+const returnArgs = (...args) => args;
+
+export const scheduleWhenLoaded = fn => {
+  fn ||= returnArgs;
+  return new Promise((resolve, reject) => {
+    whenLoaded(() => {
+      try {
+        resolve(fn());
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+};
+
 export default whenLoaded;