time-queues 1.2.3 → 1.3.0

package/README.md

@@ -29,16 +29,21 @@ cd time-queues
 npm install
 ```
 
-## Usage
+## Documentation
 
-The full documentation is available in the project's [wiki](https://github.com/uhop/time-queues/wiki). Below is a summary of the most important parts of the documentation:
+The [project wiki](https://github.com/uhop/time-queues/wiki) provides comprehensive information about the `time-queues` library.
 
-### Resource Management
+### Core Task Queue Classes
 
-- [Scheduler](https://github.com/uhop/time-queues/wiki/Scheduler): Time-based task scheduling
-- [Retainer](https://github.com/uhop/time-queues/wiki/Retainer): Manage resource lifecycle
+- [MicroTask](https://github.com/uhop/time-queues/wiki/MicroTask): Base class for deferred execution
+- [MicroTaskQueue](https://github.com/uhop/time-queues/wiki/MicroTaskQueue): Base class for task queues
+- [ListQueue](https://github.com/uhop/time-queues/wiki/ListQueue): List-based queue implementation
+
+### Concurrency Control
+
+- [LimitedQueue](https://github.com/uhop/time-queues/wiki/LimitedQueue): Queue with controlled concurrency
 - [Throttler](https://github.com/uhop/time-queues/wiki/Throttler): Control execution rate based on keys
-- [Counter](https://github.com/uhop/time-queues/wiki/Counter): Track the number of pending tasks asynchronously
+- [Counter](https://github.com/uhop/time-queues/wiki/Counter): Track pending task counts
 
 ### Browser-Specific Components
 
@@ -46,6 +51,11 @@ The full documentation is available in the project's [wiki](https://github.com/u
 - [FrameQueue](https://github.com/uhop/time-queues/wiki/FrameQueue): Execute tasks during animation frames
 - [PageWatcher](https://github.com/uhop/time-queues/wiki/PageWatcher): Monitor and respond to page lifecycle changes
 
+### Scheduling & Timing
+
+- [Scheduler](https://github.com/uhop/time-queues/wiki/Scheduler): Time-based task scheduling
+- [Retainer](https://github.com/uhop/time-queues/wiki/Retainer): Resource lifecycle management
+
 ### Utility Functions
 
 - [defer()](<https://github.com/uhop/time-queues/wiki/defer()>): Execute tasks in the next tick
@@ -54,6 +64,65 @@ The full documentation is available in the project's [wiki](https://github.com/u
 - [debounce()](<https://github.com/uhop/time-queues/wiki/debounce()>): Delay function execution until input stabilizes
 - [sample()](<https://github.com/uhop/time-queues/wiki/sample()>): Execute function at regular intervals
 - [audit()](<https://github.com/uhop/time-queues/wiki/audit()>): Execute function after specified delay
+- [batch()](<https://github.com/uhop/time-queues/wiki/batch()>): Execute async operations with controlled concurrency
+
+### Random Distribution Utilities
+
+- [random-dist](https://github.com/uhop/time-queues/wiki/random-dist): Generate random numbers from various probability distributions
+- [random-sleep](https://github.com/uhop/time-queues/wiki/random-sleep): Create randomized delays with various probability distributions
+
+## Getting Started
+
+To get started with `time-queues`, install it via npm:
+
+```sh
+npm install time-queues
+```
+
+Then import the components you need in your project:
+
+```js
+// Import specific components
+import {Scheduler, repeat} from 'time-queues/Scheduler.js';
+import idleQueue from 'time-queues/IdleQueue.js';
+import defer from 'time-queues/defer.js';
+
+// Use the components in your application
+```
+
+For more information, see the documentation for each component in the wiki.
+
+## Browser-related notes
+
+Internally it uses `list-toolkit` and leverages the following browser APIs:
+
+- [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback)
+- [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
+- [queueMicrotask()](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)
+- [setTimeout()](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout)
+- Various events and properties.
+
+There are many articles on the subject that detail how to leverage the APIs writing efficient applications.
+Some of them are:
+
+- [Background Tasks API](https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API)
+- [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
+- [Page Lifecycle API](https://developer.chrome.com/docs/web-platform/page-lifecycle-api)
+
+This package eliminates the need to write code that you'll write anyway following best practices.
+
+### Running a test web application
+
+Don't forget to look at a test web application that uses the library. For that you should start a server:
+
+```sh
+npm start
+```
+
+And navigate to [http://localhost:3000/tests/web/](http://localhost:3000/tests/web/) &mdash;
+don't forget to open the console and play around: switch tabs, make other window active,
+navigate away and come back, and so on.
+See how queues work in [tests/web/test.js](https://github.com/uhop/time-queues/blob/main/tests/web/test.js).
 
 ## License
 
@@ -61,6 +130,8 @@ This project is licensed under the BSD-3-Clause License.
 
 ## Release History
 
+- 1.3.0 _Added `batch()` and `LimitedQueue` to run asynchronous operations with controlled concurrency, random distribuitions and random sleep functions, updated dependencies, minor improvements._
+- 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`._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "time-queues",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Time queues to organize multitasking and scheduled tasks.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -12,8 +12,11 @@
     "test:bun": "tape6-bun --flags FO",
     "test:deno": "tape6-deno --flags FO",
     "test:proc": "tape6-proc --flags FO",
-    "test:proc:bun": "bun run `npx tape6-proc --self` --flags FO",
-    "test:proc:deno": "deno run -A `npx tape6-proc --self` --flags FO --runFileArgs -A",
+    "test:proc:bun": "bun run `tape6-proc --self` --flags FO",
+    "test:proc:deno": "deno run -A `tape6-proc --self` --flags FO -r -A",
+    "test:seq": "tape6-seq --flags FO",
+    "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
+    "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO",
     "ts-check": "tsc --noEmit",
     "ts-test": "tape6 --flags FO '/ts-tests/test-*.*ts'",
     "ts-test:bun": "tape6-bun --flags FO '/ts-tests/test-*.*ts'",
@@ -56,12 +59,12 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.0.10",
-    "tape-six": "^1.4.4",
-    "tape-six-proc": "^1.1.5",
+    "@types/node": "^25.2.3",
+    "tape-six": "^1.7.0",
+    "tape-six-proc": "^1.2.2",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "list-toolkit": "^2.2.4"
+    "list-toolkit": "^2.2.6"
   }
 }

package/src/CancelTaskError.d.ts

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

package/src/CancelTaskError.js

@@ -3,8 +3,8 @@
 'use strict';
 
 export class CancelTaskError extends Error {
-  constructor() {
-    super('Task was canceled');
+  constructor(message = 'Task was canceled', options) {
+    super(message, options);
     this.name = 'CancelTaskError';
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, CancelTaskError);

package/src/Counter.d.ts

@@ -15,7 +15,6 @@ export declare class Counter {
 
   /**
    * Gets the current value of the counter.
-   * @returns The current value of the counter.
    */
   get value(): number;
 

package/src/LimitedQueue.d.ts

@@ -0,0 +1,104 @@
+import {ListQueue, Task} from './ListQueue';
+
+export {Task};
+
+export declare class LimitedQueue extends ListQueue {
+  /**
+   * Whether the queue is paused.
+   */
+  paused: boolean;
+
+  /**
+   * The function that stops the queue.
+   * It is used internally by `pause()` and `resume()`.
+   */
+  stopQueue: (() => void) | null;
+
+  /**
+   * Creates a new list queue.
+   * @param limit The maximum number of tasks that can be run in parallel.
+   * @param paused Whether the queue should start paused.
+   */
+  constructor(limit: number, paused?: boolean);
+
+  /**
+   * Whether the queue is empty.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Get the maximum number of tasks that can be run in parallel.
+   */
+  get taskLimit(): number;
+
+  /**
+   * 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.
+   */
+  set taskLimit(limit: number);
+
+  /**
+   * Get the number of currently active tasks.
+   */
+  get activeTasks(): number;
+
+  /**
+   * Whether the queue is idle.
+   */
+  get isIdle(): boolean;
+
+  /**
+   * Wait for 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>;
+
+  /**
+   * Enqueues a microtask.
+   * @param fn The function to execute when the microtask is scheduled.
+   * @returns The enqueued microtask.
+   */
+  enqueue(fn: () => unknown): Task;
+
+  /**
+   * Dequeues a microtask.
+   * @param task The microtask to dequeue.
+   * @returns The queue.
+   */
+  dequeue(task: Task): 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): Task;
+
+  /**
+   * Clears the queue.
+   * @returns The queue.
+   */
+  clear(): this;
+
+  /**
+   * Pauses the queue.
+   * @returns The queue.
+   */
+  pause(): this;
+
+  /**
+   * Resumes the queue.
+   * @returns The queue.
+   */
+  resume(): this;
+
+  /**
+   * Starts the queue.
+   * It is used internally by `resume()`.
+   * It is meant to be overridden in subclasses.
+   * @returns The function that stops the queue.
+   */
+  startQueue(): (() => void) | null;
+}
+
+export default LimitedQueue;

package/src/LimitedQueue.js

@@ -0,0 +1,78 @@
+// @ts-self-types="./LimitedQueue.d.ts"
+
+import ListQueue from './ListQueue.js';
+
+export class LimitedQueue extends ListQueue {
+  #taskLimit;
+  #activeTasks;
+  #idleWaiters;
+
+  constructor(limit, paused) {
+    super(paused);
+    this.#taskLimit = limit;
+    this.#activeTasks = 0;
+    this.#idleWaiters = [];
+  }
+
+  get taskLimit() {
+    return this.#taskLimit;
+  }
+
+  set taskLimit(limit) {
+    this.#taskLimit = Math.max(1, limit);
+    this.#processTasks();
+  }
+
+  get activeTasks() {
+    return this.#activeTasks;
+  }
+
+  get isIdle() {
+    return !this.#activeTasks && this.list.isEmpty;
+  }
+
+  waitForIdle() {
+    return new Promise(resolve => {
+      if (this.isIdle) {
+        resolve();
+      } else {
+        this.#idleWaiters.push(resolve);
+      }
+    });
+  }
+
+  startQueue() {
+    this.#processTasks();
+    return null;
+  }
+
+  #processTasks() {
+    if (this.paused) return;
+    if (this.isIdle) {
+      const waiters = this.#idleWaiters;
+      this.#idleWaiters = [];
+      waiters.forEach(resolve => resolve());
+      return;
+    }
+    while (this.#activeTasks < this.#taskLimit && !this.list.isEmpty) {
+      const task = this.list.popFront();
+      ++this.#activeTasks;
+      LimitedQueue.wrap(() => task.fn({task, queue: this})).finally(() => {
+        --this.#activeTasks;
+        this.#processTasks();
+      });
+    }
+  }
+
+  static wrap(fn) {
+    return new Promise((resolve, reject) => {
+      try {
+        resolve(fn());
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+}
+
+export default LimitedQueue;

package/src/ListQueue.d.ts

@@ -82,9 +82,4 @@ 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/MicroTask.d.ts

@@ -42,9 +42,10 @@ export declare class MicroTask {
    * 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.
+   * @param error The optional error to use as the cause of the cancellation.
    * @returns The microtask.
    */
-  cancel(): this;
+  cancel(error?: Error): this;
 }
 
 export default MicroTask;

package/src/MicroTask.js

@@ -1,13 +1,12 @@
 // @ts-self-types="./MicroTask.d.ts"
 
-'use strict';
-
 import CancelTaskError from './CancelTaskError.js';
 
 export class MicroTask {
   #promise;
   #resolve;
   #reject;
+  #settled;
   constructor(fn) {
     this.fn = fn;
     this.#promise = null;
@@ -18,26 +17,42 @@ export class MicroTask {
   get promise() {
     return this.#promise;
   }
+  get settled() {
+    return this.#settled;
+  }
   makePromise() {
-    this.#promise = new Promise((resolve, reject) => {
-      this.#resolve = resolve;
-      this.#reject = reject;
-    });
+    if (this.#promise) return this;
+    if (typeof Promise.withResolvers == 'function') {
+      ({
+        promise: this.#promise,
+        resolve: this.#resolve,
+        reject: this.#reject
+      } = Promise.withResolvers());
+    } else {
+      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;
+    if (this.#resolve) {
+      this.#resolve(value);
+      this.#resolve = null;
+      this.#reject = null;
+      this.#settled = true;
+    }
     return this;
   }
-  cancel() {
-    if (!this.#reject) return;
+  cancel(error) {
     this.isCanceled = true;
-    this.#reject(new CancelTaskError());
-    this.#resolve = null;
-    this.#reject = null;
+    if (this.#reject) {
+      this.#reject(new CancelTaskError(undefined, error ? {cause: error} : undefined));
+      this.#resolve = null;
+      this.#reject = null;
+      this.#settled = true;
+    }
     return this;
   }
 }

package/src/MicroTaskQueue.d.ts

@@ -2,68 +2,72 @@ import MicroTask from './MicroTask';
 
 /**
  * A queue of microtasks that will be executed when scheduled.
- * It is a base class for other task queues.
+ * It serves as a base class for other task queues.
  */
 export declare class MicroTaskQueue {
   /**
-   * Whether the queue is paused.
+   * Whether the queue is currently paused.
+   * When paused, new tasks are queued but not executed immediately.
    */
   paused: boolean;
 
   /**
    * Creates a new microtask queue.
-   * @param paused Whether the queue should start paused.
+   * @param paused Whether the queue should start in a paused state.
    */
   constructor(paused?: boolean);
 
   /**
    * Whether the queue is empty.
-   * It is meant to be overridden in subclasses.
+   * This property should be overridden in subclasses to provide actual implementation.
    */
   get isEmpty(): boolean;
 
   /**
-   * Enqueues a microtask.
-   * It is meant to be overridden in subclasses.
+   * Enqueues a microtask for execution.
+   * This method should be overridden in subclasses to provide actual implementation.
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
   enqueue(fn: () => unknown): MicroTask;
 
   /**
-   * Dequeues a microtask.
-   * It is meant to be overridden in subclasses.
+   * Dequeues a microtask from the queue.
+   * This method should be overridden in subclasses to provide actual implementation.
    * @param task The microtask to dequeue.
-   * @returns The queue.
+   * @returns The queue instance for chaining.
    */
   dequeue(task: MicroTask): this;
 
   /**
-   * Schedules a microtask with a promise.
-   * It can be overridden in subclasses, if more arguments are needed.
+   * 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.
    * @returns The scheduled microtask.
    */
-  schedule(fn: (() => unknown) | null | undefined): MicroTask;
+  schedule(fn: (() => unknown) | null | undefined, ...args: unknown[]): MicroTask;
 
   /**
-   * Clears the queue.
-   * It is meant to be overridden in subclasses.
-   * @returns The queue.
+   * Clears all tasks from the queue.
+   * This method should be overridden in subclasses to provide actual implementation.
+   * @returns The queue instance for chaining.
    */
   clear(): this;
 
   /**
    * Pauses the queue.
-   * It is meant to be overridden in subclasses.
-   * @returns The queue.
+   * When paused, new tasks are queued but not executed immediately.
+   * This method should be overridden in subclasses to provide actual implementation.
+   * @returns The queue instance for chaining.
    */
   pause(): this;
 
   /**
    * Resumes the queue.
-   * It is meant to be overridden in subclasses.
-   * @returns The queue.
+   * When resumed, queued tasks will be executed according to their scheduling.
+   * This method should be overridden in subclasses to provide actual implementation.
+   * @returns The queue instance for chaining.
    */
   resume(): this;
 }

package/src/MicroTaskQueue.js

@@ -35,17 +35,18 @@ export class MicroTaskQueue {
   schedule(fn, ...args) {
     fn ||= MicroTaskQueue.returnArgs;
     const task = this.enqueue(
-      (...args) => {
+      function (...args) {
+        this.makePromise();
         try {
-          task.resolve(fn(...args));
+          this.resolve(fn(...args));
         } catch (error) {
-          task.cancel();
+          this.cancel(error);
         }
+        return this.promise;
       },
       ...args
     );
     task.makePromise();
-    task.fn = fn;
     return task;
   }
   static returnArgs(...args) {

package/src/Scheduler.d.ts

@@ -55,7 +55,6 @@ export declare class Task extends MicroTask {
   /**
    * 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;
@@ -67,43 +66,47 @@ export declare class Task extends MicroTask {
 export declare class Scheduler extends MicroTaskQueue {
   /**
    * Whether the scheduler is paused.
+   * When paused, new tasks are queued but not executed immediately.
    */
   paused: boolean;
 
   /**
    * The tolerance for comparing starting time of tasks.
+   * This allows for small timing differences in task execution.
    */
   tolerance: number;
 
   /**
    * Creates a new scheduler.
-   * @param paused Whether the scheduler should start paused.
-   * @param tolerance The tolerance for comparing starting time of tasks.
+   * @param paused Whether the scheduler should start in a paused state.
+   * @param tolerance The tolerance for comparing starting time of tasks (default is 4ms).
    */
-  constructor(paused?: boolean, tolerance: number = 4);
+  constructor(paused?: boolean, tolerance?: number);
 
   /**
    * Whether the scheduler is empty.
+   * Returns true if there are no tasks scheduled for execution.
    */
   get isEmpty(): boolean;
 
   /**
    * The next scheduled time or `Infinity` if the scheduler is empty.
+   * Represents the time when the next task is scheduled to execute.
    */
   get nextTime(): number;
 
   /**
-   * Enqueues a task.
+   * Enqueues a task for future execution.
    * @param fn The function to execute.
    * @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.
+   * @returns The task object that was enqueued.
    */
   enqueue(fn: ({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.
+   * @returns The scheduler object for chaining.
    */
   dequeue(task: Task): this;
 
@@ -111,7 +114,7 @@ export declare class Scheduler extends MicroTaskQueue {
    * 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 The task object.
+   * @returns The task object that was scheduled.
    */
   schedule(
     fn: (({task: Task, scheduler: Scheduler}) => unknown) | null | undefined,
@@ -119,20 +122,22 @@ export declare class Scheduler extends MicroTaskQueue {
   ): Task;
 
   /**
-   * Clears the queue.
-   * @returns The queue.
+   * Clears all tasks from the scheduler.
+   * @returns The scheduler instance for chaining.
    */
   clear(): this;
 
   /**
-   * Pauses the queue.
-   * @returns The queue.
+   * Pauses the scheduler.
+   * When paused, new tasks are queued but not executed immediately.
+   * @returns The scheduler instance for chaining.
    */
   pause(): this;
 
   /**
-   * Resumes the queue.
-   * @returns The queue.
+   * Resumes the scheduler.
+   * When resumed, queued tasks will be executed according to their scheduling.
+   * @returns The scheduler instance for chaining.
    */
   resume(): this;
 }

package/src/batch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runs asynchronous operations in parallel, no more than a specified number at a time.
+ * It takes an array of functions, which return promises when invoked without arguments.
+ * All other non-function values are passed as-is and promises are resolved.
+ * Modelled after Promise.all().
+ *
+ * @param fns An array of parameterless functions (asynchronous or not), promises, or values
+ * @param limit How many asynchronous operations to run in parallel (default is 4)
+ * @returns A promise that resolves when all functions have completed to an array of results
+ */
+export declare function batch(
+  fns: ((() => PromiseLike<unknown>) | PromiseLike<unknown> | unknown)[],
+  limit?: number
+): Promise<unknown[]>;
+
+export default batch;

package/src/batch.js

@@ -0,0 +1,41 @@
+// @ts-self-types="./batch.d.ts"
+
+'use strict';
+
+const wrap = value => {
+  if (typeof value == 'function') return Promise.resolve(value());
+  if (value && typeof value.then == 'function') return value; // thenable
+  return Promise.resolve(value);
+};
+
+export const batch = (fns, limit = 4) => {
+  if (limit < 1) limit = 1;
+
+  const result = [];
+  let next = limit,
+    available = limit;
+
+  const saveResult = (index, resolve, reject) => value => {
+    result[index] = value;
+    if (next < fns.length) {
+      wrap(fns[next]).then(saveResult(next, resolve, reject), reject);
+      ++next;
+    } else {
+      ++available;
+      if (available === limit) {
+        // we are done
+        resolve(result);
+      }
+    }
+  };
+
+  return new Promise((resolve, reject) => {
+    // start the pump
+    for (let i = 0, n = Math.min(fns.length, limit); i < n; ++i) {
+      wrap(fns[i]).then(saveResult(i, resolve, reject), reject);
+      --available;
+    }
+  });
+};
+
+export default batch;

package/src/random-dist.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generate a random number from a uniform distribution.
+ * @param min The minimum value of the distribution.
+ * @param max The maximum value of the distribution.
+ * @returns A random number from the uniform distribution.
+ */
+export declare function uniform(min: number, max: number): number;
+
+/**
+ * Generate a random number from a normal distribution.
+ * @param mean The mean of the distribution.
+ * @param stdDev The standard deviation of the distribution.
+ * @param skewness The skewness of the distribution.
+ * @returns A random number from the normal distribution.
+ */
+export declare function normal(mean: number, stdDev: number, skewness: number = 0): number;
+
+/**
+ * Generate a random number from an exponential distribution.
+ * @param lambda The rate parameter of the distribution.
+ * @returns A random number from the exponential distribution.
+ */
+export declare function expo(lambda: number): number;
+
+/**
+ * Generate a random number from a Pareto distribution.
+ * @param min The minimum value of the distribution.
+ * @param alpha The shape parameter of the distribution.
+ * @returns A random number from the Pareto distribution.
+ */
+export declare function pareto(min: number, alpha: number): number;

package/src/random-dist.js

@@ -0,0 +1,27 @@
+// @ts-self-types="./random-dist.d.ts"
+
+export const uniform = (min, max) => {
+  const range = Math.abs(max - min);
+  return Math.random() * range + Math.min(min, max);
+};
+
+export const normal = (mean, stdDev, skewness = 0) => {
+  let u = 0,
+    v = 0;
+  while (!u) u = Math.random(); // Converting [0,1) to (0,1)
+  while (!v) v = Math.random();
+  let z = Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+  if (!skewness) return z * stdDev + mean;
+  const delta = skewness / Math.sqrt(1 + skewness * skewness),
+    x = delta * z + Math.sqrt(1 - delta * delta) * v;
+  z = z >= 0 ? x : -x;
+  return z * stdDev + mean;
+};
+
+export const expo = lambda => {
+  return -Math.log(1 - Math.random()) / lambda;
+};
+
+export const pareto = (min, alpha) => {
+  return min / Math.pow(1 - Math.random(), 1 / alpha);
+};

package/src/random-sleep.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Random sleep function modelled after `sleep()`.
+ */
+export type RandomSleepFunction = () => Promise<void>;
+
+/**
+ * Creates a random sleep function that uses a uniform distribution.
+ * @param min The minimum delay in milliseconds.
+ * @param max The maximum delay in milliseconds.
+ * @returns A sleep function.
+ */
+export declare function randomUniformSleep(min: number, max: number): RandomSleepFunction;
+
+/**
+ * Creates a random sleep function that uses a normal distribution.
+ * @param mean The mean delay in milliseconds.
+ * @param stdDev The standard deviation of the delay in milliseconds.
+ * @param skewness The skewness of the delay distribution.
+ * @returns A sleep function.
+ */
+export declare function randomNormalSleep(
+  mean: number,
+  stdDev: number,
+  skewness: number = 0
+): RandomSleepFunction;
+
+/**
+ * Creates a random sleep function that uses an exponential distribution.
+ * @param rate The rate parameter of the exponential distribution (how many times per `range` an event occurs).
+ * @param range The range of the exponential distribution.
+ * @param base The base of the exponential distribution.
+ * @returns A sleep function.
+ */
+export declare function randomExpoSleep(
+  rate: number,
+  range: number,
+  base: number = 0
+): RandomSleepFunction;
+
+/**
+ * Creates a random sleep function that uses a Pareto distribution.
+ * @param min The minimum delay in milliseconds.
+ * @param ratio The ratio of the Pareto distribution, e.g., 0.8 for the 80/20 Pareto rule. Should be a value between 0.5 and 1.
+ * @returns A sleep function.
+ * @throws Error if the ratio is not between 0.5 and 1.
+ */
+export declare function randomParetoSleep(min: number, ratio: number = 0.8): RandomSleepFunction;
+
+/**
+ * A simple sleep function that uses a uniform distribution.
+ * @param max The maximum delay in milliseconds.
+ * @param min The minimum delay in milliseconds.
+ * @returns A promise that resolves after the delay.
+ */
+export declare function randomSleep(max: number, min: number = 0): Promise<void>;
+
+export default randomSleep;

package/src/random-sleep.js

@@ -0,0 +1,27 @@
+// @ts-self-types="./random-sleep.d.ts"
+
+import sleep from './sleep.js';
+import {uniform, normal, expo, pareto} from './random-dist.js';
+
+export const randomUniformSleep = (min, max) => () => sleep(uniform(min, max));
+
+export const randomNormalSleep =
+  (mean, stdDev, skewness = 0) =>
+  () =>
+    sleep(normal(mean, stdDev, skewness));
+
+export const randomExpoSleep =
+  (rate, range, base = 0) =>
+  () =>
+    sleep(range * expo(rate) + base);
+
+export const randomParetoSleep = (min, ratio = 0.8) => {
+  if (ratio <= 0.5 || ratio >= 1 || isNaN(ratio))
+    throw new Error('ratio must be greater than 0.5 and less than 1');
+  const alpha = 1 / (1 - Math.log(ratio) / Math.log(1 - ratio));
+  return () => sleep(pareto(min, alpha));
+};
+
+export const randomSleep = (max, min = 0) => sleep(uniform(min, max));
+
+export default randomSleep;

package/src/sleep.d.ts

@@ -1,7 +1,7 @@
 /**
  * Suspends the execution for a specified time.
  *
- * @param ms The time to suspend the execution for, in milliseconds or a date as an absolute time.
+ * @param ms The time to suspend the execution for, in milliseconds or a Date as an absolute time.
  * @returns A promise that resolves after the specified time.
  */
 export declare function sleep(ms: number | Date): Promise<void>;

package/src/throttle.d.ts

@@ -1,6 +1,7 @@
 /**
  * Throttles a function by ensuring it is not called more often than the specified interval.
- * The first call calls the function and starts a timeout. Until the timeout expires, any subsequent calls are ignored.
+ * The first call calls the function and starts a timeout. Until the timeout expires,
+ * any subsequent calls are ignored.
  * This function is similar to `audit()`, but the first seen arguments are passed to the function.
  *
  * @param fn The function to throttle.

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

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

package/src/when-dom-loaded.js

@@ -34,19 +34,15 @@ 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) => {
+export const scheduleWhenDomLoaded = fn =>
+  new Promise((resolve, reject) => {
     whenDomLoaded(() => {
       try {
-        resolve(fn());
+        resolve(fn?.());
       } catch (error) {
         reject(error);
       }
     });
   });
-};
 
 export default whenDomLoaded;

package/src/when-loaded.d.ts

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

package/src/when-loaded.js

@@ -32,19 +32,15 @@ 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) => {
+export const scheduleWhenLoaded = fn =>
+  new Promise((resolve, reject) => {
     whenLoaded(() => {
       try {
-        resolve(fn());
+        resolve(fn?.());
       } catch (error) {
         reject(error);
       }
     });
   });
-};
 
 export default whenLoaded;