time-queues 1.3.1 → 1.3.2

package/README.md

@@ -140,6 +140,7 @@ BSD-3-Clause
 
 ## Release History
 
+- 1.3.2 _Bug fixes (Scheduler, LimitedQueue, PageWatcher, Retainer), corrected `.d.ts` declarations, expanded tests, documentation fixes._
 - 1.3.1 _Fixed `.d.ts` declarations, consolidated TS typing tests, improved documentation._
 - 1.3.0 _Added `batch()`, `LimitedQueue`, random distributions and random sleep functions._
 - 1.2.4 _Updated dependencies._
@@ -156,3 +157,5 @@ BSD-3-Clause
 - 1.0.2 _Updated deps (`list-toolkit`)._
 - 1.0.1 _Minor update in README._
 - 1.0.0 _Initial release._
+
+See [release notes](wiki/Release-notes) for more details and history.

package/llms-full.txt

@@ -205,8 +205,8 @@ class LimitedQueue extends ListQueue {
   get activeTasks(): number;
   get isIdle(): boolean;
   waitForIdle(): Promise<void>;
-  enqueue(fn: () => unknown): Task;
-  schedule(fn: (() => unknown) | null | undefined): Task;
+  enqueue(fn: (arg: {task: Task, queue: LimitedQueue}) => unknown): Task;
+  schedule(fn: ((arg: {task: Task, queue: LimitedQueue}) => unknown) | null | undefined): Task;
 }
 export { Task };
 export default LimitedQueue;

package/llms.txt

@@ -54,7 +54,7 @@ const results = await batch(
 - **debounce** (`time-queues/debounce.js`) — `debounce(fn, ms): fn`. Delay until input stabilizes.
 - **sample** (`time-queues/sample.js`) — `sample(fn, ms): fn`. Execute at regular intervals with last seen args.
 - **audit** (`time-queues/audit.js`) — `audit(fn, ms): fn`. Collect then execute after delay with last seen args.
-- **batch** (`time-queues/batch.js`) — `batch(fns, limit?): Promise<results[]>`. Run async operations with concurrency limit (default: 5).
+- **batch** (`time-queues/batch.js`) — `batch(fns, limit?): Promise<results[]>`. Run async operations with concurrency limit (default: 4).
 
 ### Supporting classes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "time-queues",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Lightweight async task scheduling and concurrency control: schedulers, idle/frame/limited queues, throttle, debounce, batch, page lifecycle, random delays. Browsers, Node.js, Deno, Bun.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -75,7 +75,11 @@
   ],
   "tape6": {
     "tests": [
-      "/tests/test-*.*js"
+      "/tests/test-*.js",
+      "/tests/test-*.mjs"
+    ],
+    "cli": [
+      "/tests/test-*.cjs"
     ],
     "importmap": {
       "imports": {
@@ -86,13 +90,13 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.5.0",
     "prettier": "^3.8.1",
-    "tape-six": "^1.7.2",
-    "tape-six-proc": "^1.2.3",
+    "tape-six": "^1.7.12",
+    "tape-six-proc": "^1.2.7",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "list-toolkit": "^2.3.0"
+    "list-toolkit": "^2.3.2"
   }
 }

package/src/Counter.d.ts

@@ -22,7 +22,7 @@ export declare class Counter {
    * Sets the counter to a specific value.
    * @param value The new value for the counter.
    */
-  set value(value: number): void;
+  set value(value: number);
 
   /**
    * Increments the counter.

package/src/FrameQueue.d.ts

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 /**
  * A queue based on [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame).
@@ -33,7 +33,7 @@ export declare class FrameQueue extends ListQueue {
    * @param fn The function to execute.
    * @returns The task object.
    */
-  enqueue(fn: ({timeStamp: number, task: Task, queue: FrameQueue}) => unknown): Task;
+  enqueue(fn: (arg: {timeStamp: number; task: Task; queue: FrameQueue}) => unknown): Task;
 
   /**
    * Dequeues a task.
@@ -48,7 +48,7 @@ export declare class FrameQueue extends ListQueue {
    * @returns The task object.
    */
   schedule(
-    fn: (({timeStamp: number, task: Task, queue: FrameQueue}) => unknown) | null | undefined
+    fn: ((arg: {timeStamp: number; task: Task; queue: FrameQueue}) => unknown) | null | undefined
   ): Task;
 
   /**

package/src/IdleQueue.d.ts

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 /**
  * A queue based on [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback).
@@ -20,7 +20,7 @@ export declare class IdleQueue extends ListQueue {
   /**
    * The options passed to `requestIdleCallback()`.
    */
-  options: IdleCallbackOptions | undefined;
+  options: IdleRequestOptions | undefined;
 
   /**
    * Creates a new idle queue.
@@ -28,7 +28,7 @@ export declare class IdleQueue extends ListQueue {
    * @param timeoutBatchInMs The timeout batch size in milliseconds.
    * @param options The options passed to `requestIdleCallback()`.
    */
-  constructor(paused?: boolean, timeoutBatchInMs?: number, options?: IdleCallbackOptions);
+  constructor(paused?: boolean, timeoutBatchInMs?: number, options?: IdleRequestOptions);
 
   /**
    * Whether the queue is empty.
@@ -40,7 +40,7 @@ export declare class IdleQueue extends ListQueue {
    * @param fn The function to execute.
    * @returns The task object.
    */
-  enqueue(fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown): Task;
+  enqueue(fn: (arg: {deadline: IdleDeadline; task: Task; queue: IdleQueue}) => unknown): Task;
 
   /**
    * Dequeues a task.
@@ -55,7 +55,10 @@ export declare class IdleQueue extends ListQueue {
    * @returns The task object.
    */
   schedule(
-    fn: (({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown) | null | undefined
+    fn:
+      | ((arg: {deadline: IdleDeadline; task: Task; queue: IdleQueue}) => unknown)
+      | null
+      | undefined
   ): Task;
 
   /**
@@ -93,7 +96,7 @@ export const idleQueue: IdleQueue;
  * A function that schedules a task to run in the next idle period.
  */
 export const defer: (
-  fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown
+  fn: (arg: {deadline: IdleDeadline; task: Task; queue: IdleQueue}) => unknown
 ) => Task;
 
 export default idleQueue;

package/src/LimitedQueue.d.ts

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 export {Task};
 
@@ -58,7 +58,7 @@ export declare class LimitedQueue extends ListQueue {
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
-  enqueue(fn: () => unknown): Task;
+  enqueue(fn: (arg: {task: Task; queue: LimitedQueue}) => unknown): Task;
 
   /**
    * Dequeues a microtask.
@@ -72,7 +72,7 @@ export declare class LimitedQueue extends ListQueue {
    * @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.
    * @returns The task object.
    */
-  schedule(fn: (() => unknown) | null | undefined): Task;
+  schedule(fn: ((arg: {task: Task; queue: LimitedQueue}) => unknown) | null | undefined): Task;
 
   /**
    * Clears the queue.

package/src/LimitedQueue.js

@@ -9,7 +9,7 @@ export class LimitedQueue extends ListQueue {
 
   constructor(limit, paused) {
     super(paused);
-    this.#taskLimit = limit;
+    this.#taskLimit = Math.max(1, limit);
     this.#activeTasks = 0;
     this.#idleWaiters = [];
   }

package/src/ListQueue.d.ts

@@ -1,6 +1,5 @@
-import {MicroTask} from './MicroTask';
-import {MicroTaskQueue} from './MicroTaskQueue';
-import {List} from 'list-toolkit';
+import {MicroTask} from './MicroTask.js';
+import {MicroTaskQueue} from './MicroTaskQueue.js';
 
 /**
  * A list-based queue of microtasks that will be executed when scheduled.
@@ -34,7 +33,7 @@ export declare class ListQueue extends MicroTaskQueue {
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
-  enqueue(fn: () => unknown): MicroTask;
+  enqueue(fn: (...args: any[]) => unknown): MicroTask;
 
   /**
    * Dequeues a microtask.
@@ -48,7 +47,7 @@ export declare class ListQueue extends MicroTaskQueue {
    * @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.
    * @returns The task object.
    */
-  schedule(fn: (() => unknown) | null | undefined): MicroTask;
+  schedule(fn: ((...args: any[]) => unknown) | null | undefined): MicroTask;
 
   /**
    * Clears the queue.

package/src/MicroTask.d.ts

@@ -5,7 +5,7 @@ export declare class MicroTask {
   /**
    * The function to execute when the microtask is scheduled.
    */
-  fn: () => unknown;
+  fn: (...args: any[]) => unknown;
 
   /**
    * Whether the microtask has been canceled.
@@ -16,7 +16,7 @@ export declare class MicroTask {
    * Creates a new microtask.
    * @param fn The function to execute when the microtask is scheduled.
    */
-  constructor(fn: () => unknown);
+  constructor(fn: (...args: any[]) => unknown);
 
   /**
    * Makes a promise that will be resolved when the microtask is executed.

package/src/MicroTaskQueue.d.ts

@@ -1,4 +1,4 @@
-import MicroTask from './MicroTask';
+import MicroTask from './MicroTask.js';
 
 /**
  * A queue of microtasks that will be executed when scheduled.
@@ -29,7 +29,7 @@ export declare class MicroTaskQueue {
    * @param fn The function to execute when the microtask is scheduled.
    * @returns The enqueued microtask.
    */
-  enqueue(fn: () => unknown): MicroTask;
+  enqueue(fn: (...args: any[]) => unknown, ...args: unknown[]): MicroTask;
 
   /**
    * Dequeues a microtask from the queue.
@@ -46,7 +46,7 @@ export declare class MicroTaskQueue {
    * @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, ...args: unknown[]): MicroTask;
+  schedule(fn: ((...args: any[]) => unknown) | null | undefined, ...args: unknown[]): MicroTask;
 
   /**
    * Clears all tasks from the queue.

package/src/PageWatcher.d.ts

@@ -1,4 +1,4 @@
-import {ListQueue, Task} from './ListQueue';
+import {ListQueue, Task} from './ListQueue.js';
 
 /**
  * A page state.
@@ -82,7 +82,7 @@ export declare class PageWatcher extends ListQueue {
  */
 export declare const watchStates: (
   queue: ListQueue,
-  resumeStatesList: PageState[] = ['active']
+  resumeStatesList?: PageState[]
 ) => (state: PageState) => void;
 
 /**

package/src/PageWatcher.js

@@ -27,7 +27,6 @@ export class PageWatcher extends ListQueue {
   }
 
   pause() {
-    this.paused = true;
     watchedEvents.forEach(type => removeEventListener(type, this, eventHandlerOptions));
     return super.pause();
   }
@@ -50,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.js

@@ -33,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.
@@ -102,14 +102,14 @@ 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.
@@ -118,7 +118,7 @@ export declare class Scheduler extends MicroTaskQueue {
    * @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;
 
@@ -150,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

@@ -70,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;
@@ -108,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});
     }
 
@@ -118,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.

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/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

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