tiny-essentials 1.28.19 → 1.29.0

package/docs/v1/basics/objFilter.md

@@ -4,20 +4,19 @@ Type detection, extension, and analysis made easy — simple and extensible type
 
 ## Overview
 
-`objFilter.mjs` is a utility module that provides a structured and extensible way to validate, infer, and count object types in JavaScript. It’s designed to work in both Node.js and browser environments and is perfect for libraries that need consistent, extensible type-checking logic.
+`objFilter.mjs` is a utility module that provides a structured and extensible way to validate, infer, and analyze types in JavaScript. It is designed to work in both Node.js and browser environments, making it ideal for libraries that require consistent, predictable, and highly customizable type-checking logic.
 
-Whether you’re validating inputs, writing schema validators, or building tools that need to "understand" JavaScript data — this module has your back!
+Whether you are building a schema validator, a data transformation pipeline, or debugging complex nested objects, `objFilter.mjs` provides the tools to "understand" your data precisely.
 
 ---
 
 ## Features
 
-- ✅ Precise type detection (`undefined`, `null`, `array`, `date`, etc.)
-- ➕ Custom type extensions with ordering
-- 🔄 Reorder type checking priority
-- 🔍 Safe and predictable type checks
-- 🧮 Count values in arrays and objects
-- 🚫 No dependencies
+- ✅ **Precise Type Detection**: Detects primitives, built-in objects (`Map`, `Set`, `Date`, etc.), and even browser-specific types.
+- ➕ **Extensible Architecture**: Easily add custom types with specific validation and cloning logic.
+- 🔄 **Priority Control**: Reorder the evaluation sequence to ensure specific types (like `array`) are caught before generic ones (like `object`).
+- 🔍 **Deep Cloning Support**: Integrated cloning logic within the type registry for seamless data duplication.
+- 🚫 **Zero Dependencies**: Lightweight and pure JavaScript.
 
 ---
 
@@ -25,34 +24,22 @@ Whether you’re validating inputs, writing schema validators, or building tools
 
 ### 🔍 `checkObj(obj)`
 
-Checks the type of a given object and returns the validation result if a known type is detected.
+Evaluates an object against the registered validators and returns the first match found.
 
-```js
+```javascript
 checkObj('hello');
 // { valid: true, type: "string" }
 
-checkObj(123);
-// { valid: true, type: "number" }
+checkObj(new Map());
+// { valid: Map(0) {}, type: "map" }
 
 checkObj(undefined);
-// { valid: true, type: "undefined" }
-
-checkObj(Symbol('sym'));
-// { valid: true, type: "symbol" }
-
-checkObj(() => {});
-// { valid: true, type: "function" }
-
-checkObj(null);
-// { valid: true, type: "null" }
-
-checkObj(Object.create(null));
-// { valid: true, type: "object" }
+// { valid: null, type: null }
 ```
 
-Returns:
-- `{ valid: true, type: "<type>" }` if the type is recognized
-- `{ valid: null, type: null }` if no matching type is found
+**Returns:**
+- `{ valid: any, type: string }` if a match is found (`valid` contains the truthy result of the validator).
+- `{ valid: null, type: null }` if no match is found.
 
 ---
 
@@ -60,23 +47,25 @@ Returns:
 
 Returns the detected type name of a given value as a string.
 
-```js
+```javascript
 objTypeName([]); // "array"
 objTypeName(null); // "null"
 objTypeName(new Set()); // "set"
+objTypeName(123); // "number"
+objTypeName(Symbol('foo')); // "symbol"
 ```
 
-Returns:
+**Returns:**
 - A string representing the type name (e.g., `"array"`, `"date"`, `"map"`).
-- `"unknown"` if no matching type is found.
+- `"unknown"` if no match is found.
 
 ---
 
 ### ✅ `isObjType(obj, type)`
 
-Checks whether a given object matches a specific type. This check is case-insensitive.
+A strict boolean check to see if a value matches a specific type name. This check is case-insensitive.
 
-```js
+```javascript
 isObjType([], 'array'); // true
 isObjType({}, 'object'); // true
 isObjType('hello', 'string'); // true
@@ -87,82 +76,64 @@ isObjType(123, 'boolean'); // false
 
 ---
 
-### ➕ `extendObjType(newTypes, [index])`
+### ➕ `extendObjType(ni, [index])`
 
-Add your own custom types. You can optionally define where in the check order they go.
+Add your own custom types to the registry. You can provide types as an object, an array of tuples, or a single tuple.
 
-```js
+**Using an Object:**
+```javascript
 extendObjType({
-  customElement: val => val && val.tagName === 'MY-ELEMENT'
+  customType: val => typeof val === 'symbol'
 });
 ```
 
-```js
+**Using an Array of Tuples:**
+```javascript
 extendObjType([
-  [ 'alpha', val => typeof val === 'string' ],
-  [ 'beta', val => Array.isArray(val) ]
+  ['alpha', val => typeof val === 'string'],
+  ['beta', val => Array.isArray(val), (val) => [...val]] // [key, validator, cloner]
 ]);
 ```
 
-This will insert `customElement` before the built-in `object` type unless a position is specified.
-
----
-
-### 🔁 `reorderObjTypeOrder(newOrder)`
-
-Set a custom priority order for how types are checked (must include only known types).
-
-```js
-reorderObjTypeOrder([
-  'string',
-  'number',
-  'array',
-  'object'
-]);
+**Using a Single Tuple:**
+```javascript
+extendObjType(['gamma', val => typeof val === 'number']);
 ```
 
-Returns `true` if successful, or `false` if the order includes unknown types.
+*Note: If no `index` is provided, the type is inserted before the 'object' type or at the end of the registry.*
 
 ---
 
-### 📋 `cloneObjTypeOrder()`
+### 🔁 `reorderObjTypeOrder(newOrder)`
 
-Safely get a copy of the current type evaluation order.
+Sets a custom priority for type detection. All provided names must already exist in the registry.
 
-```js
-const currentOrder = cloneObjTypeOrder();
+```javascript
+reorderObjTypeOrder(['string', 'number', 'array', 'object']);
 ```
 
 ---
 
 ## Supported Types
 
-Here’s a full list of supported type names (in their default order):
-
-- `undefined`
-- `null`
-- `boolean`
-- `number`
-- `bigint`
-- `string`
-- `symbol`
-- `function`
-- `array`
-- `buffer`
-- `date`
-- `regexp`
-- `map`
-- `set`
-- `weakmap`
-- `weakset`
-- `promise`
-- `htmlElement`
-- `object`
-
-You can change this order or insert your own types with `extendObjType`.
+By default, the following types are supported (order may vary if customized):
 
----
+- **Primitives**: `undefined`, `null`, `boolean`, `number`, `nannumber`, `bigint`, `string`, `symbol`, `function`.
+- **Built-in Objects**: `array`, `date`, `regexp`, `map`, `set`, `weakmap`, `weakset`, `promise`, `url`.
+- **Browser Specific**: `file`, `htmlelement` (only available in browser environments).
+- **Generic**: `object`.
 
-### 🛠️ `getCheckObj()`
+---
 
-This function creates a clone of the functions from the `typeValidator` object. It returns a new object where the keys are the same and the values are the cloned functions.
+## API Reference
+
+| Function | Description |
+| :--- | :--- |
+| `checkObj(obj)` | Returns the first matching type and its validation result. |
+| `objTypeName(val)` | Returns the type name as a string. |
+| `isObjType(obj, type)` | Returns `true` if the value matches the type. |
+| `extendObjType(ni, index)` | Adds new types to the registry. |
+| `reorderObjTypeOrder(newOrder)` | Changes the priority of type checking. |
+| `cloneObjTypeOrder()` | Returns a copy of the current evaluation order. |
+| `getObjTypeOrder()` | Returns a copy of the current evaluation order. |
+| `getObjTypeRegistry()` | Returns a clone of the entire type registry. |

package/docs/v1/basics/promiseUtils.md

@@ -1,9 +1,11 @@
+# 🔁 Promise Utils
+
 ### 🔁 `waitForTrue(getValue, checkInterval = 100)`
 
 Waits until a provided function returns `true`, polling periodically.
 
 ```ts
-static waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<void>
+waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<void>
 ```
 
 * `getValue`: Function that returns `true` when the wait should end.
@@ -11,22 +13,29 @@ static waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<voi
 
 ---
 
-### 🔒 `createSingletonTask(baseFunction)`
+### 🔒 `createSingletonTask(baseFunction, autoReset = true)`
 
 Creates a controller object that ensures an asynchronous function is only executed once at a time. If a task is already in progress, subsequent calls to `callback` will wait for the existing promise to resolve.
 
 ```ts
 createSingletonTask<T, A extends any[]>(
-  baseFunction: (...args: A) => Promise<T>
+  baseFunction: (...args: A) => Promise<T>,
+  autoReset?: boolean
 ): {
   callback: (...args: A) => Promise<T>;
   getActivePromise: () => Promise<T> | null;
   resetActivePromise: () => void;
+  isEnded: () => boolean;
+  isFailed: () => boolean;
+  isLoading: () => boolean;
 }
 ```
 
 * `callback`: The wrapped function that manages execution state.
 * `getActivePromise`: Returns the current active promise, or `null` if no task is running.
 * `resetActivePromise`: Forces the state to reset, allowing the next call to start a new execution.
+* `isEnded`: Returns `true` if the last execution (success or failure) has finished.
+* `isFailed`: Returns `true` if the last execution resulted in an error.
+* `isLoading`: Returns `true` if an execution is currently in progress.
 
 > **Note:** This utility is designed for **request collapsing** (all callers receive the same result). If you need to execute multiple independent tasks sequentially where each call returns its own unique result, please refer to the documentation for `TinyPromiseQueue.mjs`.

package/docs/v1/basics/text.md

@@ -1,4 +1,3 @@
-
 # ✍️ text.mjs
 
 A simple utility for transforming text into title case formats.

package/docs/v1/libs/array/TinyArrayComparator.md

@@ -1,14 +1,15 @@
 # 🔍 TinyArrayComparator
 
-A lightweight, highly optimized JavaScript utility class designed to compare two arrays and efficiently detect which items were **added** or **deleted**. 
+A lightweight, highly optimized JavaScript utility class designed to compare two arrays and efficiently detect which items were **added**, **deleted**, or **edited**.
 
 ## ✨ Features
 
+- **Smart Identity Tracking:** Uses an `idKey` to distinguish between a new item and an edited version of an existing item.
+- **Deep Diffing:** Provides detailed, property-level differences (`added`, `deleted`, `modified`, `nested`) when `deepComparison` is enabled.
 - **Fast Comparison:** Uses a Map and hash-based lookups for $O(N)$ performance.
 - **Stateful Design:** Store your base array once and compare it multiple times.
 - **Zero Dependencies:** Pure Vanilla JavaScript.
-- **Deep Compatibility:** Safely hashes strings, numbers, arrays, and deep objects.
-- **Clean Architecture:** Built as an ES6 Module with strict JSDoc typing and input validation.
+- **Clean Architecture:** Built as an ES6 Module with strict JSDoc typing and robust input validation.
 
 ---
 
@@ -22,28 +23,29 @@ import TinyArrayComparator from 'tiny-essentials/libs/array/TinyArrayComparator'
 ```
 
 ### 2. Prepare Your Arrays
-Set up the initial state (`oldArray`) and the modified state (`newArray`) that you want to compare.
+To detect **edits** instead of just additions/deletions, ensure your objects have a unique identifier (like `id`).
 
 ```javascript
 const oldList = [
-  { id: 1, role: 'admin' },
-  { id: 2, role: 'user' },
-  { id: 3, role: 'moderator' }
+  { id: 1, name: 'Alice', meta: { role: 'admin' } },
+  { id: 2, name: 'Bob', meta: { role: 'user' } },
 ];
 
 const newList = [
-  { id: 1, role: 'admin' },       // Unchanged
-  { id: 3, role: 'moderator' },   // Unchanged
-  { id: 4, role: 'guest' }        // Added
-  // User ID 2 was deleted
+  { id: 1, name: 'Alice', meta: { role: 'admin' } }, // Unchanged
+  { id: 2, name: 'Bob', meta: { role: 'editor' } },   // Edited (role changed)
 ];
 ```
 
 ### 3. Initialize and Compare
-Instantiate the class passing the initial array. Then, call the `compare` method with your new array.
+Pass the `idKey` in the options so the comparator knows how to identify the same object.
 
 ```javascript
-const comparator = new TinyArrayComparator(oldList);
+const comparator = new TinyArrayComparator(oldList, { 
+  idKey: 'id', 
+  deepComparison: true 
+});
+
 const results = comparator.compare(newList);
 
 console.log(results);
@@ -53,12 +55,17 @@ console.log(results);
 ```json
 [
   {
-    "item": { "id": 4, "role": "guest" },
-    "status": "added"
-  },
-  {
-    "item": { "id": 2, "role": "user" },
-    "status": "deleted"
+    "item": { "id": 2, "name": "Bob", "meta": { "role": "editor" } },
+    "oldItem": { "id": 2, "name": "Bob", "meta": { "role": "user" } },
+    "status": "edited",
+    "details": {
+      "modified": {
+        "meta": {
+          "oldValue": { "role": "user" },
+          "newValue": { "role": "editor" }
+        }
+      }
+    }
   }
 ]
 ```
@@ -67,35 +74,39 @@ console.log(results);
 
 ## 🛠️ API Reference
 
-### `constructor([oldArray])`
+### `constructor(oldArray, options)`
 Creates a new comparator instance.
-* **`oldArray`** `(Array<any>)` *(Optional)*: The initial state of the array to be stored. Throws a `TypeError` if the provided value is not an Array.
+* **`oldArray`** `(Array<any>)` *(Optional)*: The initial state to be stored.
+* **`options`** `(Object)` *(Optional)*:
+    * **`idKey`** `(string|null)`: The property used to identify unique objects. Defaults to `null` (if `null`, comparison relies purely on value hashing).
+    * **`deepComparison`** `(boolean)`: If `true`, the `compare` method returns detailed property changes for edited items. Defaults to `true`.
 
 ### `compare(newArray)`
-Evaluates differences between the internally stored `oldArray` and the provided `newArray`. Throws a `TypeError` if the provided value is not an Array.
-* **`newArray`** `(Array<any>)`: The new array containing current modifications.
-* **Returns:** An array of objects. Each object contains the original `item` and a `status` string (either `'added'` or `'deleted'`).
-
-### `get oldArray` / `set oldArray(value)`
-Allows you to retrieve or update the base array stored inside the instance.
-* **Throws:** `TypeError` if attempting to set a non-array value.
+Evaluates differences between the stored `oldArray` and the provided `newArray`.
+* **`newArray`** `(Array<any>)`: The new array state.
+* **Returns:** `Array<DiffResult>`. Each result contains:
+    * `item`: The current version of the item.
+    * `status`: `'added' | 'deleted' | 'edited'`.
+    * `oldItem`: (Only if `status` is `'edited'`) The original version of the item.
+    * `details`: (Only if `status` is `'edited'` and `deepComparison` is `true`) A structured object showing `added`, `deleted`, `modified`, and `nested` changes.
+
+### Properties (Getters/Setters)
+* **`idKey`**: Gets or sets the property name used as a unique identifier. Must be a `string` or `null`.
+* **`deepComparison`**: Gets or sets whether detailed diffing is enabled. Must be a `boolean`.
+* **`oldArray`**: Gets or sets the base array used for comparison. Must be an `Array`.
 
 ### `static generateHash(item)`
-A static helper method if you ever need to generate a unique base36 hash string for an item outside the comparison flow.
-* **`item`** `(any)`: The target object, string, or number to hash.
-* **Returns:** A `string` representing the unique hash.
-
-```javascript
-const myHash = TinyArrayComparator.generateHash({ pony: 'Pudding' });
-console.log(myHash); // Returns a base36 string like "1b4x9z"
-```
+Generates a unique base36 hash string for any value.
+* **`item`** `(any)`: The value to hash.
+* **Returns:** `string`.
+* **@throws** `TypeError` if the item contains circular references.
 
 ---
 
 ## 💡 Best Practices
 
-* **Order Doesn't Matter:** Because this utility relies on value-hashing, the index order of items inside the arrays does not affect the comparison. It strictly checks for the existence of the values.
-* **Object References:** The returned array preserves the exact references to the items passed in the parameters, allowing you to seamlessly integrate the output back into your application logic.
-* **Reusability:** You can easily update the base state by assigning a new array to `comparator.oldArray = [...]` without creating a new instance.
+* **Identity vs. Value:** If you do **not** provide an `idKey`, an object that changes even a single property will be reported as one `deleted` item and one `added` item. Always use `idKey` when working with collections of objects to enable the `edited` status.
+* **Immutability:** For best results, treat the arrays passed to the comparator as immutable.
+* **Performance:** The complexity is $O(N)$, making it suitable for large arrays.
 
 Happy coding! 💻✨