time-queues 1.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Eugene Lazutkin
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,332 @@
+# time-queues [![NPM version][npm-img]][npm-url]
+
+[npm-img]: https://img.shields.io/npm/v/time-queus.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:
+
+* 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.
+
+Internally it uses [List Toolkit](https://github.com/uhop/list-toolkit) and leverages the following browser APIs:
+
+* [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.
+
+## Installation
+
+```sh
+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
+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/test.html — 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()`.
+
+### Scheduler
+
+`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` is not based on `ListQueue`, but implements its API.
+The following additional methods are available:
+
+| 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();
+```
+
+#### 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));
+});
+```
+
+### 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'));
+```
+
+## License
+
+This project is licensed under the BSD-3-Clause License.
+
+## Release History
+
+* 1.0.0 *Initial release.*

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "time-queues",
+  "version": "1.0.0",
+  "description": "Time queues to organize multitasking and scheduled tasks.",
+  "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
+  "scripts": {
+    "test": "tape6 --flags FO",
+    "start": "tape6-server --trace"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/uhop/time-queues.git"
+  },
+  "keywords": [
+    "timer",
+    "time",
+    "queue"
+  ],
+  "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/uhop/time-queues/issues"
+  },
+  "homepage": "https://github.com/uhop/time-queues#readme",
+  "files": [
+    "/src"
+  ],
+  "tape6": {
+    "tests": [
+      "/tests/test-*.*js"
+    ]
+  },
+  "devDependencies": {
+    "tape-six": "^0.9.5"
+  },
+  "dependencies": {
+    "list-toolkit": "^1.0.2"
+  }
+}

package/src/FrameQueue.js

@@ -0,0 +1,44 @@
+'use strict';
+
+import List from 'list-toolkit/List.js';
+import ListQueue from './ListQueue.js';
+
+export class FrameQueue extends ListQueue {
+  constructor(paused, batchInMs) {
+    super(paused);
+    this.batch = batchInMs;
+  }
+
+  startQueue() {
+    const handle = requestAnimationFrame(this.processTasks.bind(this));
+    return () => void cancelAnimationFrame(handle);
+  }
+
+  processTasks(timeStamp) {
+    if (this.stopQueue) {
+      this.stopQueue();
+      this.stopQueue = null;
+    }
+
+    if (!isNaN(this.batch)) {
+      const start = Date.now();
+      while (Date.now() - start < this.batch && !this.list.isEmpty) {
+        const task = this.list.popFront();
+        task.fn(timeStamp, task, this);
+      }
+    } else {
+      const list = this.list;
+      this.list = new List();
+      while (!list.isEmpty) {
+        const task = list.popFront();
+        task.fn(timeStamp, task, this);
+      }
+    }
+
+    if (!this.list.isEmpty) this.stopQueue = this.startQueue();
+  }
+}
+
+export const frameQueue = new FrameQueue();
+
+export default frameQueue;

package/src/IdleQueue.js

@@ -0,0 +1,56 @@
+'use strict';
+
+import List from 'list-toolkit/List.js';
+import ListQueue from './ListQueue.js';
+
+// Based on information from https://developer.mozilla.org/en-US/docs/Web/API/Background_Tasks_API
+
+export class IdleQueue extends ListQueue {
+  constructor(paused, timeoutBatchInMs, options) {
+    super(paused);
+    this.timeoutBatch = timeoutBatchInMs;
+    this.options = options;
+  }
+
+  startQueue() {
+    const handle = requestIdleCallback(this.processTasks.bind(this), this.options);
+    return () => void cancelIdleCallback(handle);
+  }
+
+  processTasks(deadline) {
+    if (this.stopQueue) {
+      this.stopQueue();
+      this.stopQueue = null;
+    }
+
+    if (deadline.didTimeout) {
+      if (!isNaN(this.timeoutBatch)) {
+        const start = Date.now();
+        while (Date.now() - start < this.timeoutBatch && !this.list.isEmpty) {
+          const task = this.list.popFront();
+          task.fn(deadline, task, this);
+        }
+      } else {
+        const list = this.list;
+        this.list = new List();
+        while (!list.isEmpty) {
+          const task = list.popFront();
+          task.fn(deadline, task, this);
+        }
+      }
+    } else {
+      while (deadline.timeRemaining() > 0 && !this.list.isEmpty) {
+        const task = this.list.popFront();
+        task.fn(deadline, task, this);
+      }
+    }
+
+    if (!this.list.isEmpty) this.stopQueue = this.startQueue();
+  }
+}
+
+export const idleQueue = new IdleQueue();
+
+export const defer = idleQueue.enqueue.bind(idleQueue);
+
+export default idleQueue;

package/src/ListQueue.js

@@ -0,0 +1,68 @@
+'use strict';
+
+import List from 'list-toolkit/List.js';
+import MicroTaskQueue from './MicroTaskQueue.js';
+
+export class ListQueue extends MicroTaskQueue {
+  constructor(paused) {
+    super(paused);
+    this.list = new List();
+    this.stopQueue = null;
+  }
+
+  get isEmpty() {
+    return this.list.isEmpty;
+  }
+
+  pause() {
+    if (!this.paused) {
+      super.pause();
+      if (this.stopQueue) this.stopQueue = (this.stopQueue(), null);
+    }
+    return this;
+  }
+
+  resume() {
+    if (this.paused) {
+      super.resume();
+      if (!this.list.isEmpty) {
+        this.stopQueue = this.startQueue();
+      }
+    }
+    return this;
+  }
+
+  enqueue(fn) {
+    const task = super.enqueue(fn);
+    this.list.pushBack(task);
+    if (!this.paused && !this.stopQueue) this.stopQueue = this.startQueue();
+    return task;
+  }
+
+  dequeue(task) {
+    for (const node of this.list.getNodeIterator()) {
+      if (node.value === task) {
+        List.pop(node);
+        break;
+      }
+    }
+    if (!this.paused && this.list.isEmpty && this.stopQueue)
+      this.stopQueue = (this.stopQueue(), null);
+    return this;
+  }
+
+  clear() {
+    const paused = this.paused;
+    if (!paused) this.pause();
+    this.list.clear();
+    if (!paused) this.resume();
+    return this;
+  }
+
+  // API to be overridden in subclasses
+  startQueue() {
+    return null;
+  }
+}
+
+export default ListQueue;

package/src/MicroTask.js

@@ -0,0 +1,9 @@
+'use strict';
+
+export class MicroTask {
+  constructor(fn) {
+    this.fn = fn;
+  }
+}
+
+export default MicroTask;

package/src/MicroTaskQueue.js

@@ -0,0 +1,33 @@
+'use strict';
+
+import MicroTask from './MicroTask.js';
+
+export class MicroTaskQueue {
+  constructor(paused) {
+    this.paused = Boolean(paused);
+  }
+  // API to be overridden in subclasses
+  get isEmpty() {
+    return true;
+  }
+  pause() {
+    this.paused = true;
+    return this;
+  }
+  resume() {
+    this.paused = false;
+    return this;
+  }
+  enqueue(fn) {
+    const task = new MicroTask(fn);
+    return task;
+  }
+  dequeue(task) {
+    return this;
+  }
+  clear() {
+    return this;
+  }
+}
+
+export default MicroTaskQueue;

package/src/PageWatcher.js

@@ -0,0 +1,99 @@
+'use strict';
+
+import ListQueue from './ListQueue.js';
+
+// Based on information from https://developer.chrome.com/docs/web-platform/page-lifecycle-api
+
+const eventHandlerOptions = {capture: true},
+  watchedEvents = ['pageshow', 'pagehide', 'focus', 'blur', 'visibilitychange', 'resume', 'freeze'];
+
+// valid states: active, passive, hidden, frozen, terminated
+
+const getState = () => {
+  if (document.visibilityState === 'hidden') {
+    return 'hidden';
+  }
+  if (document.hasFocus()) {
+    return 'active';
+  }
+  return 'passive';
+};
+
+export class PageWatcher extends ListQueue {
+  constructor(started) {
+    super(!started);
+    this.currentState = getState();
+    if (started) this.resume();
+  }
+
+  pause() {
+    this.paused = true;
+    watchedEvents.forEach(type => removeEventListener(type, this, eventHandlerOptions));
+    return super.pause();
+  }
+
+  resume() {
+    watchedEvents.forEach(type => addEventListener(type, this, eventHandlerOptions));
+    return super.resume();
+  }
+
+  enqueue(fn, initialize) {
+    const task = super.enqueue(fn);
+    if (initialize) queueMicrotask(() => fn(this.currentState, this.currentState, task, this));
+    return task;
+  }
+
+  // Implemented in ListQueue: dequeue()
+
+  clear() {
+    this.list.clear();
+    return this;
+  }
+
+  startQueue() {
+    return null;
+  }
+
+  handleEvent(event) {
+    let state = this.currentState;
+
+    switch (event.type) {
+      case 'freeze':
+        state = 'frozen';
+        break;
+      case 'pagehide':
+        state = event.persisted ? 'frozen' : 'terminated';
+        break;
+      default:
+        state = getState();
+        break;
+    }
+
+    if (this.currentState === state) return;
+
+    for (const task of this.list) {
+      task.fn(state, this.currentState, task, this);
+    }
+
+    this.currentState = state;
+  }
+}
+
+export const watchStates = (queue, resumeStatesList = ['active']) => {
+  const resumeStates = new Set(resumeStatesList);
+
+  // queues can be paused and resumed at any time
+  // so we don't need to check if queue is paused
+  // calling pause/resume multiple times is fine
+  return state => {
+    if (resumeStates.has(state)) {
+      queue.resume();
+    } else {
+      queue.pause();
+    }
+  };
+};
+
+export const pageWatcher = new PageWatcher();
+
+export default pageWatcher;

package/src/Scheduler.js

@@ -0,0 +1,125 @@
+'use strict';
+
+import MinHeap from 'list-toolkit/MinHeap.js';
+import MicroTask from './MicroTask.js';
+import MicroTaskQueue from './MicroTaskQueue.js';
+
+export class Task extends MicroTask {
+  constructor(delay, fn) {
+    super(fn);
+    if (delay instanceof Date) {
+      this.time = delay.getTime();
+      this.delay = this.time - Date.now();
+    } else {
+      this.time = Date.now() + delay;
+      this.delay = delay;
+    }
+  }
+}
+
+export class Scheduler extends MicroTaskQueue {
+  constructor(paused, tolerance = 4) {
+    super(paused);
+    this.queue = new MinHeap({less: (a, b) => a.time < b.time});
+    this.tolerance = tolerance;
+    this.stopQueue = null;
+  }
+
+  get isEmpty() {
+    return this.queue.isEmpty;
+  }
+
+  get nextTime() {
+    return this.queue.isEmpty ? Infinity : this.queue.top.time;
+  }
+
+  pause() {
+    if (!this.paused) {
+      this.paused = true;
+      if (this.stopQueue) this.stopQueue = (this.stopQueue(), null);
+    }
+    return this;
+  }
+
+  resume() {
+    if (this.paused) {
+      this.paused = false;
+      this.processTasks();
+    }
+    return this;
+  }
+
+  enqueue(fn, delay) {
+    const task = new Task(delay, fn);
+
+    if (this.paused) {
+      this.queue.push(task);
+      return task;
+    }
+
+    const nextTime = this.nextTime;
+    this.queue.push(task);
+    if (nextTime > this.nextTime) {
+      if (this.stopQueue) this.stopQueue();
+      this.stopQueue = this.startQueue();
+    }
+
+    return task;
+  }
+
+  dequeue(task) {
+    if (this.queue.isEmpty) return this;
+    if (this.paused || this.queue.top !== task) {
+      this.queue.remove(task);
+      return this;
+    }
+
+    // we are not paused and the task is the top => remove top and restart a timer if needed
+    this.pause();
+    this.queue.pop();
+    this.resume();
+    return this;
+  }
+
+  clear() {
+    const paused = this.paused;
+    if (!paused) this.pause();
+    this.queue.clear();
+    if (!paused) this.resume();
+  }
+
+  startQueue() {
+    const handle = setTimeout(
+      this.processTasks.bind(this),
+      Math.max(this.nextTime - Date.now(), 0)
+    );
+    return () => void clearTimeout(handle);
+  }
+
+  processTasks() {
+    if (this.stopQueue) this.stopQueue = (this.stopQueue(), null);
+
+    while (
+      !this.queue.isEmpty &&
+      !this.paused &&
+      this.queue.top.time <= Date.now() + this.tolerance
+    ) {
+      const task = this.queue.pop();
+      task.fn(task, this);
+    }
+
+    if (!this.paused && !this.queue.isEmpty) this.stopQueue = this.startQueue();
+  }
+}
+
+export const repeat = (fn, delay) => {
+  const repeatableTask = (task, scheduler) => {
+    fn(task, scheduler);
+    scheduler.enqueue(repeatableTask, isNaN(delay) ? task.delay : delay);
+  };
+  return repeatableTask;
+};
+
+export const scheduler = new Scheduler();
+
+export default scheduler;

package/src/defer.js

@@ -0,0 +1,13 @@
+'use strict';
+
+let deferImplementation = setTimeout;
+
+if (typeof requestIdleCallback == 'function') {
+  deferImplementation = requestIdleCallback;
+} else if (typeof setImmediate == 'function') {
+  deferImplementation = setImmediate;
+}
+
+export const defer = fn => void deferImplementation(() => fn());
+
+export default defer;

package/src/when-dom-loaded.js

@@ -0,0 +1,35 @@
+'use strict';
+
+import List from 'list-toolkit/List.js';
+
+const waitingForDom = new List();
+
+export const remove = fn => {
+  for (const node of waitingForDom.getNodeIterable()) {
+    if (node.value === fn) {
+      List.pop(node);
+      return true;
+    }
+  }
+  return false;
+}
+
+const handleDomLoaded = () => {
+  while (!waitingForDom.isEmpty) waitingForDom.pop()();
+};
+
+export const whenDomLoaded = fn => {
+  const wasEmpty = waitingForDom.isEmpty;
+  waitingForDom.push(fn);
+
+  switch (document.readyState) {
+    case 'complete':
+    case 'interactive':
+      queueMicrotask(handleDomLoaded);
+      return;
+  }
+
+  if (wasEmpty) document.addEventListener('DOMContentLoaded', handleDomLoaded);
+};
+
+export default whenDomLoaded;

package/src/when-loaded.js

@@ -0,0 +1,33 @@
+'use strict';
+
+import List from 'list-toolkit/List.js';
+
+const waitingForLoad = new List();
+
+export const remove = fn => {
+  for (const node of waitingForLoad.getNodeIterable()) {
+    if (node.value === fn) {
+      List.pop(node);
+      return true;
+    }
+  }
+  return false;
+}
+
+const handleLoaded = () => {
+  while (!waitingForLoad.isEmpty) waitingForLoad.pop()();
+};
+
+export const whenLoaded = fn => {
+  const wasEmpty = waitingForLoad.isEmpty;
+  waitingForLoad.push(fn);
+
+  if (document.readyState === 'complete') {
+    queueMicrotask(handleLoaded);
+    return;
+  }
+
+  if (wasEmpty) window.addEventListener('load', handleLoaded);
+};
+
+export default whenLoaded;