dphelper 3.5.5 → 3.7.2

package/docs/markdown/memory.md

@@ -0,0 +1,85 @@
+# memory
+
+Memory and state management.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `lock` | Lock a state property | `dphelper.memory.lock('state[key]')` |
+| `unlock` | Unlock a state property | `dphelper.memory.unlock('state[key]')` |
+
+## Description
+
+State property protection:
+- **Lock** - Make property non-writable and non-configurable
+- **Unlock** - Restore writability and configurability
+- **Global State** - Work with window-level state objects
+
+## Usage Examples
+
+### Lock State Property
+
+```javascript
+// Define global state
+window.myApp = {
+  config: { theme: 'dark' },
+  user: { name: 'John' }
+};
+
+// Lock the config
+dphelper.memory.lock('myApp.config');
+
+// Try to modify (will fail silently or throw in strict mode)
+myApp.config = {}; // Won't work - locked
+
+// Can still modify properties if not locked
+myApp.config.theme = 'light'; // May work depending on implementation
+```
+
+### Unlock State Property
+
+```javascript
+// Unlock previously locked property
+dphelper.memory.unlock('myApp.config');
+
+// Now can modify
+myApp.config = { theme: 'light' };
+```
+
+### Protect Application State
+
+```javascript
+// Create protected app state
+const appState = {
+  version: '1.0.0',
+  initialized: false,
+  data: {}
+};
+
+// Add to window
+window.appState = appState;
+
+// Lock critical properties
+dphelper.memory.lock('appState.version'); // Prevent version changes
+dphelper.memory.lock('appState.initialized'); // Prevent re-initialization
+
+// Unlock when needed (e.g., updates)
+function updateVersion(newVersion) {
+  dphelper.memory.unlock('appState.version');
+  appState.version = newVersion;
+  dphelper.memory.lock('appState.version');
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20230101
+- **Last Modified:** 20230111
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/navigation.md

@@ -0,0 +1,152 @@
+# navigation
+
+AJAX-based Single Page Application (SPA) navigation engine for seamless page transitions.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `ajax` | Initialize SPA navigation engine | `dphelper.navigation.ajax()` |
+| `load` | Load page via AJAX | `dphelper.navigation.load('/about')` |
+
+## Description
+
+Complete SPA navigation solution:
+- **AJAX Loading** - Load pages without refresh
+- **History Management** - Browser back/forward support
+- **Hash Support** - Scroll to hash elements
+- **XSS Protection** - HTML sanitization
+
+## Usage Examples
+
+### Initialize SPA Navigation
+
+```javascript
+// Initialize on page load
+document.addEventListener('DOMContentLoaded', () => {
+  dphelper.navigation.ajax();
+});
+
+// Now all anchor links will use AJAX navigation
+// <a href="/about">About</a> will load without refresh
+```
+
+### Manual Page Load
+
+```javascript
+// Load a page programmatically
+dphelper.navigation.load('/dashboard');
+
+// Loads /dashboard content into current page
+// Updates browser history
+// Scrolls to top
+
+// With slug normalization
+dphelper.navigation.load('about');     // Loads 'about/'
+dphelper.navigation.load('/contact');  // Loads 'contact/'
+dphelper.navigation.load('home');      // Loads 'home/'
+```
+
+### How It Works
+
+1. **Initialization** - `ajax()` binds all anchor tags
+2. **Click Interception** - Links are converted to AJAX handlers
+3. **Content Loading** - Page content fetched via fetch API
+4. **Content Injection** - Body content replaced (sanitized)
+5. **History Update** - Browser history updated with pushState
+
+### HTML Structure
+
+```html
+<!-- Standard links - automatically handled -->
+<nav>
+  <a href="/">Home</a>
+  <a href="/about">About</a>
+  <a href="/contact">Contact</a>
+</nav>
+
+<!-- Main content area -->
+<main id="app">
+  <!-- Content loaded here -->
+</main>
+```
+
+### Hash Navigation
+
+```html
+<!-- Scroll to element on page -->
+<a href="#section1">Section 1</a>
+
+<!-- Smooth scroll to section -->
+<div id="section1">Content</div>
+```
+
+### Security Features
+
+- **XSS Prevention** - HTML content is sanitized
+- **Same-origin** - Only same-origin URLs allowed
+- **Open Redirect Prevention** - Validates URL origins
+
+## Advanced Usage
+
+### Conditional Navigation
+
+```javascript
+class SPANavigator {
+  constructor() {
+    this.init();
+  }
+
+  init() {
+    dphelper.navigation.ajax();
+  }
+
+  navigate(path) {
+    dphelper.navigation.load(path);
+  }
+
+  // Programmatic navigation
+  goHome() {
+    this.navigate('/');
+  }
+
+  goTo(path) {
+    this.navigate(path);
+  }
+}
+
+const navigator = new SPANavigator();
+```
+
+### Loading State
+
+```javascript
+// The loader is automatically added
+// Customize with CSS:
+/*
+.loader {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: rgba(255,255,255,0.9);
+  z-index: 9999;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+*/
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20260223
+- **Last Modified:** 20260223
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/net.md

@@ -0,0 +1,60 @@
+# net
+
+Resilient networking and fetch utilities.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `smartFetch` | Fetch with automatic retry | `dphelper.net.smartFetch(url, options)` |
+
+## Description
+
+Network communication utilities:
+- **Smart Fetch** - Automatic retry with exponential backoff
+- **Resilience** - Handle transient network errors
+- **Retry Strategy** - Configurable retry attempts and delays
+
+## Usage Examples
+
+### Smart Fetch with Retry
+
+```javascript
+// Basic smart fetch
+const response = await dphelper.net.smartFetch('/api/data');
+const data = await response.json();
+
+// Fetch with options
+const result = await dphelper.net.smartFetch('https://api.example.com', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ key: 'value' })
+});
+```
+
+### API Error Handling
+
+```javascript
+// Robust API calls
+async function fetchUserData(userId) {
+  try {
+    const response = await dphelper.net.smartFetch(`/api/users/${userId}`);
+    return await response.json();
+  } catch (error) {
+    console.error('Failed to fetch user:', error);
+    return null;
+  }
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello & Jo
+- **Version:** 0.0.1
+- **Creation Date:** 20260220
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*

package/docs/markdown/obj.md

@@ -0,0 +1,242 @@
+# obj (objects)
+
+Utilities for JavaScript object manipulation.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `replaceNullObjects` | Replace null values with empty strings | `dphelper.obj.replaceNullObjects(obj)` |
+| `serialize` | Serialize objects preserving functions | `dphelper.obj.serialize(obj)` |
+| `deSerialize` | Deserialize objects by processing values | `dphelper.obj.deSerialize(obj)` |
+| `sort` | Sort object by keys | `dphelper.obj.sort(obj)` |
+| `toXML` | Convert object to XML string | `dphelper.obj.toXML(obj)` |
+| `updateByKey` | Update value if key exists | `dphelper.obj.updateByKey(obj, 'key', 'value')` |
+| `parse` | Safe JSON.parse avoiding crashes | `dphelper.obj.parse(str)` |
+| `isObject` | Check if value is non-null object | `dphelper.obj.isObject(val)` |
+| `diff` | Show differences between two objects | `dphelper.obj.diff(obj1, obj2)` |
+| `path` | Create path string from properties | `dphelper.obj.path('prop', ['a','b'])` |
+| `setProps` | Recursively set property descriptors | `dphelper.obj.setProps(obj, {writable: false})` |
+
+## Description
+
+Advanced JavaScript object manipulation:
+- **Serialization** - Convert objects to JSON/XML, handle functions
+- **Parsing** - Safe JSON parsing with error handling
+- **Comparison** - Find differences between objects
+- **Transformation** - Sort keys, update by key
+- **Property Control** - Set enumerable/writable/configurable
+
+## Usage Examples
+
+### Replace Null Values
+
+```javascript
+// Replace null values with empty strings
+const data = {
+  name: 'John',
+  email: null,
+  phone: null,
+  age: 30
+};
+
+dphelper.obj.replaceNullObjects(data);
+// Now: { name: 'John', email: '', phone: '', age: 30 }
+```
+
+### Object Serialization
+
+```javascript
+// Serialize object (including functions as strings)
+const obj = {
+  name: 'test',
+  method: function() { return 'hello'; },
+  value: 42
+};
+
+const serialized = dphelper.obj.serialize(obj);
+// Functions are converted to toString()
+
+// Deserialize back
+const deserialized = dphelper.obj.deSerialize(serialized);
+```
+
+### Object to XML
+
+```javascript
+// Convert JSON to XML
+const data = {
+  user: {
+    name: 'John',
+    email: 'john@example.com',
+    address: {
+      city: 'NYC',
+      zip: '10001'
+    }
+  }
+};
+
+const xml = dphelper.obj.toXML(data);
+/*
+<user>
+  <name>John</name>
+  <email>john@example.com</email>
+  <address>
+    <city>NYC</city>
+    <zip>10001</zip>
+  </address>
+</user>
+*/
+```
+
+### Safe JSON Parse
+
+```javascript
+// Safe parse - won't crash on invalid JSON
+const validJson = '{"name": "John", "age": 30}';
+const obj = dphelper.obj.parse(validJson);
+// { name: "John", age: 30 }
+
+const invalidJson = 'not valid json';
+const result = dphelper.obj.parse(invalidJson);
+// Returns original string, logs error
+
+// Use for API responses
+function handleApiResponse(response) {
+  return dphelper.obj.parse(response);
+}
+```
+
+### Object Difference
+
+```javascript
+// Find differences between two objects
+const obj1 = {
+  name: 'John',
+  age: 30,
+  city: 'NYC'
+};
+
+const obj2 = {
+  name: 'Jane',
+  age: 30,
+  city: 'LA'
+};
+
+const differences = dphelper.obj.diff(obj1, obj2);
+/*
+{
+  name: { obj1: 'John', obj2: 'Jane' },
+  city: { obj1: 'NYC', obj2: 'LA' }
+}
+*/
+
+// Use in testing
+function assertObjectsEqual(a, b) {
+  const diff = dphelper.obj.diff(a, b);
+  if (Object.keys(diff).length > 0) {
+    console.error('Differences found:', diff);
+    return false;
+  }
+  return true;
+}
+```
+
+### Sort Object Keys
+
+```javascript
+// Sort object alphabetically by keys
+const unsorted = {
+  z: 1,
+  a: 2,
+  m: 5,
+  b: 3
+};
+
+const sorted = dphelper.obj.sort(unsorted);
+// { a: 2, b: 3, m: 5, z: 1 }
+
+// Useful for consistent JSON stringify
+JSON.stringify(dphelper.obj.sort(unsorted));
+```
+
+### Update By Key
+
+```javascript
+// Update value if key exists
+const user = {
+  name: 'John',
+  email: 'john@example.com'
+};
+
+dphelper.obj.updateByKey(user, 'email', 'newemail@example.com');
+// { name: 'John', email: 'newemail@example.com' }
+
+dphelper.obj.updateByKey(user, 'phone', '555-1234');
+// Key doesn't exist, no change
+// { name: 'John', email: 'newemail@example.com' }
+```
+
+### Object Path
+
+```javascript
+// Create dot-notation path
+const path = dphelper.obj.path('name', ['user', 'profile']);
+// "user.profile.name"
+```
+
+### Set Properties
+
+```javascript
+// Make object immutable
+const config = {
+  apiUrl: 'https://api.example.com',
+  timeout: 5000
+};
+
+dphelper.obj.setProps(config, {
+  writable: false,
+  configurable: false
+});
+
+// Now config.apiUrl = 'changed'; // Error in strict mode
+
+// Make all properties non-enumerable
+const data = { a: 1, b: 2, c: 3 };
+dphelper.obj.setProps(data, { enumerable: false });
+
+// for...in won't show these properties
+```
+
+### Is Object Check
+
+```javascript
+// Check if value is a plain object
+console.log(dphelper.obj.isObject({}));           // true
+console.log(dphelper.obj.isObject({ a: 1 }));    // true
+console.log(dphelper.obj.isObject(null));         // false
+console.log(dphelper.obj.isObject([]));          // true (arrays are objects!)
+console.log(dphelper.obj.isObject('string'));     // false
+console.log(dphelper.obj.isObject(123));          // false
+
+// Use in type checking
+function processValue(val) {
+  if (dphelper.obj.isObject(val)) {
+    console.log('Processing object:', val);
+  } else {
+    console.log('Not an object:', typeof val);
+  }
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*

package/docs/markdown/path.md

@@ -0,0 +1,46 @@
+# path
+
+Management of URL paths.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `rail` | Extracts path segments from the URL | `dphelper.path.rail()` |
+| `hash` | Extracts hash from the URL | `dphelper.path.hash([hashUrl])` |
+| `query` | Extracts query parameters from the URL | `dphelper.path.query([queryString])` |
+
+## Description
+
+Tool for extracting segments, hashes, and query parameters from URLs.
+
+## Usage Examples
+
+### Extract URL segments
+
+If the URL is `https://example.com/blog/article-1`, `rail()` will return `['blog', 'article-1']`.
+
+```javascript
+const segments = dphelper.path.rail();
+console.log(segments[0]); // 'blog'
+```
+
+### Extract Query parameters
+
+If the URL is `?id=123&user=dario`, `query()` will return `{"id": "123", "user": "dario"}`.
+
+```javascript
+const params = dphelper.path.query();
+console.log(params.id); // '123'
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20210101
+- **Last Modified:** 20250513
+
+---
+
+*Automatically generated document*

package/docs/markdown/promise.md

@@ -0,0 +1,94 @@
+# promise
+
+Utilities for Promise management.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `check` | Check if value is a Promise | `dphelper.promise.check(value)` |
+
+## Description
+
+Promise utility functions:
+- **Type Check** - Detect if value is a Promise
+- **Cross-Environment** - Works in browser and Node.js
+- **Extended Support** - Checks for Promise-like objects (thenables)
+
+## Usage Examples
+
+### Check if Value is Promise
+
+```javascript
+// Standard Promise
+const promise = fetch('https://api.example.com/data');
+console.log(dphelper.promise.check(promise));
+// true
+
+// Promise created with Promise.resolve
+const resolved = Promise.resolve('data');
+console.log(dphelper.promise.check(resolved));
+// true
+
+// Thenable (Promise-like object)
+const thenable = { then: (resolve) => resolve('data') };
+console.log(dphelper.promise.check(thenable));
+// true
+
+// Regular value
+console.log(dphelper.promise.check('hello'));
+// false
+
+console.log(dphelper.promise.check(123));
+// false
+
+console.log(dphelper.promise.check({}));
+// false
+```
+
+### Safe Promise Handling
+
+```javascript
+// Handle both Promise and non-Promise values
+async function processValue(value) {
+  if (dphelper.promise.check(value)) {
+    return await value;
+  }
+  return value;
+}
+
+// Use in generic functions
+function handleResult(result) {
+  if (dphelper.promise.check(result)) {
+    result.then(data => console.log('Async:', data));
+  } else {
+    console.log('Sync:', result);
+  }
+}
+```
+
+### Type Guard for TypeScript
+
+```javascript
+// Type guard usage
+function logValue(val: any) {
+  if (dphelper.promise.check(val)) {
+    // TypeScript knows val is Promise here
+    val.then(data => console.log('Resolved:', data));
+  } else {
+    console.log('Value:', val);
+  }
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*