tiny-essentials 1.28.16 → 1.28.18

package/docs/v1/basics/jsonFilter.md

@@ -0,0 +1,194 @@
+# 🛠️ Object Filtering Utilities Documentation
+
+A collection of powerful, high-precision JavaScript utilities designed to filter objects based on keys, values, or complex nested conditions.
+
+## 📋 Table of Contents
+1. [`jsonFilter`](#jsonfilter) — Shallow filtering.
+2. [`jsonFilterRecursive`](#jsonfilterrecursive) — Deep/Recursive filtering.
+3. [`jsonFilterByKeys`](#jsonfilterbykeys) — Selective key/value extraction.
+
+---
+
+## 🔍 `jsonFilter`
+
+`jsonFilter` is a shallow filtering function. It creates a new object containing only the entries that satisfy a specific predicate function.
+
+### ⚙️ Syntax
+```javascript
+jsonFilter(value, filterContent);
+```
+
+### 📥 Parameters
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `Object` | The source object to be filtered. |
+| `filterContent` | `Function` | A callback: `(entry, index, array) => boolean`. |
+
+### 🚀 Example
+Filtering an object to only keep entries where the value is a number greater than 10.
+
+```javascript
+import { jsonFilter } from 'tiny-essentials/basics/jsonFilter';
+
+const data = { a: 5, b: 15, c: 20, d: 'hello' };
+
+const result = jsonFilter(data, ([key, value]) => typeof value === 'number' && value > 10);
+
+console.log(result); 
+// Output: { b: 15, c: 20 }
+```
+
+---
+
+## 🌳 `jsonFilterRecursive`
+
+`jsonFilterRecursive` performs a deep traversal of a data structure. It allows you to apply specific filtering rules depending on whether the current item is a **primitive**, an **array**, or a **complex container** (Object, Map, or Set).
+
+### ⚙️ Syntax
+```javascript
+jsonFilterRecursive(value, filter);
+```
+
+### 📥 Parameters
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `Object \| Map \| Set` | The source structure to be filtered. |
+| `filter` | `Object` | An object containing predicate functions: |
+| `filter.value` | `Function` | Applied to **primitive** values. |
+| `filter.obj` | `Function` | Applied to **nested objects, Maps, or Sets** (used for pruning). |
+| `filter.array` | `Function` | Applied to **arrays**. |
+
+> **Note:** `WeakMap` and `WeakSet` are supported but, due to their non-iterable nature, will return a new empty instance of the same type when processed.
+
+### 🚀 Example
+Filtering a complex structure containing `Map` and `Set` objects.
+
+```javascript
+import { jsonFilterRecursive } from 'tiny-essentials/basics/jsonFilter';
+
+const complexData = {
+  id: 'Yasmin',
+  food: ['pudding'],
+  tags: new Set(['premium', 'beta-tester']),
+  empty: new Set(),
+  metadata: new Map([
+    ['last_login', '2023-10-27'],
+    ['login_count', 42]
+  ]),
+  settings: {
+    theme: 'dark',
+    notifications: true
+  }
+};
+
+const filterConfig = {
+  value: ([key, val]) => typeof val === 'string', // Keep strings
+  
+  // Prune Maps or Sets if they become empty after filtering
+  obj: (container) => {
+    if (container instanceof Map || container instanceof Set) {
+      return container.size > 0;
+    }
+    return container.id !== undefined; // Prune objects that don't have an 'id'
+  },
+  
+  array: () => true                               // Keep all arrays
+};
+
+const result = jsonFilterRecursive(complexData, filterConfig);
+
+console.log(result);
+/*
+Output:
+{
+  food: ['pudding'],
+  id: 'Yasmin',
+  tags: Set { 'premium', 'beta-tester' },
+  metadata: Map { 'last_login' => '2023-10-27' }
+}
+*/
+```
+
+---
+
+## 🔑 `jsonFilterByKeys`
+
+`jsonFilterByKeys` is a highly specialized selector. It allows you to extract specific keys or key-value pairs using simple strings, tuples, or validation functions.
+
+### ⚙️ Syntax
+```javascript
+jsonFilterByKeys(item, keys, values);
+```
+
+### 📥 Parameters
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `item` | `Object` | The source object. |
+| `keys` | `Array` | An array of `string` keys OR `[key, validator/value]` tuples. |
+| `values` | `Array` (opt) | A list of allowed values or validators to apply to the keys. |
+
+### 💡 Usage Modes
+
+#### 1. Using Simple Keys + Value Whitelist
+If you provide a list of keys and a list of allowed values.
+
+```javascript
+import { jsonFilterByKeys } from 'tiny-essentials/basics/jsonFilter';
+
+const data = { status: 'active', type: 'user', age: 25 };
+// Keep only 'status' if it is 'active'
+const result = jsonFilterByKeys(data, ['status'], ['active']); 
+// Output: { status: 'active' }
+```
+
+#### 2. Using Key-Value Tuples (Highly Precise)
+You can pass a tuple `[key, condition]` where the condition is a value or a function.
+
+```javascript
+import { jsonFilterByKeys } from 'tiny-essentials/basics/jsonFilter';
+
+const data = {
+  id: 101,
+  role: 'admin',
+  score: 95,
+  enabled: true
+};
+
+// Keep 'id', 'score', and 'role'.
+const result = jsonFilterByKeys(data, [
+  'id', 
+  ['role', 'admin'],
+  ['score', (value) => value > 90]
+]);
+
+console.log(result); 
+// Output: { id: 101, role: 'admin', score: 95 }
+```
+
+#### 3. Using Validators
+You can pass functions to perform complex validation during selection.
+
+```javascript
+import { jsonFilterByKeys } from 'tiny-essentials/basics/jsonFilter';
+
+const data = {
+  name: 'Isabela',
+  age: 30,
+  score: 9.5
+};
+
+// Keep keys where the value is a number greater than 10
+const result = jsonFilterByKeys(data, ['age', 'score'], [(v) => typeof v === 'number' && v > 10]);
+
+console.log(result);
+// Output: { age: 30 }
+```
+
+---
+
+## ⚠️ Error Handling
+
+All functions implement strict runtime validation and will throw a `TypeError` if:
+- The input `value` is not a valid object.
+- The `filterContent` or `filter` predicates are not functions.
+- The `keys` or `values` arguments are not arrays when required.

package/docs/v1/libs/media/TinyRadioFm.md

@@ -12,9 +12,9 @@
 * **🎵 Dual-Stream Logic:** Manages separate playlists for `music` and `voice`, with configurable interaction rules (e.g., playing voices after music).
 * **📅 Scheduled Mutations:** Schedule tasks to `add`, `remove`, or `move` items in the playlist at specific future timestamps.
 * **⚡ Custom Injections:** Inject "Custom Positions" into the timeline that interrupt the standard cycle.
-* **🧠 Smart Queuing:** Intelligent logic to prevent audio overlaps by automatically adjusting timestamps to the end of currently playing content.
+* **🧠 Smart Queuing:** Intelligent logic to prevent audio overlaps by automatically adjusting timestamps to the end of the currently playing content.
 * **💾 State Persistence:** Full export/import capabilities, including automatic conversion of Blob URLs to Base64 for easy storage.
-* **🧹 Memory Management:** Proactive cleanup of Blob URLs and event listeners to prevent memory leaks.
+* **🧹 Memory Management:** Proactive cleanup of Blob URLs and event listeners to prevent memory leaks, with configurable optimization for media and pictures.
 
 ---
 
@@ -31,6 +31,7 @@ The behavior of the engine is controlled via the `RadioConfig` object.
 | `voiceAfterMusic` | `boolean` | `true` | If `true`, voice messages play after music tracks. |
 | `voiceMin` | `number` | `0` | Minimum number of voice messages to play in a cycle. |
 | `voiceMax` | `number` | `1` | Maximum number of voice messages to play in a cycle. |
+| `voiceWeight` | `number` | `1` | Weight used to calculate the probability of a voice block occurring ($P = W / (W + 1)$). |
 | `musicMinConsecutive`| `number` | `0` | Min times a music track must repeat consecutively. |
 | `musicMaxConsecutive`| `number` | `0` | Max consecutive music repeats (`-1` = unlimited, `0` = no repeats). |
 | `voiceMinConsecutive`| `number` | `0` | Min times a voice track must repeat consecutively. |
@@ -50,11 +51,41 @@ Prepares a `MediaContent` object by extracting metadata from an audio source.
     * `metadata`: Optional manual overrides.
     * `parseFile`: Internal helper for file parsing.
     * `callbacks`: Object containing `onProgress` and `onError` handlers.
-    * `convertBase64toBlob`: If true, the image content will be converted directly into a high-performance Blob URL, use this method.
+    * `convertBase64toBlob`: If true, the image content will be converted directly into a high-performance Blob URL.
 * **Returns:** `Promise<MediaContent>`
 * **Throws:** `MediaLoadingError`
 
----
+#### `static get/set unknownArtist(value)`
+Gets or sets the identifier used when an artist cannot be determined.
+* **Value:** A `string` or a `function` that returns a `string`.
+* **Throws:** `TypeError` if the value is not a string or a function.
+
+### 📋 Properties (Getters & Setters)
+
+#### **System State & Lifecycle**
+* `destroyed`: Returns `true` if the instance has been destroyed.
+* `size`: Total count of all content items (music + voice).
+* `seed`: Gets/Sets the core randomness seed.
+* `anchorDate`: Gets the absolute timestamp used as the timeline anchor.
+* `cycleCacheSize`: Returns the number of items currently stored in the cycle cache.
+
+#### **Playlist Access (Returns Deep Clones)**
+* `musicList`: Returns a deep clone of the music playlist.
+* `voiceList`: Returns a deep clone of the voice playlist.
+* `allList`: Returns a deep clone of the combined music and voice playlists.
+* `customPositions`: Returns a deep clone of the custom position injections.
+* `scheduledTasks`: Returns a deep clone of the pending scheduled tasks.
+
+#### **Counters**
+* `musicSize`: Total number of items in the music playlist.
+* `voiceSize`: Total number of items in the voice playlist.
+* `customPosSize`: Number of active custom position injections.
+* `tasksSize`: Number of pending scheduled tasks.
+
+#### **Configuration & Optimization**
+* `config`: Gets/Sets the current `RadioConfig` object.
+* `optimizeMediaMemory`: Gets/Sets whether Blob URLs for media should be converted to Base64 during export.
+* `optimizePictureMemory`: Gets/Sets whether Blob URLs for pictures should be converted to Base64 during export.
 
 ### 📥 Content Management
 
@@ -67,12 +98,10 @@ Adds new content to the engine immediately.
 * **Emits:** `contentAdded`
 
 #### `remove(id)`
-Instantly removes content by its unique ID across all lists, custom positions, and pending tasks. It also revokes associated Blob URLs.
+Instantly removes content by its unique ID across all lists, custom positions, and pending tasks. It also revokes associated Blob URLs to free memory.
 * **Parameters:** `id` (string)
 * **Emits:** `contentRemoved`
 
----
-
 ### 📅 Task & Config Management
 
 #### `scheduleTask(timestamp, action, type, payload, smartQueue = true)`
@@ -90,8 +119,6 @@ Performs a partial or full update of the engine configuration.
 * **Parameters:** `config` (Partial or full `RadioConfig` object).
 * **Emits:** `configChanged`
 
----
-
 ### 🔍 Timeline & Querying
 
 #### `getCurrentEvent()`
@@ -106,7 +133,9 @@ Predicts upcoming events from a specific date forward using a virtual sandbox to
 * **Returns:** `RadioEvent[]`
 * **Throws:** `TypeError` or `RangeError` if limit is invalid.
 
----
+#### `searchCustomPositions()`
+Returns a shallow copy of all active custom positions currently injected into the timeline.
+* **Returns:** `CustomPosition[]`
 
 ### 💾 Persistence & Lifecycle
 
@@ -161,4 +190,4 @@ A structural block representing a single full iteration of the radio sequence.
 * `lastMusicId`: ID of the last music played in this block.
 * `musicConsecutiveCount`: Current consecutive count for music.
 * `lastVoiceId`: ID of the last voice played in this block.
-* `voiceConsecutiveCount`: Current consecutive count for voice.
+* `voiceConsecutiveCount`: Current consecutive count for voice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.16",
+  "version": "1.28.18",
   "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"
@@ -114,6 +114,10 @@
       "require": "./dist/v1/basics/browserDetector.cjs",
       "import": "./dist/v1/basics/browserDetector.mjs"
     },
+    "./basics/jsonFilter": {
+      "require": "./dist/v1/basics/jsonFilter.cjs",
+      "import": "./dist/v1/basics/jsonFilter.mjs"
+    },
     "./fileManager": {
       "require": "./dist/v1/fileManager/index.cjs",
       "import": "./dist/v1/fileManager/index.mjs"