dphelper 3.7.1 → 3.7.2

package/docs/markdown/ai.md

@@ -0,0 +1,345 @@
+# ai
+
+AI and LLM utilities for text processing, token estimation, data formatting, and integration tools.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `tokenCount` | Estimates token count for LLM input | `dphelper.ai.tokenCount({ users: [1,2,3] })` |
+| `smartSanitize` | Removes PII (emails, phones, etc.) from text | `dphelper.ai.smartSanitize(text)` |
+| `toon` | Converts JSON to TOON format | `dphelper.ai.toon({ users: [{id: 1, name: 'Ada'}] })` |
+| `toonToJson` | Converts TOON format back to JSON | `dphelper.ai.toonToJson('users[1]{id,name}:\n  1,Ada')` |
+| `chunker` | Splits long text into chunks for RAG | `dphelper.ai.chunker(text, { size: 1000, overlap: 200 })` |
+| `similarity` | Calculates cosine similarity between vectors | `dphelper.ai.similarity(vecA, vecB)` |
+| `extractReasoning` | Extracts AI reasoning tags from response | `dphelper.ai.extractReasoning(aiResponse)` |
+| `prompt` | Template engine for prompt variable injection | `dphelper.ai.prompt('Hello {{name}}', { name: 'Ada' })` |
+| `schema` | Generates TOON-style schema definition | `dphelper.ai.schema({ id: 1, name: 'Ada' })` |
+| `snapshot` | Captures app state snapshot for AI debugging | `dphelper.ai.snapshot()` |
+
+## Description
+
+Comprehensive AI/LLM integration utilities:
+- **Token Estimation** - Estimate token counts for API limits
+- **Data Format Conversion** - TOON (Token-Oriented Object Notation) format
+- **Text Processing** - PII removal, text chunking for RAG
+- **Vector Operations** - Cosine similarity for embeddings
+- **Prompt Engineering** - Template variables, schema generation
+- **AI Debugging** - Extract reasoning, capture app snapshots
+
+## Usage Examples
+
+### Token Count Estimation
+
+```javascript
+// Estimate tokens for a string
+const text = "Hello, how are you today?";
+console.log(dphelper.ai.tokenCount(text)); // ~8 tokens
+
+// Estimate tokens for an object (uses TOON format)
+const data = {
+  users: [
+    { id: 1, name: "John", email: "john@example.com" },
+    { id: 2, name: "Jane", email: "jane@example.com" }
+  ]
+};
+console.log(dphelper.ai.tokenCount(data)); // ~45 tokens
+
+// Use for API rate limiting
+const prompt = "Analyze the following data: " + JSON.stringify(data);
+const tokens = dphelper.ai.tokenCount(prompt);
+if (tokens > 4000) {
+  console.log("Warning: Approaching token limit");
+}
+```
+
+### PII Sanitization
+
+```javascript
+// Remove personal information from text
+const text = `
+  My name is John Smith and my email is john.smith@example.com.
+  You can call me at (555) 123-4567.
+  My credit card is 1234-5678-9012-3456.
+  SSN: 123-45-6789
+`;
+
+const sanitized = dphelper.ai.smartSanitize(text);
+console.log(sanitized);
+// My name is John Smith and my email is [EMAIL].
+// You can call me at [PHONE].
+// My credit card is [CREDIT_CARD].
+// SSN: [SSN]
+
+// Use before sending data to external AI APIs
+async function sendToAI(data) {
+  const safeData = dphelper.ai.smartSanitize(JSON.stringify(data));
+  return await fetch('/api/ai/analyze', {
+    method: 'POST',
+    body: JSON.stringify({ text: safeData })
+  });
+}
+```
+
+### TOON Format Conversion
+
+```javascript
+// Convert JSON to TOON (compact, token-efficient format)
+const data = {
+  users: [
+    { id: 1, name: "Ada", age: 30 },
+    { id: 2, name: "Bob", age: 25 }
+  ]
+};
+
+const toon = dphelper.ai.toon(data);
+console.log(toon);
+/*
+users[2]{id,name,age}:
+  1,Ada,30
+  2,Bob,25
+*/
+
+// Convert back from TOON to JSON
+const json = dphelper.ai.toonToJson(toon);
+console.log(json); // Original data restored
+
+// Simple array
+const arr = [1, 2, 3, 4, 5];
+console.log(dphelper.ai.toon(arr));
+// [5]: 1, 2, 3, 4, 5
+```
+
+### Text Chunking for RAG
+
+```javascript
+const longText = sit amet...`. `Lorem ipsum dolorrepeat(100);
+
+// Split into chunks embedding for vector
+const chunks = dphelper.ai.chunker(longText, { size: 1000, overlap: 200 });
+console.log(chunks.length); // Number of chunks
+console.log(chunks[0].length); // ~1000 characters
+
+// Process each chunk for embedding
+async function embedText(text) {
+  const chunks = dphelper.ai.chunker(text, { size: 500, overlap: 50 });
+  const embeddings = [];
+
+  for (const chunk of chunks) {
+    const embedding = await getEmbedding(chunk);
+    embeddings.push({ chunk, embedding });
+  }
+
+  return embeddings;
+}
+```
+
+### Cosine Similarity
+
+```javascript
+// Calculate similarity between two embedding vectors
+const vectorA = [1.0, 0.5, 0.3, 0.8];
+const vectorB = [0.9, 0.6, 0.2, 0.7];
+
+const similarity = dphelper.ai.similarity(vectorA, vectorB);
+console.log(similarity); // ~0.98 (very similar)
+
+// Find most similar document
+const query = [1.0, 0.5, 0.3];
+const documents = [
+  [0.9, 0.4, 0.2],  // Similar
+  [0.1, 0.1, 0.1],  // Different
+  [0.8, 0.6, 0.4]   // Similar
+];
+
+let mostSimilar = 0;
+let bestDoc = 0;
+documents.forEach((doc, i) => {
+  const sim = dphelper.ai.similarity(query, doc);
+  if (sim > mostSimilar) {
+    mostSimilar = sim;
+    bestDoc = i;
+  }
+});
+console.log(`Most similar: document ${bestDoc} (${mostSimilar})`);
+```
+
+### Extract AI Reasoning
+
+```javascript
+// Extract reasoning from AI response (e.g., Claude, OpenAI o1)
+const aiResponse = `
+<think>
+The user is asking about the weather. Let me think about what data I have available.
+I can provide current conditions based on the user's location.
+</think>
+The current weather in your area is sunny with a temperature of 72°F.
+`;
+
+const extracted = dphelper.ai.extractReasoning(aiResponse);
+console.log(extracted.reasoning);
+// "The user is asking about the weather. Let me think about what data I have available..."
+
+console.log(extracted.content);
+// "The current weather in your area is sunny with a temperature of 72°F."
+```
+
+### Prompt Template Engine
+
+```javascript
+// Simple variable substitution
+const template = "Hello {{name}}, welcome to {{place}}!";
+const result = dphelper.ai.prompt(template, { name: "Ada", place: "our app" });
+console.log(result); // "Hello Ada, welcome to our app!"
+
+// With object variables (converts to TOON)
+const template2 = `Analyze this user data:
+{{user}}`;
+
+const userData = {
+  id: 123,
+  name: "John",
+  preferences: { theme: "dark", lang: "en" }
+};
+console.log(dphelper.ai.prompt(template2, { user: userData }));
+/*
+Analyze this user data:
+id: 123
+name: John
+preferences:
+  theme: dark
+  lang: en
+*/
+
+// Default values for missing variables
+const t3 = "Welcome, {{name}}! Your role is {{role:guest}}.";
+console.log(dphelper.ai.prompt(t3, { name: "Alice" }));
+// "Welcome, Alice! Your role is guest."
+```
+
+### Schema Generation
+
+```javascript
+// Generate TOON-style schema from data
+const data = {
+  id: 1,
+  name: "John",
+  email: "john@example.com",
+  age: 30,
+  active: true
+};
+
+const schema = dphelper.ai.schema(data);
+console.log(schema);
+/*
+id: number
+name: string
+email: string
+age: number
+active: boolean
+*/
+
+// Array schema
+const users = [
+  { id: 1, name: "Ada" },
+  { id: 2, name: "Bob" }
+];
+console.log(dphelper.ai.schema(users));
+// users: Array<{id: number, name: string}>
+```
+
+### App State Snapshot
+
+```javascript
+// Capture current app state for AI debugging
+const snapshot = dphelper.ai.snapshot();
+console.log(snapshot);
+
+/*
+context:
+  env: browser
+  time: 2026-03-02T09:44:55.000Z
+  url: https://app.example.com/dashboard
+  title: My Dashboard
+state: ...
+logs: ...
+system:
+  lang: en-US
+  screen: 1920x1080
+  zoom: 100
+*/
+
+// Useful for AI-assisted debugging
+async function askAIForHelp(error) {
+  const snapshot = dphelper.ai.snapshot();
+  const prompt = `I'm seeing this error: ${error}\n\nCurrent state:\n${snapshot}`;
+
+  return await fetch('/api/ai/debug', {
+    method: 'POST',
+    body: JSON.stringify({ prompt, snapshot })
+  });
+}
+```
+
+## Advanced Usage
+
+### Complete RAG Pipeline
+
+```javascript
+class RAGPipeline {
+  constructor(chunkSize = 500, overlap = 50) {
+    this.chunkSize = chunkSize;
+    this.overlap = overlap;
+  }
+
+  async indexDocument(text, metadata = {}) {
+    // Chunk the text
+    const chunks = dphelper.ai.chunker(text, {
+      size: this.chunkSize,
+      overlap: this.overlap
+    });
+
+    // Generate embeddings for each chunk
+    const documents = [];
+    for (let i = 0; i < chunks.length; i++) {
+      const embedding = await this.getEmbedding(chunks[i]);
+      documents.push({
+        id: `doc_${i}`,
+        text: chunks[i],
+        embedding,
+        metadata,
+        tokenCount: dphelper.ai.tokenCount(chunks[i])
+      });
+    }
+
+    return documents;
+  }
+
+  async query(queryText, topK = 5) {
+    const queryEmbedding = await this.getEmbedding(queryText);
+
+    // Find most similar documents
+    const results = this.documents
+      .map(doc => ({
+        ...doc,
+        similarity: dphelper.ai.similarity(queryEmbedding, doc.embedding)
+      }))
+      .sort((a, b) => b.similarity - a.similarity)
+      .slice(0, topK);
+
+    return results;
+  }
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.3
+- **Creation Date:** 20260220
+- **Last Modified:** 20260221
+- **Environment:** Works in both client and server environments
+
+---
+
+*Automatically generated document*

package/docs/markdown/anchor.md

@@ -0,0 +1,156 @@
+# anchor
+
+Convert anchor tags to JavaScript onclick events for SPA (Single Page Application) navigation while maintaining compatibility with older browsers.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `toOnClick` | Converts all anchor tags in an element to onclick events | `dphelper.anchor.toOnClick('#container')` |
+
+## Description
+
+This tool enables smooth SPA navigation by converting traditional `<a>` tags to JavaScript event handlers. It prevents full page reloads while maintaining browser history functionality. Useful for:
+- Converting legacy HTML to SPA-compatible navigation
+- Mixed environments (some pages SPA, some traditional)
+- Progressive enhancement of existing sites
+
+## Usage Examples
+
+### Basic Usage
+
+```javascript
+// Convert all links in a container to onclick events
+dphelper.anchor.toOnClick('#main-content');
+
+// Now all <a> tags in #main-content will use JavaScript navigation
+// instead of traditional page reloads
+```
+
+### HTML Structure
+
+```html
+<div id="content">
+  <nav>
+    <a href="/">Home</a>
+    <a href="/about">About</a>
+    <a href="/contact">Contact</a>
+  </nav>
+
+  <main>
+    <a href="/dashboard">Dashboard</a>
+    <a href="/settings">Settings</a>
+  </main>
+</div>
+
+<script>
+  // Convert all links in the content area
+  dphelper.anchor.toOnClick('#content');
+</script>
+```
+
+### How It Works
+
+When you call `toOnClick`:
+
+1. **Selection** - Finds all `<a>` tags within the specified element
+2. **PathRail Integration** - Adds path-based CSS classes for styling
+3. **Event Conversion** - Removes `href` attribute and adds click handlers
+4. **Navigation Handling**:
+   - Relative paths (`/dashboard`) → Uses SPA router via `history.pushState`
+   - External paths (`https://...`) → Uses `dphelper.browser.href()`
+
+### Integration with PathRail
+
+```javascript
+// PathRail must be configured for full functionality
+// When used with dphelper.navigation, enables:
+// - Dynamic page loading
+// - CSS class targeting based on current path
+// - History management
+
+// Example: Current path is /dashboard/users
+dphelper.anchor.toOnClick('#app');
+
+// Adds class 'dashboardusers' to each anchor for path-based styling
+```
+
+## Advanced Usage
+
+### SPA Router Integration
+
+```javascript
+// Simple SPA router using anchor conversion
+class SPARouter {
+  constructor(selector) {
+    this.selector = selector;
+    this.routes = {};
+
+    // Convert anchors when initialized
+    dphelper.anchor.toOnClick(selector);
+
+    // Handle browser back/forward
+    window.addEventListener('popstate', () => this.load(window.location.pathname));
+  }
+
+  addRoute(path, handler) {
+    this.routes[path] = handler;
+  }
+
+  load(path) {
+    const handler = this.routes[path];
+    if (handler) {
+      handler();
+      document.dispatchEvent(new CustomEvent('route:change', { detail: { path } }));
+    }
+  }
+
+  navigate(path) {
+    history.pushState({}, '', path);
+    this.load(path);
+  }
+}
+
+// Usage
+const router = new SPARouter('#app');
+router.addRoute('/', () => renderHome());
+router.addRoute('/about', () => renderAbout());
+router.addRoute('/dashboard', () => renderDashboard());
+```
+
+### Progressive Enhancement
+
+```javascript
+// Convert anchors while preserving accessibility
+function enhanceAnchors(containerSelector) {
+  const container = document.querySelector(containerSelector);
+  if (!container) return;
+
+  const anchors = container.querySelectorAll('a');
+
+  anchors.forEach(anchor => {
+    // Add aria-label if missing
+    if (!anchor.getAttribute('aria-label')) {
+      anchor.setAttribute('aria-label', anchor.textContent);
+    }
+
+    // Ensure keyboard accessibility
+    anchor.setAttribute('tabindex', '0');
+  });
+
+  // Convert to onclick
+  dphelper.anchor.toOnClick(containerSelector);
+}
+```
+
+## 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/array.md

@@ -0,0 +1,208 @@
+# 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*