tiny-essentials 1.28.18 → 1.29.0

package/docs/v1/libs/tools/TinyUriParser/Discord.md

@@ -0,0 +1,374 @@
+# 📡 TinyUriParser & Discord URI Toolkit
+
+> A tiny, dependency-free toolkit for parsing and rebuilding Discord URIs,
+> mentions, invites, CDN assets, and more — with strict runtime validation.
+
+---
+
+## 📖 Table of Contents
+
+1. [Overview](#-overview)
+2. [Installation](#-installation)
+3. [Core Concepts](#-core-concepts)
+4. [TinyUriParser API](#-tinyuriparser-api)
+5. [Discord Module](#-discord-module-discordmjs)
+   - [Mentions](#1--mentions)
+   - [Game Profiles](#2--game-profiles)
+   - [Guild Navigation](#3--guild-navigation)
+   - [Emojis](#4--emojis)
+   - [Timestamps](#5--timestamps)
+   - [Commands](#6--commands)
+   - [Invites](#7--invites)
+   - [Message Links](#8--message-links)
+   - [CDN Assets](#9--cdn-assets)
+6. [Known Issues](#-known-issues)
+
+---
+
+## 🎯 Overview
+
+This project has two layers:
+
+| Layer | File | Responsibility |
+| --- | --- | --- |
+| 🧩 **Engine** | `TinyUriParser` | Generic, protocol-agnostic URI parser/stringifier. |
+| 💬 **Discord** | `TinyUriParser/Discord` | All Discord-specific parsers built on top of the engine. |
+
+The engine knows **nothing** about Discord. It only knows how to:
+
+1. Test a string against a set of registered parsers.
+2. Return a structured `{ type, data }` object.
+3. Rebuild the original string from that object.
+
+The Discord module plugs into the engine by exporting **parser pairs**.
+
+---
+
+## 📦 Installation
+
+```js
+// Import the engine
+import TinyUriParser from 'tiny-essentials/libs/tools/TinyUriParser';
+
+// Import the Discord parser collection
+import { DiscordProtocolParsers } from 'tiny-essentials/libs/tools/TinyUriParser/Discord';
+```
+
+---
+
+## 🧩 Core Concepts
+
+### What is a `ParserPair`?
+
+A `ParserPair` is an immutable tuple with **exactly four** elements:
+
+```js
+[type, checker, parser, stringify]
+```
+
+| Index | Name | Type | Purpose |
+| --- | --- | --- | --- |
+| 0 | `type` | `string` | Unique identifier (e.g., `'emoji'`). |
+| 1 | `checker` | `(uri: string) => boolean` | Returns `true` if this parser can handle the URI. |
+| 2 | `parser` | `(uri: string) => ParsedUri` | Converts the URI into a structured object. |
+| 3 | `stringify` | `(data: object) => string` | Rebuilds the URI from parsed data. |
+
+### The `ParsedUri` shape
+
+Every parser returns an object with this shape:
+
+```js
+{
+  type: 'emoji',              // The parser category
+  data: { /* parser-specific payload */ }
+}
+```
+
+---
+
+## 🔧 TinyUriParser API
+
+### `TinyUriParser.buildParserPair(type, checker, parser, stringify)`
+
+Static factory. Creates a frozen `ParserPair`.
+
+```js
+const MyPair = TinyUriParser.buildParserPair(
+  'greeting',
+  (uri) => uri.startsWith('hello:'),
+  (uri) => ({ dataType: 'greeting', name: uri.slice(6) }),
+  (data) => `hello:${data.name}`,
+);
+```
+
+### `new TinyUriParser(...parsers)`
+
+Creates a new parser registry.
+
+```js
+const parser = new TinyUriParser(...DiscordProtocolParsers);
+```
+
+### `parser.parse(uri)`
+
+Parses a URI string into a `{ type, data }` object.
+
+```js
+const result = parser.parse('<:party:123456789>');
+// { type: 'emoji', data: { dataType: 'emoji', name: 'party', id: '123456789', animated: false } }
+```
+
+### `parser.stringify(parsedObject)`
+
+Rebuilds the original URI from a parsed object.
+
+```js
+parser.stringify(result);
+// '<:party:123456789>'
+```
+
+### `parser.parsers`
+
+Returns a **copy** of the registered parser pairs. Mutating the result does not affect the instance.
+
+### `parser.size`
+
+Returns the number of registered parsers.
+
+### `parser.destroy()`
+
+Clears internal state and marks the instance as destroyed. All subsequent calls throw.
+
+---
+
+## 💬 Discord Module
+
+### 📥 Importing
+
+```js
+import TinyUriParser from 'tiny-essentials/libs/tools/TinyUriParser';
+import {
+  DiscordProtocolParsers,
+  DiscordMentionParser,
+  DiscordEmojiParser,
+  // ...etc
+} from 'tiny-essentials/libs/tools/TinyUriParser/Discord';
+
+const parser = new TinyUriParser(...DiscordProtocolParsers);
+```
+
+> ⚠️ **Order matters.** `DiscordProtocolParsers` is pre-sorted from the most
+> specific parser to the most permissive. Always spread it as-is.
+
+---
+
+### 1. 👤 Mentions
+
+Parses `<@id>`, `<@!id>`, `<@&id>` and `<#id>`.
+
+| Input | `target` | `isNickname` |
+| --- | --- | --- |
+| `<@123>` | `'user'` | `false` |
+| `<@!123>` | `'user'` | `true` |
+| `<@&123>` | `'role'` | `false` |
+| `<#123>` | `'channel'` | `false` |
+
+```js
+parser.parse('<@!42>');
+// { type: 'mention', data: { dataType: 'mention', target: 'user', id: '42', isNickname: true } }
+```
+
+---
+
+### 2. 🎮 Game Profiles
+
+Parses `<@$id>`.
+
+```js
+parser.parse('<@$1402418491272986635>');
+// { type: 'game_profile', data: { dataType: 'game_profile', id: '1402418491272986635' } }
+```
+
+---
+
+### 3. 🧭 Guild Navigation
+
+Parses `<id:type>` and `<id:linked-roles:roleId>`.
+
+| Target | Description |
+| --- | --- |
+| `customize` | Opens the "Customize" tab. |
+| `browse` | Opens the "Browse Channels" tab. |
+| `guide` | Opens the server guide. |
+| `linked-roles` | Requires a `roleId`. |
+
+```js
+parser.parse('<id:linked-roles:123456789>');
+// { type: 'guild_navigation', data: { dataType: 'guild_navigation', target: 'linked-roles', roleId: '123456789' } }
+```
+
+---
+
+### 4. 😀 Emojis
+
+Parses `<:name:id>` and `<a:name:id>`.
+
+```js
+parser.parse('<a:party:123456789>');
+// { type: 'emoji', data: { dataType: 'emoji', name: 'party', id: '123456789', animated: true } }
+```
+
+---
+
+### 5. ⏰ Timestamps
+
+Parses `<t:unix>` and `<t:unix:style>`.
+
+| Style | Meaning |
+| --- | --- |
+| `t` | Short time (16:20) |
+| `T` | Long time (16:20:30) |
+| `d` | Short date (20/04/2024) |
+| `D` | Long date (20 April 2024) |
+| `f` | Short date/time |
+| `F` | Long date/time |
+| `R` | Relative ("2 hours ago") |
+| `s` | Short date/time (lowercase) |
+| `S` | Long date/time (uppercase) |
+
+```js
+parser.parse('<t:1618953630:R>');
+// { type: 'timestamp', data: { dataType: 'timestamp', timestamp: 1618953630, style: 'R' } }
+```
+
+---
+
+### 6. ⌨️ Commands
+
+Parses `</name:id>`, `</name sub:id>` and `</name group sub:id>`.
+
+```js
+parser.parse('</play music:123456789>');
+// {
+//   type: 'command',
+//   data: {
+//     dataType: 'command',
+//     name: 'play music',
+//     command: 'play',
+//     subcommandGroup: null,
+//     subcommand: 'music',
+//     id: '123456789'
+//   }
+// }
+```
+
+---
+
+### 7. 🔗 Invites
+
+Parses clean and whitespace-obfuscated invite links.
+
+| Input | `host` | `kind` | `obfuscated` |
+| --- | --- | --- | --- |
+| `discord.gg/abc` | `'discord.gg'` | `null` | `false` |
+| `discord.com/invite/abc` | `'discord.com'` | `'invite'` | `false` |
+| `discord.com/servers/abc` | `'discord.com'` | `'servers'` | `false` |
+| `discord . gg / abc` | `'discord.gg'` | `null` | `true` |
+
+```js
+parser.parse('discord.gg/abc?ref=friend');
+// {
+//   type: 'invite',
+//   data: {
+//     dataType: 'invite',
+//     code: 'abc',
+//     host: 'discord.gg',
+//     kind: null,
+//     obfuscated: false,
+//     params: { ref: 'friend' }
+//   }
+// }
+```
+
+---
+
+### 8. ✉️ Message Links
+
+Parses `https://discord.com/channels/<guild>/<channel>/<message>`.
+
+```js
+parser.parse('https://discord.com/channels/1/2/3');
+// {
+//   type: 'message_link',
+//   data: {
+//     dataType: 'message_link',
+//     guildId: '1',
+//     channelId: '2',
+//     messageId: '3',
+//     params: {}
+//   }
+// }
+```
+
+---
+
+### 9. 🖼️ CDN Assets
+
+Parses URLs from `cdn.discordapp.com` and `media.discordapp.net`.
+
+**Supported asset kinds** (in match order):
+
+```
+attachment, guild_member_avatar, guild_member_banner, achievement_icon,
+sticker_pack_banner, store_page_asset, application_asset, application_icon,
+guild_icon, guild_splash, guild_discovery_splash, banner, default_user_avatar,
+user_avatar, avatar_decoration, team_icon, emoji, sticker, role_icon,
+guild_scheduled_event_cover, guild_tag_badge
+```
+
+```js
+parser.parse('https://cdn.discordapp.com/icons/123/abc.png?size=128');
+// {
+//   type: 'cdn_asset',
+//   data: {
+//     dataType: 'cdn_asset',
+//     kind: 'guild_icon',
+//     host: 'cdn.discordapp.com',
+//     path: 'icons/123/abc.png',
+//     hash: 'abc',
+//     ext: 'png',
+//     filename: null,
+//     spoiler: false,
+//     segments: { guildId: '123' },
+//     params: { size: '128' }
+//   }
+// }
+```
+
+---
+
+## ⚠️ Known Issues
+
+### 🐛 Syntax errors (blocking)
+
+The following lines are **missing an opening parenthesis** before the template
+literal. They will throw a `SyntaxError` at parse time:
+
+```js
+// ❌ Broken
+throw new TypeError`Parser at index ${index} must be an array.`);
+
+// ✅ Fixed
+throw new TypeError(`Parser at index ${index} must be an array.`);
+```
+
+This pattern repeats in **`TinyUriParser`** (3 occurrences) and
+**`Discord`** (18 occurrences). Also check:
+
+```js
+// ❌ Broken
+return { regex: new RegExp`^${pattern}$`), names };
+
+// ✅ Fixed
+return { regex: new RegExp(`^${pattern}$`), names };
+```

package/docs/v1/libs/tools/TinyUriParser/MatrixProtocol.md

@@ -0,0 +1,54 @@
+# 🧩 Matrix Protocol Parser Documentation
+
+Welcome to the official documentation for the **Matrix Protocol Parser** module! 🚀
+
+This module is a specialized tool designed to identify, parse, and reconstruct various types of Matrix-related URIs. Whether you are dealing with MXC content, Matrix scheme URIs, shorthand identifiers, or web URLs, this module provides a unified interface to handle them safely and predictably.
+
+---
+
+## 🌟 Overview
+
+The primary goal of this module is to take a raw string (a URI) and convert it into a **strongly typed JavaScript object**. This object can then be used to extract specific information, such as a server domain, a user ID, or a room ID, without needing to manually write complex Regular Expressions every time.
+
+It is built on top of `TinyUriParser` to ensure a consistent "Parse $\rightarrow$ Validate $\rightarrow$ Reconstruct" workflow.
+
+---
+
+## 🛠 Supported URI Formats
+
+The module identifies and handles four distinct types of Matrix identifiers:
+
+| Format Type | Example Input | Description |
+| :--- | :--- | :--- |
+| **MXC URI** | `mxc://matrix.org/abc123def` | Used for Matrix Content (media, files). |
+| **Matrix Scheme** | `matrix:r/!room:server.com` | The formal protocol for Matrix resources. |
+| **Shorthand** | `#room:server.com` or `@user:server.com` | The common human-readable format. |
+| **Web URL** | `https://matrix.to/#/!room:server.com` | Full URLs used in web browsers. |
+
+---
+
+## 💎 Core Data Structures
+
+When you parse a URI, the module returns a specific object structure. Understanding these "shapes" is crucial for your logic.
+
+### 1. `MXCData` 📦
+Used when parsing `mxc://` links.
+- `dataType`: Always `'mxc'`.
+- `server`: The domain (e.g., `'matrix.org'`).
+- `dataId`: The unique content identifier.
+
+### 2. `MatrixSchemeData` 🗺️
+The most complex and versatile structure.
+- `dataType`: Always `'matrix_scheme'`.
+- `type`: The resource type (`'roomId'`, `'room'`, `'user'`, or `'event'`).
+- `subType`: The specific sub-category (used when the type is an `event`).
+- `resourceId`: The cleaned ID (e.g., `!room_id` becomes `room_id`).
+- `server`: The Matrix server domain (can be `null`).
+- `params`: A dictionary of query parameters (e.g., `{ via: 'server.com' }`).
+- `eventId`: Present only if the type is `'event'`.
+
+### 3. `MatrixWebData` 🌐
+Used when parsing full browser URLs.
+- `dataType`: Always `'matrix_web_url'`.
+- `decodedFragment`: The part of the URL after the `#`.
+- `parsed`: A nested `MatrixSchemeData` object containing the actual resource info.

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

@@ -0,0 +1,128 @@
+# 🧩 TinyUriParser Documentation
+
+Welcome to the **TinyUriParser** documentation! 🚀
+
+This project provides a lightweight, highly extensible engine designed to transform complex URI strings (like those used in the Matrix protocol) into structured JavaScript objects, and then reconstruct those objects back into their original URI strings.
+
+## 📖 Overview
+
+In modern messaging protocols, URIs are often used to identify users or rooms (e.g., `@user:example.com`). Manually parsing these using Regex every time can lead to repetitive and error-prone code. 
+
+`TinyUriParser` solves this by allowing you to define "Parser Pairs"—a set of rules that tell the engine:
+1. **How to recognize** a specific URI type.
+2. **How to turn** that string into a data object.
+3. **How to turn** that data object back into a string.
+
+---
+
+## 🏗️ The Building Block: `ParserPair`
+
+Before using the parser, you must understand the `ParserPair`. This is a "tuple" (a fixed-length array) that acts as the blueprint for a specific URI type.
+
+A `ParserPair` consists of exactly four elements:
+
+| Index | Name | Type | Description |
+| :--- | :--- | :--- | :--- |
+| `0` | **Type** | `string` | A unique name for this URI category (e.g., `'user'`). |
+| `1` | **Checker** | `function` | A function that returns `true` if the URI matches this type. |
+| `2` | **Parser** | `function` | A function that takes the URI string and returns a data object. |
+| `3` | **Stringifier**| `function` | A function that takes the data object and returns the original URI string. |
+
+### 🛠️ How to create a Pair
+Instead of creating the array manually, always use the `static buildParserPair` method.
+
+```javascript
+const myPair = TinyUriParser.buildParserPair(
+  'user', 
+  (uri) => uri.startsWith('@'), // Checker
+  (uri) => ({ id: uri.split(':')[0] }), // Parser
+  (data) => `@${data.id}:example.com` // Stringifier
+);
+```
+
+---
+
+## 🚀 Getting Started
+
+Here is a step-by-step guide on how to implement `TinyUriParser` in your daily development.
+
+### 1. Define your Parsing Logic
+First, decide how you want to handle your specific URIs.
+
+```javascript
+// 1. The Checker: Does this string look like a user URI?
+const isUserUri = (uri) => uri.startsWith('@');
+
+// 2. The Parser: Convert "@alice:matrix.org" -> { username: "alice", domain: "matrix.org" }
+const parseUser = (uri) => {
+  const [user, domain] = uri.slice(1).split(':');
+  return { username: user, domain: domain };
+};
+
+// 3. The Stringifier: Convert { username: "alice", domain: "matrix.org" } -> "@alice:matrix.org"
+const stringifyUser = (data) => `@${data.username}:${data.domain}`;
+```
+
+### 2. Initialize the Engine
+Create an instance of `TinyUriParser` and pass your pairs into the constructor.
+
+```javascript
+import TinyUriParser from 'tiny-essentials/libs/tools/TinyUriParser';
+
+const parserEngine = new TinyUriParser(
+  TinyUriParser.buildParserPair('user', isUserUri, parseUser, stringifyUser)
+);
+```
+
+### 3. Parsing a URI (String ➡️ Object)
+Use the `.parse()` method to turn a raw string into a usable object.
+
+```javascript
+try {
+  const result = parserEngine.parse('@alice:matrix.org');
+  console.log(result); 
+  // Output: { type: 'user', data: { username: 'alice', domain: 'matrix.org' } }
+} catch (error) {
+  console.error("Parsing failed:", error.message);
+}
+```
+
+### 4. Reconstructing a URI (Object ➡️ String)
+Use the `.stringify()` method to turn your object back into a valid URI string.
+
+```javascript
+const userObject = { type: 'user', data: { username: 'bob', domain: 'example.com' } };
+
+const originalUri = parserEngine.stringify(userObject);
+console.log(originalUri); 
+// Output: "@bob:example.com"
+```
+
+### 5. Resource Cleanup
+To prevent memory leaks in long-running applications, use the `.destroy()` method to clean up the instance.
+
+```javascript
+// Destroys the instance and clears the memory of all stored URI parsers
+parserEngine.destroy();
+```
+
+---
+
+## ⚠️ Error Handling
+
+The `TinyUriParser` is designed to be strict to ensure data integrity. You should always wrap your calls in `try...catch` blocks.
+
+| Error Type | Cause |
+| :--- | :--- |
+| `TypeError` | You passed a non-string to `.parse()`, or the `ParserPair` was constructed incorrectly. |
+| `Error` | The URI provided does not match any registered parser, or no reconstructor exists for the provided type. |
+
+---
+
+## 📊 Technical Specifications
+
+* **Complexity (Time):** 
+    * `parse()`: $O(N)$, where $N$ is the number of registered parsers.
+    * `stringify()`: $O(N)$, where $N$ is the number of registered parsers.
+* **Immutability:** All `ParserPair` objects are frozen using `Object.freeze()`.
+* **Uniqueness:** Parsers are stored in a `Set` to prevent duplicate registration.

package/docs/v1/libs/utils/TinyCloner.md

@@ -0,0 +1,126 @@
+# 🧩 TinyCloner Documentation
+
+Welcome to the **TinyCloner** official documentation! 🚀 
+
+`TinyCloner` is a highly modular, plugin-based deep cloning engine. Unlike standard `JSON.parse(JSON.stringify(obj))` hacks, TinyCloner is designed for professional environments where you need precision, extensibility, and total control over how specific data types are duplicated.
+
+---
+
+## ✨ Key Features
+
+*   **🔌 Plugin-Based Architecture:** Easily extend the cloner to handle custom classes, Dates, Sets, Maps, or any complex object.
+*   **🛡️ Strict Validation:** Built-in runtime checks ensure that plugins and options adhere to the required interfaces, preventing silent failures.
+*   **⚖️ Global vs. Instance Control:** Manage cloning rules globally for your whole application, or create isolated instances for specific tasks.
+*   **🔄 Deep & Shallow Modes:** Effortlessly switch between deep and shallow cloning.
+*   **🔒 Isolation Mode:** Create "sandboxed" cloners that ignore global settings to prevent side effects in complex applications.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Basic Cloning (The Quick Way)
+If you just need to clone something using the default settings, use the static `clone` method.
+
+```javascript
+import TinyCloner from 'tiny-essentials/libs/utils/TinyCloner';
+
+const original = { name: 'Yasmin', skills: ['Coding', 'Logic'] };
+
+// Perform a Deep Clone (Default)
+const deepCopy = TinyCloner.clone(original);
+deepCopy.skills.push('Architecture'); 
+
+console.log(original.skills); // ['Coding', 'Logic'] -> Safe!
+console.log(deepCopy.skills); // ['Coding', 'Logic', 'Architecture']
+```
+
+### 2. Shallow Cloning
+If you want to copy the top-level properties but keep references to nested objects, pass `false` as the second argument.
+
+```javascript
+const shallowCopy = TinyCloner.clone(original, false);
+```
+
+---
+
+## 🏗️ Advanced Usage: The Instance Pattern
+
+In large applications, you might not want to change the global behavior of `TinyCloner`. For this, you should create an **Instance**.
+
+### 🛡️ Using `isolationMode`
+When you create an instance with `isolationMode: true`, it becomes a "sandbox." It will only use the plugins you explicitly give it, ignoring any changes made to the global `TinyCloner` settings.
+
+```javascript
+// This instance is "immune" to global plugin changes
+const privateCloner = new TinyCloner({ isolationMode: true });
+
+// This instance will follow the global rules (default behavior)
+const standardCloner = new TinyCloner();
+```
+
+---
+
+## 🛠️ Extending the Cloner (Custom Plugins)
+
+This is where `TinyCloner` shines. You can teach it how to handle new types by creating a `CloningPlugin`.
+
+### 📝 The Plugin Interface
+Every plugin must follow this structure:
+1.  `id`: A unique string.
+2.  `canHandle(item)`: Returns `true` if the plugin should process the item.
+3.  `clone(item, isDeep, cloner)`: The logic to duplicate the item.
+
+### 💡 Example: Adding a `Date` Plugin
+```javascript
+import TinyCloner from 'tiny-essentials/libs/utils/TinyCloner';
+
+const datePlugin = {
+  id: 'date-plugin',
+  canHandle: (item) => item instanceof Date,
+  clone: (item, isDeep, cloner) => {
+    return new Date(item.getTime());
+  }
+};
+
+// Add it to the global registry
+TinyCloner.addPlugin(datePlugin);
+
+const data = { timestamp: new Date() };
+const clonedData = TinyCloner.clone(data);
+
+console.log(clonedData.timestamp instanceof Date); // true
+```
+
+---
+
+## 📖 API Reference
+
+### 🌍 Static Methods (Global Management)
+Use these to configure how `TinyCloner` behaves across your entire project.
+
+| Method | Description |
+| :--- | :--- |
+| `TinyCloner.clone(item, isDeep)` | The primary method to clone any item. |
+| `TinyCloner.addPlugin(plugin, pos, index)` | Adds a plugin to `start`, `end`, or a specific `index`. |
+| `TinyCloner.removePlugin(id)` | Removes a plugin by its unique ID. |
+| `TinyCloner.hasPlugin(id)` | Checks if a plugin exists globally. |
+| `TinyCloner.plugins` (get/set) | Get/Replace the entire global plugin array. |
+| `TinyCloner.set defaultIsDeep(bool)` | Sets the global default for deep cloning. |
+
+### 👤 Instance Methods (Local Management)
+Use these when working with a `new TinyCloner()` instance.
+
+| Method | Description |
+| :--- | :--- |
+| `cloner.clone(item, isDeep)` | Clones an item using instance-specific rules. |
+| `cloner.addPlugin(plugin, ...)` | Adds a plugin only to this specific instance. |
+| `cloner.removePlugin(id)` | Removes a plugin only from this instance. |
+| `cloner.plugins` (get/set) | Access the instance's specific plugin list. |
+
+---
+
+## ⚠️ Best Practices
+
+1.  **Always Use `id`:** When creating plugins, ensure the `id` is unique to avoid confusion during debugging.
+2.  **Prefer Instances for Libraries:** If you are building a library that uses `TinyCloner`, **always** create an instance (`new TinyCloner()`) instead of using the static methods. This prevents your library from accidentally changing the global settings of the user's project. 🛡️
+3.  **Validate your Plugins:** Use `TinyCloner.validatePlugin(myPlugin)` during your unit tests to ensure your custom logic is compatible.

package/docs/v1/libs/utils/TinyPromiseQueue.md

@@ -67,7 +67,7 @@ If the task is canceled before execution, it will be rejected with the message:
 
 #### Parameters:
 - `task` (`Function`): A function that returns a `Promise` to be executed sequentially.
-- `delay` (`number|null`): Optional delay (in ms) before the task is executed.
+- `delay` (`number`): Optional delay (in ms) before the task is executed.
 - `id` (`string`): Optional ID to identify the task in the queue.
 
 #### Returns: