tiny-essentials 1.28.8 → 1.28.9

package/docs/v1/README.md

@@ -21,6 +21,7 @@ Here, you can navigate through different sections of the project. Below are the
 - 📺 **[FullScreen](./basics/fullScreen.md)** — A complete fullscreen API manager with detection, event handling, and cross-browser compatibility.
 - 🧱 **[Collision](./basics/collision.md)** — Full-featured rectangle collision detection system with directional analysis, depth calculation, and center offset metrics.
 - 🎵 **[MediaContent](./basics/mediaContent.md)** — A comprehensive media processing module for downloading audio, extracting rich ID3 metadata, and managing image blobs for album art.
+- 📦 **[BrowserDetector](./basics/browserDetector.md)** — A multi-layered JavaScript utility for identifying the user's web browser and rendering engine.
 
 ### 2. **`libs/`**
 - 🗂️ **[TinyPromiseQueue](./libs/TinyPromiseQueue.md)** — A class that allows sequential execution of asynchronous tasks, supporting task delays, cancellation, and queue management.
@@ -64,6 +65,7 @@ Here, you can navigate through different sections of the project. Below are the
 * 🧠 **[TinyMamdaniInferenceSystem](./libs/TinyMamdaniInferenceSystem.md)** — A implementation of a Mamdani Inference System, allowing you to model logic using trapezoidal membership functions.
 * 📻 **[TinyRadioFm](./libs/TinyRadioFm.md)** — It is designed to handle complex playback sequences, including music and voice playlists, scheduled timeline mutations, and custom content injections, all while maintaining absolute reproducibility through a mathematical seed.
 * ⏯️ **[TinyMediaPlayer](./libs/TinyMediaPlayer.md)** — A universal media player architecture utilizing an adapter pattern to orchestrate multiple platform APIs, featuring robust playlist management, playback controls, and weighted random selection.
+* 🛠️ **[TinyDebugger](./libs/TinyDebugger.md)** — A lightweight, event-driven debugging utility designed to wrap standard `console` methods. It provides enhanced features such as custom prefixes, color support, and the ability to emit events whenever a log occurs, making it perfect for complex applications where you might want to redirect logs to an external service or a UI component.
 
 ### 2.1. **`libs/TinyClassManager`**
 

package/docs/v1/basics/browserDetector.md

@@ -0,0 +1,135 @@
+# 🌐 Browser Detection Toolkit
+
+A multi-layered JavaScript utility for identifying the user's web browser and rendering engine.
+
+## 📋 Table of Contents
+1. [Data Types](#📋-data-types)
+2. [Core Functions](#🛠️-core-functions)
+   - [isBrowserAgent](#1-isbrowseragent)
+   - [getBrowserCssPrefix](#2-getbrowsercssprefix)
+   - [getDuckTyping](#3-getducktyping)
+3. [Advanced Detection](#🎯-advanced-detection)
+   - [getBrowserPings](#4-getbrowserpings)
+   - [browserIs](#5-browseris)
+
+---
+
+## 📋 Data Types
+
+To ensure type safety and clarity, the toolkit utilizes the following definitions:
+
+### `BrowserDetected`
+A union type representing the supported browser names:
+`'chrome' | 'firefox' | 'ie' | 'edge' | 'safari' | 'opera' | 'yandex' | 'other'`
+
+### `DuckTypingResult`
+An object returned by feature detection, containing boolean flags:
+| Property | Description |
+| :--- | :--- |
+| `isOpera` | `true` if Opera is detected |
+| `isFirefox` | `true` if Firefox is detected |
+| `isSafari` | `true` if Safari is detected |
+| `isIE` | `true` if Internet Explorer is detected |
+| `isEdge` | `true` if Microsoft Edge is detected |
+| `isChrome` | `true` if Google Chrome is detected |
+| `isBlink` | `true` if the Blink rendering engine is detected |
+
+---
+
+## 🛠️ Core Functions
+
+### 1. `isBrowserAgent()`
+Parses the `navigator.userAgent` string to provide a quick identification of the browser.
+
+* **Returns:** `BrowserDetected`
+* **Best use case:** Quick, lightweight checks where absolute precision is not critical.
+
+```javascript
+import { isBrowserAgent } from 'tiny-essentials/basics/browserDetector';
+
+const browser = isBrowserAgent();
+console.log(`You are using: ${browser}`); 
+// Output example: "chrome"
+```
+
+### 2. `getBrowserCssPrefix()`
+Inspects the computed styles of the document to determine the CSS rendering engine.
+
+* **Returns:** `'gecko' | 'webkit' | 'trident' | 'other'`
+* **Best use case:** When you need to apply CSS vendor prefixes or handle engine-specific rendering quirks.
+
+```javascript
+import { getBrowserCssPrefix } from 'tiny-essentials/basics/browserDetector';
+
+const engine = getBrowserCssPrefix();
+if (engine === 'webkit') {
+  console.log("Applying WebKit specific styles... 🎨");
+}
+```
+
+### 3. `getDuckTyping()`
+Performs deep feature detection by checking for the existence of specific global objects and APIs.
+
+* **Returns:** `DuckTypingResult`
+* **Best use case:** When you need to know exactly which features are available in the current environment.
+
+```javascript
+import { getDuckTyping } from './browserDetector.js';
+
+const features = getDuckTyping();
+
+if (features.isChrome) {
+  console.log("Chrome-specific API available! ✅");
+}
+
+if (features.isBlink) {
+  console.log("Blink engine detected. ⚡");
+}
+```
+
+---
+
+## 🎯 Advanced Detection
+
+These functions aggregate the results from the core functions to provide the highest possible accuracy.
+
+### 4. `getBrowserPings(disable = [])`
+Aggregates detection results from all three methods (User Agent, CSS Prefix, and Duck Typing) to provide a "ping count" for each browser.
+
+* **Parameters:** 
+  * `disable` (Array): An optional array of `BrowserDetected` names to exclude from the results.
+* **Returns:** `Object<BrowserDetected, number>` (An object where keys are browsers and values are the number of times they were detected).
+* **Throws:** `TypeError` if `disable` is not an array or contains invalid browser names.
+
+```javascript
+import { getBrowserPings } from 'tiny-essentials/basics/browserDetector';
+
+// Get detection counts for all browsers
+const counts = getBrowserPings();
+console.log(counts);
+
+// Get counts while ignoring Internet Explorer
+const filteredCounts = getBrowserPings(['ie']);
+console.log(filteredCounts);
+```
+
+### 5. `browserIs(disable = [])`
+The most reliable method. It runs all detection strategies and returns the browser that received the highest number of "pings."
+
+* **Parameters:** 
+  * `disable` (Array): An optional array of `BrowserDetected` names to exclude.
+* **Returns:** `BrowserDetected` (The most likely browser name).
+* **Throws:** `TypeError` if `disable` is not an array or contains invalid browser names.
+
+```javascript
+import { browserIs } from 'tiny-essentials/basics/browserDetector';
+
+// Get the most accurate browser identification
+const currentBrowser = browserIs();
+
+if (currentBrowser === 'firefox') {
+  console.log("Welcome, Firefox user! 🦊");
+} else {
+  console.log(`Detected: ${currentBrowser}`);
+}
+```

package/docs/v1/libs/TinyDebugger.md

@@ -0,0 +1,119 @@
+# 🛠️ TinyDebugger Documentation
+
+`TinyDebugger` is a lightweight, event-driven debugging utility designed to wrap standard `console` methods. It provides enhanced features such as custom prefixes, color support, and the ability to emit events whenever a log occurs, making it perfect for complex applications where you might want to redirect logs to an external service or a UI component.
+
+## 🚀 Quick Start
+
+To use `TinyDebugger`, import it into your project and initialize it with a configuration object.
+
+```javascript
+import TinyDebugger from 'tiny-essentials/libs/TinyDebugger';
+
+const debuggerInstance = new TinyDebugger({
+  logger: console, // You can use standard console or a custom object
+  id: 'APP_CORE',
+  debugMode: true,
+  canEmitLogs: true,
+  useLogColors: true
+});
+
+debuggerInstance.log('info', 'Hello, Yasmin! The debugger is ready. 🌟');
+```
+
+---
+
+## ⚙️ Configuration
+
+When creating a new instance via the `constructor`, you can pass a configuration object with the following properties:
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `logger` | `Object` | **Yes** | N/A | An object implementing the `Console` interface. |
+| `id` | `string` | **Yes** | N/A | A unique identifier for this debugger instance. |
+| `debugMode` | `boolean` | **Yes** | N/A | If `false`, all logging methods will return immediately. |
+| `canEmitLogs` | `boolean` | No | `false` | If `true`, the instance will emit events for every log action. |
+| `useLogColors` | `boolean` | No | `false` | Enables ANSI color codes. *Note: Automatically disabled in Firefox.* |
+
+---
+
+## ✨ Key Features
+
+### 🎨 Custom Colors
+You can inject colors into your log messages using the `_colorName_` syntax.
+*   **Syntax:** `_color_`
+*   **Example:** `debugger.log('info', 'This is _red_ critical error!');`
+
+### 🏷️ Custom Prefixes
+You can use placeholders to insert specific prefix text into your logs.
+*   **Syntax:** `:id:`
+*   **Example:** `debugger.log('info', ':info: System initialized.');`
+
+### 📡 Event Emission
+If `canEmitLogs` is set to `true`, `TinyDebugger` acts as an `EventEmitter`, allowing you to listen to specific debugging events. This is incredibly useful for building custom developer consoles in web applications.
+
+---
+
+## 📖 API Reference
+
+### `log(logType, message, ...args)`
+The primary method for logging.
+*   **logType:** `'log' | 'info' | 'warn' | 'error' | 'debug' | 'dirxml' | 'group' | 'groupCollapsed' | 'trace'`
+*   **message:** `string` (The text to display)
+*   **args:** `...any` (Additional data to inspect)
+
+### `logLabel(logType, label)`
+Logs a specific console type associated with a label.
+*   **logType:** `'count' | 'countReset' | 'time' | 'timeEnd' | 'profile' | 'profileEnd' | 'timeStamp'`
+*   **label:** `string`
+
+### `logTimeLabel(label, ...args)`
+Starts a timer with a specific label.
+*   **label:** `string`
+
+### `logAssert(condition, ...args)`
+Logs a message only if the provided condition evaluates to `false`.
+*   **condition:** `boolean`
+
+### `logDir(item, options)`
+Displays an element as a JavaScript object (similar to `console.dir`).
+*   **item:** `any`
+*   **options:** `InspectOptions`
+
+### `logTable(tabularData, properties)`
+Displays data in a clean, readable table.
+*   **tabularData:** `any`
+*   **properties:** `string[]` (Optional array of column properties)
+
+### `logClear()`
+Clears the console.
+### `logGroupEnd()`
+Ends the current console group.
+
+---
+
+## 🛠️ Advanced Customization
+
+You can dynamically modify the behavior of your debugger instance using these internal methods:
+
+| Method | Description |
+| :--- | :--- |
+| `_addLogColor(id, code)` | Adds a new color shortcut (e.g., `_mycolor_`). |
+| `_removeLogColor(id)` | Removes a color shortcut. |
+| `_addLogPrefix(id, text)` | Adds a new prefix shortcut (e.g., `:status:`). |
+| `_removeLogPrefix(id)` | Removes a prefix shortcut. |
+
+### Example: Adding a Custom Color
+```javascript
+debuggerInstance._addLogColor('gold', '\x1b[33m');
+debuggerInstance.log('info', 'This message is _gold_!');
+```
+
+---
+
+## ⚠️ Error Handling
+
+It will throw `TypeError` if:
+1.  The `logger` provided is not a valid object.
+2.  The `id` is not a string.
+3.  Configuration booleans are provided as other types.
+4.  An invalid `logType` is passed to the logging methods.

package/docs/v1/libs/TinyMediaPlayer.md

@@ -252,7 +252,7 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 * **`existsTrack(index)`**: Returns `true` if the track exists at the given index.
 * **`getTrack(index)`**: Retrieves the track at the specified index.
 * **`removeTrack(index)`**: **(Async)** Removes a track and adjusts the current index/playback accordingly.
-* **`searchTrack(query)`**: Searches the playlist.
+* **`searchTrack(query)`**: Searches the playlist (string or function).
     * `query`: A `string` (searches title, artist, or album) or a `function` (custom logic).
     * **Returns**: `SearchResult[]` (array of objects containing the track and their corresponding indices).
 * **`clearPlaylist()`**: **(Async)** Stops playback and empties the entire playlist.
@@ -260,22 +260,22 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 #### ⏯️ Playback Controls
 * **`play()`**: **(Async)** Starts playback of the current track.
 * **`pause()`**: **(Async)** Pauses the current track.
-* **`mute()`**: **(Async)** Mutes the playback.
-* **`unMute()`**: **(Async)** Unmutes the playback.
 * **`stop()`**: **(Async)** Stops the current track completely.
 * **`next()`**: **(Async)** Advances to the next track (respects `loopMode` and `isRandom`).
 * **`prev()`**: **(Async)** Returns to the previous track (respects `loopMode` and `isRandom`).
 * **`skipTo(index)`**: **(Async)** Jumps to a specific index in the playlist.
 * **`seek(timeMs)`**: **(Async)** Jumps to a specific millisecond in the current track.
 * **`step(stepMs)`**: **(Async)** Moves the timeline forward (+) or backward (-) by `stepMs`.
+* **`mute()`**: **(Async)** Mutes the current playback.
+* **`unMute()`**: **(Async)** Unmutes the current playback.
 
 #### ⏳ Time Utilities
 * **`getCurrentTime()`**: Gets the current playback time in milliseconds.
 * **`getTotalDuration()`**: Gets the total duration of the current track in milliseconds.
 * **`getRemainingTime()`**: Gets the remaining time until the current track ends in milliseconds.
 * **`getPlaybackPercentage()`**: Gets the percentage of the current track that has been played (0-100).
-* **`isPaused` (Getter)**: Checks if the adapter is paused.
-* **`isEnded` (Getter)**: Checks if the adapter has ended.
+* **`isPaused`**: **(Getter)** Checks if the adapter is paused.
+* **`isEnded`**: **(Getter)** Checks if the adapter has ended.
 * **`getContentData()`**: **(Async)** Retrieves structured metadata for the current content.
 * **`waitIsReady()`**: **(Async)** Waits until the active adapter is fully initialized.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.8",
+  "version": "1.28.9",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "bin": {
     "tiny-essentials-fork": "./TinyFork.mjs"
@@ -112,6 +112,10 @@
       "require": "./dist/v1/basics/promiseUtils.cjs",
       "import": "./dist/v1/basics/promiseUtils.mjs"
     },
+    "./basics/browserDetector": {
+      "require": "./dist/v1/basics/browserDetector.cjs",
+      "import": "./dist/v1/basics/browserDetector.mjs"
+    },
     "./fileManager": {
       "require": "./dist/v1/fileManager/index.cjs",
       "import": "./dist/v1/fileManager/index.mjs"