esi-cap 1.7.32 → 1.7.34

package/types/lib/utils/index.md

@@ -0,0 +1,474 @@
+# esi-cap Utilities API Reference
+
+> **Module:** `utils`  
+> **Purpose:** Core utility belt — date validation, XML parsing, JSON manipulation, array operations, and UUID generation/parsing.
+
+---
+
+## Table of Contents
+
+- [Dependencies](#dependencies)
+- [Exports](#exports)
+- [Class: `date`](#class-date)
+  - [date.isValid(sDate)](#dateisvalidsdate)
+- [Class: `xml`](#class-xml)
+  - [xml.isValid(oXML)](#xmlisvalidoxml)
+- [Class: `json`](#class-json)
+  - [json.isValid(oJson)](#jsonisvalidojson)
+  - [json.copy(oJson)](#jsoncopyojson)
+  - [json.replace(oJson, sOldValue, sNewValue, oEvaluate?)](#jsonreplaceojson-soldvalue-snewvalue-oevaluate)
+  - [json.getValue(oJson, sPropertyPath)](#jsongetvalueojson-spropertypath)
+  - [json.unique(oNestedArray)](#jsonuniqueonnestedarray)
+  - [json.order(oJson, oKeyOrder)](#jsonorderojson-okeyorder)
+  - [json.projection(oJson, oColumns, bHasAssociattion?)](#jsonprojectionojson-ocolumns-bhasassociattion)
+  - [json.map(oJson, oMap)](#jsonmapojson-omap)
+  - [json.merge(oJson1, oJson2)](#jsonmergeojson1-ojson2)
+  - [json.flat(oJson, sFlattenedProperty)](#jsonflatojson-sflattenedproperty)
+  - [json.stripUndefined(oSourceJson)](#jsonstripundefinedosourcejson)
+- [Class: `array`](#class-array)
+  - [array.add(oArray, oItem)](#arrayaddoarray-oitem)
+  - [array.topN(oSortedArray, iTop)](#arraytopnosortedarray-itop)
+  - [array.flat(oArray, sFlattenedProperty)](#arrayflatoarray-sflattenedproperty)
+  - [array.unique(oArray)](#arrayuniqueoarray)
+  - [array.order(oArray, oOrder)](#arrayorderoarray-oorder)
+  - [array.projection(oArray, oColumns, bHasAssociattion?)](#arrayprojectionoarray-ocolumns-bhasassociattion)
+  - [array.map(oArray, oMap)](#arraymapoarray-omap)
+  - [array.sort(oArray, oOrderBy)](#arraysortoarray-oorderby)
+  - [array.filter(oArray, oFilterCondition)](#arrayfilteroarray-ofiltercondition)
+  - [array.hasElement(oArray, oElement)](#arrayhaselementoarray-oelement)
+  - [array.toArray(oArray)](#arraytoarrayoarray)
+  - [array.toDisArray(oArray)](#arraytodisarrayoarray)
+  - [array.toInterleavedArray(oArray, oElement)](#arraytointerleavedarray-oarray-oelement)
+  - [array.toArrayProjection(oArray, sProjectionFieldName)](#arraytoarrayprojectionoarray-sprojectionfieldname)
+  - [array.findProperty(oArray, sProjectionFieldName)](#arrayfindpropertyoarray-sprojectionfieldname)
+  - [array.toGroupByPropertyName(oArray, sPropertyName)](#arraytogroupbypropertynameoarray-spropertyname)
+  - [array.toGroupByPropertyList(oArray, oPropertyList)](#arraytogroupbypropertylistoarray-opropertylist)
+- [Class: `UUID`](#class-uuid)
+  - [constructor()](#constructor)
+  - [converse(oJsonData)](#converseoJsondata)
+  - [inverse(sUUID)](#inversesuuid)
+
+---
+
+## Dependencies
+
+| Package  | Purpose                                         |
+|----------|-------------------------------------------------|
+| `xml2js` | XML string parsing and validation               |
+| `uuid`   | UUID format validation                          |
+| `lodash` | Deep merge, orderBy, uniqWith, and isEqual      |
+
+---
+
+## Exports
+
+```js
+module.exports = { date, xml, json, array, UUID };
+```
+
+---
+
+## Class: `date`
+
+Date-related validation helpers. All methods are `static`.
+
+### `date.isValid(sDate)`
+
+| Parameter | Type     | Description                          |
+|-----------|----------|--------------------------------------|
+| `sDate`   | `string` | Date string to validate              |
+| **Returns** | `Promise<boolean>` | `true` if valid date    |
+
+**Behavior:** Parses the string via `new Date()` and verifies the result is a real Date (not `NaN`). Logs errors via the framework logger.
+
+```js
+await date.isValid("2026-04-20");    // true
+await date.isValid("not-a-date");    // false
+```
+
+---
+
+## Class: `xml`
+
+XML parsing and validation helpers. All methods are `static`.
+
+### `xml.isValid(oXML)`
+
+| Parameter | Type             | Description                 |
+|-----------|------------------|-----------------------------|
+| `oXML`    | `string\|object` | XML content to validate     |
+| **Returns** | `Promise<boolean>` | `true` if well-formed XML |
+
+**Behavior:** Uses `xml2js.Parser.parseStringPromise` to attempt parsing. Logs the parsed result on success and errors on failure.
+
+```js
+await xml.isValid("<root><item>val</item></root>"); // true
+await xml.isValid("not xml");                       // false
+```
+
+---
+
+## Class: `json`
+
+Comprehensive JSON/object manipulation utilities. All methods are `static`.
+
+### `json.isValid(oJson)`
+
+Checks if the input can be parsed as JSON via `JSON.parse`.
+
+| Parameter | Type             | Returns    |
+|-----------|------------------|------------|
+| `oJson`   | `string\|object` | `boolean`  |
+
+---
+
+### `json.copy(oJson)`
+
+Creates a deep clone using `structuredClone`. Falls back to returning the original reference if the input isn't valid JSON.
+
+| Parameter | Type     | Returns  |
+|-----------|----------|----------|
+| `oJson`   | `object` | `object` |
+
+---
+
+### `json.replace(oJson, sOldValue, sNewValue, oEvaluate?)`
+
+Recursively walks objects and arrays, replacing all string occurrences of `sOldValue` with `sNewValue`. **Mutates the input in place.**
+
+| Parameter    | Type     | Default     | Description                                              |
+|-------------|----------|-------------|----------------------------------------------------------|
+| `oJson`      | `object\|Array` | — | Target structure                                          |
+| `sOldValue`  | `string` | —           | Substring to find                                        |
+| `sNewValue`  | `string` | —           | Replacement substring                                    |
+| `oEvaluate`  | `object` | `undefined` | Optional context; when set, resolved string is evaluated as a property path via `json.getValue` |
+
+```js
+const data = { msg: "Hello {{name}}", nested: { msg: "Hi {{name}}" } };
+json.replace(data, "{{name}}", "World");
+// data → { msg: "Hello World", nested: { msg: "Hi World" } }
+```
+
+---
+
+### `json.getValue(oJson, sPropertyPath)`
+
+Resolves a dot-separated property path to its value.
+
+| Parameter        | Type     | Returns |
+|-----------------|----------|---------|
+| `oJson`          | `object` | `*`     |
+| `sPropertyPath`  | `string` | Value or `undefined` |
+
+```js
+json.getValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
+json.getValue({ a: 1 }, "x.y");                    // undefined
+```
+
+---
+
+### `json.unique(oNestedArray)`
+
+Flattens a nested array and removes duplicates using JSON serialization for deep equality.
+
+| Parameter       | Type    | Returns |
+|----------------|---------|---------|
+| `oNestedArray`  | `any[]` | `any[]` |
+
+---
+
+### `json.order(oJson, oKeyOrder)`
+
+Returns a new object with keys reordered: specified keys first, then the rest.
+
+| Parameter   | Type       | Returns  |
+|------------|------------|----------|
+| `oJson`     | `object`   | `object` |
+| `oKeyOrder` | `string[]` | —        |
+
+```js
+json.order({ c: 3, a: 1, b: 2 }, ["a", "b"]); // { a: 1, b: 2, c: 3 }
+```
+
+---
+
+### `json.projection(oJson, oColumns, bHasAssociattion?)`
+
+Filters an object to include only the specified properties.
+
+| Parameter          | Type       | Default | Description                                  |
+|-------------------|------------|---------|----------------------------------------------|
+| `oJson`            | `object`   | —       | Source object                                |
+| `oColumns`         | `string[]` | —       | Property names to keep                       |
+| `bHasAssociattion` | `boolean`  | `false` | Also include keys prefixed with column names |
+
+---
+
+### `json.map(oJson, oMap)`
+
+Creates a new object by mapping source properties via a definition object.
+
+| Parameter | Type     | Description                                           |
+|-----------|----------|-------------------------------------------------------|
+| `oJson`   | `object` | Source data                                           |
+| `oMap`    | `object` | `{ targetKey: "source.path" }` mapping definition     |
+
+```js
+json.map({ user: { name: "John" } }, { fullName: "user.name" }); // { fullName: "John" }
+```
+
+---
+
+### `json.merge(oJson1, oJson2)`
+
+Deep-merges two objects using Lodash `_.merge`. Returns `{}` if either argument is not an object.
+
+---
+
+### `json.flat(oJson, sFlattenedProperty)`
+
+Promotes a nested property's contents to the top level of the object.
+
+```js
+json.flat({ id: 1, details: { name: "A", desc: "B" } }, "details");
+// { id: 1, name: "A", desc: "B" }
+```
+
+---
+
+### `json.stripUndefined(oSourceJson)`
+
+Removes properties where the value is `undefined`, `null`, or an empty string.
+
+---
+
+## Class: `array`
+
+Array operations with automatic fallback to the `json` class for single-object inputs. All methods are `static`.
+
+### `array.add(oArray, oItem)`
+
+Appends item(s) to an array. Accepts single values or arrays.
+
+---
+
+### `array.topN(oSortedArray, iTop)`
+
+Returns the first `iTop` elements via `Array.slice`.
+
+---
+
+### `array.flat(oArray, sFlattenedProperty)`
+
+Flattens a nested property for each element. Delegates to `json.flat` for single objects.
+
+---
+
+### `array.unique(oArray)`
+
+Deduplicates using Lodash `_.uniqWith` with `_.isEqual` for deep comparison.
+
+---
+
+### `array.order(oArray, oOrder)`
+
+Reorders keys for every object in the array per the specified key order.
+
+---
+
+### `array.projection(oArray, oColumns, bHasAssociattion?)`
+
+Projects each element to only contain the listed columns.
+
+---
+
+### `array.map(oArray, oMap)`
+
+Applies a property mapping to every element in the array.
+
+---
+
+### `array.sort(oArray, oOrderBy)`
+
+Multi-column sort with type coercion support.
+
+| `oOrderBy` entry | Property | Type | Description |
+|---|---|---|---|
+| `ref` | `string[]` | Required | Column path |
+| `sort` | `'asc'\|'desc'` | Optional (default `'asc'`) | Sort direction |
+| `function` | `'Date'\|'parseFloat'` | Optional | Value coercion |
+
+```js
+array.sort(items, [
+  { ref: ["date"], sort: "desc", function: "Date" },
+  { ref: ["price"], sort: "asc", function: "parseFloat" }
+]);
+```
+
+---
+
+### `array.filter(oArray, oFilterCondition)`
+
+Filters array elements based on a list of filter conditions (AND logic).
+
+**FilterCondition:**
+| Property | Type | Description |
+|---|---|---|
+| `name` | `string` | Property name to filter by |
+| `op` | `'='\|'!='\|'>'\|'<'\|'>='\|'<='` | Comparison operator |
+| `value` | `string\|number\|boolean` | Value to compare against |
+
+```js
+array.filter(employees, [
+  { name: "age", op: ">=", value: 30 },
+  { name: "dept", op: "=", value: "Engineering" }
+]);
+```
+
+---
+
+### `array.hasElement(oArray, oElement)`
+
+Returns `true` if the element is found (strict `===` via `Array.includes`).
+
+---
+
+### `array.toArray(value)`
+
+Normalizes any value into an array: `undefined` → `[]`, non-array → `[value]`, array → as-is.
+
+---
+
+### `array.toDisArray(oArray)`
+
+Unwraps a single-element array to its value. Multi-element arrays pass through.
+
+---
+
+### `array.toInterleavedArray(oArray, oElement)`
+
+Inserts a separator element between consecutive items.
+
+```js
+array.toInterleavedArray(["a", "b", "c"], "|"); // ["a", ["|"], "b", ["|"], "c"]
+```
+
+---
+
+### `array.toArrayProjection(oArray, sProjectionFieldName)`
+
+Extracts a single field from each element into a flat array.
+
+```js
+array.toArrayProjection([{ id: 1 }, { id: 2 }], "id"); // [1, 2]
+```
+
+---
+
+### `array.findProperty(oArray, sProjectionFieldName)`
+
+Recursively searches nested structures for all values of a named property. Returns a deduplicated array.
+
+---
+
+### `array.toGroupByPropertyName(oArray, sPropertyName)`
+
+Groups elements into an object keyed by a single property's value.
+
+```js
+array.toGroupByPropertyName(
+  [{ type: "A", v: 1 }, { type: "B", v: 2 }, { type: "A", v: 3 }],
+  "type"
+);
+// { A: [{...}, {...}], B: [{...}] }
+```
+
+---
+
+### `array.toGroupByPropertyList(oArray, oPropertyList)`
+
+Groups elements by a composite key derived from multiple properties (joined with `##`). Supports dot-notation paths and recursive deep property lookup.
+
+```js
+array.toGroupByPropertyList(data, ["region", "details.category"]);
+// { "US##Electronics": [...], "EU##Clothing": [...] }
+```
+
+---
+
+## Class: `UUID`
+
+Singleton class for deterministic UUID generation and parsing based on a fixed field configuration. Encodes/decodes structured business data into RFC-4122-compliant UUIDs.
+
+### Constructor
+
+```js
+const uuidHelper = new UUID();
+```
+
+Creates a singleton instance. Subsequent `new UUID()` calls return the same instance.
+
+---
+
+### `converse(oJsonData)`
+
+Encodes structured JSON data into a deterministic UUID.
+
+| Parameter   | Type     | Description                               |
+|------------|----------|-------------------------------------------|
+| `oJsonData` | `object` | Object                                    |
+| **Returns** | `string` | A valid UUID string                       |
+| **Throws**  | `Error`  | If any field has an invalid format or the generated UUID fails validation |
+
+```js
+const uid = new UUID();
+uid.converse({
+  ABC: "AB12",
+  MNO: "I1234567",
+  XYZ: "000000012345"
+});
+// Returns a valid UUID string e.g., "c0656612-2e12-4345-8670-000000012345"
+```
+
+---
+
+### `inverse(sUUID)`
+
+Decodes a previously generated UUID back into its original structured data.
+
+| Parameter | Type     | Description                        |
+|-----------|----------|------------------------------------|
+| `sUUID`   | `string` | A UUID previously created by `converse` |
+| **Returns** | `object` | `{ ABC, MNO, XYZ }` or `{}` if invalid |
+
+```js
+const uid = new UUID();
+uid.inverse("c0656612-2e12-4345-8670-000000012345");
+// { ABC: "AB12", MNO: "I1234567", XYZ: "000000012345" }
+```
+
+---
+
+## Quick Usage Examples
+
+```js
+const { date, xml, json, array, UUID } = require('esi-cap').utils;
+
+// Validate & transform
+const valid = await date.isValid("2026-04-20");
+const items = [{ id: 1, name: "A" }, { id: 2, name: "B" }];
+
+// Project, sort, filter
+const names = array.toArrayProjection(items, "name");             // ["A", "B"]
+const sorted = array.sort(items, [{ ref: ["id"], sort: "desc" }]);
+const filtered = array.filter(items, [{ name: "id", op: ">", value: 1 }]);
+
+// Group & merge
+const grouped = array.toGroupByPropertyName(items, "name");
+const merged = json.merge({ a: 1 }, { b: 2 });                    // { a: 1, b: 2 }
+
+// UUID round-trip
+const uid = new UUID();
+const uuidStr = uid.converse({ ABC: "AB12", MNO: "I1234567", XYZ: "000000012345" });
+const original = uid.inverse(uuidStr);
+```