time-queues 1.0.4 → 1.1.0

package/README.md

@@ -3,45 +3,18 @@
 [npm-img]: https://img.shields.io/npm/v/time-queues.svg
 [npm-url]: https://npmjs.org/package/time-queues
 
-`time-queues` is an efficient library for organizing asynchronous multitasking and scheduled tasks.
-It can be used in a browser and in server-side environments like `Node`, `Deno` and `Bun`.
-It depends only on [list-toolkit](https://github.com/uhop/list-toolkit), which is a no-dependency library for efficient task queues.
 
-The following features are provided:
+`time-queues` is an efficient, lightweight library for organizing asynchronous multitasking and scheduled tasks in JavaScript applications. It works seamlessly in browsers and server-side environments like Node.js, Deno, and Bun.
 
-* All environments:
-  * **Scheduler**: a `MinHeap`-based task queue that schedules time-based tasks in the future.
-    * **repeat()**: a function that creates a repeatable task.
-  * **defer()**: a function that executes a task at a later time in the next tick.
-* Browsers:
-  * Efficient multitasking:
-    * **IdleQueue**: a task queue that executes tasks in the next idle period.
-      * Based on [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback).
-      * **defer()**: a function that executes a task at a later time in the next idle period.
-    * **FrameQueue**: a task queue that executes tasks in the next frame.
-      * Based on [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame).
-  * Page state management:
-    * **PageWatcher**: a task queue that executes tasks when the page state changes.
-      * **watchStates()**: a helper that pauses and resumes queues when the page state changes.
-    * **whenDomLoaded()**: a helper that executes tasks when the DOM is loaded.
-    * **whenLoaded()**: a helper that executes tasks when the page is loaded.
+The library provides elegant solutions for common timing and scheduling challenges, helping developers create responsive, efficient applications that follow best practices for resource management and user experience.
 
-Internally it uses [List Toolkit](https://github.com/uhop/list-toolkit) and leverages the following browser APIs:
+## Key Features
 
-* [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback)
-* [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
-* [queueMicrotask()](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)
-* [setTimeout()](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout)
-* Various events and properties.
-
-There are many articles on the subject that detail how to leverage the APIs writing efficient applications.
-Some of them are:
-
-* [Background Tasks API](https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API)
-* [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
-* [Page Lifecycle API](https://developer.chrome.com/docs/web-platform/page-lifecycle-api)
-
-This package eliminates the need to write code that you'll write anyway following best practices.
+- **Efficient Task Scheduling**: Schedule tasks to run at specific times or after delays
+- **Browser Performance Optimization**: Execute tasks during idle periods or animation frames
+- **Page Lifecycle Management**: Respond intelligently to page visibility and focus changes
+- **Resource Management**: Control execution rates with throttling and debouncing
+- **Minimal Dependencies**: Relies only on [list-toolkit](https://www.npmjs.com/package/list-toolkit), a zero-dependency library
 
 ## Installation
 
@@ -52,277 +25,35 @@ npm install time-queues
 If you want to check out the source code, you can use the following command:
 
 ```sh
-git clone https://github.com/uhop/time-queues.git
+git clone --recurse-submodules https://github.com/uhop/time-queues.git
 cd time-queues
 npm install
 ```
 
-Don't forget to look at a test web application that uses the library. For that you should start a server:
-
-```sh
-npm start
-```
-
-And navigate to [http://localhost:3000/tests/web/](http://localhost:3000/tests/web/) —
-don't forget to open the console and play around: switch tabs, make other window active,
-navigate away and come back, and so on.
-See how queues work in [tests/web/test.js](https://github.com/uhop/time-queues/blob/main/tests/web/test.js).
-
 ## Usage
 
-The full documentation is available in the project's [wiki](https://github.com/uhop/time-queues/wiki). Below is a cheat sheet of the API.
-
-### ListQueue
-
-`ListQueue` is a list-based task queue that executes tasks in the order they were added.
-It serves as a base class for other task queues. The following methods are available:
-
-| Method | Description |
-|:---|:---|
-| `ListQueue(paused)` | Create a new list queue (paused optionally). |
-| `isEmpty` | Check if the list queue is empty. |
-| `pause()` | Pause the list queue. |
-| `resume()` | Resume the list queue. |
-| `enqueue(fn)` | Schedule a function to be executed. Returns the task. |
-| `dequeue(task)` | Remove a task from the list queue. |
-| `clear()` | Remove all tasks from the list queue. |
-
-Subclasses should implement `startQueue()`.
+The full documentation is available in the project's [wiki](https://github.com/uhop/time-queues/wiki). Below is the most important parts of the documentation:
 
-### Scheduler
+### Resource Management
 
-`Scheduler` is a `MinHeap`-based task queue that schedules time-based tasks in the future.
-It can used to run periodic updates or one-time events.
+- [Scheduler](https://github.com/uhop/time-queues/wiki/Scheduler): Time-based task scheduling
+- [Retainer](https://github.com/uhop/time-queues/wiki/Retainer): Manage resource lifecycle
+- [Throttler](https://github.com/uhop/time-queues/wiki/Throttler): Control execution rate based on keys
 
-`Scheduler` is not based on `ListQueue`, but implements its API.
-The following additional methods are available:
+### Browser-Specific Components
 
-| Method | Description |
-|:---|:---|
-| `Scheduler(paused)` | Create a new scheduler (paused optionally). |
-| `nextTime` | Get the next scheduled time or 'Infinity` if the scheduler is empty. |
-| `enqueue(fn, time)` | Schedule a function to be executed at a later time. Returns the task. `time` can be a date or a number in milliseconds from now. |
-
-Scheduled functions are called once with the following arguments:
-
-* `fn(task, scheduler)`, where:
-  * `fn` — the scheduled function.
-  * `task` — the task object that corresponds to the scheduled function.
-  * `scheduler` — the scheduler object.
-
-The return value is ignored.
-
-The module provides a singleton ready to be used:
-
-```js
-import scheduler, {repeat} from 'time-queues/Scheduler.js';
-
-// schedule a task
-const task = scheduler.enqueue(() => console.log('The first task'), 1000);
-
-// run a task every second
-const hello = () => {
-  console.log('Hello, world!');
-  scheduler.enqueue(hello, 1000);
-};
-scheduler.enqueue(hello, 1000);
-
-// pause the scheduler
-scheduler.pause();
-
-// remove the first task
-scheduler.dequeue(task);
-
-// remove all tasks
-scheduler.clear();
-```
+- [IdleQueue](https://github.com/uhop/time-queues/wiki/IdleQueue): Execute tasks during browser idle periods
+- [FrameQueue](https://github.com/uhop/time-queues/wiki/FrameQueue): Execute tasks during animation frames
+- [PageWatcher](https://github.com/uhop/time-queues/wiki/PageWatcher): Monitor and respond to page lifecycle changes
 
-#### repeat()
-
-The module provides a helper function `repeat()` that creates a repeatable task:
-
-* `repeat(fn, interval)`, where:
-  * `fn` — the scheduled function.
-  * `interval` — the interval in milliseconds. If not specified the corresponding task delay is used.
-
-We can rewrite the above example using `repeat()`:
-
-```js
-// run a task every second
-scheduler.enqueue(repeat(() => console.log('Hello, world!'), 1000));
-```
-
-### defer()
-
-`defer(fn)` is a function that executes an argument function at a later time in the next tick.
-
-Deferred functions are called with no arguments. The return value is ignored.
-
-```js
-import defer from 'time-queues/defer.js';
-
-// run a task in the next tick
-defer(() => console.log('Goodbye, world!'));
-
-// run code now
-console.log('Hello, world!');
-```
-
-### IdleQueue
-
-`IdleQueue` is a task queue that executes tasks in the next idle period. It implements `ListQueue` and is based on [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback).
-
-Efficient web applications should use `IdleQueue` to schedule computations required to prepare data and
-even create necessary DOM elements.
-See [Background Tasks API](https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API) for more information.
-
-Queued functions are called once with the following arguments:
-
-* `fn(deadline, task, idleQueue)`, where:
-  * `fn` — the scheduled function.
-  * `deadline` — the deadline object. See [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback) for more information.
-  * `task` — the task object that corresponds to the scheduled function.
-  * `idleQueue` — the idle queue object.
-
-The return value is ignored.
-
-The module provides a singleton ready to be used:
-
-```js
-import idleQueue from 'time-queues/IdleQueue.js';
-import frameQueue from 'time-queues/FrameQueue.js';
-
-idleQueue.enqueue(() => {
-  // prepare our data and generate DOM
-  const div = document.createElement('div');
-  div.appendChild(document.createTextNode('Hello, world!'));
-  // now update the DOM in the next frame
-  frameQueue.enqueue(() => document.body.appendChild(div));
-});
-```
+### Utility Functions
 
-### FrameQueue
-
-`FrameQueue` is a task queue that executes tasks in the next frame. It implements `ListQueue` and is based on [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame).
-
-Efficient web applications should use `FrameQueue` to schedule DOM updates.
-See [Background Tasks API](https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API) for more information.
-
-Queued functions are called once with the following arguments:
-
-* `fn(timeStamp, task, frameQueue)`, where:
-  * `fn` — the scheduled function.
-  * `timeStamp` — the timestamp object. See [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) for more information.
-  * `task` — the task object that corresponds to the scheduled function.
-  * `frameQueue` — the frame queue object.
-
-The return value is ignored.
-
-The module provides a singleton ready to be used. See the code snippet `IdleQueue` above for more information.
-
-### PageWatcher
-
-`PageWatcher` is a task queue that executes tasks when the page state changes. It is based on [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API).
-You can find more information in [Page Lifecycle API](https://developer.chrome.com/docs/web-platform/page-lifecycle-api).
-
-Efficient web applications should use `PageWatcher` to watch for page visibility changes and react accordingly, for example, by suspending updates in the hidden state.
-
-`PageWatcher` implements `ListQueue`. The following additional/changed methods are available:
-
-| Method | Description |
-|:---|:---|
-| `PageWatcher(started)` | Create a new page watcher (started optionally). |
-| `currentState` | Get the current page state (see below). |
-| `enqueue(fn, initialize)` | Schedule a function to be executed. Returns the task. If `initialize` is truthy, the function will be queued and called immediately with the current state. |
-
-A page state can be one of the following strings:
-
-* `active` — the page is a current window, it is visible and the user can interact with it.
-* `passive` — the page is not a current window, it is visible, but the user cannot interact with it.
-* `hidden` — the page is not visible.
-* `frozen` — the page is suspended, no timers nor fetch callbacks can be executed.
-* `terminated` — the page is terminated, no new tasks can be started.
-
-Queued functions are called on every state change with the following arguments:
-
-* `fn(state, previousState, task, pageWatcher)`, where:
-  * 'fn` — the scheduled function.
-  * `state` — the new page state.
-  * `previousState` — the previous page state.
-  * `task` — the task object that corresponds to the scheduled function.
-  * `pageWatcher` — the page watcher object.
-
-The return value is ignored.
-
-The module provides a singleton ready to be used.
-
-```js
-import pageWatcher from 'time-queues/PageWatcher.js';
-
-pageWatcher.enqueue(state => console.log('state:', state), true);
-```
-
-#### watchStates()
-
-`watchStates()` is a helper that pauses and resumes queues when the page state changes.
-It can be added to a `PageWatcher` object controlling a `Scheduler` object or any other queue
-to pause it depending on a page state.
-
-The function signature is:
-
-* `watchStates(queue, resumeStatesList = ['active'])`, where:
-  * `queue` — the queue object to be controlled.
-  * `resumeStatesList` — the iterable of page states to `resume()`. All other states will pause the queue. Defaults to 'active'.
-
-The return value is a function that is suitable for `PageWatcher.enqueue()`.
-
-```js
-import pageWatcher, {watchStates} from 'time-queues/PageWatcher.js';
-import scheduler from 'time-queues/Scheduler.js';
-
-// do not process time-based tasks when the page is not visible
-pageWatcher.enqueue(watchStates(scheduler, ['active', 'passive']), true);
-```
-
-### whenDomLoaded()
-
-`whenDomLoaded()` is a helper that executes a function when the DOM is loaded.
-If the DOM is already loaded, the function will be executed with `queueMicrotask()`.
-Otherwise it'll be queued and executed when the DOM is loaded.
-See [DOMContentLoaded](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event) for more information.
-
-The function signature is:
-
-* `whenDomLoaded(fn)`, where:
-  * `fn` — the function to be executed when the DOM is loaded.
-
-It will be called with no arguments. The return value is ignored.
-
-```js
-import whenDomLoaded from 'time-queues/whenDomLoaded.js';
-
-whenDomLoaded(() => console.log('The DOM is loaded'));
-```
-
-### whenLoaded()
-
-`whenLoaded()` is a helper that executes a function when the page is fully loaded.
-If the page is already loaded, the function will be executed with `queueMicrotask()`.
-Otherwise it'll be queued and executed when the page is loaded.
-See [load](https://developer.mozilla.org/en-US/docs/Web/Events/load) for more information.
-
-The function signature is:
-
-* `whenLoaded(fn)`, where:
-  * `fn` — the function to be executed when the page is loaded.
-
-It will be called with no arguments. The return value is ignored.
-
-```js
-import whenLoaded from 'time-queues/whenLoaded.js';
-
-whenLoaded(() => console.log('The page is loaded'));
-```
+- [defer()](<https://github.com/uhop/time-queues/wiki/defer()>): Execute tasks in the next tick
+- [sleep()](<https://github.com/uhop/time-queues/wiki/sleep()>): Promise-based delay function
+- [throttle()](<https://github.com/uhop/time-queues/wiki/throttle()>): Limit function execution rate
+- [debounce()](<https://github.com/uhop/time-queues/wiki/debounce()>): Delay function execution until input stabilizes
+- [sample()](<https://github.com/uhop/time-queues/wiki/sample()>): Execute function at regular intervals
+- [audit()](<https://github.com/uhop/time-queues/wiki/audit()>): Execute function after specified delay
 
 ## License
 
@@ -330,6 +61,8 @@ This project is licensed under the BSD-3-Clause License.
 
 ## Release History
 
+* 1.1.0 *Added `Throttler`, `Retainer`, promise-based convenience time methods.*
+* 1.0.5 *Technical release: updated deps, more tests.*
 * 1.0.4 *Bug fixes and code simplifications.*
 * 1.0.3 *Updated deps (`list-toolkit`) to fix a minor bug.*
 * 1.0.2 *Updated deps (`list-toolkit`).*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "time-queues",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Time queues to organize multitasking and scheduled tasks.",
   "type": "module",
   "exports": {
@@ -11,6 +11,12 @@
     "test:bun": "tape6-bun --flags FO",
     "test:deno-original": "tape6-deno --flags FO",
     "test:deno": "deno run -A `tape6-runner main` --flags FO",
+    "test:proc": "tape6-proc --flags FO",
+    "test:proc:bun": "bun run `npx tape6-proc --self` --flags FO",
+    "test:proc:deno": "deno run -A `npx tape6-proc --self` --flags FO --runFileArgs -A",
+    "ts-check": "tsc --noEmit",
+    "lint": "prettier --check src/ tests/ wiki/",
+    "lint:fix": "prettier --write src/ tests/ wiki/",
     "start": "tape6-server --trace"
   },
   "repository": {
@@ -30,7 +36,9 @@
   },
   "homepage": "https://github.com/uhop/time-queues#readme",
   "files": [
-    "/src"
+    "/src",
+    "LICENSE",
+    "README.md"
   ],
   "tape6": {
     "tests": [
@@ -39,14 +47,18 @@
     "importmap": {
       "imports": {
         "tape-six": "/node_modules/tape-six/index.js",
+        "list-toolkit/": "/node_modules/list-toolkit/src/",
         "time-queues/": "/src/"
       }
     }
   },
   "devDependencies": {
-    "tape-six": "^0.12.2"
+    "@types/node": "^22.13.10",
+    "tape-six": "^1.0.3",
+    "tape-six-proc": "^1.0.1",
+    "typescript": "^5.8.2"
   },
   "dependencies": {
-    "list-toolkit": "^2.1.1"
+    "list-toolkit": "^2.2.1"
   }
 }

package/src/FrameQueue.d.ts

@@ -0,0 +1,71 @@
+import {ListQueue, Task} from './ListQueue';
+
+/**
+ * A queue based on [requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame).
+ * Used in an animation loop or for drawing updates.
+ */
+export declare class FrameQueue extends ListQueue {
+  /**
+   * The batch size in milliseconds for running tasks.
+   * If `undefined`, all tasks are run in a single frame.
+   */
+  batch: number | undefined;
+
+  /**
+   * Creates a new frame queue.
+   * @param paused Whether the queue should start paused.
+   * @param batchInMs The batch size in milliseconds.
+   */
+  constructor(paused: boolean = false, batchInMs?: number);
+
+  /**
+   * Whether the queue is empty.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Enqueues a task.
+   * @param fn The function to execute.
+   * @returns The task object.
+   */
+  enqueue(fn: (timeStamp: number, task: Task, queue: FrameQueue) => void): 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;
+
+  /**
+   * Starts the queue.
+   * It is used internally by `resume()`.
+   * @returns The function that stops the queue.
+   */
+  startQueue(): (() => void) | null;
+}
+
+/**
+ * The default frame queue usually used as a global queue.
+ */
+export const frameQueue: FrameQueue;
+
+export default FrameQueue;

package/src/FrameQueue.js

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

package/src/IdleQueue.d.ts

@@ -0,0 +1,83 @@
+import {ListQueue, Task} from './ListQueue';
+
+/**
+ * A queue based on [requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback).
+ * Used for background tasks.
+ */
+export declare class IdleQueue extends ListQueue {
+  /**
+   * The timeout batch size in milliseconds for running tasks.
+   * If `undefined`, all tasks are run in a single idle period.
+   * This timeout is used only when `deadline.didTimeout` passed by `requestIdleCallback()` is `true`.
+   */
+  timeoutBatch: number | undefined;
+
+  /**
+   * The options passed to `requestIdleCallback()`.
+   */
+  options: IdleCallbackOptions | undefined;
+
+  /**
+   * Creates a new idle queue.
+   * @param paused Whether the queue should start paused.
+   * @param timeoutBatchInMs The timeout batch size in milliseconds.
+   * @param options The options passed to `requestIdleCallback()`.
+   */
+  constructor(paused: boolean = false, timeoutBatchInMs?: number, options?: IdleCallbackOptions);
+
+  /**
+   * Whether the queue is empty.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Enqueues a task.
+   * @param fn The function to execute.
+   * @returns The task object.
+   */
+  enqueue(fn: (deadline: IdleDeadline, task: Task, queue: IdleQueue) => void): 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;
+
+  /**
+   * Starts the queue.
+   * It is used internally by `resume()`.
+   * @returns The function that stops the queue.
+   */
+  startQueue(): (() => void) | null;
+}
+
+/**
+ * The default idle queue usually used as a global queue.
+ */
+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) => void) => Task;
+
+export default IdleQueue;

package/src/IdleQueue.js

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

package/src/ListQueue.d.ts

@@ -0,0 +1,77 @@
+import {MicroTask} from './MicroTask';
+import {List} from 'list-toolkit';
+
+/**
+ * A list-based queue of microtasks that will be executed when scheduled.
+ * It is a base class for other list-based task queues.
+ */
+export declare class ListQueue extends MicroTaskQueue {
+  /**
+   * The list of tasks.
+   */
+  list: List<MicroTask>;
+
+  /**
+   * The function that stops the queue.
+   * It is used internally by `pause()` and `resume()`.
+   */
+  stopQueue: (() => void) | null;
+
+  /**
+   * Creates a new list queue.
+   * @param paused Whether the queue should start paused.
+   */
+  constructor(paused: boolean);
+
+  /**
+   * Whether the queue is empty.
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Enqueues a microtask.
+   * @param fn The function to execute when the microtask is scheduled.
+   * @returns The enqueued microtask.
+   */
+  enqueue(fn: () => void): MicroTask;
+
+  /**
+   * Dequeues a microtask.
+   * @param task The microtask to dequeue.
+   * @returns The queue.
+   */
+  dequeue(task: MicroTask): 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;
+
+  /**
+   * Starts the queue.
+   * It is used internally by `resume()`.
+   * It is meant to be overridden in subclasses.
+   * @returns The function that stops the queue.
+   */
+  startQueue(): (() => void) | null;
+}
+
+/**
+ * A task for list queues.
+ */
+export declare type Task = MicroTask;
+
+export default ListQueue;

package/src/ListQueue.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./ListQueue.d.ts"
+
 'use strict';
 
 import List from 'list-toolkit/list.js';
@@ -40,7 +42,7 @@ export class ListQueue extends MicroTaskQueue {
   }
 
   dequeue(task) {
-    List.pop(task);
+    this.list.removeNode(task);
     if (!this.paused && this.list.isEmpty && this.stopQueue)
       this.stopQueue = (this.stopQueue(), null);
     return this;