time-queues 1.2.4 → 1.3.1

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.
-   * @param fn The function to execute when the microtask is scheduled, it can be an async function.
+   * 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()`. They are 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

@@ -1,14 +1,19 @@
 // @ts-self-types="./MicroTaskQueue.d.ts"
 
-'use strict';
-
 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
+ */
 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
   get isEmpty() {
     return true;
   }
@@ -20,6 +25,11 @@ 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) {
     const task = new MicroTask(fn);
     return task;
@@ -31,21 +41,26 @@ export class MicroTaskQueue {
   clear() {
     return this;
   }
-  // Generic API
+  /**
+   * 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;
     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/PageWatcher.d.ts

@@ -33,7 +33,7 @@ export declare class PageWatcher extends ListQueue {
   /**
    * Enqueues a task.
    * @param fn The function to execute.
-   * @param initialize Whether the function should be executed before the state changes.
+   * @param initialize Whether the function should be called immediately with the current state.
    * @returns The task object.
    */
   enqueue(
@@ -90,4 +90,4 @@ export declare const watchStates: (
  */
 export declare const pageWatcher: PageWatcher;
 
-export default PageWatcher;
+export default pageWatcher;

package/src/PageWatcher.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./PageWatcher.d.ts"
 
-'use strict';
-
 import ListQueue from './ListQueue.js';
 
 // Based on information from https://developer.chrome.com/docs/web-platform/page-lifecycle-api

package/src/Retainer.d.ts

@@ -13,7 +13,7 @@ export declare interface RetainerOptions<T = unknown> {
   /**
    * The retention period in milliseconds.
    */
-  retentionPeriod: number;
+  retentionPeriod?: number;
 }
 
 /**
@@ -55,14 +55,14 @@ export declare class Retainer<T = unknown> implements RetainerOptions<T> {
    * Retrieves the retained value.
    * @returns The retained value as a promise.
    */
-  async get(): Promise<T>;
+  get(): Promise<T>;
 
   /**
    * Releases the retained value.
-   * @param immediately Whether to release the value immediately. Otherwise it'll be retained for the retention period.
+   * @param immediately Whether to release the value immediately. Otherwise, it will be retained for the retention period.
    * @returns The retainer object.
    */
-  async release(immediately?: boolean): Promise<this>;
+  release(immediately?: boolean): Promise<this>;
 }
 
 export default Retainer;

package/src/Retainer.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./Retainer.d.ts"
 
-'use strict';
-
 export class Retainer {
   constructor({create, destroy, retentionPeriod = 1_000}) {
     if (!create || !destroy) throw new Error('Retainer: create and destroy are required');

package/src/Scheduler.d.ts

@@ -55,10 +55,10 @@ 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.
+   * @param error The optional error to use as the cause of the cancellation.
    * @returns The microtask.
    */
-  cancel(): this;
+  cancel(error?: Error): this;
 }
 
 /**
@@ -67,51 +67,55 @@ 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.
+   * The tolerance for comparing starting times 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 times 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;
 
   /**
    * 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 fn The function to execute. If `undefined` or `null`, the task's promise will be resolved with the 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 +123,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/Scheduler.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./Scheduler.d.ts"
 
-'use strict';
-
 import MinHeap from 'list-toolkit/heap.js';
 import MicroTask from './MicroTask.js';
 import MicroTaskQueue from './MicroTaskQueue.js';
@@ -90,6 +88,7 @@ export class Scheduler extends MicroTaskQueue {
     this.queue.array.forEach(task => task.cancel());
     this.queue.clear();
     if (!paused) this.resume();
+    return this;
   }
 
   startQueue() {

package/src/Throttler.d.ts

@@ -71,6 +71,11 @@ export declare class Throttler implements ThrottlerOptions {
    */
   wait(key: unknown): Promise<void>;
 
+  /**
+   * Removes expired keys from the last seen map.
+   */
+  vacuum(): void;
+
   /**
    * Retrieves the vacuuming state.
    * @returns `true` if the vacuuming is active, `false` otherwise.
@@ -79,14 +84,14 @@ export declare class Throttler implements ThrottlerOptions {
 
   /**
    * Starts the vacuum process.
-   * The vacuum process removes keys that expired.
+   * The vacuum process removes expired keys.
    * @returns The throttler object.
    */
   startVacuum(): this;
 
   /**
    * Stops the vacuum process.
-   * The vacuum process removes keys that expired.
+   * The vacuum process removes expired keys.
    * @returns The throttler object.
    */
   stopVacuum(): this;

package/src/Throttler.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./Throttler.d.ts"
 
-'use strict';
-
 import sleep from './sleep.js';
 
 export class Throttler {
@@ -57,6 +55,7 @@ export class Throttler {
     this.handle = setInterval(() => {
       this.vacuum();
     }, this.vacuumPeriod);
+    if (this.handle.unref) this.handle.unref();
     return this;
   }
 

package/src/audit.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./audit.d.ts"
 
-'use strict';
-
 export const audit = (fn, ms) => {
   let handle = null,
     lastSeenArgs = null;

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.
+ * Modeled 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,40 @@
+// @ts-self-types="./batch.d.ts"
+
+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 (!fns.length) return Promise.resolve([]);
+  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/debounce.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./debounce.d.ts"
 
-'use strict';
-
 export const debounce = (fn, ms) => {
   let handle = null;
   return (...args) => {

package/src/defer.d.ts

@@ -6,12 +6,11 @@
  * - `setTimeout()`
  *
  * @param fn The function to delay.
- * @returns A function that, when called, will execute the provided function.
  */
-export declare function defer<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+export declare function defer(fn: () => void): void;
 
 /**
- * Schedules a function to be called when the next available time.
+ * Schedules a function to be called at the next available time.
  *
  * @param fn The function to schedule.
  * @returns A promise that resolves when the function is called.
@@ -19,7 +18,7 @@ export declare function defer<A extends unknown[]>(fn: (...args: A) => void): (.
 export declare function scheduleDefer<R extends unknown>(fn: () => R): Promise<Awaited<R>>;
 
 /**
- * Schedules a function to be called when the next available time.
+ * Schedules a function to be called at the next available time.
  *
  * @param fn The function to schedule.
  * @returns A promise that resolves when the function is called.

package/src/defer.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./defer.d.ts"
 
-'use strict';
-
 let deferImplementation = setTimeout;
 
 if (typeof requestIdleCallback == 'function') {

package/src/index.d.ts

@@ -1,5 +1,6 @@
 declare module 'time-queues' {
   export * from './audit';
+  export * from './batch';
   export * from './debounce';
   export * from './defer';
   export * from './sample';
@@ -9,15 +10,19 @@ declare module 'time-queues' {
   export * from './CancelTaskError';
   export * from './MicroTask';
   export * from './MicroTaskQueue';
+  export * from './LimitedQueue';
   export * from './ListQueue';
   export * from './FrameQueue';
   export * from './IdleQueue';
 
+  export * from './Counter';
   export * from './PageWatcher';
-  export * from './Scheduler';
   export * from './Retainer';
+  export * from './Scheduler';
   export * from './Throttler';
-  export * from './Counter';
+
+  export * from './random-dist';
+  export * from './random-sleep';
 
   export * from './when-dom-loaded';
   export * from './when-loaded';

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