dphelper 4.2.0 → 4.2.3

package/markdown/array.md

@@ -1,208 +0,0 @@
-# array
-
-Advanced utilities for JavaScript array manipulation with support for nested structures, merging, filtering, and more.
-
-## Functions
-
-| Function | Description | Example |
-|----------|-------------|---------|
-| `find` | Finds an element recursively in nested arrays | `dphelper.array.find(array, 'key')` |
-| `delete` | Deletes an element recursively by key | `dphelper.array.delete(array, 'key')` |
-| `merge` | Deep merges two objects/arrays (safe from prototype pollution) | `dphelper.array.merge(arrA, arrB)` |
-| `mergeByKey` | Merges two arrays of objects via a specific key | `dphelper.array.mergeByKey(arrA, arrB, 'id')` |
-| `unique` | Removes duplicate values from an array | `dphelper.array.unique(array)` |
-| `asc` | Sorts array in ascending order | `dphelper.array.asc(array)` |
-| `desc` | Sorts array in descending order | `dphelper.array.desc(array)` |
-| `duplicates` | Finds duplicate elements in an array | `dphelper.array.duplicates(array)` |
-| `even` | Filters even numbers from an array | `dphelper.array.even(array)` |
-| `odd` | Filters odd numbers from an array | `dphelper.array.odd(array)` |
-| `toObj` | Converts an array to an object | `dphelper.array.toObj(array)` |
-| `sumColumn` | Sums values of a column in a multidimensional array | `dphelper.array.sumColumn(arr, 0)` |
-| `shuffle` | Randomly shuffles elements (Fisher-Yates algorithm) | `dphelper.array.shuffle(array)` |
-| `generate` | Generates an array of random numbers (1 to n) | `dphelper.array.generate(10)` |
-| `testArrayInt` | Checks for missing numbers in a consecutive sequence | `dphelper.array.testArrayInt([1,2,4])` |
-| `rand32` | Generates an array of random 32-bit unsigned integers | `dphelper.array.rand32(5)` |
-| `findindex` | Finds the index of an element by key | `dphelper.array.findindex(array, 'name')` |
-| `pathToJson` | Converts an array of paths into a JSON object | `dphelper.array.pathToJson(paths, '/')` |
-| `deepClone` | Creates a deep clone using structuredClone | `dphelper.array.deepClone(array)` |
-| `match` | Finds intersection between two arrays | `dphelper.array.match(arrA, arrB)` |
-
-## Description
-
-Comprehensive array manipulation library that provides utilities for:
-- **Recursive operations** - Find, delete in nested structures
-- **Merging** - Deep merge with prototype pollution protection
-- **Filtering** - Even/odd numbers, duplicates
-- **Sorting** - Ascending/descending order
-- **Generation** - Random numbers, sequences
-- **Conversion** - Array to object, paths to JSON
-
-## Usage Examples
-
-### Finding Elements in Nested Arrays
-
-```javascript
-const data = [
-  { id: 1, name: 'John', children: [{ id: 2, name: 'Jane' }] },
-  { id: 3, name: 'Bob', children: [{ id: 4, name: 'Alice' }] }
-];
-
-// Find element with id 2
-const found = dphelper.array.find(data, 2);
-console.log(found); // { id: 2, name: 'Jane' }
-```
-
-### Deep Merging Objects
-
-```javascript
-const obj1 = { a: 1, b: { c: 2 } };
-const obj2 = { b: { d: 3 }, e: 4 };
-
-const merged = dphelper.array.merge(obj1, obj2);
-console.log(merged); // { a: 1, b: { c: 2, d: 3 }, e: 4 }
-
-// Safe from prototype pollution
-const dangerous = { '__proto__': { dangerous: true } };
-const safe = dphelper.array.merge({}, dangerous);
-console.log(safe); // { __proto__: { dangerous: true } } - safe!
-```
-
-### Merging Arrays by Key
-
-```javascript
-const users = [
-  { id: 1, name: 'John', age: 30 },
-  { id: 2, name: 'Jane', age: 25 }
-];
-
-const details = [
-  { id: 1, email: 'john@example.com' },
-  { id: 2, email: 'jane@example.com' }
-];
-
-const merged = dphelper.array.mergeByKey(users, details, 'id');
-// Result: [{ id: 1, name: 'John', age: 30, email: 'john@example.com' }, ...]
-```
-
-### Finding Duplicates
-
-```javascript
-const numbers = [1, 2, 3, 2, 4, 3, 5, 1];
-const dups = dphelper.array.duplicates(numbers);
-console.log(dups); // [2, 3, 1]
-```
-
-### Filtering Even/Odd Numbers
-
-```javascript
-const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
-
-console.log(dphelper.array.even(numbers)); // [2, 4, 6, 8, 10]
-console.log(dphelper.array.odd(numbers));   // [1, 3, 5, 7, 9]
-```
-
-### Sum Column in Multidimensional Array
-
-```javascript
-const matrix = [
-  [1, 2, 3],  // row 0
-  [4, 5, 6],  // row 1
-  [7, 8, 9]   // row 2
-];
-
-// Sum first column (index 0)
-console.log(dphelper.array.sumColumn(matrix, 0)); // 12 (1+4+7)
-
-// Sum second column (index 1)
-console.log(dphelper.array.sumColumn(matrix, 1)); // 15 (2+5+8)
-```
-
-### Shuffle Array (Fisher-Yates)
-
-```javascript
-const cards = ['A', 'B', 'C', 'D', 'E'];
-const shuffled = dphelper.array.shuffle([...cards]);
-console.log(shuffled); // Random order, e.g., ['C', 'A', 'E', 'D', 'B']
-```
-
-### Generate Random Number Sequence
-
-```javascript
-// Generate numbers 1-10 in random order
-const sequence = dphelper.array.generate(10);
-console.log(sequence); // e.g., [3, 1, 8, 5, 2, 9, 4, 7, 6, 10]
-```
-
-### Test for Consecutive Integers
-
-```javascript
-// Check for missing numbers in sequence [1, 2, 3, 4, 5]
-console.log(dphelper.array.testArrayInt([1, 2, 3, 4, 5])); // [] (complete)
-
-// Check for missing numbers in [1, 2, 4, 5]
-console.log(dphelper.array.testArrayInt([1, 2, 4, 5]));    // [3] (missing 3)
-```
-
-### Generate Random 32-bit Integers
-
-```javascript
-const randomNumbers = dphelper.array.rand32(5);
-console.log(randomNumbers.nums);   // [random1, random2, random3, random4, random5]
-console.log(randomNumbers.time);  // [execution time in ms]
-```
-
-### Path to JSON Conversion
-
-```javascript
-const paths = [
-  '/users/John',
-  '/users/John/profile',
-  '/users/John/settings',
-  '/users/Jane'
-];
-
-const json = dphelper.array.pathToJson(paths, '/');
-// Result:
-// {
-//   users: {
-//     John: {
-//       profile: null,
-//       settings: null
-//     },
-//     Jane: null
-//   }
-// }
-```
-
-### Deep Clone Array
-
-```javascript
-const original = [{ a: 1 }, { b: 2 }];
-const cloned = dphelper.array.deepClone(original);
-
-cloned[0].a = 99;
-console.log(original[0].a); // 1 (original unchanged)
-console.log(cloned[0].a);   // 99
-```
-
-### Find Array Intersection
-
-```javascript
-const words = ['apple', 'banana', 'cherry', 'date'];
-const check = ['banana', 'date', 'elderberry'];
-
-const matches = dphelper.array.match(words, check);
-console.log(matches); // ['banana', 'date']
-```
-
-## Details
-
-- **Author:** Dario Passariello
-- **Version:** 0.0.2
-- **Creation Date:** 20210101
-- **Last Modified:** 20260220
-- **Environment:** Works in both client and server environments
-
----
-
-*Automatically generated document*

package/markdown/audio.md

@@ -1,113 +0,0 @@
-# audio
-
-Audio playback utilities for managing sound effects and background music in web applications.
-
-## Functions
-
-| Function | Description | Example |
-|----------|-------------|---------|
-| `play` | Plays an audio file or removes all audio elements | `dphelper.audio.play('notification.mp3', '/sounds/')` |
-
-## Description
-
-Simple audio management for web applications:
-- **Play Sound** - Load and play audio files with optional looping
-- **Stop All** - Remove all dpHelper audio elements from the DOM
-- **Multiple Sounds** - Play different sounds simultaneously (each gets unique ID)
-
-## Usage Examples
-
-### Playing Sound Effects
-
-```javascript
-// Play a simple notification sound
-dphelper.audio.play('notification.mp3');
-
-// Play with custom path
-dphelper.audio.play('click.mp3', '/assets/sounds/');
-
-// Loop background music
-dphelper.audio.play('music.mp3', '/assets/audio/', true);
-```
-
-### Stopping Audio
-
-```javascript
-// Stop all dpHelper audio elements
-dphelper.audio.play();
-
-// This removes all audio tags created by dphelper.audio
-```
-
-### Complete Example
-
-```javascript
-// Sound manager class
-class SoundManager {
-  constructor(soundPath = '/sounds/') {
-    this.path = soundPath;
-    this.enabled = true;
-  }
-
-  playSound(name, loop = false) {
-    if (!this.enabled) return;
-    dphelper.audio.play(name, this.path, loop);
-  }
-
-  stopAll() {
-    dphelper.audio.play(); // No args = remove all
-  }
-
-  toggle(enabled) {
-    this.enabled = enabled;
-    if (!enabled) this.stopAll();
-  }
-}
-
-// Usage
-const sounds = new SoundManager('/assets/sounds/');
-
-// Play various sounds
-sounds.playSound('click.mp3');
-sounds.playSound('notification.mp3');
-sounds.playSound('background.mp3', true); // Loop
-
-// Mute all
-sounds.toggle(false);
-
-// Unmute
-sounds.toggle(true);
-```
-
-### UI Sound Effects
-
-```javascript
-// Add sounds to UI interactions
-document.querySelectorAll('button').forEach(btn => {
-  btn.addEventListener('click', () => {
-    dphelper.audio.play('click.mp3', '/sounds/');
-  });
-});
-
-// Form submission
-document.querySelector('form').addEventListener('submit', () => {
-  dphelper.audio.play('success.mp3', '/sounds/');
-});
-
-// Error handling
-function showError() {
-  dphelper.audio.play('error.mp3', '/sounds/');
-}
-```
-
-## Details
-
-- **Author:** Dario Passariello
-- **Version:** 0.0.2
-- **Creation Date:** 20240924
-- **Last Modified:** 20240924
-- **Environment:** Client-side only (browser)
-
----
-
-*Automatically generated document*

package/markdown/avoid.md

@@ -1,53 +0,0 @@
-# avoid
-
-Utilities for preventing caching issues in web applications.
-
-## Functions
-
-| Function | Description | Example |
-|----------|-------------|---------|
-| `cache` | Appends cache-busting query parameter to URL | `dphelper.avoid.cache('/api/data')` |
-
-## Description
-
-Prevents browser caching issues:
-- **Cache Busting** - Add unique query params to URLs
-
-## Usage Examples
-
-### Cache Busting
-
-```javascript
-// Add unique query parameter to prevent caching
-const url = '/api/users';
-const uncachedUrl = dphelper.avoid.cache(url);
-console.log(uncachedUrl); // "/api/users?t=abc123xyz"
-
-// Useful for:
-// - API calls that need fresh data
-// - Dynamic content
-// - Debugging (force reload)
-dphelper.avoid.cache('/api/latest-data');
-```
-
-### Using with Fetch
-
-```javascript
-// Fetch with cache busting
-async function fetchFresh(url) {
-  const response = await fetch(dphelper.avoid.cache(url));
-  return response.json();
-}
-```
-
-## Details
-
-- **Author:** Dario Passariello
-- **Version:** 0.0.2
-- **Creation Date:** 20210101
-- **Last Modified:** 20260220
-- **Environment:** Works in both client and server environments
-
----
-
-*Automatically generated document*

package/markdown/biometric.md

@@ -1,338 +0,0 @@
-# biometric
-
-WebAuthn and biometric authentication utilities for secure passwordless login using fingerprint, face recognition, and hardware security keys.
-
-## Functions
-
-| Function | Description | Example |
-|----------|-------------|---------|
-| `isAvailable` | Check if WebAuthn is available | `dphelper.biometric.isAvailable()` |
-| `getWebAuthnSupport` | Get detailed support info | `dphelper.biometric.getWebAuthnSupport()` |
-| `isSensorAvailable` | Check specific sensor (fingerprint/face/iris) | `await dphelper.biometric.isSensorAvailable('fingerprint')` |
-| `register` | Register new credential | `await dphelper.biometric.register('user123', 'example.com')` |
-| `authenticate` | Authenticate with credential | `await dphelper.biometric.authenticate('user123', 'example.com')` |
-| `getCredential` | Get stored credential by ID | `dphelper.biometric.getCredential(credentialId)` |
-| `deleteCredential` | Delete stored credential | `dphelper.biometric.deleteCredential(credentialId)` |
-| `listCredentials` | List all stored credentials | `dphelper.biometric.listCredentials()` |
-
-## Description
-
-Secure biometric authentication module providing:
-- **WebAuthn/FIDO2** - Industry-standard passwordless authentication
-- **Platform Authenticators** - Fingerprint, Face ID, Windows Hello
-- **Cross-platform** - Works with hardware security keys (YubiKey, etc.)
-- **Credential Management** - Store, retrieve, and delete credentials
-- **Sensor Detection** - Check availability of specific biometric types
-
-## Usage Examples
-
-### Checking Availability
-
-```javascript
-// Simple availability check
-if (dphelper.biometric.isAvailable()) {
-  console.log('Biometric authentication is available!');
-} else {
-  console.log('Biometric auth not supported');
-}
-
-// Get detailed support information
-const support = dphelper.biometric.getWebAuthnSupport();
-console.log(support);
-// {
-//   supported: true,
-//   platformAuthenticator: true,
-//   hybridTransport: false,
-//   uvToken: false
-// }
-
-// Check specific sensor
-const hasFingerprint = await dphelper.biometric.isSensorAvailable('fingerprint');
-const hasFace = await dphelper.biometric.isSensorAvailable('face');
-console.log('Fingerprint:', hasFingerprint, 'Face:', hasFace);
-```
-
-### Registration (Enrolling a Credential)
-
-```javascript
-// Register a new biometric credential
-async function registerUser(userId) {
-  if (!dphelper.biometric.isAvailable()) {
-    return { success: false, error: 'WebAuthn not supported' };
-  }
-
-  const result = await dphelper.biometric.register(
-    userId,           // User ID
-    'example.com',   // Relying Party ID (your domain)
-    'My App',        // Relying Party Name
-    'john@example.com' // Display name
-  );
-
-  if (result.success) {
-    console.log('Registered! Credential ID:', result.credentialId);
-    // Store credentialId in your database for this user
-  } else {
-    console.error('Registration failed:', result.error);
-  }
-
-  return result;
-}
-
-// Usage
-const result = await registerUser('user_123');
-```
-
-### Authentication (Login)
-
-```javascript
-// Authenticate with stored credential
-async function loginUser(userId, credentialId) {
-  if (!dphelper.biometric.isAvailable()) {
-    return { success: false, error: 'WebAuthn not supported' };
-  }
-
-  const result = await dphelper.biometric.authenticate(
-    userId,           // User ID
-    'example.com',   // Relying Party ID
-    credentialId     // Optional: specific credential to use
-  );
-
-  if (result.success) {
-    console.log('Authentication successful!');
-  } else {
-    console.error('Authentication failed:', result.error);
-  }
-
-  return result;
-}
-
-// Usage - login with known credential
-const result = await loginUser('user_123', 'stored_credential_id');
-```
-
-### Credential Management
-
-```javascript
-// List all stored credentials
-const credentials = dphelper.biometric.listCredentials();
-console.log('Stored credentials:', credentials);
-
-// Get a specific credential
-const cred = dphelper.biometric.getCredential('credential_id_123');
-console.log('Credential:', cred);
-
-// Delete a credential
-const deleted = dphelper.biometric.deleteCredential('credential_id_123');
-console.log('Deleted:', deleted);
-
-// After deletion
-console.log('Remaining:', dphelper.biometric.listCredentials());
-```
-
-## Advanced Usage
-
-### Complete Authentication System
-
-```javascript
-class BiometricAuth {
-  constructor(rpId, rpName) {
-    this.rpId = rpId;
-    this.rpName = rpName;
-    this.available = dphelper.biometric.isAvailable();
-  }
-
-  async checkSupport() {
-    if (!this.available) {
-      return { supported: false, reason: 'WebAuthn not supported' };
-    }
-
-    const support = dphelper.biometric.getWebAuthnSupport();
-    const fingerprint = await dphelper.biometric.isSensorAvailable('fingerprint');
-    const face = await dphelper.biometric.isSensorAvailable('face');
-
-    return {
-      supported: true,
-      platformAuthenticator: support.platformAuthenticator,
-      fingerprint,
-      face
-    };
-  }
-
-  async register(userId, userName) {
-    if (!this.available) {
-      throw new Error('Biometric authentication not available');
-    }
-
-    const result = await dphelper.biometric.register(
-      userId,
-      this.rpId,
-      this.rpName,
-      userName
-    );
-
-    if (result.success) {
-      // In production: save credentialId to your backend
-      console.log('Biometric registered:', result.credentialId);
-    }
-
-    return result;
-  }
-
-  async login(userId, credentialId) {
-    if (!this.available) {
-      throw new Error('Biometric authentication not available');
-    }
-
-    return await dphelper.biometric.authenticate(
-      userId,
-      this.rpId,
-      credentialId
-    );
-  }
-
-  getStoredCredentials() {
-    return dphelper.biometric.listCredentials();
-  }
-
-  removeCredential(credentialId) {
-    return dphelper.biometric.deleteCredential(credentialId);
-  }
-}
-
-// Usage
-const auth = new BiometricAuth('example.com', 'My Application');
-
-// Check if biometric is available
-const support = await auth.checkSupport();
-if (support.supported) {
-  console.log('Biometric types available:', support);
-}
-
-// Register new user
-await auth.register('user_123', 'john@example.com');
-
-// Login
-const loginResult = await auth.login('user_123');
-if (loginResult.success) {
-  console.log('Logged in with biometric!');
-}
-```
-
-### Passwordless Login Flow
-
-```javascript
-// Frontend: Initiate passwordless login
-async function initiatePasswordlessLogin() {
-  // 1. Check if biometric is available
-  if (!dphelper.biometric.isAvailable()) {
-    alert('Please use a supported browser');
-    return;
-  }
-
-  // 2. Get available credentials for this user
-  const credentials = dphelper.biometric.listCredentials();
-
-  if (credentials.length === 0) {
-    // No credentials - prompt to register
-    const register = confirm('No biometric credentials found. Register now?');
-    if (register) {
-      await registerNewUser();
-    }
-    return;
-  }
-
-  // 3. Attempt authentication with any stored credential
-  for (const credId of credentials) {
-    const result = await dphelper.biometric.authenticate(
-      'current_user',
-      window.location.hostname,
-      credId
-    );
-
-    if (result.success) {
-      // 4. Verify with server
-      await verifyWithServer(credId);
-      return;
-    }
-  }
-
-  console.log('All credentials failed');
-}
-
-// Server verification (pseudo-code)
-async function verifyWithServer(credentialId) {
-  const response = await fetch('/api/auth/verify', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ credentialId })
-  });
-
-  if (response.ok) {
-    const { token } = await response.json();
-    localStorage.setItem('auth_token', token);
-    window.location.href = '/dashboard';
-  }
-}
-```
-
-### Progressive Registration
-
-```javascript
-// Offer biometric as an option during existing login
-async function offerBiometricUpgrade(userId, userName) {
-  const support = await dphelper.biometric.checkSupport();
-
-  if (!support.supported) {
-    console.log('Biometric not available on this device');
-    return;
-  }
-
-  // Show modal or prompt
-  const shouldRegister = confirm(
-    `Enable ${support.fingerprint ? 'fingerprint' : 'biometric'} login for faster access?`
-  );
-
-  if (shouldRegister) {
-    const result = await dphelper.biometric.register(
-      userId,
-      window.location.hostname,
-      'My App',
-      userName
-    );
-
-    if (result.success) {
-      // Save credential to user account
-      await saveCredentialToUser(userId, result.credentialId);
-      alert('Biometric authentication enabled!');
-    } else {
-      alert('Registration failed: ' + result.error);
-    }
-  }
-}
-```
-
-## Security Notes
-
-### WebAuthn Security Features
-- **Public-key cryptography** - Uses asymmetric keys, never transmitted
-- **User presence** - Requires user action (touch/face) to authenticate
-- **Platform binding** - Credentials bound to specific device
-- **Phishing resistance** - Relying Party ID must match exactly
-
-### Best Practices
-- Always verify authentication on the server side
-- Store credential IDs in your database, not the credentials themselves
-- Support multiple credentials per user (different devices)
-- Provide fallback for unsupported browsers
-
-## Details
-
-- **Author:** Dario Passariello
-- **Version:** 0.0.1
-- **Creation Date:** 20260313
-- **Last Modified:** 20260313
-- **Environment:** Client-side only (browser with WebAuthn support)
-
----
-
-*Automatically generated document*