time-queues 1.2.1 → 1.2.3

package/README.md

@@ -3,7 +3,6 @@
 [npm-img]: https://img.shields.io/npm/v/time-queues.svg
 [npm-url]: https://npmjs.org/package/time-queues
 
-
 `time-queues` is an efficient, lightweight library for organizing asynchronous multitasking and scheduled tasks in JavaScript applications. It works seamlessly in browsers and server-side environments like Node.js, Deno, and Bun.
 
 The library provides elegant solutions for common timing and scheduling challenges, helping developers create responsive, efficient applications that follow best practices for resource management and user experience.
@@ -62,14 +61,16 @@ This project is licensed under the BSD-3-Clause License.
 
 ## Release History
 
-* 1.2.1 *Minor release: updated formal TS dependencies in `index.d.ts`.*
-* 1.2.0 *Added `Counter`. Updated dev dependencies.*
-* 1.1.2 *Updated dev dependencies. No need to upgrade.*
-* 1.1.1 *Updates to TS typings.*
-* 1.1.0 *Added `Throttler`, `Retainer`, promise-based convenience time methods.*
-* 1.0.5 *Technical release: updated deps, more tests.*
-* 1.0.4 *Bug fixes and code simplifications.*
-* 1.0.3 *Updated deps (`list-toolkit`) to fix a minor bug.*
-* 1.0.2 *Updated deps (`list-toolkit`).*
-* 1.0.1 *Minor update in README. No need to upgrade.*
-* 1.0.0 *Initial release.*
+- 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._
+- 1.1.2 _Updated dev dependencies. No need to upgrade._
+- 1.1.1 _Updates to TS typings._
+- 1.1.0 _Added `Throttler`, `Retainer`, promise-based convenience time methods._
+- 1.0.5 _Technical release: updated deps, more tests._
+- 1.0.4 _Bug fixes and code simplifications._
+- 1.0.3 _Updated deps (`list-toolkit`) to fix a minor bug._
+- 1.0.2 _Updated deps (`list-toolkit`)._
+- 1.0.1 _Minor update in README. No need to upgrade._
+- 1.0.0 _Initial release._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "time-queues",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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.4",
+    "tape-six-proc": "^1.1.5",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "list-toolkit": "^2.2.1"
+    "list-toolkit": "^2.2.4"
   }
 }

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/Counter.js

@@ -45,25 +45,28 @@ export class Counter {
 
   clearWaiters() {
     if (this.zeroWaiters.length > 0) {
-      for (const resolve of this.zeroWaiters) {
+      const zeroWaiters = this.zeroWaiters;
+      this.zeroWaiters = [];
+      for (const resolve of zeroWaiters) {
         resolve(NaN);
       }
-      this.zeroWaiters = [];
     }
     if (this.functionWaiters.size > 0) {
-      for (const {resolve} of this.functionWaiters) {
+      const functionWaiters = this.functionWaiters;
+      this.functionWaiters = new Set();
+      for (const {resolve} of functionWaiters) {
         resolve(NaN);
       }
-      this.functionWaiters.clear();
     }
   }
 
   notify() {
     if (this.count === 0 && this.zeroWaiters.length > 0) {
-      for (const resolve of this.zeroWaiters) {
+      const zeroWaiters = this.zeroWaiters;
+      this.zeroWaiters = [];
+      for (const resolve of zeroWaiters) {
         resolve(0);
       }
-      this.zeroWaiters = [];
     }
     if (this.functionWaiters.size > 0) {
       const ready = [];

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;