time-queues 1.3.1 → 1.4.0

package/src/Throttler.d.ts

@@ -17,7 +17,20 @@ export declare type ThrottlerOptions = {
 };
 
 /**
- * A throttler that throttles the execution of tasks based on a key.
+ * A throttler that paces the execution of work based on a key.
+ *
+ * Despite the name, this is **rate-limiting / pacing**, not classical
+ * "drop excess" throttle. `Throttler` does not execute functions; it
+ * exposes `wait(key)` and the caller decides what to do once awaited.
+ * Because there is nothing for `Throttler` to drop, every call is honored
+ * — N rapid calls produce delays roughly `0, throttleTimeout,
+ * 2*throttleTimeout, …`, spacing the work out across time. Use it when
+ * you need every operation to run but no faster than `throttleTimeout`
+ * apart per key.
+ *
+ * If you want React/Lodash-style "fire-leading-edge-only-then-drop"
+ * semantics, wrap your callback with `throttle()` from this package
+ * instead.
  */
 export declare class Throttler implements ThrottlerOptions {
   /**
@@ -44,11 +57,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.
@@ -58,16 +67,20 @@ export declare class Throttler implements ThrottlerOptions {
   getLastSeen(key: unknown): number;
 
   /**
-   * Retrieves the delay for a key.
+   * Retrieves the delay for a key and reserves the next slot.
+   * Each call extends the per-key queue: stored state advances by the returned
+   * delay, so the next call for the same key waits at least `throttleTimeout`
+   * past the slot just allocated. Returns the delay in milliseconds.
    * @param key The key to retrieve the delay for.
-   * @returns The delay for the key in milliseconds.
+   * @returns The delay before this caller's slot opens, in milliseconds.
    */
   getDelay(key: unknown): number;
 
   /**
-   * Waits for a key to be available.
+   * Waits until this caller's slot for `key` opens. See class docs for the
+   * pacing semantics — every call is queued, none are dropped.
    * @param key The key to wait for.
-   * @returns A promise that resolves when the key is available.
+   * @returns A promise that resolves when the slot is available.
    */
   wait(key: unknown): Promise<void>;
 

package/src/Throttler.js

@@ -3,6 +3,8 @@
 import sleep from './sleep.js';
 
 export class Throttler {
+  #handle = null;
+
   constructor({
     throttleTimeout = 1_000,
     neverSeenTimeout = 0,
@@ -12,7 +14,6 @@ export class Throttler {
     this.neverSeenTimeout = neverSeenTimeout;
     this.vacuumPeriod = vacuumPeriod;
     this.lastSeen = new Map();
-    this.handle = null;
     if (this.vacuumPeriod) this.startVacuum();
   }
 
@@ -38,7 +39,7 @@ export class Throttler {
   }
 
   get isVacuuming() {
-    return !!this.handle;
+    return !!this.#handle;
   }
 
   vacuum() {
@@ -51,18 +52,18 @@ export class Throttler {
   }
 
   startVacuum() {
-    if (this.handle) return this;
-    this.handle = setInterval(() => {
+    if (this.#handle) return this;
+    this.#handle = setInterval(() => {
       this.vacuum();
     }, this.vacuumPeriod);
-    if (this.handle.unref) this.handle.unref();
+    if (this.#handle.unref) this.#handle.unref();
     return this;
   }
 
   stopVacuum() {
-    if (!this.handle) return this;
-    clearInterval(this.handle);
-    this.handle = null;
+    if (!this.#handle) return this;
+    clearInterval(this.#handle);
+    this.#handle = null;
     return this;
   }
 }

package/src/audit.js

@@ -4,7 +4,7 @@ export const audit = (fn, ms) => {
   let handle = null,
     lastSeenArgs = null;
   return (...args) => {
-    lastSeenArgs = [...args];
+    lastSeenArgs = args;
     if (handle) return;
     handle = setTimeout(() => {
       handle = null;

package/src/defer.js

@@ -1,5 +1,6 @@
 // @ts-self-types="./defer.d.ts"
 
+/** @type {(...args: any[]) => any} */
 let deferImplementation = setTimeout;
 
 if (typeof requestIdleCallback == 'function') {

package/src/index.d.ts

@@ -1,29 +1,27 @@
-declare module 'time-queues' {
-  export * from './audit';
-  export * from './batch';
-  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 './LimitedQueue';
-  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 './Counter';
-  export * from './PageWatcher';
-  export * from './Retainer';
-  export * from './Scheduler';
-  export * from './Throttler';
+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 './random-dist';
-  export * from './random-sleep';
+export * from './random-dist.js';
+export * from './random-sleep.js';
 
-  export * from './when-dom-loaded';
-  export * from './when-loaded';
-}
+export * from './when-dom-loaded.js';
+export {whenLoaded, scheduleWhenLoaded} from './when-loaded.js';

package/src/index.js

@@ -0,0 +1,29 @@
+// @ts-self-types="./index.d.ts"
+
+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.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 './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 './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-dist.js

@@ -10,12 +10,15 @@ export const normal = (mean, stdDev, skewness = 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;
+  const r = Math.sqrt(-2.0 * Math.log(u)),
+    theta = 2.0 * Math.PI * v,
+    z1 = r * Math.cos(theta);
+  if (!skewness) return z1 * stdDev + mean;
+  // Box-Muller yields two independent N(0,1) samples per (u, v) pair; use both for skew-normal.
+  const z2 = r * Math.sin(theta),
+    delta = skewness / Math.sqrt(1 + skewness * skewness),
+    x = delta * z1 + Math.sqrt(1 - delta * delta) * z2;
+  return (z1 >= 0 ? x : -x) * stdDev + mean;
 };
 
 export const expo = lambda => {

package/src/random-sleep.d.ts

@@ -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.js

@@ -6,7 +6,7 @@ export const sample = (fn, ms) => {
     lastSeenArgs = null,
     timeout = ms;
   return (...args) => {
-    lastSeenArgs = [...args];
+    lastSeenArgs = args;
     if (handle) return;
     const diff = (Date.now() - started) % ms,
       delay = diff ? ms - diff : timeout;

package/src/when-dom-loaded.js

@@ -2,10 +2,11 @@
 
 import ValueList from 'list-toolkit/value-list.js';
 
+/** @type {ValueList<() => void>} */
 const waitingForDom = new ValueList();
 
 export const remove = fn => {
-  for (const node of waitingForDom.getNodeIterable()) {
+  for (const node of waitingForDom.getNodeIterator()) {
     if (node.value === fn) {
       waitingForDom.removeNode(node);
       return true;

package/src/when-loaded.js

@@ -2,10 +2,11 @@
 
 import ValueList from 'list-toolkit/value-list.js';
 
+/** @type {ValueList<() => void>} */
 const waitingForLoad = new ValueList();
 
 export const remove = fn => {
-  for (const node of waitingForLoad.getNodeIterable()) {
+  for (const node of waitingForLoad.getNodeIterator()) {
     if (node.value === fn) {
       waitingForLoad.removeNode(node);
       return true;