tiny-essentials 1.5.1 → 1.7.0

package/dist/v1/libs/TinyPromiseQueue.mjs

@@ -13,6 +13,7 @@ class TinyPromiseQueue {
      * @property {(value: any) => any} resolve - The resolve function from the Promise.
      * @property {(reason?: any) => any} reject - The reject function from the Promise.
      * @property {string|undefined} [id] - Optional identifier for the task.
+     * @property {string|null|undefined} [marker] - Optional marker for the task.
      * @property {number|null|undefined} [delay] - Optional delay (in ms) before the task is executed.
      */
     /** @type {Array<QueuedTask>} */
@@ -31,22 +32,26 @@ class TinyPromiseQueue {
         return this.#running;
     }
     /**
-     * Processes the next task in the queue if not already running.
-     * Ensures tasks are executed in order, one at a time.
+     * Processes the a normal task.
+     *
+     * @param {QueuedTask} data
      *
      * @returns {Promise<void>}
      */
-    async #processQueue() {
-        if (this.#running || this.#queue.length === 0)
-            return;
-        this.#running = true;
-        const data = this.#queue.shift();
+    async #normalProcessQueue(data) {
         if (data &&
             typeof data.task === 'function' &&
             typeof data.resolve === 'function' &&
             typeof data.reject === 'function') {
             const { task, resolve, reject, delay, id } = data;
             try {
+                if (id && this.#blacklist.has(id)) {
+                    reject(new Error('The function was canceled on TinyPromiseQueue.'));
+                    this.#blacklist.delete(id);
+                    this.#running = false;
+                    this.#processQueue();
+                    return;
+                }
                 if (delay && id) {
                     await new Promise((resolveDelay) => {
                         const timeoutId = setTimeout(() => {
@@ -56,13 +61,6 @@ class TinyPromiseQueue {
                         this.#timeouts[id] = timeoutId;
                     });
                 }
-                if (id && this.#blacklist.has(id)) {
-                    reject(new Error('The function was canceled on TinyPromiseQueue.'));
-                    this.#blacklist.delete(id);
-                    this.#running = false;
-                    this.#processQueue();
-                    return;
-                }
                 const result = await task();
                 resolve(result);
             }
@@ -75,6 +73,54 @@ class TinyPromiseQueue {
             }
         }
     }
+    /**
+     * Processes a group task.
+     *
+     * @returns {Promise<void>}
+     */
+    async #groupProcessQueue() {
+        /** @type {Array<QueuedTask>} */
+        const grouped = [];
+        while (this.#queue.length && this.#queue[0]?.marker === 'POINT_MARKER') {
+            // @ts-ignore
+            grouped.push(this.#queue.shift());
+        }
+        if (grouped.length === 0) {
+            this.#running = false;
+            this.#processQueue();
+            return;
+        }
+        await Promise.all(grouped.map(({ task, resolve, reject, id }) => new Promise(async (pResolve) => {
+            if (id && this.#blacklist.has(id)) {
+                this.#blacklist.delete(id);
+                reject(new Error('The function was canceled on TinyPromiseQueue.'));
+                pResolve(true);
+                return;
+            }
+            await task().then(resolve).catch(reject);
+            pResolve(true);
+        })));
+        this.#running = false;
+        this.#processQueue();
+    }
+    /**
+     * Processes the next task in the queue if not already running.
+     * Ensures tasks are executed in order, one at a time.
+     *
+     * @returns {Promise<void>}
+     */
+    async #processQueue() {
+        if (this.#running || this.#queue.length === 0)
+            return;
+        this.#running = true;
+        if (typeof this.#queue[0]?.marker !== 'string' || this.#queue[0]?.marker !== 'POINT_MARKER') {
+            const data = this.#queue.shift();
+            // @ts-ignore
+            this.#normalProcessQueue(data);
+        }
+        else
+            this.#groupProcessQueue();
+    }
     /**
      * Returns the index of a task by its ID.
      *
@@ -112,6 +158,22 @@ class TinyPromiseQueue {
         const [item] = this.#queue.splice(fromIndex, 1);
         this.#queue.splice(toIndex, 0, item);
     }
+    /**
+     * Inserts a point in the queue where subsequent tasks will be grouped and executed together in a Promise.all.
+     * If the queue is currently empty, behaves like a regular promise.
+     *
+     * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise.
+     * @param {string} [id] Optional ID to identify the task in the queue.
+     * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+     */
+    async enqueuePoint(task, id) {
+        if (!this.#running)
+            return task();
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ marker: 'POINT_MARKER', task, resolve, reject, id });
+            this.#processQueue();
+        });
+    }
     /**
      * Adds a new async task to the queue and ensures it runs in order after previous tasks.
      * Optionally, a delay can be added before the task is executed.
@@ -148,7 +210,8 @@ class TinyPromiseQueue {
         }
         const index = this.getIndexById(id);
         if (index !== -1) {
-            this.#queue.splice(index, 1);
+            const [removed] = this.#queue.splice(index, 1);
+            removed?.reject?.(new Error('The function was canceled on TinyPromiseQueue.'));
             cancelled = true;
         }
         if (cancelled)

package/docs/basics/text.md

@@ -36,3 +36,94 @@ toTitleCase('hello world'); // → "Hello World"
 ```js
 toTitleCaseLowerFirst('hello world'); // → "hello World"
 ```
+
+---
+
+## 🎯 `addAiMarkerShortcut(key = 'a')`
+
+Enables a keyboard shortcut (`Ctrl + Alt + [key]`) that toggles a CSS class on the `<body>` element. Useful for marking or highlighting AI-generated content dynamically.
+
+---
+
+### 🔤 Syntax
+
+```js
+addAiMarkerShortcut(key)
+```
+
+---
+
+### 🧾 Parameters
+
+| Name  | Type     | Default | Description                                                                  |
+| ----- | -------- | ------- | ---------------------------------------------------------------------------- |
+| `key` | `string` | `'a'`   | The character key to use in combination with `Ctrl + Alt`. Case-insensitive. |
+
+---
+
+### ⚙️ Behavior
+
+* ⌨️ When the user presses `Ctrl + Alt + [key]`, the function toggles the CSS class `detect-made-by-ai` on the `<body>` element.
+* 🧠 The shortcut only works in environments where the DOM is available (e.g., browsers).
+* 🚫 If `document.body` is not available when the shortcut is used (e.g., if the DOM hasn't finished loading), a warning is logged and nothing happens.
+
+---
+
+### ❗ Error Handling
+
+Two types of errors are handled:
+
+1. 🧱 **Non-browser environment (e.g., Node.js):**
+
+   ```
+   [AiMarkerShortcut] Environment does not support the DOM. This function must be run in a browser.
+   ```
+
+2. 🕓 **DOM not fully loaded at the time of shortcut:**
+
+   ```
+   [AiMarkerShortcut] <body> element not found. Cannot toggle class. Ensure the DOM is fully loaded when using the shortcut.
+   ```
+
+---
+
+### 🧪 Example
+
+```js
+addAiMarkerShortcut(); // Uses default key 'a'
+// Pressing Ctrl + Alt + A toggles the class "detect-made-by-ai" on <body>
+```
+
+---
+
+### 🎨 CSS Integration Example
+
+Define the class in your stylesheet to make the toggle visually meaningful:
+
+```css
+body.detect-made-by-ai .ai-content {
+  outline: 2px dashed red;
+  background-color: rgba(255, 0, 0, 0.05);
+}
+```
+
+---
+
+### 💡 Tip
+
+To avoid the `<body>` warning, make sure you only call the function after the DOM is ready:
+
+```js
+document.addEventListener('DOMContentLoaded', () => {
+  addAiMarkerShortcut();
+});
+```
+
+### 📂 CSS Templates
+
+You can use a pre-built CSS template for the `detect-made-by-ai` class, available in the following files:
+
+* `/dist/aiMarker.min.css` – A minified version of the CSS for production use.
+* `/dist/aiMarker.css` – The non-minified version for easier readability and customization.
+
+Simply include the appropriate file in your project to style the elements marked with the `detect-made-by-ai` class.

package/docs/libs/TinyPromiseQueue.md

@@ -22,6 +22,8 @@ Returns whether the queue is currently processing a task.
 #### Returns:
 - `boolean`: `true` if the queue is processing a task, otherwise `false`.
 
+---
+
 ### `getIndexById(id)` 🔍
 
 Returns the index of a task in the queue by its ID.
@@ -32,6 +34,8 @@ Returns the index of a task in the queue by its ID.
 #### Returns:
 - `number`: The index of the task in the queue, or `-1` if not found.
 
+---
+
 ### `getQueuedIds()` 📋
 
 Returns a list of IDs for all tasks currently in the queue.
@@ -39,6 +43,8 @@ Returns a list of IDs for all tasks currently in the queue.
 #### Returns:
 - `Array<{ index: number, id: string }>`: An array of task IDs and their corresponding indices.
 
+---
+
 ### `reorderQueue(fromIndex, toIndex)` 🔄
 
 Reorders a task in the queue from one index to another.
@@ -50,6 +56,8 @@ Reorders a task in the queue from one index to another.
 #### Returns:
 - `void`: This method does not return anything.
 
+---
+
 ### `enqueue(task, delay, id)` ⏳
 
 Adds a new async task to the queue and ensures it runs in order after previous tasks. Optionally, a delay can be added before the task is executed.
@@ -65,6 +73,26 @@ If the task is canceled before execution, it will be rejected with the message:
 #### Returns:
 - `Promise<any>`: A promise that resolves or rejects with the result of the task once it's processed.
 
+---
+
+### `enqueuePoint(task, id)` 🪢
+
+Adds an async task to a parallel group in the queue. All tasks added with `enqueuePoint` before the next `enqueue` will be executed **simultaneously**, but only after all previous tasks in the queue have completed.
+
+These grouped tasks share a "concurrent checkpoint" and will run using `Promise.all`. Each task resolves or rejects independently.
+
+If a task is canceled before execution, it will be rejected with the message:  
+**"The function was canceled on TinyPromiseQueue."**
+
+#### Parameters:
+- `task` (`Function`): A function that returns a `Promise` to be executed sequentially.
+- `id` (`string`): Optional ID to identify the task in the queue.
+
+#### Returns:
+- `Promise<any>`: A promise that resolves or rejects with the result of the task once it's processed.
+
+---
+
 ### `cancelTask(id)` ❌
 
 Cancels a scheduled delay and removes the task from the queue. Adds the ID to a blacklist so the task is skipped if already being processed.
@@ -113,6 +141,73 @@ setTimeout(() => {
 }, 60);
 ```
 
+```js
+import { TinyPromiseQueue } from './TinyPromiseQueue';
+
+const queue = new TinyPromiseQueue();
+await new Promise((resolve) => {
+
+    // Task generator with color-coded logs
+    function createTask(name, duration = 500) {
+      return () =>
+        new Promise((resolve) => {
+          console.log(`\x1b[34m[STARTED]\x1b[0m \x1b[36m${name}\x1b[0m`);
+          setTimeout(() => {
+            console.log(`\x1b[32m[FINISHED]\x1b[0m \x1b[36m${name}\x1b[0m`);
+            resolve(name);
+          }, duration);
+        });
+    }
+
+    // Function to simulate a parallel group of enqueues
+    const parallelEnqueueGroup = (groupName, delayStart = 0) => {
+        const count = Math.floor(Math.random() * (15 - 1 + 1) + 1);
+        for (let i = 1; i <= count; i++) {
+          const taskName = `${groupName}-${i}`;
+          queue.enqueue(createTask(taskName, 300 + i * 50), delayStart, taskName);
+        }
+    };
+
+    // Main enqueue block
+    queue.enqueue(createTask('Init-1', 400), 50, 'init-1');
+    queue.enqueue(createTask('Init-2', 400), 0, 'init-2');
+
+    // Simulate enqueues from other contexts "in parallel"
+    parallelEnqueueGroup('Alpha',     80);  // Starts after 80ms
+    parallelEnqueueGroup('Beta',     120);  // Starts after 120ms
+    parallelEnqueueGroup('Gamma',    250);  // Starts after 250ms
+    parallelEnqueueGroup('Delta',    180);  // Starts after 180ms
+    parallelEnqueueGroup('Epsilon',  300);  // Starts after 300ms
+    parallelEnqueueGroup('Zeta',     160);  // Starts after 160ms
+    parallelEnqueueGroup('Eta',       90);  // Starts after 90ms
+    parallelEnqueueGroup('Theta',    220);  // Starts after 220ms
+    parallelEnqueueGroup('Iota',     140);  // Starts after 140ms
+    parallelEnqueueGroup('Kappa',    400);  // Starts after 400ms
+    parallelEnqueueGroup('Lambda',   190);  // Starts after 190ms
+    parallelEnqueueGroup('Mu',       260);  // Starts after 260ms
+    parallelEnqueueGroup('Nu',       110);  // Starts after 110ms
+    parallelEnqueueGroup('Xi',       330);  // Starts after 330ms
+    parallelEnqueueGroup('Omicron',  170);  // Starts after 170ms
+    parallelEnqueueGroup('Pi',       280);  // Starts after 280ms
+    parallelEnqueueGroup('Rho',       70);  // Starts after 70ms
+    parallelEnqueueGroup('Sigma',    360);  // Starts after 360ms
+    parallelEnqueueGroup('Tau',      130);  // Starts after 130ms
+    parallelEnqueueGroup('Upsilon',  240);  // Starts after 240ms
+    parallelEnqueueGroup('Phi',      310);  // Starts after 310ms
+    parallelEnqueueGroup('Chi',      100);  // Starts after 100ms
+    parallelEnqueueGroup('Psi',      200);  // Starts after 200ms
+    parallelEnqueueGroup('Omega',     50);  // Starts after 50ms
+
+    // Final task to confirm everything executed
+    setTimeout(() => {
+      queue.enqueue(createTask('Finalizer', 500), 0, 'finalizer').then(() => {
+        console.log('\x1b[35m[QUEUE COMPLETE]\x1b[0m All tasks have been processed.');
+        resolve();
+      });
+    }, 250);
+});
+```
+
 ### Explanation 🧩:
 1. **Task Creation**: Tasks are created with a name and an optional duration (in ms). The task logs its start and finish times 🕰️.
 2. **Task Execution**: Tasks are enqueued one at a time, ensuring they run in the order they were added 🔁.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.5.1",
+  "version": "1.7.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",
@@ -15,9 +15,11 @@
     "fix:prettier:rollup.config": "prettier --write ./rollup.config.mjs",
     "fix:prettier:webpack.config": "prettier --write ./webpack.config.mjs",
     "auto-build": "npm run build",
-    "build": "tsc -p tsconfig.json && rollup -c && webpack --mode production",
+    "build": "npm run build:js && npm run build:css",
+    "build:js": "tsc -p tsconfig.json && rollup -c && webpack --mode production",
     "build-clean": "npm run clean && npm run build",
     "build-dist": "npm run build",
+    "build:css": "sass src/v1/scss/aiMarker.scss dist/aiMarker.css --no-source-map && sass src/v1/scss/aiMarker.scss dist/aiMarker.min.css --no-source-map --style=compressed",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"
   },
@@ -80,6 +82,7 @@
     "prettier": "3.5.3",
     "rollup": "^4.40.0",
     "rollup-preserve-directives": "^1.1.3",
+    "sass": "^1.87.0",
     "tinycolor2": "^1.6.0",
     "tslib": "^2.8.1",
     "type-fest": "^4.40.0",