tiny-essentials 1.28.18 → 1.29.0

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

@@ -0,0 +1,153 @@
+# 🛡️ TinyPasswordValidator
+
+A lightweight, robust, and highly customizable JavaScript utility for validating password strength and security requirements. This library is designed for developers who need precise control over password policies and detailed feedback for end-users.
+
+## 🌟 Features
+
+* **📏 Rule-Based Validation:** Check for length, casing, numbers, and special characters.
+* **📊 Strength Assessment:** Automatically classifies passwords as `strong`, `medium`, or `weak`.
+* **🛠️ Custom Validator Engine:** Add your own logic (e.g., checking against "forbidden words") using the manager pattern.
+* **⚠️ Strict Error Reporting:** Provides specific error messages and unique error codes for every failed rule.
+* **🔒 Security Oriented:** Built-in support for asynchronous hashing functions.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Installation
+Since this is a module, ensure your project supports ES6 modules. Import the class into your file:
+
+```javascript
+import TinyPasswordValidator from 'tiny-essentials/libs/tools/TinyPasswordValidator';
+```
+
+### 2. Basic Usage (Default Rules)
+By default, the validator requires: 8-128 characters, at least one lowercase, one uppercase, one number, and one special character (`@$!%*?&`).
+
+```javascript
+const validator = new TinyPasswordValidator();
+
+const result = validator.validate('Password123!');
+
+console.log(result.isValid);   // true
+console.log(result.strength);  // 'strong'
+```
+
+---
+
+## ⚙️ Configuration & Customization
+
+### 🛠️ Customizing Rules
+You can define specific rules during instantiation or update them later using `setRules()`.
+
+```javascript
+// Example: A much stricter configuration
+const strictValidator = new TinyPasswordValidator({
+  minLength: 12,
+  maxLength: 20,
+  requireSpecial: true,
+  requireNumbers: true
+});
+
+// Updating rules dynamically
+strictValidator.setRules({
+  minLength: 16,
+  requireUppercase: true
+});
+```
+
+### 🧩 Adding Custom Validators
+The `TinyPasswordValidator` allows you to extend its logic. This is useful for complex checks like "Password cannot contain the user's name."
+
+**Step-by-step implementation:**
+
+1. **Define a validator object** following the `CustomValidator` structure.
+2. **Use the `.add()` method** to register it.
+3. **Use the `.execute()` method** to run all registered validators.
+
+```javascript
+const validator = new TinyPasswordValidator();
+
+// 1. Define custom validator
+const noCommonWordsValidator = {
+  id: 'no-common-words',
+  name: 'No Common Words',
+  validate: (password) => {
+    const forbidden = ['password', '123456', 'qwerty'];
+    const isForbidden = forbidden.some(word => password.toLowerCase().includes(word));
+    
+    return {
+      isValid: !isForbidden,
+      strength: isForbidden ? 'weak' : 'strong',
+      errors: isForbidden ? ['Password contains a common forbidden word.'] : [],
+      errorCodes: isForbidden ? [7] : [],
+      score: isForbidden ? 0 : 1,
+      totalPossiblePoints: 1
+    };
+  }
+};
+
+// 2. Register the validator
+validator.add(noCommonWordsValidator);
+
+// 3. Execute all validators
+const result = validator.execute('Password123!');
+console.log(result.allPassed); // true (if 'Password123!' passes the custom check)
+```
+
+---
+
+## 🔍 Understanding the Output
+
+The `.validate()` method returns a `ValidationResult` object. Here is how to use it in your UI:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `isValid` | `boolean` | `true` if all rules are met, `false` otherwise. |
+| `strength` | `string` | `'strong'`, `'medium'`, or `'weak'`. |
+| `errors` | `string[]` | Array of human-readable error messages. |
+| `errorCodes` | `number[]` | Array of numeric IDs for the failed rules. |
+| `score` | `number` | How many requirements were successfully met. |
+
+### 🔢 Error Code Reference
+| Code | Meaning |
+| :--- | :--- |
+| `1` | Password is too short. |
+| `2` | Password is too long. |
+| `3` | Missing lowercase letter. |
+| `4` | Missing uppercase letter. |
+| `5` | Missing number. |
+| `6` | Missing special character. |
+
+---
+
+## 🔐 Security & Hashing
+
+The class includes a static `hashText` method. 
+
+⚠️ **IMPORTANT:** By default, `hashText` is a "dummy" function that returns the plain text. **This is only for testing purposes.**
+
+In a production environment, you **must** replace this with a real cryptographic function.
+
+**Recommended implementation:**
+```javascript
+import { hashText } from 'tiny-essentials/basics/crypto';
+
+// Replace the dummy function with a real one
+TinyPasswordValidator.hashText = hashText;
+
+// Usage
+const secureHash = await TinyPasswordValidator.hashText('my-secret-password');
+```
+
+---
+
+## 🛠️ Advanced Management
+
+The validator acts as a manager for your custom rules. You can:
+
+* **`reorder(oldIndex, newIndex)`**: Change the priority of custom validators.
+* **`sort(comparator)`**: Sort validators using a custom comparison function.
+* **`remove(id)`**: Delete a specific validator by its ID.
+* **`clear()`**: Remove all custom validators.
+* **`size`**: Check how many custom validators are currently registered.

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

@@ -150,6 +150,17 @@ The core logic. It traverses the `exports` field and checks the filesystem.
 
 ---
 
+### `async execCommandTester(actions)`
+
+**Method**
+
+Provides a CLI-based testing interface to execute specific methods or tasks defined in the `actions` object via command-line arguments.
+
+* **Returns:** `Promise<void>`
+* **Throws:** `TypeError` if `actions` is not a non-null object.
+
+---
+
 ### `get results()`
 
 **Getter**
@@ -163,7 +174,40 @@ Returns a detailed list of the validation results.
 
 ---
 
-### 📝 Customizing Messages (Templates)
+## 🚀 CLI Testing (Developer Mode)
+
+The `execCommandTester` method allows you to turn your script into a CLI tool easily, making it ideal for testing specific workflows without running the entire suite.
+
+### Example Setup
+
+```javascript
+// test-tool.mjs
+import TinyPkgExportValidator from 'tiny-essentials/libs/tools/TinyPkgExportValidator';
+
+const validator = new TinyPkgExportValidator('./package.json', '.');
+
+await validator.execCommandTester({
+  validate: async () => {
+    // Script test...
+  },
+  info: async () => {
+    console.log('Validator Version: 1.0.0');
+    console.log('Status: Ready');
+  }
+});
+```
+
+### Usage via Terminal
+
+1. **Run all registered actions:**
+   `node test-tool.mjs`
+
+2. **Run a specific action (e.g., only 'validate'):**
+   `node test-tool.mjs validate`
+
+---
+
+## 📝 Customizing Messages (Templates)
 
 The `messages` option allows you to override the default output. You can use **placeholders** within your strings to inject dynamic data at runtime.
 

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

@@ -0,0 +1,134 @@
+# 🗺️ TinySiteMap Documentation
+
+`TinySiteMap` is a robust, secure, and lightweight JavaScript service designed to manage and generate XML sitemaps or sitemap indexes. It is built to handle the complexities of XML namespaces, URL resolution, and security validation automatically.
+
+## 🚀 Overview
+
+When building websites, sitemaps are essential for SEO (Search Engine Optimization). They tell search engines which pages are available for crawling. `TinySiteMap` automates the creation of these files while ensuring they are valid and safe from common web vulnerabilities.
+
+### 🛡️ Security First (The "Why")
+This project implements two critical security layers:
+1.  **XML Injection Prevention:** The `#escapeXml` method ensures that special characters (like `<` or `&`) are converted into XML entities. This prevents malicious users from injecting unauthorized XML tags into your sitemap.
+2.  **URL Origin Validation:** The `#resolveAndValidate` method checks that every URL added to the sitemap belongs to the same origin as your `baseUrl`. This prevents "Open Redirect" style vulnerabilities where a sitemap might accidentally point to a malicious third-party domain.
+
+---
+
+## 🛠️ Getting Started
+
+### 1. Installation & Import
+Since this project uses ES6 modules, you must import it using the `import` syntax.
+
+```javascript
+import TinySiteMap from 'tiny-essentials/libs/tools/TinySiteMap';
+```
+
+### 2. Basic Configuration
+To start, you need to create an instance of `TinySiteMap` by providing a configuration object.
+
+```javascript
+const config = {
+  baseUrl: 'https://www.yourwebsite.com',
+  type: 'normal', // Use 'index' if you are creating a sitemap index
+  lastmodDateOnly: true // Formats dates as YYYY-MM-DD
+};
+
+const sitemap = new TinySiteMap(config);
+```
+
+---
+
+## 📝 Managing Entries
+
+An "entry" is a single URL or a single sitemap file within an index.
+
+### Adding a Standard URL Entry
+You can add URLs using absolute paths or relative paths. The class will automatically convert relative paths into absolute URLs based on your `baseUrl`.
+
+```javascript
+sitemap.addEntry({
+  loc: '/products/awesome-item', // Will become https://www.yourwebsite.com/products/awesome-item
+  lastmod: '2023-10-27T10:00:00Z',
+  changefreq: 'daily',
+  priority: 0.8
+});
+```
+
+### Adding Custom XML Tags
+If you need to include non-standard XML tags (for specific SEO requirements), use the `customTags` property.
+
+```javascript
+sitemap.addEntry({
+  loc: '/special-page',
+  customTags: {
+    'example:data': 'some-value'
+  }
+});
+```
+
+### CRUD Operations (Create, Read, Update, Delete)
+*   **Update:** `sitemap.updateEntry(index, { priority: 0.9 });`
+*   **Move:** `sitemap.moveEntry(fromIndex, toIndex);`
+*   **Remove:** `sitemap.removeEntry(index);`
+*   **Clear All:** `sitemap.clearAll();`
+
+---
+
+## 🧬 Advanced: Namespaces & Strategies
+
+XML namespaces allow you to include different types of data (like images or video) within your sitemap.
+
+### 1. Manual Namespaces
+You can manually add namespaces if you have specific requirements.
+
+```javascript
+sitemap.addNamespace({
+  type: 'xmlns',
+  prefix: 'myprefix',
+  uri: 'http://www.example.com/schema'
+});
+```
+
+### 2. Namespace Strategies (The Easy Way)
+Instead of manually adding every namespace, you can use built-in strategies:
+
+*   **`TinySiteMap.simpleStrategy()`**: Only includes the standard ROOT namespace.
+*   **`TinySiteMap.kaliStrategy()`**: Includes standard Google namespaces (news, image, video, xhtml).
+*   **`TinySiteMap.protocolStrategy(instance)`**: A comprehensive strategy that handles `xsi:schemaLocation` and custom tags automatically.
+
+**Example using a strategy:**
+```javascript
+const sitemap = new TinySiteMap({
+  baseUrl: 'https://www.example.com',
+  namespaceStrategy: TinySiteMap.kaliStrategy
+});
+```
+
+---
+
+## 📤 Generating the Output
+
+Once you have finished adding your entries, you can generate the final XML string.
+
+```javascript
+const xmlOutput = sitemap.generateXml();
+console.log(xmlOutput);
+```
+
+### 🎨 Adding Styles (XSL)
+To make the XML file readable in a web browser, you can provide an XSL stylesheet URL in the config:
+
+```javascript
+const sitemap = new TinySiteMap({
+  baseUrl: 'https://www.example.com',
+  xslUrl: '/styles/sitemap.xsl'
+});
+```
+
+---
+
+## ⚠️ Error Handling
+
+The class uses strict validation. If you provide invalid data, it will throw specific errors:
+*   `TypeError`: If data types are incorrect (e.g., passing a string where a number is expected).
+*   `RangeError`: If a value is out of bounds (e.g., a `priority` higher than `1.0` or more than `50,000` entries).
+*   `Error`: If security checks fail (e.g., a URL belongs to a different domain).

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

@@ -0,0 +1,97 @@
+# 🗺️ TinySiteMapStream Documentation
+
+`TinySiteMapStream` is a high-performance Node.js **Transform stream** designed for generating XML sitemaps incrementally. 
+
+Instead of building a massive XML string in your computer's memory (which can cause crashes if your website has millions of pages), this class processes one entry at a time and "streams" it to its destination (like a file or an HTTP response).
+
+---
+
+## 🚀 Core Concepts
+
+### 🛠️ What is a Transform Stream?
+Think of a Transform stream as a "processing station" on a factory conveyor belt:
+1. **Input:** It receives raw data objects (like a list of URLs from a database).
+2. **Transformation:** It converts those objects into formatted XML text.
+3. **Output:** It pushes that XML text out to the next station.
+
+### 🧬 Configuration Inheritance
+The `TinySiteMapStream` does not work alone. It requires an existing `TinySiteMap` instance. This allows the stream to "inherit" (copy) the settings you already defined, such as your `baseUrl`, `namespaces`, and `type`.
+
+---
+
+## ⚙️ Configuration Options
+
+When you create a new stream, you can pass a `TinySiteMapStreamOptions` object.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `level` | `'silent' \| 'warn' \| 'error'` | Controls how the stream reacts when it encounters a bad URL or invalid data. |
+| `xmlns` | `SitemapNamespace[]` | Custom XML namespaces to include in the header. |
+
+### ⚠️ Error Handling Levels
+Choosing the right `level` is crucial for your workflow:
+
+*   ❌ **`error`**: The stream will stop immediately and emit an error if a single entry is invalid. Use this during **development** to catch bugs.
+*   ⚠️ **`warn`**: The stream will log a warning to the console but will **continue** processing the rest of the entries. Use this in **production** to prevent one bad URL from breaking your entire sitemap.
+*   🤫 **`silent`**: The stream will skip invalid entries without saying anything. Use this if you want a completely clean log and don't care about missing specific URLs.
+
+---
+
+## 🛠️ Implementation Guide (Step-by-Step)
+
+To use this in your project, follow these three logical steps.
+
+### 1. Setup the Main Instance
+First, you must have your primary `TinySiteMap` configuration ready.
+
+```javascript
+import TinySiteMap from 'tiny-essentials/libs/tools/TinySiteMap';
+import TinySiteMapStream from 'tiny-essentials/libs/tools/TinySiteMapStream';
+import { createWriteStream } from 'node:fs';
+
+// 1. Initialize the main configuration
+const sitemapManager = new TinySiteMap({
+  baseUrl: 'https://example.com',
+  type: 'normal' // or 'index'
+});
+```
+
+### 2. Initialize the Stream
+Create the stream and pass the manager into it.
+
+```javascript
+// 2. Create the transform stream
+const stream = new TinySiteMapStream(sitemapManager, {
+  level: 'warn' // We want to know if something is wrong, but keep going
+});
+```
+
+### 3. The Data Pipeline (The "Daily Workflow")
+In a real-world scenario, you will likely pull data from a database and "pipe" it through the stream into a file.
+
+```javascript
+// 3. Create a destination (a file on your Linux system)
+const fileDestination = createWriteStream('./sitemap.xml');
+
+// 4. Start the pipeline
+// We pipe: [Your Data] -> [The Transformer] -> [The File]
+myDatabaseQueryStream
+  .pipe(stream)
+  .pipe(fileDestination)
+  .on('finish', () => console.log('✅ Sitemap generated successfully!'));
+```
+
+---
+
+## 📝 Developer Cheat Sheet
+
+### 💡 Pro-Tips for Daily Use
+
+* **Memory Efficiency:** Always use `.pipe()` instead of collecting all results in an array. This keeps your RAM usage low, even if you have 1,000,000 URLs. 📉
+* **Debugging:** If your sitemap is missing pages, change your `level` to `'warn'` temporarily. Check your terminal for `[TinySiteMapStream Warn]` messages. 🔍
+* **Validation:** The stream automatically calls `TinySiteMap.resolveAndValidate`. This means you don't need to manually check if your URLs are valid before sending them to the stream; the stream handles the heavy lifting for you. ✅
+
+### 🛠️ Summary of Internal Logic
+1. **First Entry:** The stream automatically injects the `<?xml...?>` declaration and the `<urlset>` header.
+2. **Middle Entries:** Each object is converted to an `<url>` or `<sitemap>` XML fragment.
+3. **End of Stream:** When the data ends, the stream automatically injects the `</urlset>` footer.

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

@@ -0,0 +1,146 @@
+# 🛡️ TinyURLSecurityVerifier Documentation
+
+Welcome to the official documentation for **TinyURLSecurityVerifier**. This library is a specialized tool designed to protect your applications from malicious URL-based attacks, such as Cross-Site Scripting (XSS), phishing, and credential theft.
+
+## 📝 Table of Contents
+1. [Overview](#overview)
+2. [Core Concepts](#core-concepts)
+3. [🚀 Quick Start](#-quick-start)
+4. [⚙️ Configuration](#-configuration)
+5. [🛡️ Security Layers](#-security-layers)
+6. [🛠️ API Reference](#-api-reference)
+7. [📚 Real-World Use Cases](#-real-world-use-cases)
+
+---
+
+## 🔍 Overview
+The `TinyURLSecurityVerifier` provides a multi-layered approach to URL validation. Instead of just checking if a string is a valid URL, it inspects the **intent** and **safety** of the link by analyzing protocols, domains, IP addresses, and embedded credentials.
+
+---
+
+## 🧠 Core Concepts
+
+To use this library effectively, you must understand two primary modes of operation:
+
+### 🚫 Blacklist Mode (Default)
+In this mode, the verifier looks for "bad" things. If a URL contains a protocol or domain that you have explicitly added to your lists, it is flagged as **dangerous**.
+
+### ✅ Whitelist Mode
+In this mode, the verifier looks for "good" things. It assumes everything is dangerous **unless** it is explicitly present in your allowed lists. This is the most secure setting for high-sensitivity applications.
+
+---
+
+## 🚀 Quick Start
+
+To begin using the verifier, import the class into your module:
+
+```javascript
+import TinyURLSecurityVerifier from 'tiny-essentials/libs/tools/TinyURLSecurityVerifier';
+
+// Initialize the verifier
+const verifier = new TinyURLSecurityVerifier();
+
+// Check a URL
+const urlToCheck = 'https://example.com';
+if (verifier.isDangerous(urlToCheck)) {
+  console.error('⚠️ Warning: This URL is potentially malicious!');
+} else {
+  console.log('✅ This URL is safe to use.');
+}
+```
+
+---
+
+## ⚙️ Configuration
+
+The library offers two levels of configuration: **Static** (Global) and **Instance-based** (Local).
+
+### 🌐 Global Configuration (Static)
+Static methods affect every instance of the verifier created in your application. Use these for settings that should never change, such as a global list of dangerous protocols (e.g., `javascript:`).
+
+*   `TinyURLSecurityVerifier.addProtocol(protocol)`: Adds a protocol to the global default list.
+*   `TinyURLSecurityVerifier.set defaultProtocols(array)`: Overwrites all global default protocols.
+
+### 🛠️ Local Configuration (Instance)
+Instance methods allow you to create specific verifiers for different contexts (e.g., one verifier for "User Comments" and another for "Admin Dashboard").
+
+*   `verifier.addProtocol(protocol)`: Adds a protocol only to this specific instance.
+*   `verifier.addBlacklistedDomain(domain)`: Blocks a specific domain in this instance.
+*   `verifier.isWhitelistMode = true`: Switches this specific instance to strict Whitelist mode.
+
+---
+
+## 🛡️ Security Layers
+
+The `isDangerous()` method performs a comprehensive scan across these five layers:
+
+1.  **Protocol Check 🔑**: Detects dangerous schemes like `javascript:`, `data:`, or `file:`.
+2.  **Search Parameter Check 🔍**: Inspects the query strings (e.g., `?redirect=javascript:alert(1)`) to ensure no dangerous protocols are hidden inside parameters.
+3.  **Credential Check 👤**: Detects if the URL contains embedded usernames or passwords (e.g., `https://user:pass@example.com`), which is a common phishing tactic.
+4.  **Domain Reputation Check 🌐**: Checks the hostname against your custom Blacklists or Whitelists.
+5.  **IP Address Check 📍**: Flags URLs that use raw IP addresses (IPv4 or IPv6) instead of domain names, as these are frequently used in phishing to bypass DNS filters.
+
+---
+
+## 🛠️ API Reference
+
+### Class: `TinyURLSecurityVerifier`
+
+#### `constructor()`
+Creates a new instance. It automatically inherits the current global default protocols.
+
+#### `isDangerous(href)`
+**The primary method.** Performs all security checks.
+*   **Returns:** `boolean` (`true` if dangerous, `false` if safe).
+
+#### `isProtocolDangerous(href)`
+Checks if the URL's protocol is in the dangerous list.
+*   **Note:** Behavior changes based on `isWhitelistMode`.
+
+#### `isSearchParamDangerous(href)`
+Scans all URL parameters for hidden protocol injections.
+
+#### `hasCredentials(href)`
+Checks if the URL contains user/password information in the authority component.
+
+#### `isIPAddress(href)`
+Checks if the hostname is a raw IPv4 or IPv6 address.
+
+#### `isBlacklisted(href)` / `isWhitelisted(href)`
+Checks the domain against the instance's domain lists.
+
+---
+
+## 📚 Real-World Use Cases
+
+### 1. Protecting a Comment Section (Blacklist Mode)
+When allowing users to post links, you want to block known bad domains and dangerous protocols.
+
+```javascript
+const commentVerifier = new TinyURLSecurityVerifier();
+commentVerifier.addBlacklistedDomain('malicious-site.com');
+commentVerifier.addBlacklistedDomain('phishing-link.net');
+
+const userLink = 'https://malicious-site.com/login';
+
+if (commentVerifier.isDangerous(userLink)) {
+  // Block the comment or flag it for moderation
+  console.log("Comment blocked: Malicious link detected.");
+}
+```
+
+### 2. High-Security Admin Redirects (Whitelist Mode)
+In an admin panel, you might only want to allow redirects to your own domain.
+
+```javascript
+const adminVerifier = new TinyURLSecurityVerifier();
+adminVerifier.isWhitelistMode = true; // Strict mode enabled
+adminVerifier.addAllowedDomain('my-secure-app.com');
+
+const redirectUrl = 'https://external-site.com/hack';
+
+if (adminVerifier.isDangerous(redirectUrl)) {
+  // Prevent the redirect to protect the admin
+  console.error("Security Alert: Redirect blocked!");
+}
+```