tiny-essentials 1.28.16 → 1.28.17

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.16",
+  "version": "1.28.17",
   "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"