tiny-essentials 1.28.18 → 1.29.0

package/docs/v1/libs/router/TinyRouter.md

@@ -0,0 +1,216 @@
+# 🚀 TinyRouter Documentation
+
+`TinyRouter` is a lightweight, framework-agnostic JavaScript router designed for managing client-side navigation. It allows developers to map URL paths to specific functions, handle dynamic parameters, and manage browser history seamlessly.
+
+## 📋 Table of Contents
+1. [Overview](#overview)
+2. [Key Features](#key-features)
+3. [Getting Started](#getting-started)
+4. [API Reference](#api-reference)
+    - [Properties (Getters & Setters)](#properties-getters--setters)
+    - [Constructor](#constructor)
+    - [Route Management](#route-management)
+    - [Navigation](#navigation)
+    - [History Management](#history-management)
+    - [Lifecycle Management](#lifecycle-management)
+5. [Advanced Configuration](#advanced-configuration)
+6. [Error Handling](#error-handling)
+
+---
+
+## 🌟 Overview
+
+When building Single Page Applications (SPAs), the URL needs to change when the user "moves" between views, even though the page doesn't actually reload. `TinyRouter` listens to the browser's `popstate` event and matches the current URL against a list of registered routes to execute the correct logic.
+
+## ✨ Key Features
+
+* **🧩 Flexible Route Definition:** Define routes using simple strings (e.g., `'/user/:id'`) or complex regular expressions.
+* **🏎️ Lightweight:** No external dependencies.
+* **🛠️ Debugging Support:** Integrated with `TinyDebugger` for easy troubleshooting.
+* **🔄 History Management:** Full control over navigation history, including limits and manual entry removal.
+* **📡 Lifecycle Hooks:** Hooks for route changes (`onRouteChanged`) and missing routes (`onRouteNotFound`).
+* **⏳ Sequential Operations:** Uses an internal promise queue to handle asynchronous routing operations sequentially.
+
+---
+
+## 🚀 Getting Started
+
+To use the router, you need to instantiate it, define your routes, and then call the `.start()` method.
+
+### Basic Example
+
+```javascript
+import TinyRouter from 'tiny-essentials/libs/router/TinyRouter';
+
+// 1. Initialize the router
+const router = new TinyRouter({
+  debugMode: true,
+  onRouteChanged: (match) => console.log('Navigated to:', match.path)
+});
+
+// 2. Register routes
+router.add('/home', () => {
+  console.log('Welcome to the Home Page!');
+});
+
+router.add('/user/:id', (match) => {
+  console.log(`Viewing user with ID: ${match.params.id}`);
+  console.log(`Query params:`, match.query);
+});
+
+// 3. Start the router (Crucial for deep-linking support)
+router.start();
+
+// 4. Navigate programmatically
+await router.navigate('/user/42?theme=dark');
+```
+
+---
+
+## 📖 API Reference
+
+### 🏗️ Constructor
+
+`new TinyRouter(options)`
+
+Initializes the router instance.
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `debugMode` | `boolean` | `false` | Enables internal debug logging. |
+| `useLogColors` | `boolean` | `false` | Enables colored console output. |
+| `detectHistoryChange` | `boolean` | `true` | If `true`, ensures the URL actually changed before resolving navigation. |
+| `logger` | `Console` | `console` | A custom logger object (must implement standard console methods). |
+| `onRouteChanged` | `RouteCallback` | `() => {}` | Callback executed when a route matches successfully. |
+| `onRouteNotFound` | `RouteNotFoundCallback` | `() => {}` | Callback executed when the current URL matches no registered routes. |
+| `historyLimit` | `number` | `0` | Max history entries. Use `-1` for unlimited, or `0` to disable history tracking. |
+
+### ⚙️ Properties (Getters & Setters)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `size` | `number` | Returns the number of registered routes. |
+| `routes` | `string[]` | Returns an array of all registered path patterns. |
+| `history` | `RouterHistoryEntry[]` | **Getter:** Returns a copy of the current history. <br> **Setter:** Imports a validated history array. |
+| `historyLimit` | `number` | Gets the maximum number of history entries allowed. |
+| `detectHistoryChange` | `boolean` | Gets/Sets whether to detect if navigation actually changed the URL. |
+| `onRouteChanged` | `RouteCallback` | Gets/Sets the global route change callback. |
+| `onRouteNotFound` | `RouteNotFoundCallback` | Gets/Sets the global "not found" callback. |
+| `started` | `boolean` | Returns `true` if the router is currently running. |
+| `isDestroyed` | `boolean` | Returns `true` if the router instance has been destroyed. |
+
+### 🛤️ Route Management
+
+#### `.add(patternOrOptions, callback)`
+Registers a new route.
+
+* **Mode 1: Simple String**
+  `router.add('/profile/:username', callback);`
+    Uses default segment extraction.
+* **Mode 2: Advanced Object (Regex)**
+  `router.add({ pattern: '/post/:id', searchValue: /:id/, replaceValue: ... }, callback);`
+    Allows custom regex logic via `SegmentExtractor`.
+* **Mode 3: Callback-in-Object**
+  `router.add({ pattern: '/path', callback: (p) => console.log(p) });`
+    The callback is executed with the pattern string as its argument.
+
+**Throws:**
+* `TypeError`: If arguments are invalid.
+* `Error`: If the pattern is already registered.
+
+#### `.remove(pathPattern)`
+Removes a route by its string pattern.
+
+#### `.has(pathPattern)`
+Returns `true` if the pattern is already registered.
+
+#### `.clear()`
+Removes all registered routes from the router.
+
+#### `.clearAll()`
+Clears all routes AND the entire navigation history.
+
+---
+
+### 🧭 Navigation
+
+#### `.navigate(path, state = {})`
+Moves the browser to a new URL.
+* **`path`**: The target string (e.g., `'/settings'`).
+* **`state`**: An object to store in the browser history.
+* **Returns**: `Promise<void>`
+
+#### `.go(delta)`
+Moves through the history stack.
+* **`delta`**: Integer (e.g., `-1` for back, `1` for forward).
+* **Returns**: `Promise<boolean>` (resolves to `true` if the URL actually changed, `false` otherwise).
+
+#### `.back()` / `.forward()`
+Convenience methods for `go(-1)` and `go(1)`.
+
+---
+
+### 📜 History Management
+
+#### `.removeHistoryEntry(index)`
+Removes a specific entry from the history stack by its index.
+* **Throws:** `TypeError` (if index is not an integer) or `RangeError` (if index is out of bounds).
+
+#### `.clearHistory()`
+Wipes the current navigation history.
+
+---
+
+### 🛠️ Lifecycle Management
+
+#### `.start()`
+**Important:** You must call this to activate the router. It resolves the current URL immediately so that if a user refreshes a page on a specific URL, the router can match the correct route.
+
+#### `.stop()`
+Stops the router, removes event listeners, and clears all data.
+
+#### `.destroy()`
+Permanently destroys the router instance, stopping it and preventing further use.
+
+---
+
+## 🛠️ Advanced Configuration
+
+### Custom Regex Matching
+If the standard `:param` syntax is not enough, you can use the object configuration in `.add()`:
+
+```javascript
+router.add({
+  pattern: '/files/([0-9]+).pdf', // The path template
+  searchValue: /([0-9]+)/,         // The regex to find the dynamic part
+  replaceValue: (match) => match[1] // How to extract the value
+}, (match) => {
+  console.log('File ID:', match.params.id);
+});
+```
+
+### Global Callbacks
+You can define global logic that runs every time the URL changes:
+
+```javascript
+const router = new TinyRouter({
+  onRouteChanged: (match) => {
+    // Update the page title dynamically
+    document.title = `App - ${match.path}`;
+  },
+  onRouteNotFound: ({ path }) => {
+    // Redirect to 404 or show a custom error UI
+    console.error(`404: ${path} not found`);
+  }
+});
+```
+
+---
+
+## ⚠️ Error Handling
+
+`TinyRouter` uses strict validation to ensure stability.
+
+* **`TypeError`**: Thrown when passing incorrect data types (e.g., non-integer `historyLimit` or invalid `pathPattern`).
+* **`RangeError`**: Thrown when attempting to access a history index that is out of bounds.
+* **`Error`**: Thrown when attempting to register a duplicate route or starting a router that is already running.

package/docs/v1/libs/storage/TinyMapCache.md

@@ -0,0 +1,219 @@
+# 📦 TinyMapCache Documentation
+
+`TinyMapCache` is a lightweight, event-driven, in-memory cache manager designed for JavaScript environments. It is optimized for preventing duplicate requests and managing temporary data with automatic expiration.
+
+## 🌟 Key Features
+
+*   🚀 **High Performance:** Uses an in-memory `Map` for near-instantaneous data retrieval.
+*   ⏱️ **TTL (Time-To-Live):** Automatically handles data expiration based on a configurable millisecond timer.
+*   🔔 **Event-Driven Architecture:** Extends `EventEmitter` to provide hooks for lifecycle changes (`set`, `delete`, `expire`, `purge`, `clear`).
+*   🛡️ **Data Integrity:** Uses `structuredClone` to return deep copies of data, preventing accidental mutations of the cached items.
+*   🧹 **Cascaded Purging:** Features a unique "Global Purge" capability that can trigger expiration checks across all active cache instances simultaneously.
+*   🔁 **Familiar Iteration API:** Implements `keys()`, `values()`, `entries()`, `forEach()` and `Symbol.iterator`, so it can be used in `for...of` loops and spread syntax just like a native `Map`.
+
+---
+
+## 🛠️ Getting Started
+
+### Installation
+Since this is an ES6 module, ensure your environment supports `import` syntax.
+
+```javascript
+import TinyMapCache from 'tiny-essentials/libs/storage/TinyMapCache';
+```
+
+### Basic Initialization
+```javascript
+const cache = new TinyMapCache();
+
+// Set a custom TTL (e.g., 10 seconds)
+cache.ttl = 10000; 
+```
+
+---
+
+## 📖 API Reference
+
+### ⚙️ Configuration & Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `ttl` | `number` | The Time-To-Live in milliseconds. Default is `300000` (5 minutes). |
+| `size` | `number` | Returns the current number of items stored in the cache. |
+| `[Symbol.toStringTag]` | `string` | Read-only. Always returns `'TinyMapCache'`. Used by `Object.prototype.toString`. |
+
+### 🚀 Methods
+
+#### `.set(key, data)`
+Stores a value in the cache associated with a specific key.
+*   **Key:** `string` (Required)
+*   **Data:** `any` (Required)
+*   **Note:** Triggers `purgeExpired(true)` before saving.
+
+#### `.get(key)`
+Retrieves the data associated with the key.
+*   **Key:** `string` (Required)
+*   **Returns:** The stored data if valid; `null` if expired or not found.
+*   **Note:** Triggers `purgeExpired(true)` before retrieving.
+
+#### `.has(key)`
+Checks if a key exists and is valid (not expired).
+*   **Key:** `string` (Required)
+*   **Returns:** `boolean`
+*   **Note:** Triggers `purgeExpired(true)` before checking.
+
+#### `.delete(key)`
+Removes a specific item from the cache.
+*   **Key:** `string` (Required)
+*   **Returns:** `boolean` (True if an element existed and was removed).
+
+#### `.clear()`
+Wipes all items from the current cache instance.
+
+#### `.purgeExpired(clearAll = false)`
+Manually triggers the expiration logic.
+*   **`clearAll = true`**: Triggers a purge across **all** active `TinyMapCache` instances in the application.
+*   **`clearAll = false`**: Only purges expired items in the current instance.
+
+#### `.keys()`
+Returns an iterator over the keys of all valid (non-expired) entries.
+*   **Returns:** `IterableIterator<string>`
+*   **Note:** Triggers `purgeExpired(true)` before building the result.
+
+#### `.values()`
+Returns an iterator over the values of all valid (non-expired) entries.
+*   **Returns:** `IterableIterator<T>`
+*   **Note:** Triggers `purgeExpired(true)` before building the result.
+
+#### `.entries()`
+Returns an iterator over the `[key, value]` pairs of all valid (non-expired) entries.
+*   **Returns:** `IterableIterator<[string, T]>`
+*   **Note:** Triggers `purgeExpired(true)` before building the result.
+
+#### `[Symbol.iterator]()`
+Alias for `.entries()`. Enables `for...of`, spread (`[...cache]`) and destructuring directly on the instance.
+*   **Returns:** `IterableIterator<[string, T]>`
+
+#### `.forEach(callbackFn, thisArg)`
+Executes a provided function once for each valid (non-expired) entry.
+*   **`callbackFn`:** `(data: T, key: string, cache: TinyMapCache<T>) => void` (Required)
+*   **`thisArg`:** `any` (Optional) — Value to use as `this` inside `callbackFn`.
+*   **Returns:** `void`
+*   **Throws:** `TypeError` if `callbackFn` is not a function.
+*   **Note:** Triggers `purgeExpired(true)` before iterating.
+
+---
+
+## 🔔 Event Listeners
+
+The `TinyMapCache` emits several events that you can listen to for advanced logic (like logging or synchronizing databases).
+
+| Event | Payload Type | Description |
+| :--- | :--- | :--- |
+| `'set'` | `{ key: string, data: T }` | Emitted when a new item is successfully stored. |
+| `'delete'` | `{ key: string }` | Emitted when an item is manually removed. |
+| `'expire'` | `{ key: string, data: T }` | Emitted when an item is removed due to TTL expiration. |
+| `'purge'` | `{ count: number }` | Emitted when multiple items are removed during a purge. |
+| `'clear'` | `void` | Emitted when the entire cache is wiped. |
+
+---
+
+## 💡 Practical Implementation Examples
+
+### 1. Basic Usage with TTL
+This is the most common way to use the cache to avoid redundant API calls.
+
+```javascript
+const userCache = new TinyMapCache();
+userCache.ttl = 60000; // 1 minute
+
+async function getUserData(userId) {
+  const cachedUser = userCache.get(userId);
+  
+  if (cachedUser) {
+    console.log("📦 Serving from cache");
+    return cachedUser;
+  }
+
+  console.log("🌐 Fetching from API...");
+  const data = await fetchFromDatabase(userId); // Simulated API call
+  userCache.set(userId, data);
+  return data;
+}
+```
+
+### 2. Using Events for Monitoring
+You can use events to track how much data is expiring in your system.
+
+```javascript
+const monitorCache = new TinyMapCache();
+
+monitorCache.on('expire', (payload) => {
+  console.warn(`⚠️ Item expired: ${payload.key}`);
+});
+
+monitorCache.on('purge', (payload) => {
+  console.log(`🧹 Cleanup complete. Removed ${payload.count} items.`);
+});
+```
+
+### 3. Advanced: Cascaded Purging
+If your application creates many cache instances (e.g., one per user session), you can clear them all at once to free up memory.
+
+```javascript
+const sessionCache1 = new TinyMapCache();
+const sessionCache2 = new TinyMapCache();
+
+sessionCache1.set('session_id', 123);
+sessionCache2.set('session_id', 456);
+
+// This will trigger purgeExpired(false) on sessionCache2
+sessionCache1.purgeExpired(true); 
+```
+
+### 4. Iterating Over the Cache
+All iteration helpers return a **snapshot** of the valid entries at the moment of the call. Expired items are never yielded.
+
+```javascript
+const cache = new TinyMapCache();
+cache.set('user:1', { name: 'Yasmin' });
+cache.set('user:2', { name: 'Isabela' });
+
+// for...of (uses Symbol.iterator)
+for (const [key, user] of cache) {
+  console.log(key, user.name);
+}
+
+// Spread into an array
+const allKeys = [...cache.keys()];
+const allUsers = [...cache.values()];
+
+// forEach with a bound context
+cache.forEach(function (user, key) {
+  console.log(`${key} -> ${user.name}`, this.label);
+}, { label: '(cached)' });
+```
+
+### 5. Map Compatibility Cheat Sheet
+| Native `Map` | `TinyMapCache` | Notes |
+| :--- | :--- | :--- |
+| `map.get(k)` | `cache.get(k)` | Returns `null` instead of `undefined` when missing. |
+| `map.set(k, v)` | `cache.set(k, v)` | Requires a `string` key. |
+| `map.has(k)` | `cache.has(k)` | Expired keys return `false`. |
+| `map.delete(k)` | `cache.delete(k)` | Emits `'delete'`. |
+| `map.clear()` | `cache.clear()` | Emits `'clear'`. |
+| `map.size` | `cache.size` | — |
+| `map.keys()` | `cache.keys()` | Skips expired entries. |
+| `map.values()` | `cache.values()` | Skips expired entries. |
+| `map.entries()` | `cache.entries()` | Skips expired entries. |
+| `map.forEach(fn)` | `cache.forEach(fn)` | Same argument order. |
+| `[...map]` | `[...cache]` | Same `[key, value]` shape. |
+| `new Map(iterable)` | ❌ Not supported | See "Important Technical Notes". |
+
+---
+
+## ⚠️ Important Technical Notes
+
+1.  **Automatic Cleanup:** Most methods (`get`, `set`, `has`, `delete`) automatically call `purgeExpired(true)`. This ensures you are always working with fresh data, but be aware that in very large caches, this adds a small overhead to every call.
+2.  **Memory Management:** When a `TinyMapCache` instance becomes empty (size 0), it automatically removes itself from the internal `#instances` set to prevent memory leaks.
+4.  **Snapshot Semantics:** The iteration methods (`keys`, `values`, `entries`, `forEach`) build a snapshot array before returning. Mutating the cache while iterating is therefore safe, but the loop will **not** see changes made after it started.