time-queues 1.3.0 → 1.3.2

package/src/PageWatcher.d.ts

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 /**
  * A page state.
@@ -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(
@@ -82,7 +82,7 @@ export declare class PageWatcher extends ListQueue {
  */
 export declare const watchStates: (
   queue: ListQueue,
-  resumeStatesList: PageState[] = ['active']
+  resumeStatesList?: PageState[]
 ) => (state: PageState) => void;
 
 /**
@@ -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
@@ -29,7 +27,6 @@ export class PageWatcher extends ListQueue {
   }
 
   pause() {
-    this.paused = true;
     watchedEvents.forEach(type => removeEventListener(type, this, eventHandlerOptions));
     return super.pause();
   }
@@ -52,7 +49,10 @@ export class PageWatcher extends ListQueue {
   }
 
   clear() {
-    this.list.clear();
+    while (!this.list.isEmpty) {
+      const task = this.list.popFront();
+      task.cancel();
+    }
     return this;
   }
 

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');
@@ -35,11 +33,13 @@ export class Retainer {
       await this.destroy(value);
       return this;
     }
-    this.handle = setTimeout(async () => {
+    this.handle = setTimeout(() => {
       const value = this.value;
       this.value = null;
       this.handle = null;
-      await this.destroy(value);
+      Promise.resolve()
+        .then(() => this.destroy(value))
+        .catch(() => {});
     }, this.retentionPeriod);
     return this;
   }

package/src/Scheduler.d.ts

@@ -1,5 +1,5 @@
-import MicroTask from './MicroTask';
-import MicroTaskQueue from './MicroTaskQueue';
+import MicroTask from './MicroTask.js';
+import MicroTaskQueue from './MicroTaskQueue.js';
 
 /**
  * A task that will be executed at a later time by `Scheduler`.
@@ -8,7 +8,7 @@ export declare class Task extends MicroTask {
   /**
    * The function to execute.
    */
-  fn: ({task: Task, scheduler: Scheduler}) => unknown;
+  fn: (arg: {task: Task; scheduler: Scheduler}) => unknown;
 
   /**
    * Whether the task has been canceled.
@@ -30,7 +30,7 @@ export declare class Task extends MicroTask {
    * @param delay The delay before the task is executed. It can be a number of milliseconds or a `Date` object as an absolute time.
    * @param fn The function to execute.
    */
-  constructor(delay: number | Date, fn: ({task: Task, scheduler: Scheduler}) => unknown);
+  constructor(delay: number | Date, fn: (arg: {task: Task; scheduler: Scheduler}) => unknown);
 
   /**
    * Makes a promise that will be resolved when the microtask is executed.
@@ -55,9 +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.
+   * @param error The optional error to use as the cause of the cancellation.
    * @returns The microtask.
    */
-  cancel(): this;
+  cancel(error?: Error): this;
 }
 
 /**
@@ -71,7 +72,7 @@ export declare class Scheduler extends MicroTaskQueue {
   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;
@@ -79,7 +80,7 @@ export declare class Scheduler extends MicroTaskQueue {
   /**
    * Creates a new scheduler.
    * @param paused Whether the scheduler should start in a paused state.
-   * @param tolerance The tolerance for comparing starting time of tasks (default is 4ms).
+   * @param tolerance The tolerance for comparing starting times of tasks (default is 4ms).
    */
   constructor(paused?: boolean, tolerance?: number);
 
@@ -101,23 +102,23 @@ export declare class Scheduler extends MicroTaskQueue {
    * @param delay The delay before the task is executed. It can be a number of milliseconds or a `Date` object as an absolute time.
    * @returns The task object that was enqueued.
    */
-  enqueue(fn: ({task: Task, scheduler: Scheduler}) => unknown, delay: number | Date): Task;
+  enqueue(fn: (arg: {task: Task; scheduler: Scheduler}) => unknown, delay: number | Date): Task;
 
   /**
    * Removes a task from the scheduler.
    * @param task The task to remove.
    * @returns The scheduler object for chaining.
    */
-  dequeue(task: Task): this;
+  dequeue(task: MicroTask): this;
 
   /**
    * Schedules a task to run in the future.
-   * @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 that was scheduled.
    */
   schedule(
-    fn: (({task: Task, scheduler: Scheduler}) => unknown) | null | undefined,
+    fn: ((arg: {task: Task; scheduler: Scheduler}) => unknown) | null | undefined,
     delay: number | Date
   ): Task;
 
@@ -149,9 +150,9 @@ export declare class Scheduler extends MicroTaskQueue {
  * @returns A function that can be used to enqueue the task to the scheduler.
  */
 export declare const repeat: (
-  fn: ({task: Task, scheduler: Scheduler}) => void,
+  fn: (arg: {task: Task; scheduler: Scheduler}) => void,
   delay: number | Date
-) => ({task: Task, scheduler: Scheduler}) => void;
+) => (arg: {task: Task; scheduler: Scheduler}) => void;
 
 /**
  * A scheduler instance usually used as a global scheduler.

package/src/Scheduler.js

@@ -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';
@@ -72,6 +70,7 @@ export class Scheduler extends MicroTaskQueue {
   dequeue(task) {
     task.cancel();
     if (this.queue.isEmpty) return this;
+    if (!this.queue.has(task)) return this;
     if (this.paused || this.queue.top !== task) {
       this.queue.remove(task);
       return this;
@@ -90,6 +89,7 @@ export class Scheduler extends MicroTaskQueue {
     this.queue.array.forEach(task => task.cancel());
     this.queue.clear();
     if (!paused) this.resume();
+    return this;
   }
 
   startQueue() {
@@ -109,6 +109,7 @@ export class Scheduler extends MicroTaskQueue {
       this.queue.top.time <= Date.now() + this.tolerance
     ) {
       const task = this.queue.pop();
+      if (task.isCanceled) continue;
       task.fn({task, scheduler: this});
     }
 
@@ -119,7 +120,7 @@ export class Scheduler extends MicroTaskQueue {
 export const repeat = (fn, delay) => {
   const repeatableFunction = ({task, scheduler}) => {
     fn({task, scheduler});
-    scheduler.enqueue(repeatableFunction, isNaN(delay) ? task.delay : delay);
+    if (!task.isCanceled) scheduler.enqueue(repeatableFunction, isNaN(delay) ? task.delay : delay);
   };
   return repeatableFunction;
 };

package/src/Throttler.d.ts

@@ -44,11 +44,7 @@ export declare class Throttler implements ThrottlerOptions {
    * Creates a new throttler.
    * @param options The options for the throttler.
    */
-  constructor({
-    throttleTimeout = 1_000,
-    neverSeenTimeout = 0,
-    vacuumPeriod = throttleTimeout * 3
-  }: ThrottlerOptions = {});
+  constructor(options?: ThrottlerOptions);
 
   /**
    * Retrieves the last seen time for a key as a timestamp in milliseconds.
@@ -71,6 +67,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 +80,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

@@ -2,7 +2,7 @@
  * 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().
+ * 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)

package/src/batch.js

@@ -1,7 +1,5 @@
 // @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
@@ -9,6 +7,7 @@ const wrap = value => {
 };
 
 export const batch = (fns, limit = 4) => {
+  if (!fns.length) return Promise.resolve([]);
   if (limit < 1) limit = 1;
 
   const result = [];

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,24 +1,27 @@
-declare module 'time-queues' {
-  export * from './audit';
-  export * from './debounce';
-  export * from './defer';
-  export * from './sample';
-  export * from './sleep';
-  export * from './throttle';
+export * from './audit.js';
+export * from './batch.js';
+export * from './debounce.js';
+export * from './defer.js';
+export * from './sample.js';
+export * from './sleep.js';
+export * from './throttle.js';
 
-  export * from './CancelTaskError';
-  export * from './MicroTask';
-  export * from './MicroTaskQueue';
-  export * from './ListQueue';
-  export * from './FrameQueue';
-  export * from './IdleQueue';
+export * from './CancelTaskError.js';
+export * from './MicroTask.js';
+export * from './MicroTaskQueue.js';
+export * from './LimitedQueue.js';
+export * from './ListQueue.js';
+export * from './FrameQueue.js';
+export {IdleQueue, idleQueue} from './IdleQueue.js';
 
-  export * from './PageWatcher';
-  export * from './Scheduler';
-  export * from './Retainer';
-  export * from './Throttler';
-  export * from './Counter';
+export * from './Counter.js';
+export * from './PageWatcher.js';
+export * from './Retainer.js';
+export {Task as SchedulerTask, Scheduler, repeat, scheduler} from './Scheduler.js';
+export * from './Throttler.js';
 
-  export * from './when-dom-loaded';
-  export * from './when-loaded';
-}
+export * from './random-dist.js';
+export * from './random-sleep.js';
+
+export * from './when-dom-loaded.js';
+export {whenLoaded, scheduleWhenLoaded} from './when-loaded.js';

package/src/random-dist.d.ts

@@ -13,7 +13,7 @@ export declare function uniform(min: number, max: number): number;
  * @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;
+export declare function normal(mean: number, stdDev: number, skewness?: number): number;
 
 /**
  * Generate a random number from an exponential distribution.

package/src/random-sleep.d.ts

@@ -1,5 +1,5 @@
 /**
- * Random sleep function modelled after `sleep()`.
+ * Random sleep function modeled after `sleep()`.
  */
 export type RandomSleepFunction = () => Promise<void>;
 
@@ -21,7 +21,7 @@ export declare function randomUniformSleep(min: number, max: number): RandomSlee
 export declare function randomNormalSleep(
   mean: number,
   stdDev: number,
-  skewness: number = 0
+  skewness?: number
 ): RandomSleepFunction;
 
 /**
@@ -34,7 +34,7 @@ export declare function randomNormalSleep(
 export declare function randomExpoSleep(
   rate: number,
   range: number,
-  base: number = 0
+  base?: number
 ): RandomSleepFunction;
 
 /**
@@ -44,7 +44,7 @@ export declare function randomExpoSleep(
  * @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;
+export declare function randomParetoSleep(min: number, ratio?: number): RandomSleepFunction;
 
 /**
  * A simple sleep function that uses a uniform distribution.
@@ -52,6 +52,6 @@ export declare function randomParetoSleep(min: number, ratio: number = 0.8): Ran
  * @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 declare function randomSleep(max: number, min?: number): Promise<void>;
 
 export default randomSleep;

package/src/sample.d.ts

@@ -1,7 +1,7 @@
 /**
  * Samples a function by ensuring it is not called more often than the specified interval.
  * The last seen arguments are passed to the function after the specified time interval.
- * Unlike `audit()`, intervals are not reset by the function calls and never stops.
+ * Unlike `audit()`, intervals are not reset by the function calls and never stop.
  * If no call was made to the sampled function within the specified time interval,
  * no calls are made after the specified time interval.
  *

package/src/sample.js

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

package/src/sleep.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./sleep.d.ts"
 
-'use strict';
-
 export const sleep = ms => {
   if (ms instanceof Date) {
     ms = ms.getTime() - Date.now();

package/src/throttle.js

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

package/src/when-dom-loaded.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./when-dom-loaded.d.ts"
 
-'use strict';
-
 import ValueList from 'list-toolkit/value-list.js';
 
 const waitingForDom = new ValueList();

package/src/when-loaded.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./when-loaded.d.ts"
 
-'use strict';
-
 import ValueList from 'list-toolkit/value-list.js';
 
 const waitingForLoad = new ValueList();