time-queues 1.0.5 → 1.1.1

package/src/MicroTask.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A microtask that will be executed when scheduled.
+ */
+export declare class MicroTask {
+  /**
+   * The function to execute when the microtask is scheduled.
+   */
+  fn: () => void;
+
+  /**
+   * Creates a new microtask.
+   * @param fn The function to execute when the microtask is scheduled.
+   */
+  constructor(fn: () => void);
+}
+
+export default MicroTask;

package/src/MicroTask.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./MicroTask.d.ts"
+
 'use strict';
 
 export class MicroTask {

package/src/MicroTaskQueue.d.ts

@@ -0,0 +1,63 @@
+import {MicroTask} from './MicroTask';
+
+/**
+ * A queue of microtasks that will be executed when scheduled.
+ * It is a base class for other task queues.
+ */
+export declare class MicroTaskQueue {
+  /**
+   * Whether the queue is paused.
+   */
+  paused: boolean;
+
+  /**
+   * Creates a new microtask queue.
+   * @param paused Whether the queue should start paused.
+   */
+  constructor(paused?: boolean);
+
+  /**
+   * Whether the queue is empty.
+   * It is meant to be overridden in subclasses.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Enqueues a microtask.
+   * It is meant to be overridden in subclasses.
+   * @param fn The function to execute when the microtask is scheduled.
+   * @returns The enqueued microtask.
+   */
+  enqueue(fn: () => void): MicroTask;
+
+  /**
+   * Dequeues a microtask.
+   * It is meant to be overridden in subclasses.
+   * @param task The microtask to dequeue.
+   * @returns The queue.
+   */
+  dequeue(task: MicroTask): this;
+
+  /**
+   * Clears the queue.
+   * It is meant to be overridden in subclasses.
+   * @returns The queue.
+   */
+  clear(): this;
+
+  /**
+   * Pauses the queue.
+   * It is meant to be overridden in subclasses.
+   * @returns The queue.
+   */
+  pause(): this;
+
+  /**
+   * Resumes the queue.
+   * It is meant to be overridden in subclasses.
+   * @returns The queue.
+   */
+  resume(): this;
+}
+
+export default MicroTaskQueue;

package/src/MicroTaskQueue.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./MicroTaskQueue.d.ts"
+
 'use strict';
 
 import MicroTask from './MicroTask.js';

package/src/PageWatcher.d.ts

@@ -0,0 +1,87 @@
+import {ListQueue, Task} from './ListQueue';
+
+/**
+ * A page state.
+ */
+export declare type PageState = 'active' | 'passive' | 'hidden' | 'frozen' | 'terminated';
+
+/**
+ * A queue that monitors the page's lifecycle.
+ */
+export declare class PageWatcher extends ListQueue {
+  /**
+   * Whether the queue is paused.
+   */
+  paused: boolean;
+
+  /**
+   * The current state of the page.
+   */
+  currentState: PageState;
+
+  /**
+   * Creates a new page watcher.
+   * @param started Whether the queue is unpaused initially.
+   */
+  constructor(started?: boolean);
+
+  /**
+   * Whether the queue is empty.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Enqueues a task.
+   * @param fn The function to execute.
+   * @param initialize Whether the function should be executed before the state changes.
+   * @returns The task object.
+   */
+  enqueue(
+    fn: (state: PageState, previousState: PageState, task: Task, queue: ListQueue) => void,
+    initialize?: boolean
+  ): Task;
+
+  /**
+   * Dequeues a task.
+   * @param task The task to dequeue.
+   * @returns The queue.
+   */
+  dequeue(task: Task): this;
+
+  /**
+   * Clears the queue.
+   * @returns The queue.
+   */
+  clear(): this;
+
+  /**
+   * Pauses the queue.
+   * @returns The queue.
+   */
+  pause(): this;
+
+  /**
+   * Resumes the queue.
+   * @returns The queue.
+   */
+  resume(): this;
+}
+
+/**
+ * A function that pauses or resumes a queue based on the page's state.
+ * Its result can be used as a callback for `PageWatcher`.
+ * @param queue The queue to pause or resume.
+ * @param resumeStatesList The list of states that should resume the queue.
+ * @returns A function that can be called with the current page state.
+ */
+export declare const watchStates: (
+  queue: ListQueue,
+  resumeStatesList: PageState[] = ['active']
+) => (state: PageState) => void;
+
+/**
+ * The default page watcher usually used as a global queue.
+ */
+export declare const pageWatcher: PageWatcher;
+
+export default PageWatcher;

package/src/PageWatcher.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./PageWatcher.d.ts"
+
 'use strict';
 
 import ListQueue from './ListQueue.js';

package/src/Retainer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The options for a retainer.
+ */
+export declare interface RetainerOptions<T = unknown> {
+  /**
+   * The function to create a value.
+   */
+  create: () => Promise<T> | T;
+  /**
+   * The function to destroy a value.
+   */
+  destroy: (value: T) => Promise<void> | void;
+  /**
+   * The retention period in milliseconds.
+   */
+  retentionPeriod: number;
+}
+
+/**
+ * Retains a value for a specified time.
+ */
+export declare class Retainer<T = unknown> implements RetainerOptions<T> {
+  /**
+   * The counter for the number of active references.
+   */
+  counter: number;
+
+  /**
+   * The value currently retained.
+   */
+  value: T | null;
+
+  /**
+   * The function to create a value.
+   */
+  create: () => Promise<T> | T;
+
+  /**
+   * The function to destroy a value.
+   */
+  destroy: (value: T) => Promise<void> | void;
+
+  /**
+   * The retention period in milliseconds.
+   */
+  retentionPeriod: number;
+
+  /**
+   * Creates a new retainer.
+   * @param options The options for the retainer.
+   */
+  constructor(options: RetainerOptions<T>);
+
+  /**
+   * Retrieves the retained value.
+   * @returns The retained value as a promise.
+   */
+  async get(): Promise<T>;
+
+  /**
+   * Releases the retained value.
+   * @param immediately Whether to release the value immediately. Otherwise it'll be retained for the retention period.
+   * @returns The retainer object.
+   */
+  async release(immediately?: boolean): Promise<this>;
+}
+
+export default Retainer;

package/src/Retainer.js

@@ -0,0 +1,48 @@
+// @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');
+    this.create = create;
+    this.destroy = destroy;
+    this.retentionPeriod = retentionPeriod;
+    this.counter = 0;
+    this.handle = null;
+    this.value = null;
+  }
+
+  async get() {
+    if (!this.counter) {
+      if (this.handle) {
+        clearTimeout(this.handle);
+        this.handle = null;
+      } else {
+        this.value = await this.create();
+      }
+    }
+    ++this.counter;
+    return this.value;
+  }
+
+  async release(immediately) {
+    if (this.counter <= 0) throw new Error('Retainer: counter is already zero');
+    if (--this.counter) return this;
+    if (immediately) {
+      const value = this.value;
+      this.value = null;
+      await this.destroy(value);
+      return this;
+    }
+    this.handle = setTimeout(async () => {
+      const value = this.value;
+      this.value = null;
+      this.handle = null;
+      await this.destroy(value);
+    }, this.retentionPeriod);
+    return this;
+  }
+}
+
+export default Retainer;

package/src/Scheduler.d.ts

@@ -0,0 +1,119 @@
+import MicroTask from './MicroTask';
+import MicroTaskQueue from './MicroTaskQueue';
+
+/**
+ * A task that will be executed at a later time by `Scheduler`.
+ */
+export declare class Task extends MicroTask {
+  /**
+   * The function to execute.
+   */
+  fn: (task: Task, scheduler: Scheduler) => void;
+
+  /**
+   * The time in milliseconds (Unix timestamp) when the task is scheduled to run.
+   */
+  time: number;
+
+  /**
+   * The delay in milliseconds before the task is executed.
+   */
+  delay: number;
+
+  /**
+   * Creates a new task.
+   * @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);
+}
+
+/**
+ * A scheduler that manages tasks to be executed at a later time.
+ */
+export declare class Scheduler extends MicroTaskQueue {
+  /**
+   * Whether the scheduler is paused.
+   */
+  paused: boolean;
+
+  /**
+   * The tolerance for comparing starting time of tasks.
+   */
+  tolerance: number;
+
+  /**
+   * Creates a new scheduler.
+   * @param paused Whether the scheduler should start paused.
+   * @param tolerance The tolerance for comparing starting time of tasks.
+   */
+  constructor(paused?: boolean, tolerance: number = 4);
+
+  /**
+   * Whether the scheduler is empty.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * The next scheduled time or `Infinity` if the scheduler is empty.
+   */
+  get nextTime(): number;
+
+  /**
+   * Enqueues a task.
+   * @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.
+   */
+  enqueue(fn: (task: Task, scheduler: Scheduler) => void, delay: number | Date): Task;
+
+  /**
+   * Removes a task from the scheduler.
+   * @param task The task to remove.
+   * @returns The scheduler object.
+   */
+  dequeue(task: Task): this;
+
+  /**
+   * Creates a promise that resolves after a delay.
+   * @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.
+   */
+  schedule(delay: number | Date): Promise<{task: Task; scheduler: Scheduler}>;
+
+  /**
+   * Clears the queue.
+   * @returns The queue.
+   */
+  clear(): this;
+
+  /**
+   * Pauses the queue.
+   * @returns The queue.
+   */
+  pause(): this;
+
+  /**
+   * Resumes the queue.
+   * @returns The queue.
+   */
+  resume(): this;
+}
+
+/**
+ * Creates a repeatable task.
+ * @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 A function that can be used to enqueue the task to the scheduler.
+ */
+export declare const repeat: (
+  fn: (task: Task, scheduler: Scheduler) => void,
+  delay: number | Date
+) => (task: Task, scheduler: Scheduler) => void;
+
+/**
+ * A scheduler instance usually used as a global scheduler.
+ */
+export declare const scheduler: Scheduler;
+
+export default scheduler;

package/src/Scheduler.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./Scheduler.d.ts"
+
 'use strict';
 
 import MinHeap from 'list-toolkit/heap.js';
@@ -81,6 +83,12 @@ 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();
@@ -113,11 +121,11 @@ export class Scheduler extends MicroTaskQueue {
 }
 
 export const repeat = (fn, delay) => {
-  const repeatableTask = (task, scheduler) => {
+  const repeatableFunction = (task, scheduler) => {
     fn(task, scheduler);
-    scheduler.enqueue(repeatableTask, isNaN(delay) ? task.delay : delay);
+    scheduler.enqueue(repeatableFunction, isNaN(delay) ? task.delay : delay);
   };
-  return repeatableTask;
+  return repeatableFunction;
 };
 
 export const scheduler = new Scheduler();

package/src/Throttler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Options for the throttler.
+ */
+export declare type ThrottlerOptions = {
+  /**
+   * The throttle timeout.
+   */
+  throttleTimeout?: number;
+  /**
+   * The timeout for keys that have never been seen.
+   */
+  neverSeenTimeout?: number;
+  /**
+   * The vacuum period.
+   */
+  vacuumPeriod?: number;
+};
+
+/**
+ * A throttler that throttles the execution of tasks based on a key.
+ */
+export declare class Throttler implements ThrottlerOptions {
+  /**
+   * The throttle timeout.
+   */
+  throttleTimeout: number;
+
+  /**
+   * The timeout for keys that have never been seen.
+   */
+  neverSeenTimeout: number;
+
+  /**
+   * The vacuum period.
+   */
+  vacuumPeriod: number;
+
+  /**
+   * The last seen times for keys.
+   */
+  lastSeen: Map<unknown, number>;
+
+  /**
+   * Creates a new throttler.
+   * @param options The options for the throttler.
+   */
+  constructor({
+    throttleTimeout = 1_000,
+    neverSeenTimeout = 0,
+    vacuumPeriod = throttleTimeout * 3
+  }: ThrottlerOptions = {});
+
+  /**
+   * Retrieves the last seen time for a key as a timestamp in milliseconds.
+   * @param key The key to retrieve the last seen time for.
+   * @returns The last seen time for the key or `0` if the key has never been seen.
+   */
+  getLastSeen(key: unknown): number;
+
+  /**
+   * Retrieves the delay for a key.
+   * @param key The key to retrieve the delay for.
+   * @returns The delay for the key in milliseconds.
+   */
+  getDelay(key: unknown): number;
+
+  /**
+   * Waits for a key to be available.
+   * @param key The key to wait for.
+   * @returns A promise that resolves when the key is available.
+   */
+  wait(key: unknown): Promise<void>;
+
+  /**
+   * Retrieves the vacuuming state.
+   * @returns `true` if the vacuuming is active, `false` otherwise.
+   */
+  get isVacuuming(): boolean;
+
+  /**
+   * Starts the vacuum process.
+   * The vacuum process removes keys that expired.
+   * @returns The throttler object.
+   */
+  startVacuum(): this;
+
+  /**
+   * Stops the vacuum process.
+   * The vacuum process removes keys that expired.
+   * @returns The throttler object.
+   */
+  stopVacuum(): this;
+}
+
+export default Throttler;

package/src/Throttler.js

@@ -0,0 +1,71 @@
+// @ts-self-types="./Throttler.d.ts"
+
+'use strict';
+
+import sleep from './sleep.js';
+
+export class Throttler {
+  constructor({
+    throttleTimeout = 1_000,
+    neverSeenTimeout = 0,
+    vacuumPeriod = throttleTimeout * 3
+  } = {}) {
+    this.throttleTimeout = throttleTimeout;
+    this.neverSeenTimeout = neverSeenTimeout;
+    this.vacuumPeriod = vacuumPeriod;
+    this.lastSeen = new Map();
+    this.handle = null;
+    if (this.vacuumPeriod) this.startVacuum();
+  }
+
+  getLastSeen(key) {
+    return this.lastSeen.get(key) ?? 0;
+  }
+
+  getDelay(key) {
+    const now = Date.now();
+    let lastSeen = now,
+      delay = this.neverSeenTimeout;
+    if (this.lastSeen.has(key)) {
+      lastSeen = this.lastSeen.get(key);
+      delay = Math.max(0, this.throttleTimeout - (now - lastSeen));
+    }
+    this.lastSeen.set(key, lastSeen + delay);
+    return delay;
+  }
+
+  async wait(key) {
+    const delay = this.getDelay(key);
+    if (delay > 0) await sleep(delay);
+  }
+
+  get isVacuuming() {
+    return !!this.handle;
+  }
+
+  vacuum() {
+    const now = Date.now();
+    for (const [key, lastSeen] of this.lastSeen) {
+      if (now - lastSeen > this.throttleTimeout) {
+        this.lastSeen.delete(key);
+      }
+    }
+  }
+
+  startVacuum() {
+    if (this.handle) return this;
+    this.handle = setInterval(() => {
+      this.vacuum();
+    }, this.vacuumPeriod);
+    return this;
+  }
+
+  stopVacuum() {
+    if (!this.handle) return this;
+    clearInterval(this.handle);
+    this.handle = null;
+    return this;
+  }
+}
+
+export default Throttler;

package/src/audit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Audits a function by ensuring it is not called more often than the specified interval.
+ * The first call starts a timeout. At the end of the timeout, the last seen arguments are passed to the function.
+ * This function is similar to `throttle()`, but the last seen arguments are passed to the function.
+ *
+ * @param fn The function to audit.
+ * @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,
+  ms: number
+): (...args: Parameters<T>) => void;
+
+export default audit;

package/src/audit.js

@@ -0,0 +1,20 @@
+// @ts-self-types="./audit.d.ts"
+
+'use strict';
+
+export const audit = (fn, ms) => {
+  let handle = null,
+    lastSeenArgs = null;
+  return (...args) => {
+    lastSeenArgs = [...args];
+    if (handle) return;
+    handle = setTimeout(() => {
+      handle = null;
+      const args = lastSeenArgs;
+      lastSeenArgs = null;
+      fn(...args);
+    }, ms);
+  };
+};
+
+export default audit;

package/src/debounce.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Debounces a function by using the last seen arguments after the specified time interval.
+ * Every call to the debounced function will reset the timeout.
+ *
+ * @param fn The function to debounce.
+ * @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,
+  ms: number
+): (...args: Parameters<T>) => void;
+
+export default debounce;

package/src/debounce.js

@@ -0,0 +1,16 @@
+// @ts-self-types="./debounce.d.ts"
+
+'use strict';
+
+export const debounce = (fn, ms) => {
+  let handle = null;
+  return (...args) => {
+    if (handle) clearTimeout(handle);
+    handle = setTimeout(() => {
+      handle = null;
+      fn(...args);
+    }, ms);
+  };
+};
+
+export default debounce;