tiny-essentials 1.12.2 → 1.13.0

package/dist/v1/libs/TinyDomReadyManager.cjs

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * A basic function that performs a task when the system is ready.
+ * Used for handlers in the readiness queue.
+ *
+ * @typedef {() => void} Fn
+ */
+
+/**
+ * A function that determines whether a specific handler should be executed.
+ * Should return `true` to allow execution, or `false` to skip the handler.
+ *
+ * @typedef {() => boolean} FnFilter
+ */
+
+/**
+ * @typedef {Object} Handler
+ * @property {Fn} fn - Function to execute when ready.
+ * @property {boolean} once - Whether to execute only once.
+ * @property {number} priority - Execution order (higher priority runs first).
+ * @property {FnFilter|null} filter - Optional filter function to determine execution.
+ * @property {boolean} domOnly - Whether to run as soon as DOM is ready (before full readiness).
+ */
+
+class TinyDomReadyManager {
+  /** @type {Handler[]} */
+  #handlers = [];
+
+  /** @type {boolean} */
+  #isDomReady = false;
+
+  /** @type {boolean} */
+  #isFullyReady = false;
+
+  /** @type {Promise<any>[]} */
+  #promises = [];
+
+  /**
+   * Checks if the DOM is ready and if all Promises have been resolved.
+   */
+  #checkAllReady() {
+    if (this.#isDomReady) {
+      Promise.all(this.#promises)
+        .then(() => {
+          this.#isFullyReady = true;
+          this.#runHandlers(false); // run non-domOnly
+        })
+        .catch((err) => {
+          console.error('[TinyDomReadyManager] Promise rejected:', err);
+        });
+    }
+  }
+
+  /**
+   * Executes handlers by filtering them by `domOnly` flag and sorting by priority.
+   * @param {boolean} domOnlyOnly - Whether to run only `domOnly` handlers.
+   */
+  #runHandlers(domOnlyOnly) {
+    this.#handlers
+      .filter((h) => h.domOnly === domOnlyOnly)
+      .sort((a, b) => b.priority - a.priority)
+      .forEach((handler) => this.#invokeHandler(handler));
+
+    this.#handlers = this.#handlers.filter((h) => !(h.once && (domOnlyOnly ? h.domOnly : true)));
+  }
+
+  /**
+   * Executes a handler if its filter passes.
+   * @param {Handler} handler
+   */
+  #invokeHandler(handler) {
+    if (typeof handler.filter === 'function') {
+      try {
+        if (!handler.filter()) return;
+      } catch (err) {
+        console.warn('[TinyDomReadyManager] Filter error:', err);
+        return;
+      }
+    }
+
+    try {
+      handler.fn();
+    } catch (err) {
+      console.error('[TinyDomReadyManager] Handler error:', err);
+    }
+  }
+
+  /**
+   * Marks the system as DOM-ready and runs DOM-only handlers.
+   * @private
+   */
+  _markDomReady() {
+    this.#isDomReady = true;
+    this.#runHandlers(true); // Run domOnly
+    this.#checkAllReady(); // Then check for full readiness
+  }
+
+  /**
+   * Initializes the manager using `DOMContentLoaded`.
+   */
+  init() {
+    if (this.#isDomReady) throw new Error('[TinyDomReadyManager] init() has already been called.');
+
+    if (document.readyState === 'interactive' || document.readyState === 'complete') {
+      this._markDomReady();
+    } else {
+      document.addEventListener('DOMContentLoaded', () => this._markDomReady());
+    }
+  }
+
+  /**
+   * Adds a Promise to delay full readiness.
+   * @param {Promise<any>} promise
+   * @throws {TypeError}
+   */
+  addPromise(promise) {
+    if (!(promise instanceof Promise))
+      throw new TypeError('[TinyDomReadyManager] promise must be a valid Promise.');
+
+    if (this.#isFullyReady) return;
+    this.#promises.push(promise);
+    if (this.#isDomReady) this.#checkAllReady();
+  }
+
+  /**
+   * Registers a handler to run either after DOM is ready or after full readiness.
+   *
+   * @param {Fn} fn - Function to execute.
+   * @param {Object} [options]
+   * @param {boolean} [options.once=true] - Execute only once.
+   * @param {number} [options.priority=0] - Higher priority runs first.
+   * @param {FnFilter|null} [options.filter=null] - Optional filter function.
+   * @param {boolean} [options.domOnly=false] - If true, executes after DOM ready only.
+   * @throws {TypeError} If fn is not a function.
+   */
+  onReady(fn, { once = true, priority = 0, filter = null, domOnly = false } = {}) {
+    if (typeof fn !== 'function')
+      throw new TypeError('[TinyDomReadyManager] fn must be a function.');
+
+    const handler = { fn, once, priority, filter, domOnly };
+
+    if (domOnly && this.#isDomReady) {
+      this.#invokeHandler(handler);
+      if (!once) this.#handlers.push(handler);
+      return;
+    }
+
+    if (!domOnly && this.#isFullyReady) {
+      this.#invokeHandler(handler);
+    } else {
+      this.#handlers.push(handler);
+    }
+  }
+
+  /**
+   * Returns whether the system is fully ready (DOM + Promises).
+   * @returns {boolean}
+   */
+  isReady() {
+    return this.#isFullyReady;
+  }
+
+  /**
+   * Returns whether the DOM is ready (DOMContentLoaded has fired).
+   * Does not wait for promises.
+   * @returns {boolean}
+   */
+  isDomReady() {
+    return this.#isDomReady;
+  }
+}
+
+module.exports = TinyDomReadyManager;

package/dist/v1/libs/TinyDomReadyManager.d.mts

@@ -0,0 +1,100 @@
+export default TinyDomReadyManager;
+/**
+ * A basic function that performs a task when the system is ready.
+ * Used for handlers in the readiness queue.
+ */
+export type Fn = () => void;
+/**
+ * A function that determines whether a specific handler should be executed.
+ * Should return `true` to allow execution, or `false` to skip the handler.
+ */
+export type FnFilter = () => boolean;
+export type Handler = {
+    /**
+     * - Function to execute when ready.
+     */
+    fn: Fn;
+    /**
+     * - Whether to execute only once.
+     */
+    once: boolean;
+    /**
+     * - Execution order (higher priority runs first).
+     */
+    priority: number;
+    /**
+     * - Optional filter function to determine execution.
+     */
+    filter: FnFilter | null;
+    /**
+     * - Whether to run as soon as DOM is ready (before full readiness).
+     */
+    domOnly: boolean;
+};
+/**
+ * A basic function that performs a task when the system is ready.
+ * Used for handlers in the readiness queue.
+ *
+ * @typedef {() => void} Fn
+ */
+/**
+ * A function that determines whether a specific handler should be executed.
+ * Should return `true` to allow execution, or `false` to skip the handler.
+ *
+ * @typedef {() => boolean} FnFilter
+ */
+/**
+ * @typedef {Object} Handler
+ * @property {Fn} fn - Function to execute when ready.
+ * @property {boolean} once - Whether to execute only once.
+ * @property {number} priority - Execution order (higher priority runs first).
+ * @property {FnFilter|null} filter - Optional filter function to determine execution.
+ * @property {boolean} domOnly - Whether to run as soon as DOM is ready (before full readiness).
+ */
+declare class TinyDomReadyManager {
+    /**
+     * Marks the system as DOM-ready and runs DOM-only handlers.
+     * @private
+     */
+    private _markDomReady;
+    /**
+     * Initializes the manager using `DOMContentLoaded`.
+     */
+    init(): void;
+    /**
+     * Adds a Promise to delay full readiness.
+     * @param {Promise<any>} promise
+     * @throws {TypeError}
+     */
+    addPromise(promise: Promise<any>): void;
+    /**
+     * Registers a handler to run either after DOM is ready or after full readiness.
+     *
+     * @param {Fn} fn - Function to execute.
+     * @param {Object} [options]
+     * @param {boolean} [options.once=true] - Execute only once.
+     * @param {number} [options.priority=0] - Higher priority runs first.
+     * @param {FnFilter|null} [options.filter=null] - Optional filter function.
+     * @param {boolean} [options.domOnly=false] - If true, executes after DOM ready only.
+     * @throws {TypeError} If fn is not a function.
+     */
+    onReady(fn: Fn, { once, priority, filter, domOnly }?: {
+        once?: boolean | undefined;
+        priority?: number | undefined;
+        filter?: FnFilter | null | undefined;
+        domOnly?: boolean | undefined;
+    }): void;
+    /**
+     * Returns whether the system is fully ready (DOM + Promises).
+     * @returns {boolean}
+     */
+    isReady(): boolean;
+    /**
+     * Returns whether the DOM is ready (DOMContentLoaded has fired).
+     * Does not wait for promises.
+     * @returns {boolean}
+     */
+    isDomReady(): boolean;
+    #private;
+}
+//# sourceMappingURL=TinyDomReadyManager.d.mts.map

package/dist/v1/libs/TinyDomReadyManager.mjs

@@ -0,0 +1,158 @@
+/**
+ * A basic function that performs a task when the system is ready.
+ * Used for handlers in the readiness queue.
+ *
+ * @typedef {() => void} Fn
+ */
+/**
+ * A function that determines whether a specific handler should be executed.
+ * Should return `true` to allow execution, or `false` to skip the handler.
+ *
+ * @typedef {() => boolean} FnFilter
+ */
+/**
+ * @typedef {Object} Handler
+ * @property {Fn} fn - Function to execute when ready.
+ * @property {boolean} once - Whether to execute only once.
+ * @property {number} priority - Execution order (higher priority runs first).
+ * @property {FnFilter|null} filter - Optional filter function to determine execution.
+ * @property {boolean} domOnly - Whether to run as soon as DOM is ready (before full readiness).
+ */
+class TinyDomReadyManager {
+    /** @type {Handler[]} */
+    #handlers = [];
+    /** @type {boolean} */
+    #isDomReady = false;
+    /** @type {boolean} */
+    #isFullyReady = false;
+    /** @type {Promise<any>[]} */
+    #promises = [];
+    /**
+     * Checks if the DOM is ready and if all Promises have been resolved.
+     */
+    #checkAllReady() {
+        if (this.#isDomReady) {
+            Promise.all(this.#promises)
+                .then(() => {
+                this.#isFullyReady = true;
+                this.#runHandlers(false); // run non-domOnly
+            })
+                .catch((err) => {
+                console.error('[TinyDomReadyManager] Promise rejected:', err);
+            });
+        }
+    }
+    /**
+     * Executes handlers by filtering them by `domOnly` flag and sorting by priority.
+     * @param {boolean} domOnlyOnly - Whether to run only `domOnly` handlers.
+     */
+    #runHandlers(domOnlyOnly) {
+        this.#handlers
+            .filter((h) => h.domOnly === domOnlyOnly)
+            .sort((a, b) => b.priority - a.priority)
+            .forEach((handler) => this.#invokeHandler(handler));
+        this.#handlers = this.#handlers.filter((h) => !(h.once && (domOnlyOnly ? h.domOnly : true)));
+    }
+    /**
+     * Executes a handler if its filter passes.
+     * @param {Handler} handler
+     */
+    #invokeHandler(handler) {
+        if (typeof handler.filter === 'function') {
+            try {
+                if (!handler.filter())
+                    return;
+            }
+            catch (err) {
+                console.warn('[TinyDomReadyManager] Filter error:', err);
+                return;
+            }
+        }
+        try {
+            handler.fn();
+        }
+        catch (err) {
+            console.error('[TinyDomReadyManager] Handler error:', err);
+        }
+    }
+    /**
+     * Marks the system as DOM-ready and runs DOM-only handlers.
+     * @private
+     */
+    _markDomReady() {
+        this.#isDomReady = true;
+        this.#runHandlers(true); // Run domOnly
+        this.#checkAllReady(); // Then check for full readiness
+    }
+    /**
+     * Initializes the manager using `DOMContentLoaded`.
+     */
+    init() {
+        if (this.#isDomReady)
+            throw new Error('[TinyDomReadyManager] init() has already been called.');
+        if (document.readyState === 'interactive' || document.readyState === 'complete') {
+            this._markDomReady();
+        }
+        else {
+            document.addEventListener('DOMContentLoaded', () => this._markDomReady());
+        }
+    }
+    /**
+     * Adds a Promise to delay full readiness.
+     * @param {Promise<any>} promise
+     * @throws {TypeError}
+     */
+    addPromise(promise) {
+        if (!(promise instanceof Promise))
+            throw new TypeError('[TinyDomReadyManager] promise must be a valid Promise.');
+        if (this.#isFullyReady)
+            return;
+        this.#promises.push(promise);
+        if (this.#isDomReady)
+            this.#checkAllReady();
+    }
+    /**
+     * Registers a handler to run either after DOM is ready or after full readiness.
+     *
+     * @param {Fn} fn - Function to execute.
+     * @param {Object} [options]
+     * @param {boolean} [options.once=true] - Execute only once.
+     * @param {number} [options.priority=0] - Higher priority runs first.
+     * @param {FnFilter|null} [options.filter=null] - Optional filter function.
+     * @param {boolean} [options.domOnly=false] - If true, executes after DOM ready only.
+     * @throws {TypeError} If fn is not a function.
+     */
+    onReady(fn, { once = true, priority = 0, filter = null, domOnly = false } = {}) {
+        if (typeof fn !== 'function')
+            throw new TypeError('[TinyDomReadyManager] fn must be a function.');
+        const handler = { fn, once, priority, filter, domOnly };
+        if (domOnly && this.#isDomReady) {
+            this.#invokeHandler(handler);
+            if (!once)
+                this.#handlers.push(handler);
+            return;
+        }
+        if (!domOnly && this.#isFullyReady) {
+            this.#invokeHandler(handler);
+        }
+        else {
+            this.#handlers.push(handler);
+        }
+    }
+    /**
+     * Returns whether the system is fully ready (DOM + Promises).
+     * @returns {boolean}
+     */
+    isReady() {
+        return this.#isFullyReady;
+    }
+    /**
+     * Returns whether the DOM is ready (DOMContentLoaded has fired).
+     * Does not wait for promises.
+     * @returns {boolean}
+     */
+    isDomReady() {
+        return this.#isDomReady;
+    }
+}
+export default TinyDomReadyManager;

package/docs/v1/README.md

@@ -31,6 +31,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 📥 **[TinyDragDropDetector](./libs/TinyDragDropDetector.md)** — A lightweight drag-and-drop detector for files, handling the full drag lifecycle (`enter`, `over`, `leave`, `drop`) with CSS hover management and safe event handling on any DOM element or the full page.
 * 📂 **[TinyUploadClicker](./libs/TinyUploadClicker.md)** — A minimal utility to bind any clickable element to a hidden file input, offering full control over styling, behavior, and upload event hooks.
 * 🧲 **[TinyDragger](./libs/TinyDragger.md)** — A flexible drag-and-drop manager with collision detection, jail constraints, vibration feedback, visual proxies, revert-on-drop, and full custom event support.
+* 🕒 **[TinyDomReadyManager](./libs/TinyDomReadyManager.md)** — A readiness manager for DOM and async conditions, supporting prioritized callbacks, custom filters, and event-based or promise-based bootstrapping.
 
 ### 3. **`fileManager/`**
 * 📁 **[main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/libs/TinyDomReadyManager.md

@@ -0,0 +1,198 @@
+# 🕒 TinyDomReadyManager
+
+A flexible, customizable JavaScript class to execute code **only when the DOM is ready**, or when additional asynchronous requirements (like Promises or asset loads) are met.
+Supports **prioritized callbacks**, **filters**, and now even **DOM-only fast execution**!
+
+---
+
+## 🧠 Type Definitions
+
+### `Fn` 🛠️
+
+```ts
+type Fn = () => void;
+```
+
+A basic function to be executed once the system is ready.
+
+---
+
+### `FnFilter` 🔍
+
+```ts
+type FnFilter = () => boolean;
+```
+
+A conditional function that decides whether a handler should be executed.
+Returns `true` to allow execution, or `false` to skip.
+
+---
+
+### `Handler` 🧩
+
+```ts
+interface Handler {
+  fn: Fn;
+  once: boolean;
+  priority: number;
+  filter: FnFilter | null;
+  domOnly: boolean;
+}
+```
+
+Describes a registered handler and how it should be treated during readiness flow.
+
+---
+
+## 🚀 Class: `TinyDomReadyManager`
+
+### `init()` 🕓
+
+```ts
+init(): void
+```
+
+Initializes the manager and waits for the `DOMContentLoaded` event.
+If the DOM is already ready, it triggers immediately.
+
+* ⚠️ Throws an `Error` if called more than once.
+
+---
+
+### `addPromise(promise)` ⏳
+
+```ts
+addPromise(promise: Promise<any>): void
+```
+
+Adds a custom `Promise` that delays full readiness.
+This allows tasks like `fetch()` or image preloading to block late-stage handlers.
+
+* ⚠️ Throws a `TypeError` if `promise` is not a real `Promise`.
+
+---
+
+### `onReady(fn, options?)` ✅
+
+```ts
+onReady(fn: Fn, options?: {
+  once?: boolean;
+  priority?: number;
+  filter?: FnFilter | null;
+  domOnly?: boolean;
+}): void
+```
+
+Registers a function to run at the right moment:
+
+| Option     | Type               | Default | Description                                                              |
+| ---------- | ------------------ | ------- | ------------------------------------------------------------------------ |
+| `once`     | `boolean`          | `true`  | Whether to execute only once                                             |
+| `priority` | `number`           | `0`     | Higher values run earlier                                                |
+| `filter`   | `FnFilter \| null` | `null`  | Optional condition before executing                                      |
+| `domOnly`  | `boolean`          | `false` | 🚀 If `true`, runs immediately after **DOM is ready**, skipping promises |
+
+* ⚠️ Throws a `TypeError` if `fn` is not a function.
+
+---
+
+### `isReady()` 📡
+
+```ts
+isReady(): boolean
+```
+
+Returns `true` only after both the DOM is ready **and** all added promises have resolved.
+
+---
+
+### `isDomReady()` 🧱
+
+```ts
+isDomReady(): boolean
+```
+
+Returns `true` if the DOM is already ready (i.e., `DOMContentLoaded` has fired).
+Returns `false` if the DOM is still loading.
+
+> ✅ Useful when you want to know *just* when the document is interactive, regardless of async operations.
+
+---
+
+## 🧪 Readiness Phases
+
+| Phase           | Description                              |
+| --------------- | ---------------------------------------- |
+| **DOM Ready**   | Triggers `domOnly: true` handlers        |
+| **Fully Ready** | Triggers all normal `onReady()` handlers |
+
+---
+
+## 💡 Example Usage
+
+### Basic Usage
+
+```js
+import TinyDomReadyManager from './TinyDomReadyManager.js';
+
+const manager = new TinyDomReadyManager();
+
+manager.onReady(() => {
+  console.log('Ready after DOM + Promises!');
+});
+
+manager.addPromise(fetch('/config.json'));
+manager.init();
+```
+
+---
+
+### DOM-Only Handler (Faster)
+
+```js
+manager.onReady(() => {
+  console.log('DOM is ready, skipping Promises!');
+}, { domOnly: true, priority: 100 });
+```
+
+---
+
+### Conditional + Prioritized
+
+```js
+manager.onReady(() => {
+  console.log('Only runs if in dark mode');
+}, {
+  priority: 5,
+  filter: () => document.documentElement.classList.contains('dark')
+});
+```
+
+---
+
+### Mixing Both Types
+
+```js
+manager.onReady(() => {
+  console.log('DOM-only logic A');
+}, { domOnly: true, priority: 10 });
+
+manager.onReady(() => {
+  console.log('DOM-only logic B');
+}, { domOnly: true, priority: 5 });
+
+manager.onReady(() => {
+  console.log('Waits for API call');
+});
+
+manager.addPromise(fetch('/api/user'));
+manager.init();
+```
+
+---
+
+## 📌 Notes
+
+* `domOnly` handlers are ideal for UI setup or event binding.
+* Regular handlers are best for things that depend on data loading or external states.
+* All handlers are executed safely, and exceptions are caught with warning logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",