dphelper 3.7.1 → 3.7.2

package/docs/markdown/socket.md

@@ -0,0 +1,134 @@
+# socket
+
+WebSocket utilities for real-time bidirectional communication.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `info` | Get socket library information | `dphelper.socket.info()` |
+| `start` | Initialize and start a socket connection | `dphelper.socket.start(element, server, name)` |
+| `connect` | Connect to a WebSocket server | `dphelper.socket.connect(server, name)` |
+| `open` | Open a named socket connection | `dphelper.socket.open(id, server, name)` |
+| `send` | Send data through socket | `dphelper.socket.send(message, type, name)` |
+| `receive` | Set up message receiver | `dphelper.socket.receive(element, name)` |
+| `keepAlive` | Maintain connection with ping/pong | `dphelper.socket.keepAlive(name)` |
+| `ping` | Send ping to server | `dphelper.socket.ping(name)` |
+| `check` | Check and cleanup closed connections | `dphelper.socket.check()` |
+| `list` | List all active WebSocket connections | `dphelper.socket.list()` |
+
+## Description
+
+Complete WebSocket management toolkit:
+- **Connection Management** - Connect, disconnect, keep-alive
+- **Messaging** - Send and receive data
+- **Monitoring** - Track active connections
+- **Security** - Enforces WSS (TLS) for production
+
+## Usage Examples
+
+### Basic Connection
+
+```javascript
+// Initialize a socket connection
+dphelper.socket.connect('wss://example.com/socket', 'myConnection');
+
+// Set up message receiver
+dphelper.socket.receive('#messageContainer', 'myConnection');
+
+// Send a message
+dphelper.socket.send('Hello World', 'message', 'myConnection');
+```
+
+### Complete Real-time Chat
+
+```javascript
+// Initialize chat connection
+function initChat() {
+  const server = 'wss://chat.example.com/ws';
+  const name = 'chat';
+
+  // Connect to server
+  dphelper.socket.connect(server, name);
+
+  // Set up message handler
+  dphelper.socket.receive('#chatMessages', name);
+
+  // Keep connection alive
+  dphelper.socket.keepAlive(name);
+}
+
+// Send message
+function sendMessage(text) {
+  dphelper.socket.send(text, 'chat', 'chat');
+}
+
+// HTML: <div id="chatMessages"></div>
+// HTML: <input type="text" id="chatInput">
+// HTML: <button onclick="sendMessage(document.getElementById('chatInput').value)">Send</button>
+```
+
+### Multiple Socket Connections
+
+```javascript
+// Create multiple named connections
+dphelper.socket.connect('wss://api.example.com/notifications', 'notifications');
+dphelper.socket.connect('wss://api.example.com/updates', 'updates');
+dphelper.socket.connect('wss://api.example.com/chat', 'chat');
+
+// Send to specific connection
+dphelper.socket.send('New user', 'notification', 'notifications');
+dphelper.socket.send('Update data', 'update', 'updates');
+
+// List all active connections
+const connections = dphelper.socket.list();
+console.log(`Active connections: ${connections.length}`);
+```
+
+### Keep-Alive Implementation
+
+```javascript
+// Maintain connection with automatic ping/pong
+dphelper.socket.keepAlive('mainConnection');
+
+// Manual ping
+dphelper.socket.ping('mainConnection');
+
+// Check connection health
+dphelper.socket.check();
+```
+
+### Form Submission via Socket
+
+```javascript
+// Send form data through socket
+document.querySelector('form').addEventListener('submit', (e) => {
+  e.preventDefault();
+
+  const formData = new FormData(e.target);
+  const data = Object.fromEntries(formData);
+
+  dphelper.socket.send(JSON.stringify(data), 'form', 'mainConnection');
+});
+```
+
+## Security Features
+
+- **TLS Enforcement** - Only allows secure WebSocket connections (wss://)
+- **URL Validation** - Prevents arbitrary origin connections
+- **Same-origin fallback** - Supports relative URLs
+
+> [!IMPORTANT]
+> **Input Validation Required:** Callers must validate and sanitize URLs before passing them to socket functions. Use `dphelper.sanitize.url()` for URL validation.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260329
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/sse.md

@@ -0,0 +1,120 @@
+# sse
+
+Server-Sent Events (SSE) client for real-time streaming data.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `open` | Open SSE connection with custom options | `dphelper.sse.open('/api/stream', options)` |
+
+## Description
+
+Server-Sent Events client:
+- **Streaming** - Receive real-time updates from server
+- **Custom Headers** - POST requests, authentication
+- **Event Types** - message, error, open handlers
+- **Auto Reconnect** - Built-in connection handling
+
+## Usage Examples
+
+### Basic SSE Connection
+
+```javascript
+// Open SSE connection
+const sse = dphelper.sse.open('/api/stream');
+
+// Listen for messages
+sse.on('message', (data) => {
+  console.log('Received:', data);
+});
+
+// Handle errors
+sse.on('error', (err) => {
+  console.error('SSE Error:', err);
+});
+
+// Connection opened
+sse.on('open', (info) => {
+  console.log('Connected:', info.status);
+});
+```
+
+### POST Request with Headers
+
+```javascript
+// SSE with authentication
+const sse = dphelper.sse.open('/api/stream', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer token',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({ query: 'updates' })
+});
+
+sse.on('message', (data) => {
+  updateUI(data);
+});
+```
+
+### Complete Real-time Updates
+
+```javascript
+class RealtimeUpdater {
+  constructor(url, options = {}) {
+    this.url = url;
+    this.options = options;
+    this.connection = null;
+  }
+
+  connect() {
+    this.connection = dphelper.sse.open(this.url, this.options);
+
+    this.connection.on('message', (data) => {
+      this.handleMessage(data);
+    });
+
+    this.connection.on('error', (err) => {
+      console.error('Connection error:', err);
+    });
+
+    this.connection.on('open', (info) => {
+      console.log('Connected:', info.status);
+    });
+  }
+
+  handleMessage(data) {
+    console.log('Update:', data);
+  }
+
+  disconnect() {
+    if (this.connection) {
+      this.connection.close();
+    }
+  }
+}
+
+// Usage
+const updater = new RealtimeUpdater('/api/updates', {
+  headers: { 'X-API-Key': 'secret' }
+});
+updater.connect();
+```
+
+## Security Notes
+
+> [!IMPORTANT]
+> **Input Validation Required:** SSE connections require URL validation by the caller. Use `dphelper.sanitize.url()` before opening connections.
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20260221
+- **Last Modified:** 20260329
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/svg.md

@@ -0,0 +1,167 @@
+# svg
+
+SVG manipulation utilities for creating connections, diagrams, and converting elements to SVG format.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `init` | Initialize SVG connection between elements | `dphelper.svg.init(container, [el1, 'right'], [el2, 'left'])` |
+| `check` | Check SVG browser support | `dphelper.svg.check()` |
+| `update` | Update SVG connection positions | `dphelper.svg.update(rect1, rect2, path)` |
+| `getCurve` | Calculate curve path between points | `dphelper.svg.getCurve([x1,y1], [x2,y2], distance)` |
+| `getIntersection` | Calculate element intersection point | `dphelper.svg.getIntersection(dx, dy, cx, cy, w, h)` |
+| `setConnector` | Set connector point on element | `dphelper.svg.setConnector(element, 'right')` |
+| `removeConnection` | Remove SVG connection from container | `dphelper.svg.removeConnection(container)` |
+| `makeScrollable` | Update connection on scroll | `dphelper.svg.makeScrollable(svg, scroll, el1, el2, rect1, rect2)` |
+| `makeDraggable` | Make SVG element draggable | `dphelper.svg.makeDraggable(event)` |
+| `toggle` | Toggle SVG connection on/off | `dphelper.svg.toggle(event, container, el1, el2)` |
+| `convert` | Convert HTML element to SVG | `dphelper.svg.convert({ children: '#myDiv' })` |
+
+## Description
+
+Complete SVG toolkit:
+- **Connection Drawing** - Create visual links between elements
+- **Geometry Calculations** - Curves, intersections, positions
+- **Interactivity** - Draggable elements, scroll handling
+- **Conversion** - Transform HTML to SVG
+
+## Usage Examples
+
+### Creating Connections
+
+```javascript
+// HTML structure
+// <div id="container">
+//   <div id="element1">Source</div>
+//   <div id="element2">Target</div>
+// </div>
+
+const container = document.getElementById('container');
+const el1 = document.getElementById('element1');
+const el2 = document.getElementById('element2');
+
+// Initialize connection from right of el1 to left of el2
+dphelper.svg.init(container, [el1, 'right'], [el2, 'left']);
+
+// Connection uses bezier curves
+```
+
+### Connection Sides
+
+```javascript
+// Available connection points
+dphelper.svg.init(container, [el1, 'top'], [el2, 'bottom']);
+dphelper.svg.init(container, [el1, 'right'], [el2, 'left']);
+dphelper.svg.init(container, [el1, 'left'], [el2, 'right']);
+dphelper.svg.init(container, [el1, 'bottom'], [el2, 'top']);
+```
+
+### Toggle Connection
+
+```javascript
+// Toggle connection with checkbox
+const checkbox = document.getElementById('toggleConnection');
+const container = document.getElementById('diagram');
+const source1 = document.getElementById('node1');
+const source2 = document.getElementById('node2');
+
+checkbox.addEventListener('change', (e) => {
+  dphelper.svg.toggle(e, container, source1, source2);
+});
+```
+
+### HTML to SVG Conversion
+
+```javascript
+// Convert a div to SVG
+dphelper.svg.convert({
+  children: '#myContent',  // Element to convert
+  active: true,
+  size: [1920, 1080],     // ViewBox size
+  fit: ['100%', '100%'],  // Display size
+  preserveAspectRatio: 'xMidYMid meet'
+});
+
+// Creates SVG with foreignObject containing the HTML
+```
+
+### Check SVG Support
+
+```javascript
+// Check if browser supports SVG
+if (dphelper.svg.check()) {
+  console.log('SVG supported');
+} else {
+  console.log('SVG not supported - fallback to canvas');
+}
+```
+
+### Remove Connections
+
+```javascript
+// Remove all SVG connections from container
+dphelper.svg.removeConnection(document.getElementById('container'));
+```
+
+## Advanced Usage
+
+### Flowchart Builder
+
+```javascript
+class FlowchartBuilder {
+  constructor(containerId) {
+    this.container = document.getElementById(containerId);
+    this.connections = [];
+  }
+
+  addNode(id, x, y, label) {
+    const node = document.createElement('div');
+    node.id = id;
+    node.className = 'flow-node';
+    node.style.left = x + 'px';
+    node.style.top = y + 'px';
+    node.textContent = label;
+    this.container.appendChild(node);
+    return node;
+  }
+
+  connect(fromId, toId) {
+    const from = document.getElementById(fromId);
+    const to = document.getElementById(toId);
+
+    dphelper.svg.init(this.container, [from, 'right'], [to, 'left']);
+  }
+}
+
+// Usage
+const flowchart = new FlowchartBuilder('canvas');
+flowchart.addNode('start', 10, 50, 'Start');
+flowchart.addNode('process', 200, 50, 'Process');
+flowchart.addNode('end', 400, 50, 'End');
+
+flowchart.connect('start', 'process');
+flowchart.connect('process', 'end');
+```
+
+### Draggable SVG Elements
+
+```javascript
+// Make SVG elements draggable
+const svgElement = document.querySelector('#mySvg circle');
+dphelper.svg.makeDraggable(svgElement);
+
+// Enables mouse drag functionality on SVG elements
+```
+
+## 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/sync.md

@@ -0,0 +1,147 @@
+# sync
+
+Modern state synchronization and browser storage helpers.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `tab` | Sync data between tabs | `dphelper.sync.tab(channel, callback)` |
+| `storageProxy` | Auto-syncing localStorage proxy | `dphelper.sync.storageProxy(key, defaultValue)` |
+| `pulse` | Low-latency cross-tab event bus | `dphelper.sync.pulse(channel, callback)` |
+
+## Description
+
+Cross-tab synchronization:
+- **BroadcastChannel** - Native browser API for tab communication
+- **Storage Proxy** - Automatic localStorage synchronization
+- **Event Bus** - Real-time messaging between tabs
+- **Security** - Same-origin validation, prototype pollution protection
+
+## Usage Examples
+
+### Cross-Tab Communication
+
+```javascript
+// Open two tabs and communicate between them
+
+// In Tab 1: Listen for messages
+const sync = dphelper.sync.tab('chat', (data) => {
+  console.log('Received:', data);
+});
+
+// In Tab 1: Send message to other tabs
+sync.post({ message: 'Hello from Tab 1!' });
+
+// When done, close the channel
+sync.close();
+```
+
+### Real-time Updates Across Tabs
+
+```javascript
+// Sync user preferences across tabs
+const prefs = dphelper.sync.tab('user_prefs', (data) => {
+  console.log('Preferences updated:', data);
+  applyTheme(data.theme);
+});
+
+// Update preferences (sends to all other tabs)
+prefs.post({ theme: 'dark', notifications: true });
+```
+
+### Auto-syncing localStorage
+
+```javascript
+// Create auto-syncing storage proxy
+const settings = dphelper.sync.storageProxy('app_settings', {
+  theme: 'light',
+  language: 'en',
+  notifications: true
+});
+
+// Changes automatically sync to localStorage
+settings.theme = 'dark';
+// localStorage now has: { "app_settings": "{\"theme\":\"dark\",...}" }
+
+// Changes sync across tabs (with StorageEvent listener)
+```
+
+### With Encryption
+
+```javascript
+// Create encrypted storage proxy
+const secureSettings = dphelper.sync.storageProxy('secure_data', {
+  apiKey: 'secret-key',
+  token: 'auth-token'
+}, 'my-secret-key');
+
+// Data is encrypted in localStorage
+```
+
+### Pulse Event Bus
+
+```javascript
+// Low-latency messaging with pulse
+const pulse = dphelper.sync.pulse('notifications', (data) => {
+  showNotification(data);
+});
+
+// Send notification
+pulse.emit({ type: 'info', message: 'New message!' });
+
+// Stop listening
+pulse.stop();
+```
+
+### Complete Real-time App
+
+```javascript
+// Multi-tab state management
+class TabSync {
+  constructor(channel) {
+    this.channel = channel;
+    this.connection = null;
+  }
+
+  connect() {
+    this.connection = dphelper.sync.tab(this.channel, (data) => {
+      this.handleMessage(data);
+    });
+  }
+
+  handleMessage(data) {
+    console.log('Sync:', data);
+    // Update UI
+  }
+
+  broadcast(action, payload) {
+    if (this.connection) {
+      this.connection.post({ action, payload, timestamp: Date.now() });
+    }
+  }
+
+  disconnect() {
+    if (this.connection) {
+      this.connection.close();
+    }
+  }
+}
+
+// Usage
+const sync = new TabSync('app_state');
+sync.connect();
+sync.broadcast('UPDATE_USER', { name: 'John' });
+```
+
+## Details
+
+- **Author:** Dario Passariello & Jo
+- **Version:** 0.0.2
+- **Creation Date:** 20260220
+- **Last Modified:** 20260221
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/system.md

@@ -0,0 +1,78 @@
+# system
+
+Utilities for extending system-level functionality.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `multiSplit` | Split string by multiple delimiters | `dphelper.system.multiSplit(str, tokens)` |
+
+## Description
+
+System-level utilities:
+- **Multi-Split** - Split a string using multiple delimiters at once
+- **Safe** - No prototype pollution, clean implementation
+
+## Usage Examples
+
+### Multi-Split
+
+```javascript
+// Split by multiple delimiters
+const str = "apple,pear:banana;orange";
+const fruits = dphelper.system.multiSplit(str, [',', ':', ';']);
+// Result: ["apple", "pear", "banana", "orange"]
+
+// Parse CSV with mixed delimiters
+const data = "name,email:phone;address";
+const parts = dphelper.system.multiSplit(data, [',', ':', ';']);
+// ["name", "email", "phone", "address"]
+
+// Parse log line
+const log = "ERROR|WARNING|INFO:message here";
+const sections = dphelper.system.multiSplit(log, ['|', ':']);
+// ["ERROR", "WARNING", "INFO", "message here"]
+
+// URL parsing
+const url = "protocol:host/path?query=value";
+const urlParts = dphelper.system.multiSplit(url, ['://', '/', '?', '=']);
+// More complex parsing
+```
+
+### Parse Complex Data
+
+```javascript
+// Parse mixed delimiter data
+function parseData(input) {
+  const delimiters = [',', ';', '|', '\t'];
+  return dphelper.system.multiSplit(input.trim(), delimiters);
+}
+
+console.log(parseData("a,b;c|d"));
+// ["a", "b", "c", "d"]
+
+console.log(parseData("item1\titem2,item3;item4"));
+// ["item1", "item2", "item3", "item4"]
+```
+
+### CSV Header Processing
+
+```javascript
+// Process CSV with various delimiters
+const csv = "name,age,city;country";
+const headers = dphelper.system.multiSplit(csv, [',', ';']);
+// ["name", "age", "city", "country"]
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20231121
+- **Last Modified:** 20260220
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*