tiny-essentials 1.28.19 → 1.29.0

package/docs/v1/libs/tools/TinyBrowserMonitor.md

@@ -0,0 +1,170 @@
+# 🌐 TinyBrowserMonitor Documentation
+
+Welcome to the **TinyBrowserMonitor** documentation! 🚀 This lightweight, high-performance utility is designed to give developers real-time insights into a user's network environment and device performance.
+
+Whether you are building a progressive web app (PWA) that needs to react to offline status, a data-heavy dashboard that needs to adjust quality based on bandwidth, or a high-performance application requiring deep web vitals tracking, `TinyBrowserMonitor` has you covered.
+
+---
+
+## 🌟 Overview
+
+`TinyBrowserMonitor` is an event-driven monitor that tracks several critical pillars of environment health:
+1.  **Connectivity Status:** Are we online or offline? 📶
+2.  **Connection Quality:** Bandwidth, Latency, Connection Type, and API availability. ⚡
+3.  **Battery Status:** Charge level and charging state. 🔋
+4.  **Device Metrics:** Hardware constraints like device memory. 💻
+5.  **Resource Performance:** Loading duration of assets (images, scripts, etc.). ⏱️
+6.  **Web Vitals & Performance:** Deep insights into Paint timing, Navigation, Layout Shift (CLS), LCP, and Long Tasks. 🚀
+
+---
+
+## 📦 Getting Started
+
+### Installation & Import
+Since this module uses ES6 syntax, ensure your environment supports `import`.
+
+```javascript
+import TinyBrowserMonitor from 'tiny-essentials/libs/tools/TinyBrowserMonitor';
+```
+
+### Initialization
+```javascript
+/**
+ * @param {MonitorOptions} [options={}] - Configuration options.
+ * @param {number} [options.resourceLimit=1000] - Maximum number of resource metrics to store. Use -1 for infinite.
+ * @param {SystemValue[]} [options.systems] - List of systems to enable. If empty, all are enabled.
+ * @param {number} [options.memoryIntervalMs=100] - Interval in milliseconds for memory polling.
+ * @param {number} [options.fpsIntervalMs=1000] - Interval in miliseconds for fps polling.
+ */
+const monitor = new TinyBrowserMonitor(options);
+```
+
+---
+
+## 🛠️ Core Features
+
+### 1. Real-time Connectivity Tracking
+Automatically detects when a user loses or regains internet access.
+
+### 2. Network Quality Metrics
+Leverages the **Network Information API** to provide:
+* `downlink`: Effective bandwidth in Mbps.
+* `rtt`: Estimated round-trip time (latency).
+* `effectiveType`: The connection type (e.g., '4g', '3g').
+* `saveData`: Detects if the user has "Data Saver" mode enabled.
+* `enabled`: Indicates if the Network Information API is supported.
+
+### 3. Battery & Device Monitoring
+* **Battery:** Tracks `level`, `charging` state, and time to full/empty.
+* **Device:** Provides approximate `memory` (GB) via the Device Memory API.
+
+### 4. Comprehensive Performance & Web Vitals
+Uses the `PerformanceObserver` API to track:
+* **Resource Loading:** Detailed metrics for every fetched asset.
+* **Paint Timing:** `first-paint` and `first-contentful-paint`.
+* **Navigation Timing:** `ttfb`, `domContentLoaded`, and `loadEvent`.
+* **Core Web Vitals:** `layoutShift` (CLS) and `lcp` (Largest Contentful Paint).
+* **Responsiveness:** Tracks `longTasks` to monitor main thread blockage.
+
+---
+
+## 📖 Usage Guide
+
+### 📡 Method 1: The Event-Driven Approach (Recommended)
+Since `TinyBrowserMonitor` extends `EventEmitter`, you can listen for specific events.
+
+#### Global Updates
+Listen for any change in the monitored systems. The payload contains a comprehensive `NetworkEvent` report.
+```javascript
+monitor.on('NetworkUpdated', (data) => {
+  console.log('📊 Full Report:', data);
+  if (data.event) console.log('Triggered by event:', data.event.type);
+});
+```
+
+#### Specific System Events
+You can listen to granular updates to optimize performance:
+
+* **Connectivity:** `monitor.on('ConnectivityUpdated', (status) => ...)`
+* **Battery:** `monitor.on('BatteryUpdated', (battery) => ...)`
+* **Memory:** `monitor.on('MemoryUsage', (memory) => ...)`
+* **FPS:** `monitor.on('FPS', (fps) => ...)`
+* **Window Resize:** `monitor.on('WindowResize', (metrics) => ...)`
+
+#### Performance & Web Vitals Events
+* **Paint:** `monitor.on('PaintUpdated', (paint) => ...)`
+* **Navigation:** `monitor.on('NavigationUpdated', (nav) => ...)`
+* **Layout Shift:** `monitor.on('LayoutShiftUpdated', ({ layoutShift }) => ...)`
+* **LCP:** `monitor.on('LcpUpdated', ({ lcp }) => ...)`
+* **Long Tasks:** `monitor.on('LongTaskUpdated', ({ lcp }) => ...)` 
+  > *Note: The payload contains an array of task durations under the `lcp` key.*
+
+#### Resource Lifecycle Events
+Emitted when the resource history changes:
+* `ResourceAdded`: Emitted when a new resource is tracked. `(oldItem, newItem)`
+* `ResourceDeleted`: Emitted when an old resource is removed (FIFO). `(oldItem, newItem)`
+* `ResourceEdited`: Emitted if resource data is updated. `(oldItem, newItem)`
+
+#### Lifecycle
+* **Destroyed:** Emitted when the monitor is cleaned up. `monitor.on('Destroyed', () => ...)`
+
+---
+
+### 📸 Method 2: Snapshot Access & Helpers
+Check metrics at any specific moment without waiting for an event.
+
+#### Snapshot Getters
+All getters return **read-only (frozen)** objects to ensure data integrity.
+```javascript
+const connectivity = monitor.connectivity;
+const quality = monitor.quality;
+const resources = monitor.resources;
+const battery = monitor.battery;
+const device = monitor.device;
+const performance = monitor.performance;
+const memoryUsage = monitor.memoryUsage;
+const windowMetrics = monitor.windowMetrics;
+const screenMetrics = monitor.screenMetrics;
+const fps = monitor.fps;
+```
+
+#### Utility Methods
+```javascript
+// Check how many systems are currently active
+console.log(monitor.size); 
+
+// Check if a specific system is enabled
+if (monitor.has('battery')) { ... }
+
+// Get human-readable memory (e.g., '1.5 GB')
+const memory = monitor.getFormattedMemoryUsage('GB'); 
+// Returns: { used: 1.5, total: 8, limit: 16 }
+```
+
+---
+
+## 🧹 Cleanup & Memory Management
+
+To prevent **memory leaks**, especially in Single Page Applications (SPAs), you **must** call the `destroy()` method when the component or page is unmounted.
+
+```javascript
+// Cleanup
+monitor.destroy();
+
+// Listen for destruction
+monitor.on('Destroyed', () => console.log('Monitor cleaned up.'));
+```
+
+**What `destroy()` does:**
+* ✅ Removes `online`/`offline` window listeners.
+* ✅ Removes `connection` change listeners.
+* ✅ Disconnects all `PerformanceObserver` instances.
+* ✅ Clears all internal event emitters.
+* ✅ Sets `isDestroyed` to `true`.
+
+---
+
+## ⚠️ Important Notes
+
+* **Immutability:** All returned reports are read-only. Attempting to change properties directly will fail.
+* **Resource Limit:** If a `resourceLimit` is set, the monitor uses FIFO (First-In, First-Out) logic to remove the oldest entries.

package/docs/v1/libs/tools/TinyDebugger.md

@@ -13,6 +13,7 @@ const debuggerInstance = new TinyDebugger({
   logger: console, // You can use standard console or a custom object
   id: 'APP_CORE',
   debugMode: true,
+  autoHideId: false,
   canEmitLogs: true,
   useLogColors: true
 });
@@ -28,7 +29,8 @@ When creating a new instance via the `constructor`, you can pass a configuration
 
 | Property | Type | Required | Default | Description |
 | :--- | :--- | :--- | :--- | :--- |
-| `logger` | `Object` | **Yes** | N/A | An object implementing the `Console` interface. |
+| `logger` | `Partial<Console>` | **Yes** | N/A | An object implementing the `Console` interface. |
+| `autoHideId` | `boolean` | No | `false` | Whether to hide the instance id whenever a sub id is set. |
 | `id` | `string` | **Yes** | N/A | A unique identifier for this debugger instance. |
 | `debugMode` | `boolean` | **Yes** | N/A | If `false`, all logging methods will return immediately. |
 | `canEmitLogs` | `boolean` | No | `false` | If `true`, the instance will emit events for every log action. |
@@ -53,6 +55,22 @@ If `canEmitLogs` is set to `true`, `TinyDebugger` acts as an `EventEmitter`, all
 
 ---
 
+## 🧩 Instance Properties
+
+These properties are accessed directly on the instance (not as methods).
+
+| Property | Type | Access | Description |
+| :--- | :--- | :--- | :--- |
+| `logId` | `string` | read-only | The instance debug id. |
+| `logSubId` | `string` | read / write | A sub-identifier. **Can only be assigned once.** Reading it before assignment throws an `Error`. |
+| `debugMode` | `boolean` | read / write | Enables or disables all logging. |
+| `canEmitLogs` | `boolean` | read-only | Whether event emission is enabled. |
+| `useLogColors` | `boolean` | read / write | Enables or disables ANSI colors. |
+
+> ⚠️ **Note:** Setting `debugMode` or `useLogColors` emits the `setDebugMode` event.
+
+---
+
 ## 📖 API Reference
 
 ### `log(logType, message, ...args)`
@@ -101,6 +119,21 @@ You can dynamically modify the behavior of your debugger instance using these in
 | `_removeLogColor(id)` | Removes a color shortcut. |
 | `_addLogPrefix(id, text)` | Adds a new prefix shortcut (e.g., `:status:`). |
 | `_removeLogPrefix(id)` | Removes a prefix shortcut. |
+| `_applyLogFormatting(text)` | Applies all prefix and color replacements to a string and returns the result. |
+
+### Default Colors
+
+`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`.
+
+### Default Prefixes
+
+| Shortcut | Output |
+| :--- | :--- |
+| `:log:` | `[_log_LOG_reset_]` |
+| `:info:` | `[_info_INFO_reset_]` |
+| `:warn:` | `[_warn_WARN_reset_]` |
+| `:error:` | `[_error_ERROR_reset_]` |
+| `:debug:` | `[_debug_DEBUG_reset_]` |
 
 ### Example: Adding a Custom Color
 ```javascript
@@ -110,6 +143,89 @@ debuggerInstance.log('info', 'This message is _gold_!');
 
 ---
 
+## 🎨 Color Convention
+
+`TinyDebugger` follows a visual convention for color usage. Following it keeps logs predictable: a reader can identify the role of each element by its color alone, without reading the full message.
+
+| Color | Applies to | Meaning |
+| :--- | :--- | :--- |
+| 🔵 Blue | Main class | The **primary class** of the current context. |
+| 🟢 Green | Sub-class | A **sub-class** that belongs to something connected to the main class. |
+
+### How to read it
+
+*   **Blue = the main class.** This is the entry point of the context you are looking at.
+*   **Green = the sub-class.** This is a class that is connected to (owned by, instantiated by, or dependent on) the main class. It is not the entry point itself.
+
+### Example
+
+```javascript
+// The main class is blue, the sub-class is green.
+debugger.log('info', '[_main_class_Server_reset_] started [_sub_class_Router_reset_]');
+```
+
+In the example above:
+
+*   `[Server]` is the **main class** (blue).
+*   `[Router]` is a **sub-class** connected to `Server` (green).
+
+> 💡 **Tip:** Use `_addLogColor(id, code)` to register these shortcuts once and reuse them across your project instead of repeating raw ANSI codes.
+
+---
+
+## 📡 Events
+
+When `canEmitLogs` is `true`, the instance emits the following events:
+
+| Event | Payload | Emitted when |
+| :--- | :--- | :--- |
+| `setDebugMode` | `boolean` | `debugMode` or `useLogColors` is changed. |
+| `debug:log` | `(prefix, message, ...args)` | `log()` is called. |
+| `debug:clear` | — | `logClear()` is called. |
+| `debug:groupEnd` | — | `logGroupEnd()` is called. |
+| `debug:logLabel` | `(logType, label)` | `logLabel()` is called. |
+| `debug:timeLog` | `(label, ...args)` | `logTimeLabel()` is called. |
+| `debug:assert` | `(condition, ...args)` | `logAssert()` is called. |
+| `debug:dir` | `(item, options)` | `logDir()` is called. |
+| `debug:table` | `(tabularData, properties)` | `logTable()` is called. |
+
+---
+
+## 🖥️ Console Facade
+
+The `toConsole()` method returns a `console`-compatible object. Every call is
+routed through the instance's logging methods, so formatting, debug mode, and
+event emission keep working automatically.
+
+```javascript
+const debug = new TinyDebugger({
+  logger: console,
+  id: 'APP_CORE',
+  debugMode: true,
+});
+
+const log = debug.toConsole();
+
+log.log('Hello, %s!', 'world'); // Routed through debug.log('log', ...)
+log.warn('Careful!');
+log.table([{ a: 1 }, { a: 2 }]);
+```
+
+### Supported methods
+
+| Group | Methods |
+| :--- | :--- |
+| Standard | `log`, `info`, `warn`, `error`, `debug` |
+| Grouping | `group`, `groupCollapsed`, `groupEnd` |
+| Inspection | `dir`, `dirxml`, `table`, `trace` |
+| Assertion | `assert` |
+| Timers | `time`, `timeEnd`, `timeLog`, `timeStamp` |
+| Counters | `count`, `countReset` |
+| Profiler | `profile`, `profileEnd` |
+| Utility | `clear` |
+
+---
+
 ## ⚠️ Error Handling
 
 It will throw `TypeError` if:

package/docs/v1/libs/tools/TinyHtmlTagRegexBuilder.md

@@ -0,0 +1,141 @@
+# 🛠️ TinyHtmlTagRegexBuilder
+
+Welcome to the official documentation for `TinyHtmlTagRegexBuilder`. This utility is designed to make parsing specific HTML tags using Regular Expressions much more structured, predictable, and easy to manage in your daily development workflow.
+
+## 📝 Overview
+
+Parsing HTML with Regular Expressions can be complex and error-prone. The `TinyHtmlTagRegexBuilder` solves this by providing a high-level configuration interface to build specialized Regex patterns. 
+
+Instead of writing long, confusing regex strings manually, you define the **rules** (the tag name, the attributes you want, and how to handle content), and this class generates the engine for you.
+
+---
+
+## 🚀 Getting Started
+
+Since this project uses ES6 modules, you can import it into your JavaScript files like this:
+
+```javascript
+import TinyHtmlTagRegexBuilder from 'tiny-essentials/libs/tools/TinyHtmlTagRegexBuilder';
+```
+
+---
+
+## ⚙️ Configuration Guide
+
+When you create a new instance using `new TinyHtmlTagRegexBuilder(config)`, you must provide a configuration object. Here is a breakdown of every property available:
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `tagName` | `string` | **Yes** | N/A | The name of the HTML tag you want to target (e.g., `'a'`, `'img'`, `'div'`). |
+| `attributes` | `string[]` | No | `[]` | An array of specific attribute names you want to extract individually. |
+| `captureAllAttributes` | `boolean` | **Yes** | N/A | Determines if you want to grab *every* attribute or only the ones listed in `attributes`. |
+| `freeMode` | `boolean` | No | `false` | If `true`, the regex will match content even if it spans multiple lines. |
+| `contentPattern` | `string` | No | `'[\s\S]*?'` | A custom regex pattern to define what constitutes the "inner content" of the tag. |
+
+---
+
+## 🛠️ Usage Modes
+
+This is the most important part of the tool. You must choose one of two "modes" based on your goal.
+
+### 🎯 Mode 1: The "Precision Sniper" (Specific Attributes)
+**Use this when:** You only care about a few specific attributes (like `href` in an `<a>` tag or `src` in an `<img>` tag) and want to ignore everything else.
+
+*   **Requirement:** `captureAllAttributes` must be `false`.
+*   **How it works:** It uses "Lookaheads" to find exactly the attributes you requested in the `attributes` array.
+
+### 📦 Mode 2: The "Grab Everything" (All Attributes)
+**Use this when:** You don't know which attributes will be present, but you want to capture every single one of them.
+
+*   **Requirement:** `captureAllAttributes` must be `true`.
+*   **How it works:** It captures the entire attribute string and then uses an internal parser to turn it into a clean JavaScript object.
+
+---
+
+## 🧪 Practical Examples
+
+Here are two real-world scenarios to help you implement this in your projects.
+
+### Example 1: Extracting Links (`<a>` tags) 🔗
+In this example, we only care about the `href` attribute.
+
+```javascript
+const linkBuilder = new TinyHtmlTagRegexBuilder({
+  tagName: 'a',
+  attributes: ['href'],
+  captureAllAttributes: false
+});
+
+const html = '<a href="https://google.com" class="link">Click Me</a>';
+const results = linkBuilder.parse(html);
+
+console.log(results);
+/* 
+Output:
+[{
+  attributes: { href: 'https://google.com' },
+  child: 'Click Me'
+}]
+*/
+```
+
+### Example 2: Extracting All Attributes and Multi-line Content 📄
+In this example, we want everything inside a `div`, including newlines, and we want all attributes.
+
+```javascript
+const divBuilder = new TinyHtmlTagRegexBuilder({
+  tagName: 'div',
+  captureAllAttributes: true,
+  freeMode: true
+});
+
+const html = `
+<div id="main" class="container" data-role="wrapper">
+  <h1>Hello World</h1>
+</div>`;
+
+const results = divBuilder.parse(html);
+
+console.log(results);
+/* 
+Output:
+[{
+  attributes: { 
+    id: 'main', 
+    class: 'container', 
+    'data-role': 'wrapper' 
+  },
+  child: '\n  <h1>Hello World</h1>\n'
+}]
+*/
+```
+
+---
+
+## 📖 API Reference
+
+### `constructor(config)`
+Initializes the builder. 
+*   **Throws:** `TypeError` if `tagName` is not a string, if it contains invalid characters (`<`, `>`, or spaces), or if `captureAllAttributes` is not a boolean.
+
+### `toRegExp(flag = 'g')`
+Returns the compiled `RegExp` object.
+*   **Parameter:** `flag` (string) - Standard regex flags (default is `'g'`).
+
+### `parse(htmlString)`
+The primary method. It executes the regex against your string and returns an array of objects.
+*   **Returns:** `ParsedHtmlTag[]` (An array of objects containing `attributes` and `child`).
+
+### `toString()`
+Returns the raw regex string used for matching. Useful for debugging!
+
+---
+
+## ⚠️ Error Handling
+
+To ensure your code is robust, this class implements **Strict Runtime Validation**. If you pass the wrong data type, the code will "fail fast" by throwing a `TypeError`.
+
+**Common Errors to Watch For:**
+1.  `TypeError: The tagName must be a single word...` — You tried to use a tag like `<div >` (with a space) or `<p>`.
+2.  `TypeError: captureAllAttributes must be a boolean.` — You forgot to define this required property.
+3.  `TypeError: freeMode must be a boolean.` — You provided a string or number instead of `true`/`false`.

package/docs/v1/libs/tools/TinyHttpResponseRegistry.md

@@ -0,0 +1,129 @@
+# 📦 Tiny HTTP Response Registry
+
+A robust, immutable, and internationalized registry for managing HTTP status codes. This module ensures that your application's HTTP response data (names, summaries, and descriptions) remains consistent, validated, and ready for multi-language support.
+
+## 🌟 Overview
+
+In large-scale applications, managing HTTP error messages manually can lead to bugs (e.g., typos in "Not Found") and difficulty when translating the app into other languages. 
+
+`TinyHttpResponseRegistry` solves this by:
+1. **Centralizing** all HTTP response data.
+2. **Enforcing strict types** to prevent invalid data from entering your system.
+3. **Supporting Localization (i18n)** so you can serve "Not Found" in English and "Não Encontrado" in Portuguese using the same ID.
+
+---
+
+## 🚀 Key Features
+
+*   **🔒 Immutability:** Uses `structuredClone` and private fields (`#`) to ensure that once a response is registered, it cannot be accidentally changed by other parts of the program.
+*   **🌍 Internationalization (i18n):** Deeply integrated with `TinyI18` to allow seamless language switching.
+*   **💎 Data Integrity:** Uses a "Static Default" system to provide base responses that are shared across all instances of the registry.
+
+---
+
+## 📖 API Reference
+
+### `constructor(initialResponses)`
+Initializes the registry.
+*   **Parameters:** `initialResponses` (Optional `HttpResponses` object).
+*   **Throws:** `TypeError` if `initialResponses` is not a valid object.
+
+### `addResponse(id, response, locale)`
+Registers a new HTTP status code.
+*   **Parameters:**
+    *   `id` (`number`): The HTTP code (e.g., `404`).
+    *   `response` (`HttpResponse`): An object containing `{ name, summary, description }`.
+    *   `locale` (`string`, optional): The language for this specific entry.
+*   **Throws:** 
+    *   `TypeError`: If the response object is missing required properties or has wrong types.
+    *   `Error`: If the ID is already registered.
+
+### `get(id, params, locale)`
+Retrieves the data for a specific code.
+*   **Parameters:**
+    *   `id` (`number`): The HTTP code to search for.
+    *   `params` (`Object`, optional): Variables for string replacement in translations.
+    *   `locale` (`string`, optional): The language to retrieve.
+*   **Returns:** `HttpResponse | null` (The object containing `name`, `summary`, and `description`, or `null` if not found).
+
+### `has(id)`
+Checks if a code exists.
+*   **Returns:** `boolean`.
+
+### `getAll()`
+Returns every registered response in the current instance.
+*   **Returns:** `HttpResponses` object.
+
+---
+
+## 💡 Practical Examples
+
+### 1. Basic Usage 🛠️
+Standard setup and retrieval of a default code.
+
+```javascript
+import TinyHttpResponseRegistry from 'tiny-essentials/libs/tools/TinyHttpResponseRegistry';
+
+const registry = new TinyHttpResponseRegistry();
+
+// Check if 404 exists
+console.log(registry.has(404)); // true
+
+// Get data
+const error404 = registry.get(404);
+console.log(error404.name); // "Not Found"
+```
+
+### 2. Adding Custom Responses & Localization 🌍
+How to add your own codes and support multiple languages.
+
+```javascript
+const registry = new TinyHttpResponseRegistry();
+
+// Adding a custom error in English
+registry.addResponse(501, {
+  name: 'Not Implemented',
+  summary: 'Service not implemented',
+  description: 'The server does not support the functionality required to fulfill the request.'
+}, 'en');
+
+// Adding the same error in Portuguese
+registry.addResponse(501, {
+  name: 'Não Implementado',
+  summary: 'Serviço não implementado',
+  description: 'O servidor não suporta a funcionalidade necessária.'
+}, 'pt');
+
+// Retrieving based on locale
+console.log(registry.get(501, {}, 'en').name); // "Not Implemented"
+console.log(registry.get(501, {}, 'pt').name); // "Não Implementado"
+```
+
+### 3. Error Handling ⚠️
+The registry is designed to fail loudly if you make a mistake, which is better than failing silently in production.
+
+```javascript
+const registry = new TinyHttpResponseRegistry();
+
+try {
+  // Error: 'summary' is missing
+  registry.addResponse(418, {
+    name: 'I am a teapot',
+    description: 'I refuse to brew coffee'
+  });
+} catch (error) {
+  console.error(error.message); 
+  // Output: "Property 'summary' in status 418 must be a string."
+}
+```
+
+---
+
+## 🛠️ Daily Workflow Integration
+
+When working on a project using this module, follow these steps:
+
+1.  **Initialization:** Create a single instance of `TinyHttpResponseRegistry` at the start of your application lifecycle (e.g., in an `app.js` or `container.js` file).
+2.  **Registration Phase:** During the application startup, use `addResponse` to load all your custom business-logic error codes.
+3.  **Usage Phase:** In your Controllers or Middleware, use `registry.get(code)` to fetch the correct message to send back to the client.
+4.  **Localization:** Always pass the user's preferred language (detected from the `Accept-Language` header) into the `.get()` method.