dphelper 3.5.5 → 3.7.2

package/docs/markdown/json.md

@@ -0,0 +1,269 @@
+# json
+
+JSON utilities for parsing, validation, conversion, and sanitization.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `counter` | Count occurrences of key-value in JSON | `dphelper.json.counter(data, 'status', 'active')` |
+| `toCsv` | Convert JSON array to CSV string | `dphelper.json.toCsv(users)` |
+| `saveCsvAs` | Download JSON as CSV file | `dphelper.json.saveCsvAs(csvData, 'export')` |
+| `is` | Check if string is valid JSON | `dphelper.json.is('{"key": "value"}')` |
+| `parse` | Parse JSON string safely | `dphelper.json.parse('{"key": "value"}')` |
+| `sanitize` | Sanitize malformed JSON string | `dphelper.json.sanitize(input)` |
+| `sanitizeJsonValue` | Sanitize individual JSON values | `dphelper.json.sanitizeJsonValue('hello')` |
+
+## Description
+
+Complete JSON manipulation toolkit:
+- **Validation** - Check if strings are valid JSON
+- **Parsing** - Safe JSON parsing with error handling
+- **Conversion** - JSON to CSV export
+- **Sanitization** - Clean JSON strings, prevent injection
+
+## Usage Examples
+
+### JSON Validation
+
+```javascript
+// Check if string is valid JSON
+console.log(dphelper.json.is('{"name": "John", "age": 30}')); // true
+console.log(dphelper.json.is('[1, 2, 3]'));                   // true
+console.log(dphelper.json.is('not valid json'));              // false
+console.log(dphelper.json.is(''));                            // false
+
+// Use for API response validation
+function handleResponse(response) {
+  const text = await response.text();
+  if (!dphelper.json.is(text)) {
+    throw new Error('Invalid JSON response');
+  }
+  return JSON.parse(text);
+}
+```
+
+### JSON Parsing
+
+```javascript
+// Parse JSON safely
+const obj = dphelper.json.parse('{"name": "John", "age": 30}');
+console.log(obj); // { name: "John", age: 30 }
+
+// Handles parsing errors gracefully
+const bad = dphelper.json.parse('not json');
+console.log(bad); // "Json not parsable"
+
+// Use for user input
+function parseUserInput(input) {
+  try {
+    return dphelper.json.parse(input);
+  } catch {
+    return null;
+  }
+}
+```
+
+### Counting JSON Properties
+
+```javascript
+const data = {
+  items: [
+    { id: 1, status: 'active' },
+    { id: 2, status: 'active' },
+    { id: 3, status: 'inactive' },
+    { id: 4, status: 'active' }
+  ]
+};
+
+// Count items with specific status
+console.log(dphelper.json.counter(data, 'status', 'active')); // 3
+console.log(dphelper.json.counter(data, 'status', 'inactive')); // 1
+
+// Count total keys
+console.log(dphelper.json.counter(data)); // 1 (the 'items' key)
+
+// Works with nested arrays
+const users = {
+  users: [
+    { role: 'admin', active: true },
+    { role: 'user', active: true },
+    { role: 'user', active: false }
+  ]
+};
+console.log(dphelper.json.counter(users, 'role', 'user')); // 2
+```
+
+### JSON to CSV Conversion
+
+```javascript
+// Convert array of objects to CSV
+const users = [
+  { name: 'John', age: 30, city: 'NYC' },
+  { name: 'Jane', age: 25, city: 'LA' },
+  { name: 'Bob', age: 35, city: 'Chicago' }
+];
+
+const csv = dphelper.json.toCsv(users);
+console.log(csv);
+/*
+name,age,city
+John,30,NYC
+Jane,25,LA
+Bob,35,Chicago
+*/
+
+// Export API response to CSV
+async function exportToCsv() {
+  const response = await fetch('/api/users');
+  const users = await response.json();
+
+  const csv = dphelper.json.toCsv(users);
+  dphelper.json.saveCsvAs(csv, 'users-export');
+}
+```
+
+### Save CSV as File
+
+```javascript
+// Download CSV data as file
+const data = [
+  { product: 'Apple', price: 1.99, quantity: 100 },
+  { product: 'Banana', price: 0.59, quantity: 200 }
+];
+
+const csv = dphelper.json.toCsv(data);
+dphelper.json.saveCsvAs(csv, 'products');
+
+// Filename will include timestamp: "products_20260302120000.csv"
+```
+
+### JSON Sanitization
+
+```javascript
+// Sanitize malformed JSON
+const dirty = '{ "name": "John", "age": 30 }';
+console.log(dphelper.json.sanitize(dirty));
+// '{ "name":"John","age":30}'
+
+// Clean up spacing issues
+const messy = '{ "key" : "value" }';
+console.log(dphelper.json.sanitize(messy));
+// '{"key":"value"}'
+
+// Handles various data types
+const mixed = '{ "string": "hello", "number": 42, "bool": true, "null": null }';
+console.log(dphelper.json.sanitize(mixed));
+// '{"string":"hello","number":42,"bool":true,"null":""}'
+```
+
+### Value Sanitization
+
+```javascript
+// Sanitize individual JSON values
+console.log(dphelper.json.sanitizeJsonValue('hello'));      // '"hello"'
+console.log(dphelper.json.sanitizeJsonValue('hello world')); // '"hello world"'
+console.log(dphelper.json.sanitizeJsonValue('test"quote')); // '"test"quote"'
+console.log(dphelper.json.sanitizeJsonValue('line1\nline2')); // '"line1\nline2"'
+console.log(dphelper.json.sanitizeJsonValue('tab\there'));    // '"tab here"'
+
+// Use for building JSON manually
+function safeJsonString(key, value) {
+  const safeValue = dphelper.json.sanitizeJsonValue(value);
+  return `"${key}":${safeValue}`;
+}
+```
+
+## Advanced Usage
+
+### Complete Data Export
+
+```javascript
+class DataExporter {
+  constructor() {}
+
+  exportToCsv(data, filename) {
+    if (!Array.isArray(data) || data.length === 0) {
+      console.error('Data must be a non-empty array');
+      return;
+    }
+
+    const csv = dphelper.json.toCsv(data);
+    dphelper.json.saveCsvAs(csv, filename);
+  }
+
+  exportTableToCsv(tableId, filename) {
+    const rows = document.querySelectorAll(`#${tableId} tr`);
+    const data = Array.from(rows).map(row => {
+      return Array.from(row.querySelectorAll('td')).map(td => td.textContent);
+    });
+
+    this.exportToCsv(data, filename);
+  }
+}
+
+// Usage
+const exporter = new DataExporter();
+exporter.exportToCsv(userList, 'users');
+```
+
+### JSON Validation Middleware
+
+```javascript
+function validateJsonMiddleware(req, res, next) {
+  let body = '';
+
+  req.on('data', chunk => {
+    body += chunk.toString();
+  });
+
+  req.on('end', () => {
+    if (!dphelper.json.is(body)) {
+      return res.status(400).json({ error: 'Invalid JSON' });
+    }
+
+    try {
+      req.body = dphelper.json.parse(body);
+      next();
+    } catch (err) {
+      return res.status(400).json({ error: 'JSON parse error' });
+    }
+  });
+}
+```
+
+### API Response Handler
+
+```javascript
+async function fetchJson(url) {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+
+  const text = await response.text();
+
+  if (!dphelper.json.is(text)) {
+    throw new Error('Response is not valid JSON');
+  }
+
+  return dphelper.json.parse(text);
+}
+
+// Usage
+const data = await fetchJson('/api/users');
+console.log(data);
+```
+
+## 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/docs/markdown/load.md

@@ -0,0 +1,133 @@
+# load
+
+Dynamic file and script loading utilities for managing modules, components, and resources.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `all` | Load all files from glob object | `dphelper.load.all(import.meta.glob('./**/*.ts'))` |
+| `file` | Load a specific file | `dphelper.load.file(path)` |
+| `fileToElement` | Load file content into element | `dphelper.load.fileToElement('#target', '/content.html')` |
+| `script` | Dynamically load scripts | `dphelper.load.script(['/app.js'])` |
+| `toJson` | Create JSON from folder glob | `dphelper.load.toJson(glob, 'routes')` |
+
+## Description
+
+Dynamic loading utilities:
+- **Module Loading** - Load ES modules via Vite/esbuild
+- **File Loading** - Fetch and inject content
+- **Script Loading** - Dynamic script injection
+- **Caching** - Optional result caching
+
+## Usage Examples
+
+### Load All Modules (Vite)
+
+```javascript
+// Load all TypeScript modules from folder
+dphelper.load.all(
+  import.meta.glob('./components/*.ts', { eager: true }),
+  'components'
+);
+
+// Components are now loaded and cached
+console.log(window.components); // ['./components/Button.ts', ...]
+```
+
+### Load File to Element
+
+```javascript
+// Load HTML content into element
+await dphelper.load.fileToElement('#content', '/partials/home.html');
+
+// Loads home.html and inserts into #content
+// Content is sanitized for XSS protection
+```
+
+### Dynamic Script Loading
+
+```javascript
+// Load multiple scripts
+dphelper.load.script([
+  'https://cdn.example.com/lib1.js',
+  'https://cdn.example.com/lib2.js'
+], 'body');
+
+// Scripts load asynchronously
+// Appended to specified element (default: html)
+```
+
+### Create JSON from Glob
+
+```javascript
+// Create route registry from folder
+dphelper.load.toJson(
+  import.meta.glob('./routes/*.ts'),
+  'routes'
+);
+
+// Creates window.routes as JSON object
+// Keys are file paths, values are modules
+```
+
+## Advanced Usage
+
+### Component Lazy Loading
+
+```javascript
+// Load components on demand
+async function loadComponent(name) {
+  const modules = import.meta.glob('./components/*.vue');
+  const loader = modules[`./components/${name}.vue`];
+
+  if (loader) {
+    return await loader();
+  }
+
+  throw new Error(`Component ${name} not found`);
+}
+
+// Usage
+const Button = await loadComponent('Button');
+```
+
+### Dynamic Module Loading
+
+```javascript
+class ModuleLoader {
+  constructor(basePath) {
+    this.basePath = basePath;
+  }
+
+  async load(moduleName) {
+    const modules = import.meta.glob('./modules/*.js');
+    const key = `./modules/${moduleName}.js`;
+
+    if (modules[key]) {
+      return await modules[key]();
+    }
+
+    return null;
+  }
+
+  loadAll() {
+    dphelper.load.all(
+      import.meta.glob('./modules/*.js', { eager: true }),
+      'allModules'
+    );
+  }
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.3
+- **Creation Date:** 20210101
+- **Last Modified:** 20260228
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/logging.md

@@ -0,0 +1,99 @@
+# logging
+
+Advanced logging system.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `list` | Get all stored logs | `dphelper.log.list()` |
+| `reg` | Log regular message | `dphelper.log.reg(message)` |
+| `debug` | Log debug message | `dphelper.log.debug(message)` |
+| `error` | Log error message | `dphelper.log.error(message)` |
+
+## Description
+
+Application logging system:
+- **Multiple Levels** - Regular, debug, and error logging
+- **Log Storage** - Keep history of all logged messages
+- **Retrieval** - Access logs anytime with list()
+- **Development** - Useful for debugging and monitoring
+
+## Usage Examples
+
+### Basic Logging
+
+```javascript
+// Regular log
+dphelper.log.reg('Application started');
+dphelper.log.reg('User logged in');
+
+// Debug log
+dphelper.log.debug('Variable value:', someVariable);
+dphelper.log.debug('API Response:', response);
+
+// Error log
+dphelper.log.error('Failed to fetch data');
+dphelper.log.error('Invalid input:', error);
+```
+
+### Retrieve Logs
+
+```javascript
+// Get all logs
+const allLogs = dphelper.log.list();
+// Returns array of all logged messages
+
+// Display in console
+console.table(dphelper.log.list());
+
+// Filter by type
+const logs = dphelper.log.list();
+const errors = logs.filter(l => l.type === 'error');
+```
+
+### Debugging Application
+
+```javascript
+// Track function execution
+function processData(data) {
+  dphelper.log.debug('Processing started', data);
+
+  try {
+    const result = transform(data);
+    dphelper.log.debug('Processing complete', result);
+    return result;
+  } catch (err) {
+    dphelper.log.error('Processing failed', err);
+    throw err;
+  }
+}
+```
+
+### Error Tracking
+
+```javascript
+// API error handling
+async function fetchData(url) {
+  try {
+    const response = await fetch(url);
+    dphelper.log.reg(`Fetched: ${url}`);
+    return response.json();
+  } catch (err) {
+    dphelper.log.error(`Failed to fetch ${url}`, err);
+    return null;
+  }
+}
+```
+
+## 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/math.md

@@ -0,0 +1,172 @@
+# math
+
+Advanced mathematical functions and utilities.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `rnd` | Generate a random number | `dphelper.math.rnd()` |
+| `tmr` | Get current epoch time in seconds | `dphelper.math.tmr()` |
+| `isOdd` | Check if a number is odd | `dphelper.math.isOdd(a)` |
+| `percent` | Calculate percentage (n/tot * 100) | `dphelper.math.percent(n, tot)` |
+| `isPrime` | Check if a number is prime | `dphelper.math.isPrime(n)` |
+
+## Description
+
+Mathematical utility functions:
+- **Random** - Generate random numbers based on time
+- **Time** - Get epoch timestamp in seconds
+- **Number Tests** - Check odd/even, prime numbers
+- **Percentage** - Calculate percentage of value relative to total
+
+## Usage Examples
+
+### Random Number Generation
+
+```javascript
+// Generate random number
+const randomNum = dphelper.math.rnd();
+// Returns a random number (typically 6 digits)
+
+// Use in unique ID generation
+function generateId() {
+  return `id_${dphelper.math.rnd()}_${Date.now()}`;
+}
+```
+
+### Time Measurement
+
+```javascript
+// Get current epoch in seconds
+const timestamp = dphelper.math.tmr();
+// Returns current Unix timestamp (seconds)
+
+// Measure function execution time
+function myFunction() {
+  // ... some operations
+}
+
+const start = dphelper.math.tmr();
+myFunction();
+const end = dphelper.math.tmr();
+console.log(`Execution took ${end - start} seconds`);
+```
+
+### Odd/Even Detection
+
+```javascript
+// Check if number is odd
+console.log(dphelper.math.isOdd(5));   // true
+console.log(dphelper.math.isOdd(4));   // false
+console.log(dphelper.math.isOdd(0));   // false
+console.log(dphelper.math.isOdd(-3));  // true
+
+// Use in filtering
+const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+const oddNumbers = numbers.filter(n => dphelper.math.isOdd(n));
+// [1, 3, 5, 7, 9]
+```
+
+### Percentage Calculation
+
+```javascript
+// Basic percentage
+const percent = dphelper.math.percent(25, 100);
+// Output: 25
+
+// Calculate progress
+const progress = dphelper.math.percent(45, 100);
+console.log(`${progress}% complete`);
+// 45% complete
+
+// Sales commission
+function calculateCommission(sales, target) {
+  return dphelper.math.percent(sales, target);
+}
+
+console.log(calculateCommission(50000, 100000)); // 50%
+
+// Vote percentage
+const votes = { yes: 450, no: 50, abstained: 25 };
+const total = votes.yes + votes.no + votes.abstained;
+
+console.log(`Yes: ${dphelper.math.percent(votes.yes, total)}%`);
+console.log(`No: ${dphelper.math.percent(votes.no, total)}%`);
+// Yes: 81.8%
+// No: 9.1%
+```
+
+### Prime Number Check
+
+```javascript
+// Check if number is prime
+console.log(dphelper.math.isPrime(7));   // true
+console.log(dphelper.math.isPrime(4));   // false
+console.log(dphelper.math.isPrime(1));   // false
+console.log(dphelper.math.isPrime(2));   // true
+console.log(dphelper.math.isPrime(17));  // true
+console.log(dphelper.math.isPrime(18));  // false
+
+// Find prime numbers in range
+function findPrimes(min, max) {
+  const primes = [];
+  for (let i = min; i <= max; i++) {
+    if (dphelper.math.isPrime(i)) {
+      primes.push(i);
+    }
+  }
+  return primes;
+}
+
+console.log(findPrimes(1, 20));
+// [2, 3, 5, 7, 11, 13, 17, 19]
+
+// Use in validation
+function isValidPrimeInput(n) {
+  return Number.isInteger(n) && n > 0 && dphelper.math.isPrime(n);
+}
+```
+
+### Combined Math Operations
+
+```javascript
+class MathUtils {
+  // Calculate discount percentage
+  static discountPercentage(original, sale) {
+    const percent = dphelper.math.percent(sale, original);
+    return Math.round(100 - percent);
+  }
+
+  // Check if number is odd prime
+  static isOddPrime(n) {
+    return dphelper.math.isOdd(n) && dphelper.math.isPrime(n);
+  }
+
+  // Generate random odd number
+  static randomOdd(min = 1, max = 100) {
+    let num;
+    do {
+      num = Math.floor(Math.random() * (max - min + 1)) + min;
+    } while (!dphelper.math.isOdd(num));
+    return num;
+  }
+}
+
+console.log(MathUtils.discountPercentage(100, 75));  // 25
+console.log(MathUtils.isOddPrime(7));               // true
+console.log(MathUtils.isOddPrime(2));               // false
+console.log(MathUtils.randomOdd(1, 50));            // Random odd number
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*