tiny-essentials 1.28.19 → 1.29.0

package/docs/v1/regexp/UrlDetector.md

@@ -0,0 +1,117 @@
+# 🌐 URL Regex Utility Module
+
+A robust and highly customizable JavaScript utility for building, validating, and extracting URLs using precise Regular Expressions. This module is designed for developers who need strict control over what constitutes a "valid" URL in their specific application context. 🚀
+
+## 📋 Table of Contents
+1. [Overview](#overview)
+2. [Configuration (`UrlRegexOptions`)](#configuration-urlregexoptions)
+3. [API Reference](#api-reference)
+4. [Practical Examples](#practical-examples)
+5. [Error Handling](#error-handling)
+
+---
+
+## 🚀 Overview
+
+The `URL Regex Utility` allows you to define exactly how a URL should look. Instead of using a "one-size-fits-all" regex, you can specify protocols, subdomains, and even the character length of the domain and TLD (Top-Level Domain). This is extremely useful for security-sensitive applications where you only want to allow specific types of links.
+
+---
+
+## ⚙️ Configuration (`UrlRegexOptions`)
+
+When using any function in this module, you can pass an optional `options` object to customize the behavior.
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `protocol` | `string` | `'https?'` | The scheme to match (e.g., `'http'`, `'https'`, or a custom pattern like `'ftp'`). |
+| `subDomain` | `string` | `''` | The specific subdomain string to look for (e.g., `'www'` or `'api'`). |
+| `subDomainOptional` | `boolean` | `true` | If `true`, the URL doesn't *need* the subdomain. If `false`, it is mandatory. |
+| `nameMaxLength` | `[number, number]` | `[1, 256]` | An array defining the `[min, max]` length of the domain name. |
+| `topLevelDomainLength` | `[number, number]` | `[1, 6]` | An array defining the `[min, max]` length of the TLD (e.g., `.com`, `.org`). |
+
+---
+
+## 📖 API Reference
+
+### 🛠 `urlStringRegexBuilder(options)`
+**Description:** The engine of the module. It generates a raw regex pattern string based on your configuration.
+* **Returns:** `{string}` A string representing the regex pattern.
+
+### 🔒 `urlRegex(options)`
+**Description:** Creates a `RegExp` object that is **anchored**. This means the URL must match the pattern from the very start (`^`) to the very end (`$`) of the string.
+* **Returns:** `{RegExp}` An anchored RegExp object.
+
+### ✅ `isValidUrl(s, options)`
+**Description:** The most common function for validation. It checks if a single string is a valid URL according to your rules.
+* **Parameters:** 
+    * `s` `{string}`: The string to validate.
+    * `options` `{UrlRegexOptions}`: Your custom configuration.
+* **Returns:** `{boolean}` `true` if valid, `false` otherwise.
+
+### 🔍 `findUrlRegex(options)`
+**Description:** Generates a **global** `RegExp` object. This is used when you want to find multiple URLs within a larger block of text.
+* **Returns:** `{RegExp}` A global (`g`) RegExp object.
+
+### 📥 `extractUrls(text, options)`
+**Description:** Scans a block of text and pulls out every URL that matches your configuration.
+* **Parameters:**
+    * `text` `{string}`: The text content to search through.
+    * `options` `{UrlRegexOptions}`: Your custom configuration.
+* **Returns:** `{string[]}` An array of matching URL strings. Returns an empty array `[]` if no matches are found.
+
+---
+
+## 🛠 Practical Examples
+
+### 1. Simple Validation ✅
+Checking if a standard URL is valid.
+
+```javascript
+import { isValidUrl } from 'tiny-essentials/regexp/UrlDetector';
+
+const url = "https://google.com";
+const isValid = isValidUrl(url); 
+
+console.log(isValid); // true
+```
+
+### 2. Strict Subdomain Requirement 🔒
+Ensuring a URL *must* start with `api.`.
+
+```javascript
+import { isValidUrl } from 'tiny-essentials/regexp/UrlDetector';
+
+const options = {
+  subDomain: 'api',
+  subDomainOptional: false
+};
+
+console.log(isValidUrl("https://api.example.com", options)); // true
+console.log(isValidUrl("https://example.com", options));     // false
+```
+
+### 3. Extracting Links from Text 📥
+Finding all links inside a paragraph.
+
+```javascript
+import { extractUrls } from 'tiny-essentials/regexp/UrlDetector';
+
+const blogPost = "Check our site at https://mysite.com or follow us at http://social.com/user";
+const links = extractUrls(blogPost);
+
+console.log(links); 
+// Output: ["https://mysite.com", "http://social.com/user"]
+```
+
+---
+
+## ⚠️ Error Handling
+
+To ensure your code doesn't fail silently, this module uses **strict runtime validation**. If you provide the wrong data type, the module will throw a `TypeError`.
+
+**Common Errors:**
+* `TypeError: Options must be an object.` — Occurs if `options` is a string, number, or null.
+* `TypeError: The "protocol" property must be a string.` — Occurs if you pass a non-string to `protocol`.
+* `TypeError: The input must be a string.` — Occurs if you pass something other than a string to `isValidUrl` or `extractUrls`.
+
+> **💡 Pro-Tip:** Always wrap your calls in a `try...catch` block if you are handling user-provided input to prevent your application from crashing!

package/docs/v1/regexp/Username/Base.md

@@ -0,0 +1,131 @@
+# 🛠️ Username Regex Utility
+
+A robust, highly configurable JavaScript utility designed to generate regular expressions for **validating**, **finding**, and **extracting** usernames from text. This tool supports complex rules like specific prefixes, domains, length constraints, and automated text transformations.
+
+## 🚀 Key Features
+
+*   **🎯 Precision Matching:** Create highly specific patterns (e.g., `@user`, `#123`, or `user@domain.com`).
+*   **🛡️ Type Safety:** Built-in runtime validation to catch configuration errors immediately.
+*   **🔄 Automatic Transformation:** Automatically convert extracted usernames to `lowercase`, `uppercase`, or a custom function result.
+*   **🔍 Multi-Pattern Support:** Pass an array of configurations to match multiple different username formats in a single pass.
+*   **📄 Smart Boundaries:** Intelligent handling of word boundaries to prevent "false positives" when usernames start or end with special characters (like `@`).
+
+---
+
+## ⚙️ Configuration Guide
+
+The core of this utility is the `UsernameRegexOptions` object. This object defines exactly what a "valid username" looks like for your specific project.
+
+### `UsernameRegexOptions` Properties
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `validValues` | `string` | `'[a-zA-Z0-9_]'` | A regex character class defining allowed characters. |
+| `length` | `[number, number]` | `[3, 20]` | An array representing `[min_length, max_length]`. |
+| `start` | `string` | `""` | A regex pattern required at the **start** of the username. |
+| `end` | `string` | `""` | A regex pattern required at the **end** of the username. |
+| `prefix` | `string` | `""` | A literal string prefix (e.g., `@` or `#`). |
+| `domain` | `string` | `undefined` | A literal domain (e.g., `@gmail.com`). Escaped automatically. |
+| `domainPattern` | `string` | `undefined` | A regex pattern for the domain (e.g., `@[a-z]+\.com`). |
+| `transform` | `UsernameTransform` | `null` | `'lowercase'`, `'uppercase'`, or a custom function. |
+
+---
+
+## 📖 API Reference
+
+### 1. `isValidUsername(string, options)`
+**Use case:** Form validation. Use this to check if a user's input in a text field is valid.
+
+*   **Returns:** `boolean`
+*   **Throws:** `TypeError` if the first argument is not a string.
+
+```javascript
+// Example: Validating a simple username
+const isOk = isValidUsername('Yasmin_99', { length: [3, 10] }); 
+console.log(isOk); // true
+```
+
+### 2. `extractUsernames(text, options)`
+**Use case:** Data scraping or parsing. Use this to pull all usernames out of a large block of text.
+
+*   **Returns:** `string[]` (An array of matched usernames).
+*   **Note:** If you provide an array of options, the transformation from the *first* option will be applied to all matches.
+
+```javascript
+const text = "Contact @Admin or @Moderator_1";
+const users = extractUsernames(text, { 
+  prefix: '@', 
+  transform: 'lowercase' 
+});
+console.log(users); // ['@admin', '@moderator_1']
+```
+
+### 3. `findUsernameRegex(options)`
+**Use case:** Advanced regex creation. Generates a global (`/g`) regular expression for use with `.match()` or `.replace()`.
+
+*   **Returns:** `RegExp`
+
+### 4. `usernameRegex(options)`
+**Use case:** Strict matching. Generates a regex that matches the **entire** string from start to finish (`^...$`).
+
+*   **Returns:** `RegExp`
+
+---
+
+## 🛠️ Real-World Workflow Examples
+
+### Scenario A: Social Media Style (The "@" Prefix)
+You are building a chat app where users are mentioned using `@username`.
+
+```javascript
+const socialOptions = {
+  prefix: '@',
+  length: [3, 15],
+  validValues: '[a-zA-Z0-9_]'
+};
+
+// Extracting mentions from a chat message
+const message = "Hello @yasmin, welcome to the group @dev_user!";
+const mentions = extractUsernames(message, socialOptions);
+// Result: ["@yasmin", "@dev_user"]
+```
+
+### Scenario B: Matrix/Identity Style (Domain required)
+You need to find users on a specific Matrix server.
+
+```javascript
+const matrixOptions = {
+  prefix: '@',
+  domain: '@matrix.org',
+  length: [3, 20]
+};
+
+const text = "Check in with @alice@matrix.org and @bob@matrix.org";
+const users = extractUsernames(text, matrixOptions);
+console.log(users);
+// Result: ["@alice@matrix.org", "@bob@matrix.org"]
+```
+
+### Scenario C: Multi-Format Parsing (Complex)
+Your system supports both `#hashtag` style and `@username` style.
+
+```javascript
+const multiOptions = [
+  { prefix: '@', length: [3, 10] },
+  { prefix: '#', length: [3, 15] }
+];
+
+const text = "Follow @user and use #coding";
+const matches = extractUsernames(text, multiOptions);
+console.log(matches);
+// Result: ["@user", "#coding"]
+```
+
+---
+
+## ⚠️ Error Handling
+
+This library is designed to be "fail-fast." If you pass incorrect types, it will throw specific errors to help you debug immediately:
+
+*   **`TypeError`**: Thrown if you pass a number where a string is expected, or if an object property is missing its required type.
+*   **`RangeError`**: Thrown if your `length` array has a minimum value greater than the maximum (e.g., `[20, 5]`) or if lengths are negative.

package/docs/v1/regexp/Username/Discord.md

@@ -0,0 +1,267 @@
+# 🎮 Discord Pattern Templates
+
+> A declarative catalog of **35 regular-expression templates** that describe Discord's
+> markup, mentions, links and CDN assets.
+
+This module contains **no logic**. It is a frozen, plain-object registry. All the
+intelligence lives in the engine; this file only declares *what* a
+Discord artifact looks like.
+
+---
+
+## 📑 Table of Contents
+
+1. [What is this file?](#-what-is-this-file)
+2. [The 60-second mental model](#-the-60-second-mental-model)
+3. [Template catalog](#-template-catalog)
+   - [Markup & mentions](#-markup--mentions)
+   - [Links & invites](#-links--invites)
+   - [CDN assets](#-cdn-assets)
+4. [Daily usage recipes](#-daily-usage-recipes)
+5. [Testing your changes](#-testing-your-changes)
+6. [Adding a new template](#-adding-a-new-template)
+7. [Quick reference](#-quick-reference)
+
+---
+
+## 📌 What is this file?
+
+`Discord` is a **data-only module**. It exports a single frozen object:
+
+```javascript
+import DiscordRegex from 'tiny-essentials/regexp/Username/Discord';
+
+DiscordRegex.userMention;
+// { prefix: '<@', validValues: '[0-9]', length: [17, 22], domain: '>' }
+```
+
+Each key is a **`UsernameRegexTemplate`** — a plain object that the engine
+translates into a `RegExp`. Nothing is compiled until you call the engine.
+
+**Use it when you need to:**
+
+- ✅ Validate that a string is a real Discord snowflake mention.
+- ✅ Extract every CDN URL from a message before it is deleted or cached.
+- ✅ Detect invite links for anti-spam / moderation.
+- ✅ Build a syntax highlighter for Discord-flavoured markdown.
+
+**Do not use it for:** authentication, permission checks, or anything where a
+regex is the only line of defence. A regex proves *shape*, never *authorization*.
+
+---
+
+## 🧠 The 60-second mental model
+
+Every template is expanded by the engine in this exact order:
+
+```text
+^  {start}  {prefix}  (?:{validValues}){min,max}  {domainPart}  $
+   └ raw ─┘ └escaped┘ └──── the "core" ────────┘  └ suffix ──┘
+```
+
+| Step | Function | Reads |
+| :--- | :--- | :--- |
+| 1 | `getPrefix()` | `start`, `prefix` |
+| 2 | `usernameStringRegexBuilder()` | `validValues`, `length` |
+| 3 | `getDomainPart()` | `domainPattern` **or** `domain`, plus `end` |
+
+The result is a **single-line, fully anchored** pattern. There is no `m` flag
+and no `s` flag, so `.` never matches a newline.
+
+---
+
+## 📚 Template Catalog
+
+### 🏷️ Markup & mentions
+
+| Key | Example match | Notes |
+| :--- | :--- | :--- |
+| `spoiler` | `\|\|hidden text\|\|` | 1–2000 chars. Content excludes a lone `\|`. |
+| `mediaSpoiler` | `SPOILER_cat.png` | Discord's attachment spoiler prefix. |
+| `userMention` | `<@123456789012345678>` | Snowflake = 17–22 digits. |
+| `nicknameMention` | `<@!123456789012345678>` | Mention with server nickname. |
+| `roleMention` | `<@&123456789012345678>` | Role ping. |
+| `channelMention` | `<#123456789012345678>` | Text, voice, forum, stage — all types. |
+| `customEmoji` | `<:party_parrot:123456789012345678>` | Name: 2–32 chars. |
+| `animatedEmoji` | `<a:party_parrot:123456789012345678>` | Same, with the `a:` marker. |
+| `timestamp` | `<t:1700000000:R>` | Style is optional. |
+| `slashCommand` | `</ping:123456789012345678>` | Also matches subcommands. |
+| `gameProfile` | `<@$123456789012345678>` | Game profile mention. |
+| `guildNavigation` | `<id:customize>` | Also `<id:linked-roles:ID>`. |
+
+**Why `spoiler` is ReDoS-safe** — the content class is
+`[^|]|\|(?!\|)`. The two alternatives are mutually exclusive on the first
+character, so the engine never has to backtrack. It stays linear even at
+`{1,2000}`.
+
+---
+
+### 🔗 Links & invites
+
+| Key | Example match | Notes |
+| :--- | :--- | :--- |
+| `messageLink` | `https://discord.com/channels/111…/222…/333…` | Accepts `@me` for DMs. |
+| `inviteLink` | `https://discord.gg/abc123` | Also `discord.com/invite/…`. |
+
+Both keep the query string attached via `end: OPTIONAL_QUERY_STRING`, so
+`?utm_source=discord` stays inside the match instead of being silently dropped.
+
+---
+
+### 🖼️ CDN assets
+
+Every CDN template shares the same skeleton:
+
+```text
+https?://(?:cdn\.discordapp\.com|media\.discordapp\.net)/<path>/<SNOWFLAKE>/<HASH>.<ext>
+```
+
+| Key | Path segment |
+| :--- | :--- |
+| `cdnAttachment` | `/attachments/CHANNEL/ATTACHMENT/FILENAME` |
+| `cdnEmoji` | `/emojis/EMOJI_ID.ext` |
+| `cdnGuildIcon` | `/icons/GUILD/HASH.ext` |
+| `cdnGuildSplash` | `/splashes/GUILD/HASH.ext` |
+| `cdnGuildDiscoverySplash` | `/discovery-splashes/GUILD/HASH.ext` |
+| `cdnBanner` | `/banners/ID/HASH.ext` |
+| `cdnDefaultUserAvatar` | `/embed/avatars/0.ext` |
+| `cdnUserAvatar` | `/avatars/USER/HASH.ext` |
+| `cdnGuildMemberAvatar` | `/guilds/GUILD/users/USER/avatars/HASH.ext` |
+| `cdnGuildMemberBanner` | `/guilds/GUILD/users/USER/banners/HASH.ext` |
+| `cdnAvatarDecoration` | `/avatar-decoration-presets/HASH.ext` |
+| `cdnApplicationIcon` | `/app-icons/APP/HASH.ext` |
+| `cdnApplicationAsset` | `/app-assets/APP/HASH.ext` |
+| `cdnAchievementIcon` | `/app-assets/APP/achievements/ID/icons/HASH.ext` |
+| `cdnStorePageAsset` | `/app-assets/APP/store/HASH` |
+| `cdnStickerPackBanner` | `/app-assets/APP/store/HASH.ext` |
+| `cdnTeamIcon` | `/team-icons/TEAM/HASH.ext` |
+| `cdnSticker` | `/stickers/STICKER.ext` |
+| `cdnRoleIcon` | `/role-icons/ROLE/HASH.ext` |
+| `cdnGuildScheduledEventCover` | `/guild-events/EVENT/HASH.ext` |
+| `cdnGuildTagBadge` | `/guild-tag-badges/GUILD/HASH.ext` |
+
+**Accepted extensions:** `jpg`, `jpeg`, `png`, `webp`, `gif`, `avif`.
+
+---
+
+## 🚀 Daily usage recipes
+
+### 1. Validate a single mention
+
+```javascript
+import { isValidUsername } from 'tiny-essentials/regexp/Username';
+import DiscordRegex from 'tiny-essentials/regexp/Username/templates/Discord';
+
+isValidUsername('<@123456789012345678>', DiscordRegex.userMention);
+// true
+```
+
+### 2. Extract every mention from a message
+
+```javascript
+import { extractUsernames } from 'tiny-essentials/regexp/Username';
+import DiscordRegex from 'tiny-essentials/regexp/Username/templates/Discord';
+
+const mentions = extractUsernames(
+  'hey <@123456789012345678> and <@987654321098765432>',
+  [DiscordRegex.userMention, DiscordRegex.nicknameMention],
+);
+// ['<@123456789012345678>', '<@987654321098765432>']
+```
+
+### 3. Build a reusable validator once
+
+```javascript
+import { usernameRegex } from 'tiny-essentials/regexp/Username';
+import DiscordRegex from 'tiny-essentials/regexp/Username/templates/Discord';
+
+// Build the RegExp once and reuse it — never rebuild inside a loop.
+const INVITE = usernameRegex(DiscordRegex.inviteLink);
+
+export const isInvite = (text) => INVITE.test(text);
+```
+
+### 4. Normalize mentions to lowercase
+
+```javascript
+const rules = { ...DiscordRegex.customEmoji, transform: 'lowercase' };
+const emojis = extractUsernames('<:Party_Parrot:123456789012345678>', rules);
+// ['<:party_parrot:123456789012345678>']
+```
+
+---
+
+## 🧪 Testing your changes
+
+Because this file is pure data, a snapshot test is enough:
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import { usernameRegex } from 'tiny-essentials/regexp/Username';
+import DiscordRegex from 'tiny-essentials/regexp/Username/templates/Discord';
+
+describe('Discord', () => {
+  it('matches a standard user mention', () => {
+    expect(usernameRegex(DiscordRegex.userMention).test('<@123456789012345678>')).toBe(true);
+  });
+
+  it('rejects a mention with a short snowflake', () => {
+    expect(usernameRegex(DiscordRegex.userMention).test('<@123>')).toBe(false);
+  });
+
+  it('keeps the query string on a CDN attachment', () => {
+    const url = 'https://cdn.discordapp.com/attachments/111111111111111111/222222222222222222/a.png?ex=1';
+    expect(usernameRegex(DiscordRegex.cdnAttachment).test(url)).toBe(true);
+  });
+});
+```
+
+**Always test the negative case.** A pattern that matches everything is worse
+than no pattern at all.
+
+---
+
+## ➕ Adding a new template
+
+1. **Pick the right section.** Keep CDN entries at the bottom, grouped.
+2. **Reuse the shared constants.** `SNOWFLAKE`, `CDN_HOST`, `CDN_EXT`,
+   `CDN_HASH` and `OPTIONAL_QUERY_STRING` already exist. Do not duplicate them.
+3. **Prefer `prefix`/`domain` over `start`/`domainPattern`** unless you truly
+   need regex. Escaped literals are safer.
+4. **Add the JSDoc block** with `@type {UsernameRegexTemplate}` so the editor
+   keeps autocompleting.
+5. **Add a row to the catalog table** in this document.
+
+```javascript
+  /**
+   * CDN: Soundboard Sound
+   * Format: https://cdn.discordapp.com/soundboard-sounds/ID
+   * @type {UsernameRegexTemplate}
+   */
+  cdnSoundboardSound: {
+    start: `${CDN_HOST}/soundboard-sounds/`,
+    validValues: '[0-9]',
+    length: [17, 22],
+    end: OPTIONAL_QUERY_STRING,
+  },
+```
+
+---
+
+## 📋 Quick reference
+
+```javascript
+import DiscordRegex from 'tiny-essentials/regexp/Username/templates/Discord';
+
+// 35 keys, all frozen at the top level.
+Object.keys(DiscordRegex).length; // 35
+
+// Every value follows the same shape:
+// { start?, prefix?, validValues, length, domain?, domainPattern?, end? }
+```
+
+| Group | Count | Keys |
+| :--- | :--: | :--- |
+| Markup & mentions | 12 | `spoiler`, `mediaSpoiler`, `userMention`, `nicknameMention`, `roleMention`, `channelMention`, `customEmoji`, `animatedEmoji`, `timestamp`, `slashCommand`, `gameProfile`, `guildNavigation` |
+| Links & invites | 2 | `messageLink`, `inviteLink` |
+| CDN assets | 21 | `cdn*` |

package/docs/v1/regexp/Username/MatrixProtocol.md

@@ -0,0 +1,131 @@
+# 🧩 Matrix Protocol Regex Templates
+
+> A battle-tested collection of Regular Expression templates for parsing
+> [Matrix](https://matrix.org) identifiers: users, rooms, events, groups,
+> permalinks, URIs, HTML mentions, and media URIs.
+
+---
+
+## 📖 Table of Contents
+
+- [What is this?](#-what-is-this)
+- [Template Catalog](#-template-catalog)
+- [Quick Start](#-quick-start)
+- [Testing Cheatsheet](#-testing-cheatsheet)
+- [References](#-references)
+
+---
+
+## 🎯 What is this?
+
+`MatrixProtocol` is a **pure data module**. It does not export functions.
+It exports a single frozen object where every key is a **template** that
+describes *one* Matrix identifier shape.
+
+The heavy lifting (turning a template into a `RegExp`) is done by the
+sibling module. Think of it like this:
+
+```
+tiny-essentials/regexp/Username/templates/MatrixProtocol   →   the recipe   (what a Matrix ID looks like)
+tiny-essentials/regexp/Username                            →   the chef     (turns the recipe into a RegExp)
+```
+
+**Why split it?** Because a template is data. Data can be serialized,
+snapshotted, diffed in code review, and reused across runtimes. A raw
+`RegExp` literal cannot.
+
+---
+
+## 📚 Template Catalog
+
+| Key | Matches | Example |
+| --- | --- | --- |
+| `userName` | User ID | `@alice:matrix.org` |
+| `roomName` | Room alias | `#general:matrix.org` |
+| `roomId` | Room ID | `!AbCdEf:matrix.org` |
+| `eventId` | Event ID (v1–v3+) | `$abc123:matrix.org` |
+| `groupId` | Legacy group / space | `+mygroup:matrix.org` |
+| `matrixToLink` | `matrix.to` permalink | `https://matrix.to/#/@alice:matrix.org` |
+| `matrixUri` | RFC 8922 URI | `matrix:u/alice:matrix.org` |
+| `htmlMention` | HTML anchor mention | `<a href="https://matrix.to/#/@alice:matrix.org">Alice</a>` |
+| `mxcUri` | Media content URI | `mxc://matrix.org/AbC123` |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Import the template you need
+
+```javascript
+import MatrixProtocolRegex from 'tiny-essentials/regexp/Username/templates/MatrixProtocol';
+import { isValidUsername, usernameRegex, findUsernameRegex, extractUsernames } from 'tiny-essentials/regexp/Username';
+```
+
+### 2. Validate a single identifier
+
+```javascript
+import { isValidUsername } from 'tiny-essentials/regexp/Username';
+import MatrixProtocolRegex from 'tiny-essentials/regexp/Username/templates/MatrixProtocol';
+
+isValidUsername('@alice:matrix.org', MatrixProtocolRegex.userName);
+// => true
+
+isValidUsername('@Alice:matrix.org', MatrixProtocolRegex.userName);
+// => false  (Matrix user IDs are lowercase-only)
+```
+
+### 3. Extract every Matrix ID from a wall of text
+
+```javascript
+import { extractUsernames } from 'tiny-essentials/regexp/Username';
+import MatrixProtocolRegex from 'tiny-essentials/regexp/Username/templates/MatrixProtocol';
+
+const message = `
+  Hey, ping @alice:matrix.org or join #general:matrix.org
+  Docs: https://matrix.to/#/@bob:example.com
+`;
+
+extractUsernames(message, [
+  MatrixProtocolRegex.userName,
+  MatrixProtocolRegex.roomName,
+  MatrixProtocolRegex.matrixToLink,
+]);
+// => [
+//   '@alice:matrix.org',
+//   '#general:matrix.org',
+//   'https://matrix.to/#/@bob:example.com'
+// ]
+```
+
+---
+
+## 🧪 Testing Cheatsheet
+
+A quick table of inputs and their expected results, ready to be turned
+into a test suite.
+
+| Template | Input | Valid? |
+| --- | --- | --- |
+| `userName` | `@alice:matrix.org` | ✅ |
+| `userName` | `@Alice:matrix.org` | ❌ uppercase |
+| `userName` | `@alice:localhost` | ❌ no TLD |
+| `roomName` | `#General:matrix.org` | ✅ |
+| `roomId` | `!AbC-123:matrix.org` | ✅ |
+| `eventId` | `$AbC123` | ✅ |
+| `eventId` | `$AbC123:matrix.org` | ✅ |
+| `groupId` | `+mygroup:matrix.org` | ✅ |
+| `matrixToLink` | `https://matrix.to/#/@a:b.org` | ✅ |
+| `matrixToLink` | `matrix.to/#/@a:b.org` | ✅ |
+| `matrixUri` | `matrix:u/alice:matrix.org` | ✅ |
+| `matrixUri` | `matrix:roomid/abc:matrix.org` | ✅ |
+| `mxcUri` | `mxc://matrix.org/AbC123` | ✅ |
+| `mxcUri` | `mxc://matrix.org/` | ❌ empty media ID |
+
+---
+
+## 🔗 References
+
+- [Matrix Identifier Grammar](https://spec.matrix.org/latest/appendices/#identifier-grammar)
+- [Matrix Client-Server API](https://spec.matrix.org/latest/client-server-api/)
+- [RFC 8922 — The `matrix:` URI Scheme](https://www.rfc-editor.org/rfc/rfc8922)
+- [matrix.to](https://matrix.to) — Permalink resolver