tiny-essentials 1.28.15 → 1.28.17

package/docs/v1/basics/jsonFilter.md

@@ -0,0 +1,194 @@
+# 🛠️ Object Filtering Utilities Documentation
+
+A collection of powerful, high-precision JavaScript utilities designed to filter objects based on keys, values, or complex nested conditions.
+
+## 📋 Table of Contents
+1. [`jsonFilter`](#jsonfilter) — Shallow filtering.
+2. [`jsonFilterRecursive`](#jsonfilterrecursive) — Deep/Recursive filtering.
+3. [`jsonFilterByKeys`](#jsonfilterbykeys) — Selective key/value extraction.
+
+---
+
+## 🔍 `jsonFilter`
+
+`jsonFilter` is a shallow filtering function. It creates a new object containing only the entries that satisfy a specific predicate function.
+
+### ⚙️ Syntax
+```javascript
+jsonFilter(value, filterContent);
+```
+
+### 📥 Parameters
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `Object` | The source object to be filtered. |
+| `filterContent` | `Function` | A callback: `(entry, index, array) => boolean`. |
+
+### 🚀 Example
+Filtering an object to only keep entries where the value is a number greater than 10.
+
+```javascript
+import { jsonFilter } from 'tiny-essentials/basics/jsonFilter';
+
+const data = { a: 5, b: 15, c: 20, d: 'hello' };
+
+const result = jsonFilter(data, ([key, value]) => typeof value === 'number' && value > 10);
+
+console.log(result); 
+// Output: { b: 15, c: 20 }
+```
+
+---
+
+## 🌳 `jsonFilterRecursive`
+
+`jsonFilterRecursive` performs a deep traversal of a data structure. It allows you to apply specific filtering rules depending on whether the current item is a **primitive**, an **array**, or a **complex container** (Object, Map, or Set).
+
+### ⚙️ Syntax
+```javascript
+jsonFilterRecursive(value, filter);
+```
+
+### 📥 Parameters
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `Object \| Map \| Set` | The source structure to be filtered. |
+| `filter` | `Object` | An object containing predicate functions: |
+| `filter.value` | `Function` | Applied to **primitive** values. |
+| `filter.obj` | `Function` | Applied to **nested objects, Maps, or Sets** (used for pruning). |
+| `filter.array` | `Function` | Applied to **arrays**. |
+
+> **Note:** `WeakMap` and `WeakSet` are supported but, due to their non-iterable nature, will return a new empty instance of the same type when processed.
+
+### 🚀 Example
+Filtering a complex structure containing `Map` and `Set` objects.
+
+```javascript
+import { jsonFilterRecursive } from 'tiny-essentials/basics/jsonFilter';
+
+const complexData = {
+  id: 'Yasmin',
+  food: ['pudding'],
+  tags: new Set(['premium', 'beta-tester']),
+  empty: new Set(),
+  metadata: new Map([
+    ['last_login', '2023-10-27'],
+    ['login_count', 42]
+  ]),
+  settings: {
+    theme: 'dark',
+    notifications: true
+  }
+};
+
+const filterConfig = {
+  value: ([key, val]) => typeof val === 'string', // Keep strings
+  
+  // Prune Maps or Sets if they become empty after filtering
+  obj: (container) => {
+    if (container instanceof Map || container instanceof Set) {
+      return container.size > 0;
+    }
+    return container.id !== undefined; // Prune objects that don't have an 'id'
+  },
+  
+  array: () => true                               // Keep all arrays
+};
+
+const result = jsonFilterRecursive(complexData, filterConfig);
+
+console.log(result);
+/*
+Output:
+{
+  food: ['pudding'],
+  id: 'Yasmin',
+  tags: Set { 'premium', 'beta-tester' },
+  metadata: Map { 'last_login' => '2023-10-27' }
+}
+*/
+```
+
+---
+
+## 🔑 `jsonFilterByKeys`
+
+`jsonFilterByKeys` is a highly specialized selector. It allows you to extract specific keys or key-value pairs using simple strings, tuples, or validation functions.
+
+### ⚙️ Syntax
+```javascript
+jsonFilterByKeys(item, keys, values);
+```
+
+### 📥 Parameters
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `item` | `Object` | The source object. |
+| `keys` | `Array` | An array of `string` keys OR `[key, validator/value]` tuples. |
+| `values` | `Array` (opt) | A list of allowed values or validators to apply to the keys. |
+
+### 💡 Usage Modes
+
+#### 1. Using Simple Keys + Value Whitelist
+If you provide a list of keys and a list of allowed values.
+
+```javascript
+import { jsonFilterByKeys } from 'tiny-essentials/basics/jsonFilter';
+
+const data = { status: 'active', type: 'user', age: 25 };
+// Keep only 'status' if it is 'active'
+const result = jsonFilterByKeys(data, ['status'], ['active']); 
+// Output: { status: 'active' }
+```
+
+#### 2. Using Key-Value Tuples (Highly Precise)
+You can pass a tuple `[key, condition]` where the condition is a value or a function.
+
+```javascript
+import { jsonFilterByKeys } from 'tiny-essentials/basics/jsonFilter';
+
+const data = {
+  id: 101,
+  role: 'admin',
+  score: 95,
+  enabled: true
+};
+
+// Keep 'id', 'score', and 'role'.
+const result = jsonFilterByKeys(data, [
+  'id', 
+  ['role', 'admin'],
+  ['score', (value) => value > 90]
+]);
+
+console.log(result); 
+// Output: { id: 101, role: 'admin', score: 95 }
+```
+
+#### 3. Using Validators
+You can pass functions to perform complex validation during selection.
+
+```javascript
+import { jsonFilterByKeys } from 'tiny-essentials/basics/jsonFilter';
+
+const data = {
+  name: 'Isabela',
+  age: 30,
+  score: 9.5
+};
+
+// Keep keys where the value is a number greater than 10
+const result = jsonFilterByKeys(data, ['age', 'score'], [(v) => typeof v === 'number' && v > 10]);
+
+console.log(result);
+// Output: { age: 30 }
+```
+
+---
+
+## ⚠️ Error Handling
+
+All functions implement strict runtime validation and will throw a `TypeError` if:
+- The input `value` is not a valid object.
+- The `filterContent` or `filter` predicates are not functions.
+- The `keys` or `values` arguments are not arrays when required.

package/docs/v1/libs/{TinyArrayComparator.md → array/TinyArrayComparator.md}

@@ -18,7 +18,7 @@ A lightweight, highly optimized JavaScript utility class designed to compare two
 Since this project uses modern ES6 modules, simply import it into your working file.
 
 ```javascript
-import TinyArrayComparator from 'tiny-essentials/libs/TinyArrayComparator';
+import TinyArrayComparator from 'tiny-essentials/libs/array/TinyArrayComparator';
 ```
 
 ### 2. Prepare Your Arrays

package/docs/v1/libs/{TinyArrayPaginator.md → array/TinyArrayPaginator.md}

@@ -121,7 +121,7 @@ Filters and paginates the stored data.
 ### 📌 Example Usage
 
 ```js
-import TinyArrayPaginator from 'tiny-essentials/libs/TinyArrayPaginator';
+import TinyArrayPaginator from 'tiny-essentials/libs/array/TinyArrayPaginator';
 
 const paginator = new TinyArrayPaginator([
   { id: 1, category: 'fruit' },

package/docs/v1/libs/{ColorSafeStringify.md → color/ColorSafeStringify.md}

@@ -26,7 +26,7 @@ Then import both the stable stringifier and `ColorSafeStringify`:
 
 ```js
 import stringify from 'safe-stable-stringify';
-import ColorSafeStringify from 'tiny-essentials/libs/ColorSafeStringify';
+import ColorSafeStringify from 'tiny-essentials/libs/color/ColorSafeStringify';
 ```
 
 ---

package/docs/v1/libs/{TinyLevelUp.md → game/TinyLevelUp.md}

@@ -227,7 +227,7 @@ console.log(`You need ${missing} more XP to level up! 🚀`);
 ## 🌟 Example Usage
 
 ```js
-import TinyLevelUp from 'tiny-essentials/libs/TinyLevelUp';
+import TinyLevelUp from 'tiny-essentials/libs/game/TinyLevelUp';
 
 const levelSystem = new TinyLevelUp(15, 10);
 const user = levelSystem.createUser();

package/docs/v1/libs/{TinyDomReadyManager.md → html/TinyDomReadyManager.md}

@@ -133,7 +133,7 @@ Returns `false` if the DOM is still loading.
 ### Basic Usage
 
 ```js
-import TinyDomReadyManager from 'tiny-essentials/libs/TinyDomReadyManager';
+import TinyDomReadyManager from 'tiny-essentials/libs/html/TinyDomReadyManager';
 
 const manager = new TinyDomReadyManager();
 

package/docs/v1/libs/{TinyElementObserver.md → html/TinyElementObserver.md}

@@ -75,7 +75,7 @@ new TinyElementObserver(el, {
 ## 🔹 Example Usage
 
 ```js
-import TinyElementObserver from 'tiny-essentials/libs/TinyElementObserver';
+import TinyElementObserver from 'tiny-essentials/libs/html/TinyElementObserver';
 
 // Define a detector
 const logDetector = (mutation, index, mutations) => {

package/docs/v1/libs/{TinyDragDropDetector.md → html/drag/TinyDragDropDetector.md}

@@ -18,7 +18,7 @@ A lightweight JavaScript utility for detecting drag-and-drop file operations on
 ## 🔧 Usage Example
 
 ```javascript
-import TinyDragDropDetector from 'tiny-essentials/libs/TinyDragDropDetector';
+import TinyDragDropDetector from 'tiny-essentials/libs/html/drag/TinyDragDropDetector';
 
 const dnd = new TinyDragDropDetector({
   target: document.getElementById('drop-area'),

package/docs/v1/libs/{TinyDragger.md → html/drag/TinyDragger.md}

@@ -22,7 +22,7 @@ It supports visual proxies, jail boundaries, collision detection, vibration feed
 ## 📦 Installation
 
 ```js
-import TinyDragger from 'tiny-essentials/libs/TinyDragger';
+import TinyDragger from 'tiny-essentials/libs/html/drag/TinyDragger';
 ```
 
 ---

package/docs/v1/libs/{TinyIframeEvents.md → html/events/TinyIframeEvents.md}

@@ -23,7 +23,7 @@ This module abstracts the complexity of cross-origin communication by establishi
 ### In the parent:
 
 ```js
-import TinyIframeEvents from 'tiny-essentials/libs/TinyIframeEvents';
+import TinyIframeEvents from 'tiny-essentials/libs/html/events/TinyIframeEvents';
 
 const iframe = document.querySelector('iframe');
 
@@ -53,7 +53,7 @@ parentEvents.on('win:reply:fromIframe', (data, event) => {
 ### In the iframe:
 
 ```js
-import TinyIframeEvents from 'tiny-essentials/libs/TinyIframeEvents';
+import TinyIframeEvents from 'tiny-essentials/libs/html/events/TinyIframeEvents';
 
 const iframeEvents = new TinyIframeEvents({
   // Make sure these match the parent's config if you changed them!

package/docs/v1/libs/{TinyNewWinEvents.md → html/events/TinyNewWinEvents.md}

@@ -21,7 +21,7 @@ Ideal for secure, bidirectional messaging with route-based logic.
 ### In the main window:
 
 ```js
-import TinyNewWinEvents from 'tiny-essentials/libs/TinyNewWinEvents';
+import TinyNewWinEvents from 'tiny-essentials/libs/html/events/TinyNewWinEvents';
 
 const events = new TinyNewWinEvents({
   url: '/popup.html',
@@ -42,7 +42,7 @@ events.winEmit('init:data', { id: 123 });
 ### In the popup window:
 
 ```js
-import TinyNewWinEvents from 'tiny-essentials/libs/TinyNewWinEvents';
+import TinyNewWinEvents from 'tiny-essentials/libs/html/events/TinyNewWinEvents';
 
 const events = new TinyNewWinEvents();
 

package/docs/v1/libs/{TinyNotifications.md → html/notification/TinyNotifications.md}

@@ -164,7 +164,7 @@ Set or retrieve the default click handler for all notifications.
 ## 📦 Example
 
 ```js
-import TinyNotifications from 'tiny-essentials/libs/TinyNotifications';
+import TinyNotifications from 'tiny-essentials/libs/html/notification/TinyNotifications';
 
 const notify = new TinyNotifications({
   audio: '/sounds/ping.mp3',

package/docs/v1/libs/{TinyAfterScrollWatcher.md → html/scroll/TinyAfterScrollWatcher.md}

@@ -19,7 +19,7 @@ Perfect for optimizing logic that should only run **after** the user has finishe
 ## 📦 Import
 
 ```js
-import TinyAfterScrollWatcher from 'tiny-essentials/libs/TinyAfterScrollWatcher';
+import TinyAfterScrollWatcher from 'tiny-essentials/libs/html/scroll/TinyAfterScrollWatcher';
 ```
 
 ---

package/docs/v1/libs/{TinyAnalogClock.md → html/templates/TinyAnalogClock.md}

@@ -19,7 +19,7 @@
 Import the class into your JavaScript module.
 
 ```javascript
-import TinyAnalogClock from 'tiny-essentials/libs/TinyAnalogClock';
+import TinyAnalogClock from 'tiny-essentials/libs/html/templates/TinyAnalogClock';
 ```
 
 ### 2. Basic Usage

package/docs/v1/libs/{TinyCookieConsent.md → html/templates/TinyCookieConsent.md}

@@ -135,7 +135,7 @@ Returns `false` if preferences are missing or category is not allowed.
 ## 🧩 Example Usage
 
 ```js
-import TinyCookieConsent from 'tiny-essentials/libs/TinyCookieConsent';
+import TinyCookieConsent from 'tiny-essentials/libs/html/templates/TinyCookieConsent';
 
 const consent = new TinyCookieConsent({
   message: "We use cookies to personalize your experience.",

package/docs/v1/libs/{TinyLoadingScreen.md → html/templates/TinyLoadingScreen.md}

@@ -121,7 +121,7 @@ loader.onChange = (status) => {
 ### Basic Example
 
 ```js
-import TinyLoadingScreen from 'tiny-essentials/libs/TinyLoadingScreen';
+import TinyLoadingScreen from 'tiny-essentials/libs/html/templates/TinyLoadingScreen';
 
 const loader = new TinyLoadingScreen();
 loader.defaultMessage = 'Loading...';

package/docs/v1/libs/{TinyMediaPlayer.md → media/TinyMediaPlayer.md}

@@ -48,16 +48,16 @@ You can integrate `TinyMediaPlayer` into your project using two methods: using t
 The library provides several optimized adapters for common media sources. You can import them and register them directly with your player instance.
 
 **Available Adapters:**
-* `YoutubeMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/Youtube` (https://www.youtube.com/watch?v=XXXXXXXXXXX)
-* `SoundCloudMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/SoundCloud` (https://api.soundcloud.com/tracks/XXXXXXXXX (From SoundCloud Embed))
-* `HtmlAudioAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlAudio`
-* `HtmlVideoAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlVideo`
+* `YoutubeMediaAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/Youtube` (https://www.youtube.com/watch?v=XXXXXXXXXXX)
+* `SoundCloudMediaAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/SoundCloud` (https://api.soundcloud.com/tracks/XXXXXXXXX (From SoundCloud Embed))
+* `HtmlAudioAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/HtmlAudio`
+* `HtmlVideoAdapter` from `tiny-essentials/libs/media/TinyMediaPlayer/HtmlVideo`
 
 **Example Usage:**
 ```javascript
-import TinyMediaPlayer from 'tiny-essentials/libs/TinyMediaPlayer';
-import { YoutubeMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Youtube';
-import { HtmlAudioAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/HtmlAudio';
+import TinyMediaPlayer from 'tiny-essentials/libs/media/TinyMediaPlayer';
+import { YoutubeMediaAdapter } from 'tiny-essentials/libs/media/TinyMediaPlayer/Youtube';
+import { HtmlAudioAdapter } from 'tiny-essentials/libs/media/TinyMediaPlayer/HtmlAudio';
 
 const player = new TinyMediaPlayer({
   persistVolume: true
@@ -82,7 +82,7 @@ If you need to support a service not covered by the pre-built adapters, you can
 
 **Example Implementation:**
 ```javascript
-import { BaseMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Base';
+import { BaseMediaAdapter } from 'tiny-essentials/libs/media/TinyMediaPlayer/Base';
 
 /**
  * A custom adapter for a hypothetical streaming service.

package/docs/v1/libs/{TinyClipboard.md → text/TinyClipboard.md}

@@ -192,7 +192,7 @@ Gets the current function used for copying blobs.
 ## 🧠 Usage Example
 
 ```ts
-import TinyClipboard from 'tiny-essentials/libs/TinyClipboard';
+import TinyClipboard from 'tiny-essentials/libs/text/TinyClipboard';
 
 const clipboard = new TinyClipboard();
 

package/docs/v1/libs/{TinyTextDiffer.md → text/TinyTextDiffer.md}

@@ -21,7 +21,7 @@ It uses the **Longest Common Subsequence (LCS)** algorithm to ensure that change
 Since this is an ES Module, you can simply import it into your project:
 
 ```javascript
-import TinyTextDiffer from 'tiny-essentials/libs/TinyTextDiffer';
+import TinyTextDiffer from 'tiny-essentials/libs/text/TinyTextDiffer';
 
 const differ = new TinyTextDiffer(["Initial text", "Updated text!"]);
 

package/docs/v1/libs/{TinyTextarea.md → text/TinyTextarea.md}

@@ -17,7 +17,7 @@ A lightweight JavaScript utility for automatically resizing `<textarea>` element
 ## 🚀 Usage
 
 ```js
-import TinyTextarea from 'tiny-essentials/libs/TinyTextarea';
+import TinyTextarea from 'tiny-essentials/libs/text/TinyTextarea';
 
 const textarea = document.querySelector('textarea');
 

package/docs/v1/libs/{TinyClassManager → tools/TinyClassManager}/TinyPluginInliner.md

@@ -55,7 +55,7 @@ This is the file that uses the `TinyClassManager` to compose your final class.
 
 ```javascript
 // src/main.mjs
-import TinyClassManager from 'tiny-essentials/libs/TinyClassManager';
+import TinyClassManager from 'tiny-essentials/libs/tools/TinyClassManager';
 import { LoggerPlugin } from './plugins/LoggerPlugin.mjs';
 
 class BaseUser {}
@@ -72,7 +72,7 @@ export default User;
 Create a build script (e.g., `build.mjs`) to trigger the process.
 
 ```javascript
-import TinyPluginInliner from 'tiny-essentials/libs/TinyClassManager/TinyPluginInliner';
+import TinyPluginInliner from 'tiny-essentials/libs/tools/TinyClassManager/TinyPluginInliner';
 
 const builder = new TinyPluginInliner({
   entryPoint: 'src/main.mjs',

package/docs/v1/libs/{TinyClassManager.md → tools/TinyClassManager.md}

@@ -42,7 +42,7 @@ Let's break down exactly how to design, extend, and instantiate a class structur
 Every structure needs a solid foundation. The core class is the absolute minimum requirement and contains properties that every subsequent plugin might rely on.
 
 ```javascript
-import TinyClassManager from 'tiny-essentials/libs/TinyClassManager';
+import TinyClassManager from 'tiny-essentials/libs/tools/TinyClassManager';
 
 // The foundational class
 class EntityCore {

package/docs/v1/libs/{TinyDebugger.md → tools/TinyDebugger.md}

@@ -7,7 +7,7 @@
 To use `TinyDebugger`, import it into your project and initialize it with a configuration object.
 
 ```javascript
-import TinyDebugger from 'tiny-essentials/libs/TinyDebugger';
+import TinyDebugger from 'tiny-essentials/libs/tools/TinyDebugger';
 
 const debuggerInstance = new TinyDebugger({
   logger: console, // You can use standard console or a custom object