tiny-essentials 1.28.18 → 1.29.0

package/docs/v1/regexp/Email.md

@@ -0,0 +1,127 @@
+# 📧 Email Validation Toolkit
+
+A robust, highly configurable JavaScript utility for validating email addresses and extracting them from text using customizable Regular Expressions and strict filtering rules.
+
+## 🌟 Overview
+
+This toolkit is designed for developers who need more than just basic email validation. It allows you to define exactly what a "valid" email looks like for your specific application—whether you want to restrict users to a specific company domain, block certain usernames, or use custom logic.
+
+---
+
+## ⚙️ The Configuration Object (`EmailRegexOptions`)
+
+The "brain" of this toolkit is the `options` object. Instead of writing complex Regex every time, you pass this object to the functions to control the behavior.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `validName` | `string` | The regex pattern for the part **before** the `@`. (Default: `[a-zA-Z0-9._%+-]+`) |
+| `validDomain` | `string` | The regex pattern for the part **after** the `@`. (Default: `[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}`) |
+| `blacklistDomains` | `string[]` | List of domains that are **not** allowed (e.g., `['tempmail.com']`). |
+| `whitelistDomains` | `string[]` | List of domains that are the **only** ones allowed. |
+| `blacklistUsernames` | `string[]` | List of usernames that are **not** allowed (e.g., `['admin', 'root']`). |
+| `whitelistUsernames` | `string[]` | List of usernames that are the **only** ones allowed. |
+| `customValidator` | `Function` | A function `(email: string) => boolean` for logic that Regex cannot handle. |
+
+---
+
+## 🛠️ Core Functions
+
+### 1. `isValidEmail(s, options)`
+**The most common tool.** Use this to check if a single string is a valid email based on your rules.
+
+*   **Input:** A `string` and an optional `options` object.
+*   **Returns:** `boolean` (`true` if valid, `false` otherwise).
+*   **Throws:** `TypeError` if the first argument is not a string.
+
+### 2. `extractEmails(text, options)`
+**The "Scraper" tool.** Use this when you have a large block of text (like a comment section or an email body) and you want to find all valid emails within it.
+
+*   **Input:** A `string` (the text to search) and an optional `options` object.
+*   **Returns:** `string[]` (An array of found emails. Returns an empty array `[]` if none are found).
+*   **Throws:** `TypeError` if the input text is not a string.
+
+---
+
+## 🚀 Practical Daily Scenarios
+
+Here is how you would use these tools in different professional programming scenarios.
+
+### Scenario A: Simple Validation 🔍
+*Goal: Just check if the email follows standard formatting.*
+
+```javascript
+import { isValidEmail } from 'tiny-essentials/regexp/Email';
+
+const email = "user@example.com";
+
+if (isValidEmail(email)) {
+  console.log("✅ This is a valid email format.");
+} else {
+  console.log("❌ Invalid email format.");
+}
+```
+
+### Scenario B: Corporate/Internal Restriction 🏢
+*Goal: Only allow users from your company domain (`@company.com`).*
+
+```javascript
+import { isValidEmail } from 'tiny-essentials/regexp/Email';
+
+const userEmail = "employee@company.com";
+const guestEmail = "stranger@gmail.com";
+
+const companyOnlyOptions = {
+  whitelistDomains: ['company.com']
+};
+
+console.log(isValidEmail(userEmail, companyOnlyOptions)); // true
+console.log(isValidEmail(guestEmail, companyOnlyOptions)); // false
+```
+
+### Scenario C: Preventing "Bad" Usernames & Domains 🛡️
+*Goal: Block specific disposable email providers and restricted usernames.*
+
+```javascript
+import { isValidEmail } from 'tiny-essentials/regexp/Email';
+
+const securityOptions = {
+  blacklistDomains: ['spam.org', 'trashmail.net'],
+  blacklistUsernames: ['admin', 'root', 'support']
+};
+
+console.log(isValidEmail("admin@example.com", securityOptions)); // false (Username is blacklisted)
+console.log(isValidEmail("user@spam.org", securityOptions));      // false (Domain is blacklisted)
+console.log(isValidEmail("valid.user@example.com", securityOptions)); // true
+```
+
+### Scenario D: Extracting Emails from a Log File 📑
+*Goal: Pull all valid emails from a messy text block.*
+
+```javascript
+import { extractEmails } from 'tiny-essentials/regexp/Email';
+
+const logData = "Contact us at support@company.com or sales@company.com. Do not use admin@evil.com.";
+
+const options = {
+  whitelistDomains: ['company.com']
+};
+
+const validCompanyEmails = extractEmails(logData, options);
+
+console.log(validCompanyEmails); 
+// Output: ["support@company.com", "sales@company.com"]
+// Note: "admin@evil.com" was ignored because it didn't match the whitelist.
+```
+
+---
+
+## ⚠️ Error Handling & Safety
+
+This module is designed with **Strict Type Safety**. To prevent bugs in large applications, the functions will throw errors if you pass the wrong data types.
+
+| Error Type | Cause |
+| :--- | :--- |
+| `TypeError` | You passed a `number` or `null` instead of a `string` to `isValidEmail` or `extractEmails`. |
+| `TypeError` | You passed an invalid object to the `options` parameter (e.g., a `blacklistDomain` that is a string instead of an array). |
+
+**Pro-tip:** Always wrap your calls in `try...catch` blocks if you are handling user input that might be unpredictable!

package/docs/v1/regexp/Glob.md

@@ -0,0 +1,155 @@
+# 🌟 GlobMaster Utility
+
+Welcome to the **GlobMaster** documentation! 🚀 This utility is a professional-grade tool designed to bridge the gap between human-readable **GLOB patterns** (commonly used in file systems) and machine-executable **JavaScript Regular Expressions (RegExp)**.
+
+Whether you are building a file explorer, a routing system, or a search filter, GlobMaster makes pattern matching intuitive and powerful.
+
+---
+
+## ✨ Core Features
+
+GlobMaster supports the most essential GLOB syntax used in modern development:
+
+*   `*` : Matches any characters **except** path separators (`/`).
+*   `**` : Matches any characters **including** path separators (useful for recursive directory matching).
+*   `?` : Matches exactly one single character (excluding path separators).
+*   `[...]` : Matches any one of the characters inside the brackets.
+*   `[!...]` : Negated character class (matches any character **not** inside the brackets).
+*   `{a,b}` : Alternation (matches `a`, `b`, or `c`).
+*   `\` : Escape character to treat special symbols as literal characters.
+
+---
+
+## 🛠 API Reference
+
+### 1. `compileGlob`
+Converts a GLOB pattern into an array of regex-ready strings.
+
+**Signature:**
+```javascript
+export const compileGlob(globData, strict = true);
+```
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `globData` | `string \| string[]` | Required | The pattern to compile. Can be a single string or an array of strings. |
+| `strict` | `boolean` | `true` | If `true`, throws a `SyntaxError` for unmatched brackets `[` or braces `{`. |
+
+**Returns:**
+*   `string[]`: An array of strings representing the components of the compiled Regular Expression.
+
+**Errors:**
+*   `TypeError`: If `globData` is not a string or array of strings, or if `strict` is not a boolean.
+*   `SyntaxError`: If `strict` is enabled and the pattern has unbalanced syntax.
+
+---
+
+### 2. `compileGlobRegExp`
+The most common method. Converts a GLOB pattern directly into a functional `RegExp` object.
+
+**Signature:**
+```javascript
+export const compileGlobRegExp(globPattern, flags = '', strict = true);
+```
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `globPattern` | `string` | Required | The GLOB pattern to convert. |
+| `flags` | `string` | `''` | Standard RegExp flags (e.g., `'i'` for case-insensitive). |
+| `strict` | `boolean` | `true` | If `true`, performs strict syntax validation. |
+
+**Returns:**
+*   `RegExp`: A ready-to-use Regular Expression object.
+
+---
+
+### 3. `decompileGlob`
+The inverse of the compiler. It takes a `RegExp` and reconstructs the original GLOB pattern.
+
+**Signature:**
+```javascript
+export const decompileGlob(regexp);
+```
+
+**Parameters:**
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `regexp` | `RegExp \| string \| string[]` | The pattern to decompile. |
+
+**Returns:**
+*   `string[]`: An array containing the reconstructed GLOB pattern components.
+
+---
+
+### 4. `isValidGlob`
+A lightweight way to check if a pattern is syntactically correct without needing to handle errors manually.
+
+**Signature:**
+```javascript
+export const isValidGlob(globPattern);
+```
+
+**Returns:**
+*   `boolean`: `true` if the pattern is valid, `false` if there is a syntax error.
+
+---
+
+## 💡 Daily Workflow Examples
+
+Here is how you will use this project in your day-to-day development.
+
+### Scenario A: Filtering Files in a Directory
+If you want to find all `.js` files in any subfolder:
+
+```javascript
+import { compileGlobRegExp } from 'tiny-essentials/regexp/Glob';
+
+const pattern = compileGlobRegExp('**/*.js');
+const files = ['src/index.js', 'README.md', 'lib/utils/math.js', 'config.json'];
+
+const matches = files.filter(file => pattern.test(file));
+
+console.log(matches); 
+// Output: ['src/index.js', 'lib/utils/math.js']
+```
+
+### Scenario B: Validating User Input
+When a user types a search pattern, you want to ensure they didn't break the syntax before processing it.
+
+```javascript
+import { isValidGlob } from 'tiny-essentials/regexp/Glob';
+
+const userInput = "src/[a-z{"; // This is invalid due to the unclosed brace
+
+if (isValidGlob(userInput)) {
+  console.log("Pattern is valid! Proceeding...");
+} else {
+  console.error("Invalid pattern detected. Please check your brackets.");
+}
+```
+
+### Scenario C: Converting Regex back to Human-Readable GLOB
+If you have a complex Regex and want to display its "human" version in a UI:
+
+```javascript
+import { decompileGlob } from 'tiny-essentials/regexp/Glob';
+
+const myRegex = /^src\/.*\.js$/;
+const humanPattern = decompileGlob(myRegex);
+
+console.log(humanPattern.join('')); 
+// Output: "src/*.js"
+```
+
+---
+
+## ⚠️ Error Handling Guide
+
+To ensure your application doesn't crash, always wrap your compilation in a `try...catch` block if you are dealing with dynamic user input.
+
+| Error Type | Cause |
+| :--- | :--- |
+| `TypeError` | You passed a number, object (not array), or null where a string was expected. |
+| `SyntaxError` | (In strict mode) You have an opening `[` or `{` without a closing counterpart. |

package/docs/v1/regexp/IPv4.md

@@ -0,0 +1,103 @@
+# 🌐 IPv4 Utility Library
+
+A lightweight, high-performance JavaScript module designed to validate and extract IPv4 addresses. This library is ideal for form validation, log parsing, and network security filtering.
+
+## 🚀 Overview
+
+This project provides tools to handle IPv4 addresses using highly optimized Regular Expressions. It distinguishes between **exact validation** (checking if a string is strictly an IP) and **extraction** (finding IPs within a large block of text).
+
+---
+
+## 🛠️ API Reference
+
+### `isValidIPv4(s)`
+Validates if a string is a correctly formatted IPv4 address.
+
+* **Parameters:**
+    * `s` (`string`): The input string to be validated.
+* **Returns:** 
+    * `boolean`: `true` if the string is a valid IPv4 address, `false` otherwise.
+* **Throws:** 
+    * `TypeError`: If the input `s` is not a string.
+
+**Example Usage:**
+```javascript
+import { isValidIPv4 } from 'tiny-essentials/regexp/Ipv4';
+
+console.log(isValidIPv4('192.168.1.1')); // 🟢 true
+console.log(isValidIPv4('256.0.0.1'));   // 🔴 false (256 is out of range)
+console.log(isValidIPv4('192.168.1'));   // 🔴 false (missing octet)
+```
+
+---
+
+### `extractIPsV4(text)`
+Scans a block of text and retrieves all IPv4 addresses found within it.
+
+* **Parameters:**
+    * `text` (`string`): The text content to search.
+* **Returns:** 
+    * `string[]`: An array of all matched IP addresses. Returns an empty array `[]` if no matches are found.
+* **Throws:** 
+    * `TypeError`: If the input `text` is not a string.
+
+**Example Usage:**
+```javascript
+import { extractIPsV4 } from 'tiny-essentials/regexp/Ipv4';
+
+const logData = "Error from 10.0.0.1 and connection lost at 192.168.0.100";
+const ips = extractIPsV4(logData);
+
+console.log(ips); // 📋 ["10.0.0.1", "192.168.0.100"]
+```
+
+---
+
+### `ipv4Regex()`
+Returns a `RegExp` object for exact matching.
+
+* **Returns:** 
+    * `RegExp`: A regex pattern that matches exactly four octets (0-255) separated by dots.
+
+---
+
+### `findIPv4Regex()`
+Returns a global `RegExp` object for finding multiple matches.
+
+* **Returns:** 
+    * `RegExp`: A global (`g`) regex pattern using word boundaries (`\b`) to ensure it only matches complete IP addresses.
+
+---
+
+## 💡 Practical Use Cases
+
+### 1. 📝 Frontend: Form Validation
+When a user enters their IP address in a configuration field, you want to ensure it is valid before sending it to the server.
+
+```javascript
+const userInput = document.querySelector('#ip-input').value;
+
+if (isValidIPv4(userInput)) {
+  // Proceed with API call
+  submitConfig(userInput);
+} else {
+  // Show error to user
+  showError("Please enter a valid IPv4 address (e.g., 192.168.1.1)");
+}
+```
+
+### 2. 🔍 Backend/DevOps: Log Analysis
+If you are processing server logs to find which IP addresses are causing errors.
+
+```javascript
+import { extractIPsV4 } from 'tiny-essentials/regexp/Ipv4';
+
+const serverLogs = `
+  [2023-10-01 10:00] INFO: User 172.16.254.1 logged in.
+  [2023-10-01 10:05] WARN: Failed attempt from 10.5.5.5.
+  [2023-10-01 10:10] ERROR: Connection dropped by 192.168.1.1.
+`;
+
+const maliciousIPs = extractIPsV4(serverLogs);
+console.log(`Found ${maliciousIPs.length} IP addresses in logs.`);
+```

package/docs/v1/regexp/IPv6.md

@@ -0,0 +1,122 @@
+# 🌐 IPv6 Utility Library
+
+A lightweight JavaScript utility for validating and extracting IPv6 addresses using optimized Regular Expressions.
+
+## 📖 Overview
+
+This library provides essential tools for developers working with networking data. It allows you to:
+1.  **Validate** if a specific string is a correctly formatted IPv6 address.
+2.  **Extract** all IPv6 addresses found within a larger block of text (such as log files or network reports).
+3.  **Access** the underlying Regular Expressions for custom implementations.
+
+---
+
+## 🚀 Getting Started
+
+### Installation
+Since this library uses **ES6 Modules**, ensure your project is configured to support them. You can import the functions directly into your JavaScript files:
+
+```javascript
+import { isValidIPv6, extractIPsV6, ipv6Regex, findIPv6Regex } from 'tiny-essentials/regexp/Ipv6';
+```
+
+---
+
+## 🛠 API Reference
+
+### `isValidIPv6(s)`
+Checks if the provided string is a valid IPv6 address.
+
+*   **Parameters:**
+    *   `s` (`string`): The input string to be validated.
+*   **Returns:** 
+    *   `boolean`: Returns `true` if the string is a valid IPv6 address, otherwise `false`.
+*   **Throws:** 
+    *   `TypeError`: If the input `s` is not a string.
+
+### `extractIPsV6(text)`
+Scans a string and returns all IPv6 addresses found within it.
+
+*   **Parameters:**
+    *   `text` (`string`): The text content to search through.
+*   **Returns:** 
+    *   `string[]`: An array containing all matched IPv6 addresses. Returns an empty array `[]` if no matches are found.
+*   **Throws:** 
+    *   `TypeError`: If the input `text` is not a string.
+
+### `ipv6Regex()`
+Generates a strict Regular Expression for IPv6 validation.
+
+*   **Returns:** 
+    *   `RegExp`: A regex object anchored with `^` and `$` to ensure the entire string is checked.
+
+### `findIPv6Regex()`
+Generates a global Regular Expression for searching.
+
+*   **Returns:** 
+    *   `RegExp`: A regex object with the `g` (global) flag, useful for finding multiple occurrences in a text.
+
+---
+
+## 💡 Practical Examples
+
+### 1. Validating User Input
+Use `isValidIPv6` to verify data entered by a user in a network configuration form.
+
+```javascript
+import { isValidIPv6 } from 'tiny-essentials/regexp/Ipv6';
+
+const userInput = "2001:0db8:85a3:0000:0000:8a2e:0370:7334";
+
+if (isValidIPv6(userInput)) {
+  console.log("✅ Valid IPv6 address.");
+} else {
+  console.log("❌ Invalid IPv6 address.");
+}
+```
+
+### 2. Parsing Log Files
+Use `extractIPsV6` to quickly grab all IP addresses from a server log file.
+
+```javascript
+import { extractIPsV6 } from 'tiny-essentials/regexp/Ipv6';
+
+const logData = `
+  [2025-01-01 10:00] Connection from 2001:db8::1
+  [2025-01-01 10:05] Connection from fe80::ff00:43:ff:fe12:3456
+  [2025-01-01 10:10] Unknown error from 192.168.1.1
+`;
+
+const foundIPs = extractIPsV6(logData);
+
+console.log("Detected IPv6 addresses:", foundIPs);
+// Output: ["2001:db8::1", "fe80::ff00:43:ff:fe12:3456"]
+```
+
+---
+
+## ⚠️ Error Handling
+
+The library implements strict type checking to prevent bugs in your application. If you pass a non-string value (like `null`, `undefined`, or a `number`) to the primary functions, the library will throw a `TypeError`.
+
+**Example of error handling:**
+
+```javascript
+import { isValidIPv6 } from 'tiny-essentials/regexp/Ipv6';
+
+try {
+  isValidIPv6(12345); // This will trigger the error
+} catch (error) {
+  if (error instanceof TypeError) {
+    console.error("⚠️ Error: " + error.message); 
+    // Output: "⚠️ Error: The input must be a string."
+  }
+}
+```
+
+---
+
+## ⚙️ Technical Implementation Details
+
+*   **Regex Logic:** The library uses a specialized pattern that accounts for standard IPv6 formats and **zero compression** (the `::` notation).
+*   **Complexity Note:** While IPv4 validation is straightforward, this implementation handles the hexadecimal complexity and variable group lengths required for IPv6.

package/docs/v1/regexp/SegmentExtractor.md

@@ -0,0 +1,120 @@
+# 🛠️ Path Segment Extractor Utility
+
+Welcome to the documentation for the **Path Segment Extractor**. This utility is a powerful, lightweight factory designed to transform string-based path patterns (like `/user/:id`) into highly efficient regular expressions capable of extracting dynamic parameters from URLs.
+
+If you are building a custom router or a URL parser, this tool is your best friend! 🚀
+
+---
+
+## 📖 Overview
+
+The core logic relies on a **Factory Pattern**. Instead of creating a regex manually every time, you use `makeSegmentExtractor` to define *how* a dynamic segment looks (e.g., is it prefixed with a colon `:` or wrapped in curly braces `{}`?). Once defined, you can generate multiple "extractors" for different route patterns.
+
+### 🌟 Key Features
+* ✅ **Highly Customizable**: Define your own syntax for dynamic segments.
+* ✅ **Type Safe**: Strict runtime validation ensures you don't pass incorrect data types.
+* ✅ **Performant**: Compiles patterns into optimized `RegExp` objects.
+* ✅ **URL Decoded**: Automatically handles `decodeURIComponent` for extracted parameters.
+
+---
+
+## 🚀 Quick Start
+
+The easiest way to use this library is via the pre-configured `segmentExtractorV1`, which supports the standard `:paramName` syntax used by frameworks like Express.js.
+
+```javascript
+import { segmentExtractorV1 } from 'tiny-essentials/regexp/SegmentExtractor';
+
+// 1. Define your pattern
+const userRoute = segmentExtractorV1('/user/:id/posts/:postId');
+
+// 2. Test a real path
+const result = userRoute.exec('/user/yasmin/posts/42');
+
+if (result.match) {
+  console.log('✅ Match found!');
+  console.log('User ID:', result.params.id);       // "yasmin"
+  console.log('Post ID:', result.params.postId);   // "42"
+} else {
+  console.log('❌ No match.');
+}
+```
+
+---
+
+## ⚙️ API Reference
+
+### `makeSegmentExtractor(searchValue, replaceValue, errorConfig)`
+
+This is the main factory function.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `searchValue` | `string \| RegExp` | The pattern used to find dynamic segments in your string. |
+| `replaceValue` | `Function` | A callback that transforms the found segment into a Regex capture group. |
+| `errorConfig` | `Object` | Configuration for custom error messages. |
+
+#### ⚠️ Errors Thrown
+* `TypeError`: If `searchValue` is not a string/RegExp.
+* `TypeError`: If `replaceValue` is not a function.
+* `TypeError`: If `errorConfig` is missing or invalid.
+
+---
+
+### `segmentExtractorV1(pathPattern)`
+
+A specialized version of the factory pre-configured for the `:name` syntax.
+
+**Returns:** A `SegExResult` object.
+
+---
+
+## 🛠️ Advanced: Creating Custom Extractors
+
+What if your project uses `{id}` instead of `:id`? You can create a custom extractor using `makeSegmentExtractor`.
+
+```javascript
+import { makeSegmentExtractor } from 'tiny-essentials/regexp/SegmentExtractor';
+
+// Define an extractor for {bracket} syntax
+const bracketExtractor = makeSegmentExtractor(
+  /\{([^}]+)\}/g, // 1. Look for anything inside { }
+  (paramNames, _, paramName) => { // 2. Transform it
+    paramNames.push(paramName);    // Store the name (e.g., "id")
+    return '([^}]+)';              // Return regex group (match everything inside)
+  },
+  { pathPatternErrorMsg: 'Pattern must be a string!' }
+);
+
+const route = bracketExtractor('/files/{fileId}');
+const data = route.exec('/files/document_01.pdf');
+
+console.log(data.params.fileId); // "document_01.pdf"
+```
+
+---
+
+## 📊 Data Structures
+
+Understanding the returned objects is crucial for implementing the logic in your application.
+
+### `SegExResult` (The Object returned by the extractor)
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `regex` | `RegExp` | The compiled regular expression. |
+| `paramNames` | `string[]` | An array of the names of the parameters found (in order). |
+| `exec` | `Function` | The function used to perform the actual matching. |
+
+### `SegExData` (The Object returned by `.exec()`)
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `params` | `Record<string, string>` | A map where keys are parameter names and values are the extracted strings. |
+| `match` | `boolean` | `true` if the path matched the pattern, `false` otherwise. |
+
+---
+
+## 💡 Pro-Tips for Developers
+
+1.  **Reuse Extractors**: Do not call `segmentExtractorV1` inside a loop or a high-frequency function. Call it **once** at the top level to compile the regex, and then reuse the returned function. This is much faster! 🏎️
+2.  **Decoding**: The `exec` function automatically runs `decodeURIComponent`. This means `%20` in a URL will correctly become a space `" "` in your `params` object.
+3.  **Strictness**: The regex is wrapped in `^` and `$`. This means the path must match the pattern **exactly** from start to finish.