dphelper 3.5.5 → 3.7.2

package/docs/markdown/check.md

@@ -0,0 +1,65 @@
+# check
+
+Validation utilities for version comparison and other checks.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `version` | Compare two version strings | `dphelper.check.version('1.2.0', '1.1.0')` |
+
+## Description
+
+Version comparison utilities:
+- **Semantic Versioning** - Compare version numbers
+- **Custom Options** - Lexicographic and zero-pad support
+
+## Usage Examples
+
+### Version Comparison
+
+```javascript
+// Compare versions
+console.log(dphelper.check.version('1.2.0', '1.1.0'));  // 1 (v1 > v2)
+console.log(dphelper.check.version('1.1.0', '1.2.0'));  // -1 (v1 < v2)
+console.log(dphelper.check.version('1.0.0', '1.0.0'));  // 0 (equal)
+
+// With zero padding
+console.log(dphelper.check.version('1.2', '1.2.0', { zero: true })); // 0
+
+// With lexicographic comparison
+console.log(dphelper.check.version('1.0.0a', '1.0.0b', { lex: true })); // -1
+```
+
+### Software Update Checker
+
+```javascript
+function checkForUpdate(currentVersion, latestVersion) {
+  const result = dphelper.check.version(currentVersion, latestVersion);
+
+  if (result === 1) {
+    console.log('Update available!');
+    return 'Update available';
+  } else if (result === 0) {
+    console.log('You have the latest version.');
+    return 'Up to date';
+  } else {
+    console.log('You are on a newer version.');
+    return 'Ahead';
+  }
+}
+
+checkForUpdate('1.0.0', '1.1.0'); // "Update available!"
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20240829
+- **Last Modified:** 20240829
+- **Environment:** Works in both client and server environments
+
+---
+
+*Automatically generated document*

package/docs/markdown/color.md

@@ -0,0 +1,159 @@
+# color
+
+Color manipulation utilities for converting between color formats and generating color gradients.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `hex` | Converts a number (0-255) to hexadecimal | `dphelper.color.hex(255)` |
+| `toHex` | Converts RGB array to hex string | `dphelper.color.toHex([255, 128, 0])` |
+| `toRGB` | Converts hex string to RGB array | `dphelper.color.toRGB('#ff8000')` |
+| `oleColor` | Converts hex to OLE color format | `dphelper.color.oleColor('#ffffff')` |
+| `gradient` | Generates gradient between two colors | `dphelper.color.gradient('#ff0000', '#0000ff', 10)` |
+
+## Description
+
+Comprehensive color manipulation tools:
+- **Format Conversion** - RGB ↔ Hex, OLE color format
+- **Gradient Generation** - Create smooth color transitions
+- **Number Formatting** - Convert color values to hex
+
+## Usage Examples
+
+### Number to Hex
+
+```javascript
+// Convert a number to 2-digit hex
+console.log(dphelper.color.hex(0));   // "00"
+console.log(dphelper.color.hex(255)); // "ff"
+console.log(dphelper.color.hex(128)); // "80"
+
+// Clamps values outside 0-255
+console.log(dphelper.color.hex(300)); // "ff"
+console.log(dphelper.color.hex(-10)); // "00"
+```
+
+### RGB to Hex Conversion
+
+```javascript
+// Convert RGB array to hex
+console.log(dphelper.color.toHex([255, 255, 255])); // "ffffff"
+console.log(dphelper.color.toHex([255, 0, 0]));     // "ff0000"
+console.log(dphelper.color.toHex([0, 255, 0]));     // "00ff00"
+console.log(dphelper.color.toHex([0, 0, 255]));     // "0000ff"
+console.log(dphelper.color.toHex([255, 128, 0]));   // "ff8000"
+
+// Common colors
+const orange = [255, 165, 0];
+console.log('#' + dphelper.color.toHex(orange)); // "#ffa500"
+```
+
+### Hex to RGB Conversion
+
+```javascript
+// Convert hex to RGB array
+console.log(dphelper.color.toRGB('#ffffff')); // [255, 255, 255]
+console.log(dphelper.color.toRGB('#ff0000')); // [255, 0, 0]
+console.log(dphelper.color.toRGB('#00ff00')); // [0, 255, 0]
+console.log(dphelper.color.toRGB('#0000ff')); // [0, 0, 255]
+
+// Without hash
+console.log(dphelper.color.toRGB('ff8000')); // [255, 128, 0]
+```
+
+### OLE Color Conversion
+
+```javascript
+// Convert to OLE color (used in older Windows APIs)
+console.log(dphelper.color.oleColor('#000000')); // "0"
+console.log(dphelper.color.oleColor('#ffffff')); // "16777215"
+console.log(dphelper.color.oleColor('#ff0000')); // "255"
+console.log(dphelper.color.oleColor('#00ff00')); // "65280"
+console.log(dphelper.color.oleColor('#0000ff')); // "16711680"
+```
+
+### Gradient Generation
+
+```javascript
+// Generate gradient from red to blue
+const gradient = dphelper.color.gradient('#ff0000', '#0000ff', 10);
+console.log(gradient);
+// ["ff0000", "e61b1b", "cc3636", "b35151", "996c6c", "808080", "669696", "4dabab", "33c0c0", "1ad6d6", "0000ff"]
+
+// Useful for creating color scales
+const heatmapColors = dphelper.color.gradient('#0000ff', '#ff0000', 20);
+
+// Cool to warm gradient
+const sunrise = dphelper.color.gradient('#ff9a9e', '#fecfef', 15);
+```
+
+## Advanced Usage
+
+### Color Utilities Class
+
+```javascript
+class ColorUtils {
+  static random() {
+    const r = Math.floor(Math.random() * 256);
+    const g = Math.floor(Math.random() * 256);
+    const b = Math.floor(Math.random() * 256);
+    return '#' + dphelper.color.toHex([r, g, b]);
+  }
+
+  static invert(hex) {
+    const [r, g, b] = dphelper.color.toRGB(hex);
+    return '#' + dphelper.color.toHex([255 - r, 255 - g, 255 - b]);
+  }
+
+  static lighten(hex, percent) {
+    const [r, g, b] = dphelper.color.toRGB(hex);
+    return '#' + dphelper.color.toHex([
+      Math.min(255, Math.floor(r + (255 - r) * percent)),
+      Math.min(255, Math.floor(g + (255 - g) * percent)),
+      Math.min(255, Math.floor(b + (255 - b) * percent))
+    ]);
+  }
+
+  static darken(hex, percent) {
+    const [r, g, b] = dphelper.color.toRGB(hex);
+    return '#' + dphelper.color.toHex([
+      Math.max(0, Math.floor(r * (1 - percent))),
+      Math.max(0, Math.floor(g * (1 - percent))),
+      Math.max(0, Math.floor(b * (1 - percent)))
+    ]);
+  }
+}
+
+// Usage
+console.log(ColorUtils.random());      // "#a3b21c"
+console.log(ColorUtils.invert('#ff0000')); // "#00ffff"
+console.log(ColorUtils.lighten('#888888', 0.2)); // "#adadad"
+console.log(ColorUtils.darken('#888888', 0.2)); // "#636363"
+```
+
+### Dynamic Chart Colors
+
+```javascript
+function generateChartColors(count) {
+  const colors = [];
+  for (let i = 0; i < count; i++) {
+    const hue = (i * 360 / count) % 360;
+    const rgb = this.hslToRgb(hue, 70, 50);
+    colors.push('#' + dphelper.color.toHex(rgb));
+  }
+  return colors;
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/compress.md

@@ -0,0 +1,310 @@
+# compress
+
+Compression and encoding utilities for data compression, decompression, and various encoding formats including gzip, deflate, LZW, base64, URL, and HTML encoding.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `gzip` | Compress with gzip | `await dphelper.compress.gzip('Hello World')` |
+| `gunzip` | Decompress gzip | `await dphelper.compress.gunzip(compressedBlob)` |
+| `deflate` | Compress with deflate | `await dphelper.compress.deflate('Hello World')` |
+| `inflate` | Decompress deflate | `await dphelper.compress.inflate(compressedBlob)` |
+| `compress` | LZW compress | `dphelper.compress.compress('Hello World')` |
+| `decompress` | LZW decompress | `dphelper.compress.decompress(compressedString)` |
+| `base64Encode` | Encode to base64 | `dphelper.compress.base64Encode('Hello')` |
+| `base64Decode` | Decode from base64 | `dphelper.compress.base64Decode('SGVsbG8=')` |
+| `urlEncode` | URL encode | `dphelper.compress.urlEncode('Hello World!')` |
+| `urlDecode` | URL decode | `dphelper.compress.urlDecode('Hello%20World!')` |
+| `htmlEncode` | HTML encode | `dphelper.compress.htmlEncode('<script>')` |
+| `htmlDecode` | HTML decode | `dphelper.compress.htmlDecode('<script>')` |
+
+## Description
+
+Comprehensive compression and encoding module providing:
+- **Gzip/Deflate** - Browser-native compression using CompressionStream API
+- **LZW Compression** - JavaScript-compatible compression for data storage
+- **Base64** - Binary-to-text encoding for data transfer
+- **URL Encoding** - Percent-encoding for URLs and query strings
+- **HTML Encoding** - Escape special characters for safe HTML rendering
+- **Universal** - Works in both browser and server environments
+
+## Usage Examples
+
+### Gzip Compression
+
+```javascript
+// Compress string with gzip
+const original = 'Hello World! This is a test string for compression.';
+const compressed = await dphelper.compress.gzip(original);
+
+console.log('Original size:', original.length);
+console.log('Compressed type:', compressed.type); // "application/gzip"
+
+// Decompress
+const decompressed = await dphelper.compress.gunzip(compressed);
+console.log('Decompressed:', decompressed); // "Hello World! This is a test..."
+```
+
+### Deflate Compression
+
+```javascript
+// Compress with deflate (smaller than gzip, no header)
+const data = JSON.stringify({ users: [...], metadata: {...} });
+const deflated = await dphelper.compress.deflate(data);
+
+// Decompress
+const inflated = await dphelper.compress.inflate(deflated);
+console.log(JSON.parse(inflated));
+```
+
+### LZW Compression (JavaScript Compatible)
+
+```javascript
+// LZW compression - works in both browser and Node.js
+const original = 'ABABABABABABABAB';
+const compressed = dphelper.compress.compress(original);
+
+console.log('Original:', original.length, 'chars');
+console.log('Compressed:', compressed.length, 'chars');
+
+// Decompress
+const decompressed = dphelper.compress.decompress(compressed);
+console.log('Decompressed:', decompressed); // "ABABABABABABABAB"
+```
+
+### Base64 Encoding
+
+```javascript
+// Encode string to base64
+const plain = 'Hello, World!';
+const encoded = dphelper.compress.base64Encode(plain);
+console.log(encoded); // "SGVsbG8sIFdvcmxkIQ=="
+
+// Decode from base64
+const decoded = dphelper.compress.base64Decode(encoded);
+console.log(decoded); // "Hello, World!"
+
+// Encode binary data
+const bytes = new Uint8Array([72, 101, 108, 108, 111]);
+const binaryEncoded = dphelper.compress.base64Encode(String.fromCharCode(...bytes));
+console.log(binaryEncoded); // "SGVsbG8="
+```
+
+### URL Encoding
+
+```javascript
+// URL encode (percent-encoding)
+const url = 'Hello World! Test=1&value=abc';
+const encoded = dphelper.compress.urlEncode(url);
+console.log(encoded); // "Hello%20World!%20Test%3D1%26value%3Dabc"
+
+// URL decode
+const decoded = dphelper.compress.urlDecode(encoded);
+console.log(decoded); // "Hello World! Test=1&value=abc"
+
+// Encode for query string
+const query = 'name=John Doe&city=New York';
+const queryEncoded = dphelper.compress.urlEncode(query);
+console.log(queryEncoded); // "name%3DJohn%20Doe%26city%3DNew%20York"
+```
+
+### HTML Encoding
+
+```javascript
+// HTML encode (escape special characters)
+const unsafe = '<script>alert("XSS!")</script>';
+const encoded = dphelper.compress.htmlEncode(unsafe);
+console.log(encoded);
+// "<script>alert("XSS!")</script>"
+
+// HTML decode
+const decoded = dphelper.compress.htmlDecode(encoded);
+console.log(decoded); // '<script>alert("XSS!")</script>'
+
+// Encode user input before displaying
+const userInput = '<div onclick="evil()">Click me</div>';
+const safe = dphelper.compress.htmlEncode(userInput);
+// In HTML: <div onclick="evil()">Click me</div>
+```
+
+## Advanced Usage
+
+### Data Compression for Storage
+
+```javascript
+class CompressedStorage {
+  async compress(key, data) {
+    const json = JSON.stringify(data);
+    const compressed = await dphelper.compress.gzip(json);
+    localStorage.setItem(key, await compressed.text());
+  }
+
+  async decompress(key) {
+    const stored = localStorage.getItem(key);
+    if (!stored) return null;
+
+    const blob = new Blob([stored], { type: 'application/gzip' });
+    const decompressed = await dphelper.compress.gunzip(blob);
+    return JSON.parse(decompressed);
+  }
+}
+
+// Usage
+const storage = new CompressedStorage();
+await storage.compress('cache', { users: [...], timestamp: Date.now() });
+const data = await storage.decompress('cache');
+```
+
+### API Response Compression
+
+```javascript
+// Compress data before sending to server
+async function sendCompressed(url, data) {
+  const json = JSON.stringify(data);
+  const compressed = await dphelper.compress.gzip(json);
+
+  return fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/gzip'
+    },
+    body: compressed
+  });
+}
+
+// Decompress server response
+async function fetchCompressed(url) {
+  const response = await fetch(url);
+  const compressed = await response.blob();
+  const decompressed = await dphelper.compress.gunzip(compressed);
+  return JSON.parse(decompressed);
+}
+```
+
+### String Compression for URLs
+
+```javascript
+// Compress data for URL-safe storage (using LZW)
+function compressForUrl(data) {
+  const compressed = dphelper.compress.compress(JSON.stringify(data));
+  return dphelper.compress.base64Encode(compressed)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+// Decompress from URL
+function decompressFromUrl(encoded) {
+  const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = base64.padEnd(base64.length + (4 - base64.length % 4) % 4, '=');
+  const compressed = dphelper.compress.base64Decode(padded);
+  return JSON.parse(dphelper.compress.decompress(compressed));
+}
+
+// Usage
+const data = { id: 123, type: 'test', values: [1,2,3] };
+const encoded = compressForUrl(data);
+console.log(encoded); // URL-safe compressed string
+
+const decoded = decompressFromUrl(encoded);
+console.log(decoded); // { id: 123, type: 'test', values: [1,2,3] }
+```
+
+### Secure Data Transfer
+
+```javascript
+// Encode sensitive data for transfer
+function encodeSecure(data) {
+  const json = JSON.stringify(data);
+  const base64 = dphelper.compress.base64Encode(json);
+  return base64;
+}
+
+// Decode secure data
+function decodeSecure(encoded) {
+  const json = dphelper.compress.base64Decode(encoded);
+  return JSON.parse(json);
+}
+
+// Sanitize HTML content
+function sanitizeHtml(content) {
+  return dphelper.compress.htmlEncode(content);
+}
+
+// Build safe query string
+function buildQueryString(params) {
+  return Object.entries(params)
+    .map(([k, v]) => `${dphelper.compress.urlEncode(k)}=${dphelper.compress.urlEncode(v)}`)
+    .join('&');
+}
+
+console.log(buildQueryString({ name: 'John Doe', age: '30' }));
+// "name=John%20Doe=30"
+```
+
+### Cache with Compression
+
+```javascript
+class CacheManager {
+  constructor(prefix = 'cache_') {
+    this.prefix = prefix;
+  }
+
+  async set(key, value, maxAge = 3600000) {
+    const entry = {
+      data: value,
+      expires: Date.now() + maxAge
+    };
+
+    const compressed = await dphelper.compress.gzip(JSON.stringify(entry));
+    localStorage.setItem(
+      this.prefix + key,
+      await compressed.text()
+    );
+  }
+
+  async get(key) {
+    const stored = localStorage.getItem(this.prefix + key);
+    if (!stored) return null;
+
+    try {
+      const blob = new Blob([stored], { type: 'application/gzip' });
+      const decompressed = await dphelper.compress.gunzip(blob);
+      const entry = JSON.parse(decompressed);
+
+      if (Date.now() > entry.expires) {
+        localStorage.removeItem(this.prefix + key);
+        return null;
+      }
+
+      return entry.data;
+    } catch {
+      return null;
+    }
+  }
+
+  clear() {
+    Object.keys(localStorage)
+      .filter(k => k.startsWith(this.prefix))
+      .forEach(k => localStorage.removeItem(k));
+  }
+}
+
+// Usage
+const cache = new CacheManager();
+await cache.set('user_123', { name: 'John', email: 'john@example.com' });
+const user = await cache.get('user_123');
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.1
+- **Creation Date:** 20260313
+- **Last Modified:** 20260313
+- **Environment:** Works in both client and server environments
+
+---
+
+*Automatically generated document*

package/docs/markdown/cookie.md

@@ -0,0 +1,115 @@
+# cookie
+
+Cookie management utilities with security features.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `set` | Creates a cookie with specified properties | `dphelper.cookie.set({name: 'user', value: 'john', time: 365})` |
+| `get` | Retrieves a cookie value by name | `dphelper.cookie.get('user')` |
+| `delete` | Deletes a cookie by name | `dphelper.cookie.delete('user')` |
+| `removeAll` | Clears all cookies | `dphelper.cookie.removeAll()` |
+
+## Description
+
+Complete cookie management:
+- **Create** - Set cookies with expiration, path, security
+- **Read** - Get cookie values
+- **Delete** - Remove specific or all cookies
+- **Security** - SameSite, Secure flags for CSRF protection
+
+## Usage Examples
+
+### Setting Cookies
+
+```javascript
+// Simple cookie
+dphelper.cookie.set({
+  name: 'theme',
+  value: 'dark'
+});
+
+// Cookie with expiration (days)
+dphelper.cookie.set({
+  name: 'user',
+  value: 'john@example.com',
+  time: 30 // 30 days
+});
+
+// Secure cookie (HTTPS only)
+dphelper.cookie.set({
+  name: 'session',
+  value: 'abc123',
+  secure: true,
+  sameSite: 'Strict'
+});
+```
+
+### Reading Cookies
+
+```javascript
+// Get cookie value
+const theme = dphelper.cookie.get('theme');
+console.log(theme); // "dark"
+
+// Get session
+const session = dphelper.cookie.get('session');
+```
+
+### Deleting Cookies
+
+```javascript
+// Delete specific cookie
+dphelper.cookie.delete('theme');
+
+// Clear all cookies
+dphelper.cookie.removeAll();
+```
+
+### Complete Example
+
+```javascript
+class CookieManager {
+  constructor() {}
+
+  // Save user preferences
+  savePreferences(prefs) {
+    dphelper.cookie.set({
+      name: 'preferences',
+      value: JSON.stringify(prefs),
+      time: 365,
+      sameSite: 'Lax'
+    });
+  }
+
+  // Load preferences
+  loadPreferences() {
+    const prefs = dphelper.cookie.get('preferences');
+    return prefs ? JSON.parse(prefs) : null;
+  }
+
+  // Clear all
+  clearAll() {
+    dphelper.cookie.removeAll();
+  }
+}
+```
+
+## Security Features
+
+- **SameSite** - Default 'Lax' for CSRF protection
+- **Secure** - Automatic on HTTPS
+- **Value Encoding** - URL encoding to prevent injection
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20240613
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*