dolphin-client 1.0.4 → 1.0.6

package/README.md

@@ -29,13 +29,17 @@ By breathing life back into standard HTML, we have resurrected the simplicity of
 
 ## Features
 
+- **Universal Backend Compatibility**: Native out-of-the-box support for PHP (Laravel, CakePHP, WordPress) and Node.js (Express, NestJS, Fastify). Auto-extracts/injects CSRF tokens and nonces, normalizes multi-format validation error payloads directly into reactive forms, and supports HTTP method spoofing (`_method`) and subfolder base URLs automatically.
+- **HTML Component Imports (`data-import`)**: Declaratively import reusable layouts (e.g. `header.html`, `footer.html`) dynamically in pure HTML with robust concurrent promise caching, nested rendering, and circular dependency checks.
+- **Instant SPA Viewport Router (`data-spa`)**: Converts static pages into highly responsive Single Page Applications (SPAs) with zero manual JS. High-jacks links, swaps viewports dynamically with smooth fading transitions, and updates page titles and history navigation (`popstate`).
 - **Hookless Reactivity**: Bind topics to DOM elements via HTML data attributes—no React, Vue, or Angular state management required.
 - **Svelte-Style Templates Compiler**: Native browser compiler supporting Svelte-style loop blocks (`{#each ... as ...}`), multi-level nested conditionals (`{#if} / {:else if} / {:else}`), loop indices (`index`), optional chaining, and dynamic attribute interpolation.
 - **Unified Event Binding**: Loop-based browser event handling for values (`data-rt-push`) and actions (`data-rt-[event]` / `data-api-[event]`).
 - **Context API/Prop drilling in Pure DOM**: Crawls up the DOM tree (`getClosestContext`) to fetch parent contexts and inject parameters.
 - **REST API + Realtime Hybrid Support**: Evaluates templates (`data-rt-template`) on initial HTTP fetches (`data-api-get`) and transitions seamlessly to real-time WebSockets on connection.
 - **WebRTC Intercom Signaling**: Built-in methods to handle peer connections, track negotiation, ICE candidates, and signaling.
-- **Ultralight weight**: Zero external dependencies, pure browser-native runtime APIs (~39KB compressed bundle!).
+- **DolphinStore JS API & React Integration**: Programmatic store query, filtering (`where`), sorting (`orderBy`), and live collection syncing with auto-REST/WS fallback. Integrates seamlessly with React (class or hook components) using native external store subscriptions.
+- **Ultralight weight**: Zero external dependencies, pure browser-native runtime APIs (~47KB compressed bundle!).
 
 ---
 
@@ -177,7 +181,26 @@ Manage local stores and run complex calculations, conditions, and toggles **dire
 <button data-store-click="app.darkMode = !app.darkMode">Toggle Dark Mode</button>
 ```
 
-### 5. Silent Zero-Configuration Auto-Initialization
+### 5. JavaScript Store API & React Integration
+Query and filter dynamic collections programmatically in JS or sync them with React without state hooks:
+
+```javascript
+// Access the reactive store (auto-fetches GET /users and subscribes to WS db:sync/users)
+const users = dolphin.store.users;
+
+// Dynamic client-side filtering and sorting
+const activeAdmins = users.where(u => u.active && u.role === 'admin').orderBy('name', 'asc');
+
+// Subscribe to store changes manually
+const unsubscribe = dolphin.store.subscribe(() => {
+  console.log("Updated admin count:", activeAdmins.items.length);
+});
+
+// Clean up when no longer needed to prevent memory leaks
+dolphin.store.destroy();
+```
+
+### 6. Silent Zero-Configuration Auto-Initialization
 When loaded via a standard `<script>` tag in browser environments, Dolphin Client automatically boots up a default client instance as `window.dolphin` on `DOMContentLoaded`.
 
 For debugging, pass `data-debug="true"` on your script tag to turn on gorgeous, color-coded logging in your developer console for all API calls, WebSocket events, and Store updates:

package/dist/api.d.ts

@@ -12,7 +12,27 @@ export declare class APIHandler {
         del(pathOrOptions: any, options: any): any;
         request(method: any, subPath: any, body: any, options: any): any;
         requestDirect(method: any, path: any, body: any, options: any): any;
+        _findCSRFToken(): string;
+        _resolveBaseUrl(path: string): string;
+        _normalizeValidationErrors(errData: any): Record<string, string>;
     };
+    /**
+     * Attempts to find a CSRF token in the document (meta tags, forms, or cookies).
+     * Works for Laravel, CakePHP, WordPress, Express, NestJS, etc.
+     * @private
+     */
+    _findCSRFToken(): string | null;
+    /**
+     * Dynamically resolves the Base Path/URL from `<base href="...">` or subfolders.
+     * @private
+     */
+    _resolveBaseUrl(path: string): string;
+    /**
+     * Normalizes backend validation errors from major PHP and Node.js frameworks
+     * into a unified { [field]: message } object.
+     * @private
+     */
+    _normalizeValidationErrors(errData: any): Record<string, string>;
     /**
      * Intercept request for offline-first caching and queuing.
      */

package/dist/core.d.ts

@@ -14,6 +14,8 @@ export declare class DolphinClient {
     fileHandlers: Set<any>;
     _offlineQueue: string[];
     reconnectAttempts: number;
+    /** @fix: Store timer ID so disconnect() can cancel pending reconnects (was: memory/logic leak) */
+    _reconnectTimer: ReturnType<typeof setTimeout> | null;
     _attachedListeners: {
         target: any;
         event: string;
@@ -78,7 +80,7 @@ export declare class DolphinClient {
      * @param {function(number): void} [onProgress]  — progress callback (0-100)
      * @returns {Promise<void>}
      */
-    pubFile(fileId: any, fileData: any, filename: string, onProgress: any): Promise<void>;
+    pubFile(fileId: any, fileData: any, filename?: string, onProgress?: any): Promise<void>;
     /** @private */
     _uint8ToBase64(uint8: any): string;
     /**