dolphin-client 1.0.5 → 1.0.9

package/dist/store.d.ts

@@ -3,6 +3,8 @@ export declare class DolphinStore {
     data: Map<string, any>;
     listeners: Set<any>;
     subscribed: Set<string>;
+    /** @fix: Store unsubscribe functions so destroy() can clean up WS subscriptions (was: subscriptions never removed) */
+    _unsubscribers: Map<string, () => void>;
     /** @param {DolphinClient} client */
     constructor(client: any);
     /** @private */
@@ -19,4 +21,9 @@ export declare class DolphinStore {
     getSnapshot(collection: any): any;
     /** @private */
     _notify(): void;
+    /**
+     * Clean up all WebSocket subscriptions and listeners.
+     * Call this when the store is no longer needed to prevent resource leaks.
+     */
+    destroy(): void;
 }

package/fulltutorial.md

@@ -731,4 +731,239 @@ By marrying the **reactive strength of Dolphin Client** with the **premium desig
 - **Auto Reconnect Policy**: Dolphin Client has an exponentional backoff reconnect strategy built-in. Set `maxReconnect` options to customize connection retry budgets.
 - **Graceful Hardware Fallbacks**: Always test your WebRTC systems with receive-only transceivers (`recvonly`) so desktop terminals with no microphoness/cameras can still receive and play signals properly.
 
+---
+
+## १६. Universal Backend Frameworks Integration (PHP & Node.js ब्याकइन्ड एकीकरण)
+
+Dolphin Client comes with **native out-of-the-box support** for major backend frameworks, including PHP frameworks (CakePHP, WordPress, Laravel) and Node.js backend frameworks (Express, NestJS, Fastify). You do not need to configure any custom ajax headers or write error-handling logic—Dolphin handles it directly!
+
+### १६.१. Automatic CSRF and Nonce Token Injection
+Mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) are automatically injected with security verification tokens to bypass server-side security checks:
+1. **Laravel**: Automatically reads standard token `<input type="hidden" name="_token" value="...">` produced by `@csrf` or `csrf-token` meta tags.
+2. **CakePHP**: Grabs `_csrfToken` hidden input fields or `csrfToken` cookies.
+3. **WordPress**: Automatically retrieves security nonces from `window.wpApiSettings.nonce` or `<meta name="wp-nonce">` and injects them in `X-WP-Nonce` header.
+4. **Node.js (CSRF protection)**: Reads standard `XSRF-TOKEN` or `_csrf` cookies/meta tags.
+
+Dolphin automatically injects these tokens inside the **Request Headers** (`X-CSRF-Token`, `X-XSRF-TOKEN`, `X-WP-Nonce`) and **Request Payload** (`_csrfToken`, `_token`, `_csrf`) under the hood!
+
+### १६.२. HTTP Method Spoofing (`_method`)
+Traditional HTML forms only support `GET` and `POST`. PHP and Node.js backend routers support HTTP Method Spoofing to process `PUT`, `PATCH`, or `DELETE`.
+If `methodSpoofing: true` is configured in `options`, or a hidden `<input type="hidden" name="_method" value="PUT">` is present in a form:
+- Dolphin Client maps the fetch request method to a `POST`.
+- Attaches the spoofed method as a request header `X-HTTP-Method-Override: PUT` and inside the payload body as `_method: "PUT"`.
+
+### १६.३. Unified Validation Error Parsing
+Different backends output validation errors in different structures. Dolphin Client includes a **Universal Error Adapter** that normalizes all formats into a flat `{ [field]: errorMessage }` object, then automatically publishes them to state `errors/{field}`:
+- **Laravel / Yii Format**: `{ errors: { email: ["Must be valid email"] } }` → `errors/email` is updated.
+- **CakePHP Format**: `{ errors: { email: { _required: "Email is required" } } }` → `errors/email` is updated.
+- **Node.js (Joi/Yup/Express-Validator) Format**: `[ { path: "email", msg: "Invalid email" } ]` → `errors/email` is updated.
+
+This means you can display server-side validation errors in HTML instantly with **zero JavaScript**:
+```html
+<form data-api-submit="POST /users/register">
+  <input name="email" />
+  <!-- Server-side validation errors show up here instantly! -->
+  <span class="error" data-rt-bind="errors/email"></span>
+</form>
+```
+
+### १६.४. Base Path & Subfolder Resolution
+If your PHP/WordPress application is hosted locally under a subfolder (e.g. `http://localhost/my-wp-site/`), Dolphin Client automatically respects the `<base href="...">` or `<meta name="base-path">` tags to dynamically prefix all relative API targets (e.g., resolving `data-api-get="/api/posts"` to `http://localhost/my-wp-site/api/posts`).
+
+---
+
+## १७. Buildless SPA Architecture: Component Imports & Link Routing
+
+Dolphin Client v2.0 empowers you to build pure, lightning-fast **Single Page Applications (SPAs)** using standard static HTML pages (like `home.html`, `about.html`, `product.html`) with **exactly zero lines of manual frontend JS** and **zero compiler/bundler setups!**
+
+### १७.१. Declarative Component Layout Imports (`data-import`)
+Rather than copy-pasting headers, navs, and footers across all HTML pages, you can declare layouts dynamically:
+```html
+<!-- index.html (Master Layout) -->
+<body>
+  <!-- Imports header.html into this container dynamically -->
+  <div data-import="components/header.html"></div>
+  
+  <main id="viewport">
+    <h1>Page Content</h1>
+  </main>
+  
+  <div data-import="components/footer.html"></div>
+</body>
+```
+
+#### Under the Hood:
+- **Promise-Based Caching**: Multiple duplicate imports of the same component (like identical buttons or sidebars) are fetched **exactly once** from the server using concurrent promise resolution.
+- **Recursive Resolution**: Imported files can safely import sub-files (e.g., `header.html` importing `nav.html`).
+- **Circular Check**: Safely breaks circular locks (e.g. layout A importing layout B which imports layout A) and displays an alert.
+- **Reactivity Re-scanning**: Dolphin automatically executes store and DOM binding scans on newly imported HTML components.
+
+### १७.२. Instant SPA Viewport Router (`data-spa`)
+Converts traditional page transitions into a smooth Single Page Application experience by hijacking links:
+```html
+<!-- Links with data-spa will route dynamically without reloads! -->
+<nav>
+  <a href="home.html" data-spa>Home</a>
+  <a href="about.html" data-spa>About Us</a>
+  <a href="product.html" data-spa>Products</a>
+</nav>
+```
+
+#### Configuration Options (in constructor):
+- **`routerViewport`**: Selector pointing to the container to be replaced (default: `'main, #viewport, body'`).
+- **`routerTransitions`**: Enables a smooth CSS fade transition between viewport changes (default: `true`).
+
+```javascript
+const dolphin = new DolphinModule.DolphinClient(undefined, undefined, {
+  routerViewport: '#viewport',
+  routerTransitions: true
+});
+```
+
+#### Transition Styles (automatically injected):
+When navigating, Dolphin applies a fading animation by adding `.dolphin-fade-out` and `.dolphin-fade-in` to the viewport, giving your buildless static site a fluid, modern, app-like finish!
+
+---
+
+## १८. Direct React Integration & DolphinStore API (React र DolphinStore एपीआई एकीकरण)
+
+Dolphin Client मा भएको **DolphinStore** ले तपाईँलाई क्लाइन्ट-साइड स्टेट र ब्याकइन्ड डेटा कलेक्सनहरू (GET API र real-time WebSocket Syncing) सजिलै व्यवस्थापन गर्न दिन्छ। यसलाई तपाईँले म्यानुअल जाभास्क्रिप्ट कोड वा **React** सँग सजिलै जोड्न सक्नुहुन्छ।
+
+---
+
+### १८.१. DolphinStore JS API
+जब तपाईँ `DolphinClient` इन्स्टन्स सिर्जना गर्नुहुन्छ, `dolphin.store` स्वतः उपलब्ध हुन्छ। कुनै पनि कलेक्सन प्रोपर्टी (जस्तै `store.devices` वा `store.orders`) पहिलो पटक एक्सेस गर्दा, यसले:
+1. **स्वचालित HTTP Fetch**: `/devices` वा `/orders` मा `GET` रिक्वेस्ट पठाउँछ।
+2. **स्वचालित WebSocket Sync**: `db:sync/devices` च्यानलमा स्वतः सब्सक्राइब गर्छ र ब्याकइन्डमा कुनै आइटम `create`, `update`, वा `delete` हुँदा कलेक्सन डेटा रियल-टाइम अपडेट गर्छ।
+
+#### क) डेटा फिल्टरिङ र सर्टिङ (Filtering & Sorting)
+तपाईँले स्टोर कलेक्सनहरूमा `.where(filterFn)` र `.orderBy(key, direction)` प्रयोग गरेर इन-मेमोरी फिल्टर र सर्ट गर्न सक्नुहुन्छ:
+
+```javascript
+const orders = dolphin.store.orders;
+
+// active र total 50 भन्दा बढी भएका अर्डरहरू फिल्टर गरी मूल्यअनुसार सर्ट गर्ने
+const highValueOrders = orders
+  .where(o => o.status === 'active' && o.total > 50)
+  .orderBy('price', 'desc');
+
+console.log("Filtered orders:", highValueOrders.items);
+```
+
+#### ख) म्यानुअल सब्सक्राइब (Manual Subscription & Snapshot)
+```javascript
+// १. स्टोरमा आउने जुनसुकै अपडेट सुन्न सब्सक्राइब गर्ने
+const unsubscribe = dolphin.store.subscribe(() => {
+  const currentOrders = dolphin.store.getSnapshot('orders');
+  console.log("Store Updated! Orders:", currentOrders.items);
+});
+
+// २. काम सकिएपछि अनसबस्क्राइब गर्ने
+unsubscribe();
+```
+
+---
+
+### १८.२. Hookless React Integration (क्लास कम्पोनेन्टमा प्रयोग)
+यदि तपाईँ React मा कुनै पनि state hooks (`useState`, `useEffect`) प्रयोग नगरी Dolphin Store सँग सिधै रियल-टाइम डेटा बाइन्ड गर्न चाहनुहुन्छ भने, **React Class Components** सबैभन्दा उत्तम विकल्प हो। यसले React लाई विशुद्ध रूपमा रेन्डरिङ इन्जिन मात्र बनाउँछ:
+
+```jsx
+import React from 'react';
+
+class OrderDashboard extends React.Component {
+  constructor(props) {
+    super(props);
+    // १. initial store snapshot स्टेटमा राख्ने
+    this.state = {
+      orders: window.dolphin.store.getSnapshot('orders')
+    };
+  }
+
+  componentDidMount() {
+    // २. स्टोर अपडेट हुँदा लोकल स्टेट अपडेट गर्न सब्सक्राइब गर्ने
+    this.unsubscribe = window.dolphin.store.subscribe(() => {
+      this.setState({
+        orders: window.dolphin.store.getSnapshot('orders')
+      });
+    });
+  }
+
+  componentWillUnmount() {
+    // ३. कम्पोनेन्ट अनमाउन्ट हुँदा अनसबस्क्राइब गर्ने
+    if (this.unsubscribe) this.unsubscribe();
+  }
+
+  render() {
+    const { items, loading, error } = this.state.orders;
+
+    if (loading) return <div>लोड हुँदैछ...</div>;
+    if (error) return <div>त्रुटि: {error}</div>;
+
+    return (
+      <div className="orders-list">
+        <h2>रियल-टाइम अर्डरहरू ({items.length})</h2>
+        {items.map(order => (
+          <div key={order.id} className="order-item">
+            <span>अर्डर #{order.id}</span> - <span>रू. {order.amount}</span>
+          </div>
+        ))}
+      </div>
+    );
+  }
+}
+
+export default OrderDashboard;
+```
+
+---
+
+### १८.३. React Hook Integration using `useSyncExternalStore` (हूक कम्पोनेन्टमा प्रयोग)
+यदि तपाईँ React 18+ को functional components प्रयोग गर्दै हुनुहुन्छ भने, React को आधिकारिक **`useSyncExternalStore`** API को प्रयोग गरेर Dolphin Store लाई विना कुनै अनावश्यक re-render वा state synchronization झन्झट सिधै हूकमा एकीकृत गर्न सक्नुहुन्छ:
+
+```jsx
+import { useSyncExternalStore } from 'react';
+
+// custom react hook सिर्जना गर्ने
+function useDolphinCollection(collectionName) {
+  const store = window.dolphin.store;
+  
+  // १. external store subscribe गर्ने तरिका
+  const subscribe = (onStoreChange) => store.subscribe(onStoreChange);
+  
+  // २. snapshot लिनको लागि getSnapshot
+  const getSnapshot = () => store.getSnapshot(collectionName);
+  
+  // React ले यो स्टोर अपडेट हुँदा स्वतः कम्पोनेन्टलाई re-render गराउँछ
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+// React component मा प्रयोग गर्दा:
+export function UsersList() {
+  const { items, loading, error } = useDolphinCollection('users');
+
+  if (loading) return <p>लोड हुँदैछ...</p>;
+  if (error) return <p>त्रुटि भयो: {error}</p>;
+
+  return (
+    <ul>
+      {items.map(user => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+### १८.४. Prevent Resource Leaks with `destroy()`
+जब तपाईँको सिंगल पेज वा स्टोर अब प्रयोगमा आउँदैन (जस्तै SPA navigation वा HMR/Hot Reloading को समयमा), स्टोरलाई पूर्ण रूपमा नष्ट गर्न `dolphin.store.destroy()` कल गर्नु आवश्यक हुन्छ। यसले सबै एक्टिभ WebSocket subscriptions र listeners हटाई मेमोरी लिक हुनबाट जोगाउँछ:
+
+```javascript
+// clean up dolphin store
+dolphin.store.destroy();
+```
+
+---
+
 Enjoy building hookless, lightning-fast, and premium real-time applications with **Dolphin Client**! 🐬

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dolphin-client",
-  "version": "1.0.5",
+  "version": "1.0.9",
   "description": "HTML is back! Hookless, framework-agnostic real-time reactive DOM-binding client for Dolphin Server with WebSockets, WebRTC signaling, and offline REST API fallbacks.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -13,11 +13,17 @@
       "require": "./dist/index.cjs"
     }
   },
+  "bin": {
+    "dolphin-client": "./bin/cli.cjs"
+  },
   "files": [
     "dist",
     "README.md",
     "LICENSE",
-    "fulltutorial.md"
+    "fulltutorial.md",
+    "scripts",
+    ".vscode",
+    "bin"
   ],
   "scripts": {
     "build": "npm run build:iife && npm run build:min && npm run build:esm && npm run build:cjs && tsc",
@@ -25,7 +31,8 @@
     "build:min": "esbuild ./src/index.ts --bundle --minify --outfile=dist/dolphin-client.min.js --format=iife --global-name=DolphinModule",
     "build:esm": "esbuild ./src/index.ts --bundle --outfile=dist/index.js --format=esm",
     "build:cjs": "esbuild ./src/index.ts --bundle --outfile=dist/index.cjs --format=cjs",
-    "test": "jest"
+    "test": "jest",
+    "postinstall": "node scripts/postinstall.js"
   },
   "jest": {
     "preset": "ts-jest",

package/scripts/postinstall.js

@@ -0,0 +1,57 @@
+const path = require('path');
+const fs = require('fs');
+
+// This script runs automatically after npm install dolphin-client.
+// It sets up the VS Code Custom HTML Data configuration in the host project's .vscode folder
+// so autocomplete for Dolphin Client attributes works instantly out-of-the-box!
+
+try {
+    const currentPath = __dirname;
+    // Check if we are inside a node_modules folder (production installation)
+    if (currentPath.includes('node_modules')) {
+        // Resolve host project root (e.g. node_modules/dolphin-client/scripts -> hostRoot)
+        const hostRoot = path.resolve(__dirname, '../../..');
+        const vscodeDir = path.join(hostRoot, '.vscode');
+
+        // 1. Ensure the host's .vscode directory exists
+        if (!fs.existsSync(vscodeDir)) {
+            fs.mkdirSync(vscodeDir, { recursive: true });
+            console.log('[Dolphin Client] Created .vscode directory in project root.');
+        }
+
+        // 2. Copy the dolphin-tags.json file to the host's .vscode folder
+        const sourceTags = path.resolve(__dirname, '../.vscode/dolphin-tags.json');
+        const destTags = path.join(vscodeDir, 'dolphin-tags.json');
+        if (fs.existsSync(sourceTags)) {
+            fs.copyFileSync(sourceTags, destTags);
+            console.log('[Dolphin Client] Copied HTML custom data configuration to .vscode/dolphin-tags.json');
+        }
+
+        // 3. Update the host's settings.json to include the custom data file path
+        const settingsPath = path.join(vscodeDir, 'settings.json');
+        let settings = {};
+        if (fs.existsSync(settingsPath)) {
+            try {
+                settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            } catch (e) {
+                settings = {};
+            }
+        }
+
+        if (!settings['html.customData']) {
+            settings['html.customData'] = [];
+        }
+
+        const relativePath = '.vscode/dolphin-tags.json';
+        if (!settings['html.customData'].includes(relativePath)) {
+            settings['html.customData'].push(relativePath);
+            fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+            console.log('[Dolphin Client] Registered dolphin-tags.json in .vscode/settings.json');
+        }
+        
+        console.log('\x1b[36m%s\x1b[0m', '🐬 [Dolphin Client] VS Code Autocomplete successfully configured!');
+        console.log('\x1b[33m%s\x1b[0m', '👉 Note: Please run "Developer: Reload Window" in VS Code to activate suggestions.');
+    }
+} catch (err) {
+    console.warn('[Dolphin Client] Failed to auto-configure VS Code autocomplete:', err.message);
+}