time-queues 1.3.0 → 1.3.1

package/llms.txt

@@ -0,0 +1,95 @@
+# time-queues
+
+> Lightweight async task scheduling and concurrency control for JavaScript: schedulers, idle/frame/limited queues, throttle, debounce, batch, page lifecycle, random delays.
+
+- NPM: https://npmjs.org/package/time-queues
+- GitHub: https://github.com/uhop/time-queues
+- Wiki: https://github.com/uhop/time-queues/wiki
+- License: BSD-3-Clause
+
+## Install
+
+```bash
+npm install time-queues
+```
+
+## Quick start
+
+```js
+import sleep from 'time-queues/sleep.js';
+import {Scheduler, repeat} from 'time-queues/Scheduler.js';
+import {batch} from 'time-queues/batch.js';
+
+// Simple delay
+await sleep(1000);
+
+// Run a task every 5 seconds
+const scheduler = new Scheduler();
+scheduler.enqueue(repeat(({task, scheduler}) => {
+  console.log('tick');
+}, 5000), 5000);
+
+// Fetch URLs, max 3 at a time
+const results = await batch(
+  urls.map(url => () => fetch(url).then(r => r.json())),
+  3
+);
+```
+
+## Modules
+
+### Queues
+
+- **Scheduler** (`time-queues/Scheduler.js`) — time-based task scheduling with delays, dates, and repeats. Extends MicroTaskQueue. Uses a min-heap. Exports: `Scheduler`, `Task`, `repeat(fn, delay)`, `scheduler` (global instance).
+- **IdleQueue** (`time-queues/IdleQueue.js`) — run tasks during browser idle periods via `requestIdleCallback()`. Extends ListQueue. Exports: `IdleQueue`, `idleQueue` (global instance), `defer(fn)`.
+- **FrameQueue** (`time-queues/FrameQueue.js`) — run tasks in animation frames via `requestAnimationFrame()`. Extends ListQueue. Exports: `FrameQueue`, `frameQueue` (global instance).
+- **LimitedQueue** (`time-queues/LimitedQueue.js`) — concurrency-controlled async queue. Extends ListQueue. Exports: `LimitedQueue`, `Task`.
+- **PageWatcher** (`time-queues/PageWatcher.js`) — react to page lifecycle changes (active, passive, hidden, frozen, terminated). Extends ListQueue. Exports: `PageWatcher`, `watchStates(states, fn)`, `pageWatcher` (global instance).
+
+### Utility functions
+
+- **sleep** (`time-queues/sleep.js`) — `sleep(ms | Date): Promise<void>`. Promise-based delay.
+- **defer** (`time-queues/defer.js`) — `defer(fn): void`. Execute on next tick via `requestIdleCallback`/`setImmediate`/`setTimeout`. Also exports `scheduleDefer(fn): Promise`.
+- **throttle** (`time-queues/throttle.js`) — `throttle(fn, ms): fn`. Rate-limit: execute immediately, ignore calls until timeout expires.
+- **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).
+
+### Supporting classes
+
+- **Throttler** (`time-queues/Throttler.js`) — key-based rate limiting with vacuum cleanup. Methods: `getDelay(key)`, `wait(key)`, `startVacuum()`, `stopVacuum()`.
+- **Retainer** (`time-queues/Retainer.js`) — resource lifecycle management with reference counting. Methods: `get(): Promise<value>`, `release(): Promise<void>`.
+- **Counter** (`time-queues/Counter.js`) — numeric counter with async waiting. Methods: `increment()`, `decrement()`, `advance(delta)`, `waitForZero()`, `waitFor(target)`.
+- **CancelTaskError** (`time-queues/CancelTaskError.js`) — `Error` subclass for task cancellation signals.
+
+### Base classes
+
+- **MicroTask** (`time-queues/MicroTask.js`) — base task unit with lazy promise creation. Methods: `makePromise()`, `resolve(value)`, `cancel(error)`.
+- **MicroTaskQueue** (`time-queues/MicroTaskQueue.js`) — abstract queue base class. Methods: `enqueue(fn)`, `dequeue(task)`, `schedule(fn)`, `clear()`, `pause()`, `resume()`.
+- **ListQueue** (`time-queues/ListQueue.js`) — linked-list queue implementation extending MicroTaskQueue. Adds `startQueue()` lifecycle.
+
+### Random utilities
+
+- **random-dist** (`time-queues/random-dist.js`) — `uniform(min, max)`, `normal(mean, stdDev, skewness?)`, `expo(lambda)`, `pareto(min, alpha)`.
+- **random-sleep** (`time-queues/random-sleep.js`) — `randomUniformSleep(min, max)`, `randomNormalSleep(mean, stdDev)`, `randomExpoSleep(lambda, scale)`, `randomParetoSleep(min, ratio)`, `randomSleep(max)`. Each returns `() => Promise<void>`.
+
+### Page load helpers
+
+- **whenDomLoaded** (`time-queues/when-dom-loaded.js`) — `whenDomLoaded(fn)`. Also exports `scheduleWhenDomLoaded(fn): Promise`, `remove(fn): boolean`.
+- **whenLoaded** (`time-queues/when-loaded.js`) — `whenLoaded(fn)`. Also exports `scheduleWhenLoaded(fn): Promise`, `remove(fn): boolean`.
+
+## Key concepts
+
+- All modules are **ESM** with `import ... from 'time-queues/<module>.js'`.
+- **Inheritance**: `MicroTaskQueue` → `ListQueue` → `IdleQueue`/`FrameQueue`/`LimitedQueue`/`PageWatcher`. `Scheduler` extends `MicroTaskQueue` directly.
+- **Lazy promises** — only created when `.makePromise()` is called or via `schedule()`.
+- **Clean cancellation** — all tasks support cancellation via `CancelTaskError`.
+- **Graceful degradation** — feature detection for browser APIs, works in Node.js/Bun/Deno.
+- **TypeScript** — built-in `.d.ts` declarations for all modules.
+
+## Links
+
+- Docs: https://github.com/uhop/time-queues/wiki
+- npm: https://www.npmjs.com/package/time-queues
+- Full LLM reference: https://github.com/uhop/time-queues/blob/master/llms-full.txt

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "time-queues",
-  "version": "1.3.0",
-  "description": "Time queues to organize multitasking and scheduled tasks.",
+  "version": "1.3.1",
+  "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",
   "exports": {
@@ -21,8 +21,14 @@
     "ts-test": "tape6 --flags FO '/ts-tests/test-*.*ts'",
     "ts-test:bun": "tape6-bun --flags FO '/ts-tests/test-*.*ts'",
     "ts-test:deno": "tape6-deno --flags FO '/ts-tests/test-*.*ts'",
-    "lint": "prettier --check src/ tests/ wiki/",
-    "lint:fix": "prettier --write src/ tests/ wiki/",
+    "ts-test:proc": "tape6-proc --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:proc:bun": "bun run `tape6-proc --self` --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:proc:deno": "deno run -A `tape6-proc --self` --flags FO -r -A '/ts-tests/test-*.*ts'",
+    "ts-test:seq": "tape6-seq --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:seq:bun": "bun run `tape6-seq --self` --flags FO '/ts-tests/test-*.*ts'",
+    "ts-test:seq:deno": "deno run -A `tape6-seq --self` --flags FO '/ts-tests/test-*.*ts'",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write .",
     "start": "tape6-server --trace"
   },
   "repository": {
@@ -30,9 +36,25 @@
     "url": "git+ssh://git@github.com/uhop/time-queues.git"
   },
   "keywords": [
+    "scheduler",
+    "task-queue",
+    "async-queue",
+    "concurrency",
+    "throttle",
+    "debounce",
+    "rate-limit",
+    "batch",
+    "sleep",
+    "defer",
+    "idle-queue",
+    "requestIdleCallback",
+    "requestAnimationFrame",
+    "page-lifecycle",
     "timer",
     "time",
-    "queue"
+    "queue",
+    "esm",
+    "typescript"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "funding": "https://github.com/sponsors/uhop",
@@ -40,11 +62,16 @@
   "bugs": {
     "url": "https://github.com/uhop/time-queues/issues"
   },
+  "github": "https://github.com/uhop/time-queues",
   "homepage": "https://github.com/uhop/time-queues#readme",
+  "llms": "https://raw.githubusercontent.com/uhop/time-queues/master/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/time-queues/master/llms-full.txt",
   "files": [
     "/src",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "tape6": {
     "tests": [
@@ -59,12 +86,13 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^25.2.3",
-    "tape-six": "^1.7.0",
-    "tape-six-proc": "^1.2.2",
+    "@types/node": "^25.3.0",
+    "prettier": "^3.8.1",
+    "tape-six": "^1.7.2",
+    "tape-six-proc": "^1.2.3",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "list-toolkit": "^2.2.6"
+    "list-toolkit": "^2.3.0"
   }
 }

package/src/CancelTaskError.d.ts

@@ -2,7 +2,8 @@
  * A cancellation error that is thrown when a microtask is canceled.
  */
 export declare class CancelTaskError extends Error {
-  constructor(message: string = 'Task was canceled', options?: ErrorOptions);
+  name: 'CancelTaskError';
+  constructor(message?: string, options?: ErrorOptions);
 }
 
 export default CancelTaskError;

package/src/CancelTaskError.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./CancelTaskError.d.ts"
 
-'use strict';
-
 export class CancelTaskError extends Error {
   constructor(message = 'Task was canceled', options) {
     super(message, options);

package/src/Counter.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./Counter.d.ts"
 
-'use strict';
-
 export class Counter {
   constructor(initial = 0) {
     this.count = initial;

package/src/FrameQueue.d.ts

@@ -44,7 +44,7 @@ export declare class FrameQueue extends ListQueue {
 
   /**
    * Schedules a task to run in the next frame.
-   * @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.
    * @returns The task object.
    */
   schedule(
@@ -82,4 +82,4 @@ export declare class FrameQueue extends ListQueue {
  */
 export const frameQueue: FrameQueue;
 
-export default FrameQueue;
+export default frameQueue;

package/src/FrameQueue.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./FrameQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 

package/src/IdleQueue.d.ts

@@ -51,7 +51,7 @@ export declare class IdleQueue extends ListQueue {
 
   /**
    * Schedules a task to run in the next idle period.
-   * @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.
    * @returns The task object.
    */
   schedule(
@@ -96,4 +96,4 @@ export const defer: (
   fn: ({deadline: IdleDeadline, task: Task, queue: IdleQueue}) => unknown
 ) => Task;
 
-export default IdleQueue;
+export default idleQueue;

package/src/IdleQueue.js

@@ -1,7 +1,5 @@
 // @ts-self-types="./IdleQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import ListQueue from './ListQueue.js';
 

package/src/LimitedQueue.d.ts

@@ -15,7 +15,7 @@ export declare class LimitedQueue extends ListQueue {
   stopQueue: (() => void) | null;
 
   /**
-   * Creates a new list queue.
+   * Creates a new limited queue.
    * @param limit The maximum number of tasks that can be run in parallel.
    * @param paused Whether the queue should start paused.
    */
@@ -33,7 +33,7 @@ export declare class LimitedQueue extends ListQueue {
 
   /**
    * Set the maximum number of tasks that can be run in parallel.
-   * @param limit The new maximum number of tasks that can be run in parallel. It can dynamically add more tasks if the current number of tasks is less than the new limit.
+   * @param limit The new maximum number of tasks that can be run in parallel. Setting a higher limit may immediately start additional tasks.
    */
   set taskLimit(limit: number);
 
@@ -48,7 +48,7 @@ export declare class LimitedQueue extends ListQueue {
   get isIdle(): boolean;
 
   /**
-   * Wait for queue to become idle.
+   * Waits for the queue to become idle.
    * @returns A promise that resolves when the queue becomes idle. If the queue is already idle, the promise is resolved immediately.
    */
   waitForIdle(): Promise<void>;
@@ -69,7 +69,7 @@ export declare class LimitedQueue extends ListQueue {
 
   /**
    * Schedules a microtask.
-   * @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.
    * @returns The task object.
    */
   schedule(fn: (() => unknown) | null | undefined): Task;

package/src/ListQueue.d.ts

@@ -45,7 +45,7 @@ export declare class ListQueue extends MicroTaskQueue {
 
   /**
    * Schedules a microtask.
-   * @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.
    * @returns The task object.
    */
   schedule(fn: (() => unknown) | null | undefined): MicroTask;

package/src/ListQueue.js

@@ -1,14 +1,20 @@
 // @ts-self-types="./ListQueue.d.ts"
 
-'use strict';
-
 import List from 'list-toolkit/list.js';
 import MicroTaskQueue from './MicroTaskQueue.js';
 
+/**
+ * ListQueue extends MicroTaskQueue with linked-list task storage.
+ * AI-NOTE: This is the concrete base class most specialized queues extend.
+ * Key pattern: startQueue() returns a stop function (or null if not started).
+ * @see IdleQueue, FrameQueue, LimitedQueue, Scheduler - All extend ListQueue
+ */
 export class ListQueue extends MicroTaskQueue {
   constructor(paused) {
     super(paused);
+    // AI-NOTE: Using list-toolkit List for O(1) push/pop operations
     this.list = new List();
+    // AI-NOTE: stopQueue holds the stop function returned by startQueue(), or null
     this.stopQueue = null;
   }
 
@@ -19,6 +25,7 @@ export class ListQueue extends MicroTaskQueue {
   pause() {
     if (!this.paused) {
       super.pause();
+      // AI-NOTE: Pattern: call stop function, then null it
       if (this.stopQueue) this.stopQueue = (this.stopQueue(), null);
     }
     return this;
@@ -27,6 +34,7 @@ export class ListQueue extends MicroTaskQueue {
   resume() {
     if (this.paused) {
       super.resume();
+      // AI-NOTE: Auto-start processing if tasks exist and not already running
       if (!this.list.isEmpty) {
         this.stopQueue = this.startQueue();
       }
@@ -37,6 +45,7 @@ export class ListQueue extends MicroTaskQueue {
   enqueue(fn) {
     const task = super.enqueue(fn);
     this.list.pushBack(task);
+    // AI-NOTE: Auto-start queue on first task if not paused and not running
     if (!this.paused && !this.stopQueue) this.stopQueue = this.startQueue();
     return task;
   }
@@ -44,6 +53,7 @@ export class ListQueue extends MicroTaskQueue {
   dequeue(task) {
     task.cancel();
     this.list.removeNode(task);
+    // AI-NOTE: Auto-stop queue when empty (unless paused)
     if (!this.paused && this.list.isEmpty && this.stopQueue)
       this.stopQueue = (this.stopQueue(), null);
     return this;
@@ -60,7 +70,12 @@ export class ListQueue extends MicroTaskQueue {
     return this;
   }
 
-  // API to be overridden in subclasses
+  /**
+   * Start processing the queue - MUST be overridden by subclasses.
+   * AI-NOTE: This is the abstract method pattern - base returns null.
+   * Subclasses return a function that stops the processing.
+   * @returns {Function|null} Stop function or null if not started
+   */
   startQueue() {
     return null;
   }

package/src/MicroTask.d.ts

@@ -31,6 +31,11 @@ export declare class MicroTask {
    */
   get promise(): Promise<unknown> | null;
 
+  /**
+   * Whether the microtask has been settled (resolved or canceled).
+   */
+  get settled(): boolean;
+
   /**
    * Resolves the microtask, if a promise is created.
    * @param value The value to resolve the microtask with.

package/src/MicroTask.js

@@ -2,6 +2,11 @@
 
 import CancelTaskError from './CancelTaskError.js';
 
+/**
+ * Base class for deferred task execution with lazy promise creation.
+ * AI-NOTE: Promises are created lazily via makePromise() - not in constructor.
+ * This allows tasks to be created without immediate promise overhead.
+ */
 export class MicroTask {
   #promise;
   #resolve;
@@ -9,17 +14,25 @@ export class MicroTask {
   #settled;
   constructor(fn) {
     this.fn = fn;
+    // AI-NOTE: Private fields initialized to null - lazy initialization pattern
     this.#promise = null;
     this.#resolve = null;
     this.#reject = null;
+    this.#settled = false;
     this.isCanceled = false;
   }
+  // AI-NOTE: Returns null until makePromise() is called - this is intentional
   get promise() {
     return this.#promise;
   }
   get settled() {
     return this.#settled;
   }
+  /**
+   * Creates the promise and resolution functions.
+   * AI-NOTE: Uses Promise.withResolvers() when available (modern environments),
+   * falls back to manual Promise constructor for broader compatibility.
+   */
   makePromise() {
     if (this.#promise) return this;
     if (typeof Promise.withResolvers == 'function') {
@@ -45,6 +58,10 @@ export class MicroTask {
     }
     return this;
   }
+  /**
+   * Cancel the task with optional error cause.
+   * AI-NOTE: Always rejects with CancelTaskError to distinguish from other errors.
+   */
   cancel(error) {
     this.isCanceled = true;
     if (this.#reject) {

package/src/MicroTaskQueue.d.ts

@@ -42,8 +42,8 @@ export declare class MicroTaskQueue {
   /**
    * 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()`. It is there to accommodate custom implementations in subclasses.
+   * @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, ...args: unknown[]): MicroTask;

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,7 +41,11 @@ 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(

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,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);
 
@@ -112,7 +113,7 @@ export declare class Scheduler extends MicroTaskQueue {
 
   /**
    * 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.
    */

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