dphelper 3.2.2 → 3.2.5

package/docs/SUMMARY.md

@@ -0,0 +1,54 @@
+# Table of contents
+
+* [dpHelper](../README.md)
+
+## General
+
+## Tools
+
+* [anchor](tools/anchor.md)
+* [ai](tools/ai.md)
+* [array](tools/array.md)
+* [audio](tools/audio.md)
+* [avoid](tools/avoid.md)
+* [browser](tools/browser.md)
+* [check](tools/check.md)
+* [color](tools/color.md)
+* [cookie](tools/cookie.md)
+* [coords](tools/coords.md)
+* [credits](tools/credits.md)
+* [date](tools/date.md)
+* [disable](tools/disable.md)
+* [dispatch](tools/dispatch.md)
+* [element](tools/element.md)
+* [event](tools/event.md)
+* [form](tools/form.md)
+* [format](tools/format.md)
+* [json](tools/json.md)
+* [load](tools/load.md)
+* [logging](tools/logging.md)
+* [math](tools/math.md)
+* [memory](tools/memory.md)
+* [navigation](tools/navigation.md)
+* [net](tools/net.md)
+* [obj](tools/obj.md)
+* [path](tools/path.md)
+* [promise](tools/promise.md)
+* [sanitize](tools/sanitize.md)
+* [screen](tools/screen.md)
+* [scrollbar](tools/scrollbar.md)
+* [security](tools/security.md)
+* [shortcut](tools/shortcut.md)
+* [socket](tools/socket.md)
+* [svg](tools/svg.md)
+* [sync](tools/sync.md)
+* [system](tools/system.md)
+* [terminal](tools/terminal.md)
+* [text](tools/text.md)
+* [timer](tools/timer.md)
+* [tools](tools/tools.md)
+* [translators](tools/translators.md)
+* [trigger](tools/trigger.md)
+* [type](tools/type.md)
+* [ui](tools/ui.md)
+* [window](tools/window.md)

package/docs/tools/ai.md

@@ -0,0 +1,25 @@
+# ai
+
+AI-related utilities and LLM helpers.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `tokenCount` | Estimates token count for LLMs (approx 4 chars/token) | `dphelper.ai.tokenCount(text)` |
+| `smartSanitize` | Removes PII (emails, phones, CC) for AI privacy | `dphelper.ai.smartSanitize(text)` |
+
+## Description
+
+The AI module provides lightweight helpers to interact with LLMs, including privacy sanitization and token estimation to optimize API costs and security.
+
+## Details
+
+- **Author:** Dario Passariello & Jo
+- **Version:** 0.0.1
+- **Creation Date:** 20260220
+- **Last Modified:** 20260220
+
+---
+
+*Automatically generated document*

package/docs/tools/anchor.md

@@ -0,0 +1,33 @@
+# anchor
+
+Tool for managing HTML links and converting them into onclick events.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `toOnClick` | Converts all links in an element into onclick events | `dphelper.anchor.toOnClick('#container')` |
+
+## Description
+
+This tool allows you to convert all links in an element into 'onclick'. Useful for working with SPAs while maintaining full compatibility with all browsers.
+
+## Usage Examples
+
+### Automatic link conversion
+
+```javascript
+// Converts all links in the #main-content div
+dphelper.anchor.toOnClick('#main-content');
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/array.md

@@ -0,0 +1,36 @@
+# array
+
+Advanced utilities for JavaScript array manipulation.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `find` | Finds an element recursively | `dphelper.array.find(array, 'key')` |
+| `delete` | Deletes an element recursively by key | `dphelper.array.delete(array, 'key')` |
+| `merge` | Merges two objects/arrays recursively | `dphelper.array.merge(arrA, arrB)` |
+| `mergeByKey` | Merges two arrays of objects via a specific key | `dphelper.array.mergeByKey(arrA, arrB, 'id')` |
+| `duplicates` | Finds duplicate elements in an array | `dphelper.array.duplicates(array)` |
+| `even` / `odd` | Filters even or odd numbers | `dphelper.array.even(array)` |
+| `sumColumn` | Sums values of a column in a multidimensional array | `dphelper.array.sumColumn(arr, 0)` |
+| `shuffle` | Randomly shuffles elements | `dphelper.array.shuffle(array)` |
+| `generate` | Generates an array of random numbers | `dphelper.array.generate(10)` |
+| `testArrayInt` | Checks for missing numbers in a sequence | `dphelper.array.testArrayInt([1,2,4])` |
+| `rand32` | Generates an array of random 32-bit integers | `dphelper.array.rand32(5)` |
+| `match` | Finds intersections between two arrays of words | `dphelper.array.match(arrA, arrB)` |
+| `pathToJson` | Converts an array of paths into a JSON object | `dphelper.array.pathToJson(paths, '/')` |
+
+## Description
+
+Tool for advanced array manipulation. Native functions (such as `unique` via Set, `sort`, or `structuredClone`) have been removed to encourage the use of modern JavaScript APIs.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+
+---
+
+*Automatically generated document*

package/docs/tools/audio.md

@@ -0,0 +1,30 @@
+# audio
+
+Management of audio playback in web pages.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `play` | Plays an audio file or stops existing ones | `dphelper.audio.play('sound.mp3')` |
+
+## Description
+
+Plays an audio file if it is not already playing. If called without arguments, it stops and removes **only** the audio elements previously created by `dphelper`, protecting other players on the page.
+
+## Parameters
+
+- `file` - (Optional) Name of the audio file. If omitted, cleans up its own audio elements.
+- `path` - File path (default: "").
+- `loop` - Continuous playback (default: false).
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20240924
+- **Last Modified:** 20260220
+
+---
+
+*Automatically generated document*

package/docs/tools/avoid.md

@@ -0,0 +1,28 @@
+# avoid
+
+Utilities for preventing browser caching.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `cache` | Adds a cache-busting parameter to the URI | `dphelper.avoid.cache(uri)` |
+
+## Description
+
+Appends a unique query parameter to a given URI to prevent the browser from using a cached version of the resource.
+
+## Parameters
+
+- `uri` - The URI to which the cache-busting parameter will be added.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/browser.md

@@ -0,0 +1,45 @@
+# browser
+
+Functionality for navigation and browser state.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `state` | Pushes a new state to the history | `dphelper.browser.state([state, title, url])` |
+| `forw` | Moves forward in the history | `dphelper.browser.forw([number])` |
+| `back` | Moves backward in the history | `dphelper.browser.back([number])` |
+| `reload` | Reloads the page | `dphelper.browser.reload()` |
+| `href` | Navigates to a URL | `dphelper.browser.href()` |
+| `offLine` | Shows an offline message | `dphelper.browser.offLine()` |
+| `zoom` | Returns the zoom level | `dphelper.browser.zoom()` |
+| `status` | Returns a description of the HTTP status | `dphelper.browser.status()` |
+
+## Description
+
+A complete tool for managing browser navigation, including history, URLs, and connection status.
+
+## Usage Examples
+
+### Change URL without reloading
+
+```javascript
+dphelper.browser.state({ id: 1 }, "Page Title", "/new-url");
+```
+
+### Forced navigation
+
+```javascript
+dphelper.browser.href("https://google.com");
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/check.md

@@ -0,0 +1,24 @@
+# check
+
+Validation and check utilities.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `version` | Compares two version strings | `dphelper.check.version([v1], [v2], [opts])` |
+
+## Description
+
+Tool for validating versions and performing other checks.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20240829
+- **Last Modified:** 20240829
+
+---
+
+*Automatically generated document*

package/docs/tools/color.md

@@ -0,0 +1,28 @@
+# color
+
+Utilities for color conversion and management.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `hex` | Converts a number (0-255) into a two-digit hexadecimal string | `dphelper.color.hex(255)` |
+| `toHex` | Converts an RGB array to a hexadecimal string | `dphelper.color.toHex([255, 0, 0])` |
+| `toRGB` | Converts a hexadecimal string to an RGB array | `dphelper.color.toRGB('#FF0000')` |
+| `oleColor` | Converts a hex color to OLE decimal format (used in legacy Windows) | `dphelper.color.oleColor('#FFFFFF')` |
+| `gradient` | Generates a color scale (array) between two shades | `dphelper.color.gradient('#000', '#FFF', 10)` |
+
+## Description
+
+Tool for conversion between different color formats. Hexadecimal conversion logic has been modernized using native JavaScript methods.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+
+---
+
+*Automatically generated document*

package/docs/tools/cookie.md

@@ -0,0 +1,27 @@
+# cookie
+
+Management of browser cookies.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `set` | Creates a cookie with specified properties | `dphelper.cookie.set({name, value, time, path = '/'})` |
+| `get` | Retrieves the value of a cookie | `dphelper.cookie.get(name)` |
+| `delete` | Deletes a specific cookie | `dphelper.cookie.delete(name)` |
+| `removeAll` | Removes all cookies | `dphelper.cookie.removeAll()` |
+
+## Description
+
+Complete tool for cookie management: creation, reading, and deletion.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20240613
+
+---
+
+*Automatically generated document*

package/docs/tools/coords.md

@@ -0,0 +1,28 @@
+# coords
+
+Utilities for geographic calculations, coordinate conversions, and spatial mappings.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `degreesToRadians` | Converts degrees to radians | `dphelper.coords.degreesToRadians(180)` |
+| `latToMeters` | Approximates conversion from latitude to meters | `dphelper.coords.latToMeters([lat, lng])` |
+| `distance` | Calculates distance between two points (Haversine) in Km, Mi, and NMi | `dphelper.coords.distance(p1, p2)` |
+| `polarToCartesian` | Converts polar coordinates to Cartesian (X, Y) | `dphelper.coords.polarToCartesian(cx, cy, r, angle)` |
+| `mapDegreesToPixels` | Maps geographic degrees to pixel coordinates with padding | `dphelper.coords.mapDegreesToPixels(deg, min, max, pMin, pMax, pad)` |
+
+## Description
+
+Specialized tool for trigonometric and geographic calculations. Mapping formulas (pixel/degrees) have been optimized and commented for better readability and geometric precision.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+
+---
+
+*Automatically generated document*

package/docs/tools/credits.md

@@ -0,0 +1,28 @@
+# credits
+
+Log project information to the console.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `credits` | Logs project properties | `dphelper.credits(props)` |
+
+## Description
+
+Logs various properties about a project to the console in a formatted manner.
+
+## Parameters
+
+- `props` - The project properties (name, version, description, license, author, email).
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/date.md

@@ -0,0 +1,44 @@
+# date
+
+Advanced utilities for date management.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `toIso` | Converts a date to ISO format | `dphelper.date.toIso([value, int = 'en'])` |
+| `toMMDDYYYY` | Converts to MMDDYYYY format | `dphelper.date.toMMDDYYYY([value])` |
+| `toYYYYMMDD` | Converts to YYYYMMDD format | `dphelper.date.toYYYYMMDD([value])` |
+| `toHuman` | Converts to a human-readable format | `dphelper.date.toHuman([value])` |
+| `convert` | Converts dates between formats | `dphelper.date.convert()` |
+
+## Description
+
+Complete tool for converting and formatting dates in various formats.
+
+## Usage Examples
+
+### Database Format
+
+```javascript
+const dbDate = dphelper.date.toYYYYMMDD(new Date());
+console.log(dbDate); // '20260223'
+```
+
+### Human-Readable Format
+
+```javascript
+const humanDate = dphelper.date.toHuman("20260223");
+console.log(humanDate); // '23 February 2026' (depends on locale)
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20230101
+
+---
+
+*Automatically generated document*

package/docs/tools/disable.md

@@ -0,0 +1,28 @@
+# disable
+
+Disabling browser functionalities on DOM elements.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `select` | Disables text selection | `dphelper.disable.select([el = 'body'])` |
+| `spellCheck` | Disables spell checking | `dphelper.disable.spellCheck([tmr = 5000])` |
+| `rightClick` | Disables the context menu | `dphelper.disable.rightClick([el = 'body'])` |
+| `copy` | Disables copy functionality | `dphelper.disable.copy([el = 'body'])` |
+| `paste` | Disables paste functionality | `dphelper.disable.paste([el = 'body'])` |
+
+## Description
+
+Tool for disabling browser features on specific elements: text selection, copy, paste, right-click, and spell-check.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/dispatch.md

@@ -0,0 +1,26 @@
+# dispatch
+
+Custom event dispatching system.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `set` | Dispatches a custom event | `dphelper.dispatch.set([name, value])` |
+| `listen` | Listens for specified events | `dphelper.dispatch.listen([eventNames, callback=null], flag = true)` |
+| `remove` | Removes an event listener | `dphelper.dispatch.remove([eventNames, callback=null], flag = true)` |
+
+## Description
+
+Tool for managing custom events: dispatch, listen, and remove.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20231231
+- **Last Modified:** 20240612
+
+---
+
+*Automatically generated document*

package/docs/tools/element.md

@@ -0,0 +1,25 @@
+# element
+
+Advanced manipulation of DOM elements.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `fitScale` | Scales an element based on the window | `dphelper.element.fitScale([el = 'root', scale = 1, fit = false])` |
+| `scaleBasedOnWindow` | Scales based on window dimensions | `dphelper.element.scaleBasedOnWindow(elm, scale, fit)` |
+
+## Description
+
+Tool for responsive scaling of DOM elements based on window size.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20230527
+- **Last Modified:** 20230527
+
+---
+
+*Automatically generated document*

package/docs/tools/event.md

@@ -0,0 +1,27 @@
+# event
+
+Advanced management of DOM events.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `list` | Lists attached events | `dphelper.event.list([element])` |
+| `multi` | Attaches multiple event listeners | `dphelper.event.multi([element, eventNames, listener])` |
+| `copy` | Copies content to clipboard | `dphelper.event.copy([element])` |
+| `onDrag` | Manages drag functionality | `dphelper.event.onDrag([element])` |
+
+## Description
+
+Tool for advanced event management: event listing, multiple listeners, and drag-and-drop support.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/form.md

@@ -0,0 +1,49 @@
+# form
+
+Complete management of HTML forms.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `serialize` | Serializes form into an object | `dphelper.form.serialize([form])` |
+| `confirmType` | Confirms the type of a value | `dphelper.form.confirmType([type, value])` |
+| `required` | Checks if a value is required | `dphelper.form.required([value])` |
+| `minLength` | Checks minimum length | `dphelper.form.minLength([value, num = 1])` |
+| `maxLength` | Checks maximum length | `dphelper.form.maxLength([value, num = 1])` |
+
+## Description
+
+Complete tool for form management: serialization, validation, and field control.
+
+## Usage Examples
+
+### Serialize a Form
+
+```javascript
+const formData = dphelper.form.serialize('#my-form');
+console.log(formData.email); // 'user@email.com'
+```
+
+### Quick Validation
+
+```javascript
+if (!dphelper.form.required(input.value)) {
+    console.error("Required field!");
+}
+
+if (!dphelper.form.minLength(password.value, 8)) {
+    console.warn("Password too short.");
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/format.md

@@ -0,0 +1,25 @@
+# format
+
+Utilities for data formatting.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `currency` | Formats a number as currency | `dphelper.format.currency(value, locale, currency)` |
+| `phoneNumber` | Formats a string as a phone number | `dphelper.format.phoneNumber(value, countryCode)` |
+
+## Description
+
+Tool for formatting currencies and phone numbers.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20210101
+
+---
+
+*Automatically generated document*

package/docs/tools/json.md

@@ -0,0 +1,28 @@
+# json
+
+Utilities for JSON data manipulation.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `is` | Verifies if a string is a valid JSON | `dphelper.json.is(str)` |
+| `sanitize` | Attempts to fix and normalize malformed JSON strings | `dphelper.json.sanitize(str)` |
+| `toCsv` | Converts an array of objects to CSV format | `dphelper.json.toCsv(data)` |
+| `saveCsvAs` | Generates and downloads a CSV file from provided data | `dphelper.json.saveCsvAs(csv, 'file.csv')` |
+| `counter` | Counts occurrences of keys/values in a structure | `dphelper.json.counter(data)` |
+
+## Description
+
+Tool for JSON manipulation: safe parsing, normalization of dirty data (via `sanitize`), CSV conversions, and validation.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+
+---
+
+*Automatically generated document*

package/docs/tools/load.md

@@ -0,0 +1,26 @@
+# load
+
+Asynchronous resource loading.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `all` | Loads all files from a directory context | `dphelper.load.all(require.context('Scripts', true, /\.(js|ts)$/) [, 'cacheName'])` |
+| `file` | Loads a specific file | `dphelper.load.file(filePath)` |
+| `fileToElement` | Loads a file and inserts it into an element | `dphelper.load.fileToElement(filePath, elementSelector)` |
+
+## Description
+
+Tool for asynchronous loading of files and resources: scripts, files, and HTML content.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20240101
+
+---
+
+*Automatically generated document*