dolphin-server-modules 2.2.1 → 2.2.5

package/scripts/client.js

@@ -176,11 +176,6 @@ class AuthHandler {
         this.user = null;
     }
 
-    /**
-     * @param {string} email
-     * @param {string} password
-     * @returns {Promise<any>}
-     */
     async login(email, password) {
         const res = await this.client.api.post('/auth/login', { email, password });
         if (res.accessToken) {
@@ -190,12 +185,10 @@ class AuthHandler {
         return res;
     }
 
-    /** @param {any} data */
     async register(data) {
         return await this.client.api.post('/auth/register', data);
     }
 
-    /** @returns {Promise<DolphinResponse>} */
     async me() {
         const res = await this.client.api.get('/auth/me');
         if (res.success) {
@@ -216,6 +209,170 @@ class AuthHandler {
     }
 }
 
+/**
+ * DolphinStore - Reactive State Sync (Zustand Alternative)
+ * Automatically syncs database collections with local state.
+ */
+class DolphinStore {
+    /** @param {DolphinClient} client */
+    constructor(client) {
+        this.client = client;
+        /** @type {Map<string, { items: any[], loading: boolean, error: string|null, success: boolean }>} */
+        this.data = new Map();
+        /** @type {Set<function()>} */
+        this.listeners = new Set();
+        /** @type {Set<string>} */
+        this.subscribed = new Set();
+
+        return new Proxy(this, {
+            get: (target, prop) => {
+                if (prop in target) return target[prop];
+                if (typeof prop === 'string') {
+                    return this._getCollection(prop);
+                }
+            }
+        });
+    }
+
+    /** @private */
+    _getCollection(name) {
+        if (!this.data.has(name)) {
+            const collection = {
+                _rawItems: [],
+                items: [],
+                loading: true,
+                error: null,
+                success: false,
+                _filter: null,
+                _sort: null,
+
+                /**
+                 * फिल्टर सेट गर्ने (Local filtering)
+                 * @param {function(any): boolean} fn 
+                 */
+                where: (fn) => {
+                    collection._filter = fn;
+                    this._applyTransform(collection);
+                    return collection;
+                },
+
+                /**
+                 * सर्टिङ सेट गर्ने
+                 * @param {string} key 
+                 * @param {'asc'|'desc'} [direction] 
+                 */
+                orderBy: (key, direction = 'asc') => {
+                    collection._sort = { key, direction };
+                    this._applyTransform(collection);
+                    return collection;
+                },
+
+                /**
+                 * फिल्टर र सर्ट हटाउने
+                 */
+                clear: () => {
+                    collection._filter = null;
+                    collection._sort = null;
+                    this._applyTransform(collection);
+                    return collection;
+                }
+            };
+
+            this.data.set(name, collection);
+            this._fetchAndSync(name);
+        }
+        return this.data.get(name);
+    }
+
+    /** @private */
+    async _fetchAndSync(name) {
+        const state = this.data.get(name);
+        try {
+            // 1. Initial Fetch
+            const res = await this.client.api.get(`/${name.toLowerCase()}`);
+            state._rawItems = Array.isArray(res) ? res : (res.data || []);
+            state.loading = false;
+            state.success = true;
+            state.error = null;
+            this._applyTransform(state);
+
+            // 2. Realtime Sync (if connected)
+            if (!this.subscribed.has(name)) {
+                const topic = `db:sync/${name.toLowerCase()}`;
+                this.client.subscribe(topic, (update) => {
+                    this._handleRemoteUpdate(name, update);
+                });
+                this.subscribed.add(name);
+            }
+        } catch (e) {
+            state.loading = false;
+            state.success = false;
+            state.error = e.data?.error || e.message || 'Fetch failed';
+            this._notify();
+            console.error(`[DolphinStore] Sync failed for ${name}:`, e);
+        }
+    }
+
+    /** @private */
+    _applyTransform(state) {
+        let result = [...state._rawItems];
+
+        // 1. Filter
+        if (state._filter) {
+            result = result.filter(state._filter);
+        }
+
+        // 2. Sort
+        if (state._sort) {
+            const { key, direction } = state._sort;
+            result.sort((a, b) => {
+                const av = a[key];
+                const bv = b[key];
+                if (av === bv) return 0;
+                const compare = av > bv ? 1 : -1;
+                return direction === 'asc' ? compare : -compare;
+            });
+        }
+
+        state.items = result;
+        this._notify();
+    }
+
+    /** @private */
+    _handleRemoteUpdate(collection, update) {
+        const state = this.data.get(collection);
+        if (!state) return;
+
+        let items = state._rawItems;
+        const { type, data } = update; // type: 'create', 'update', 'delete'
+
+        if (type === 'create') {
+            items = [...items, data];
+        } else if (type === 'update') {
+            items = items.map(item => (item.id === data.id || item._id === data._id) ? { ...item, ...data } : item);
+        } else if (type === 'delete') {
+            items = items.filter(item => (item.id !== data.id && item._id !== data._id));
+        }
+
+        state._rawItems = items;
+        this._applyTransform(state);
+    }
+
+    /** Subscribe for React components (useSyncExternalStore) */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    getSnapshot(collection) {
+        return this.data.get(collection) || { items: [], loading: false, error: null, success: false };
+    }
+
+    _notify() {
+        this.listeners.forEach(l => l());
+    }
+}
+
 class DolphinClient {
     /**
      * @param {string} [url]
@@ -256,6 +413,7 @@ class DolphinClient {
         // Sub-handlers
         this.api = new APIHandler(this);
         this.auth = new AuthHandler(this);
+        this.store = new DolphinStore(this);
 
         /** @type {Map<string, Set<TopicCallback>>} */
         this.handlers = new Map(); // topic -> Set of callbacks
@@ -395,7 +553,13 @@ class DolphinClient {
      * @param {TopicCallback} callback
      */
     subscribe(topic, callback) {
-        if (!this.handlers.has(topic)) this.handlers.set(topic, new Set());
+        if (!this.handlers.has(topic)) {
+            this.handlers.set(topic, new Set());
+            // Tell server we want to sub
+            if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+                this.socket.send(JSON.stringify({ type: 'sub', topic }));
+            }
+        }
         this.handlers.get(topic).add(callback);
     }
 
@@ -409,6 +573,10 @@ class DolphinClient {
             callbacks.delete(callback);
             if (callbacks.size === 0) {
                 this.handlers.delete(topic);
+                // Tell server we want to unsub
+                if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+                    this.socket.send(JSON.stringify({ type: 'unsub', topic }));
+                }
             }
         }
     }

package/scripts/dolphin-persist.js

@@ -0,0 +1,211 @@
+/**
+ * DolphinPersist - Offline Cache Plugin for Dolphin Client
+ * 
+ * Optional, zero-dependency persistence layer for DolphinStore.
+ * Supports both localStorage (simple) and IndexedDB (large data).
+ * 
+ * Usage:
+ *   // Auto-detect best storage:
+ *   const persist = new DolphinPersist();
+ *   dolphin.store.use(persist);
+ *
+ *   // Force localStorage:
+ *   const persist = new DolphinPersist({ driver: 'localstorage' });
+ *
+ *   // Force IndexedDB:
+ *   const persist = new DolphinPersist({ driver: 'indexeddb' });
+ */
+
+class DolphinPersist {
+    /**
+     * @param {{ driver?: 'auto'|'localstorage'|'indexeddb', prefix?: string, ttl?: number }} options
+     */
+    constructor(options = {}) {
+        this.driver = options.driver || 'auto';
+        this.prefix = options.prefix || 'dolphin_persist_';
+        this.ttl = options.ttl || 0; // 0 = no expiry (milliseconds)
+        this._db = null;
+        this._ready = false;
+        this._readyPromise = this._init();
+    }
+
+    async _init() {
+        if (this.driver === 'auto') {
+            this.driver = typeof indexedDB !== 'undefined' ? 'indexeddb' : 'localstorage';
+        }
+
+        if (this.driver === 'indexeddb') {
+            try {
+                await this._openIndexedDB();
+            } catch {
+                console.warn('[DolphinPersist] IndexedDB unavailable, falling back to localStorage');
+                this.driver = 'localstorage';
+            }
+        }
+
+        this._ready = true;
+    }
+
+    _openIndexedDB() {
+        return new Promise((resolve, reject) => {
+            const req = indexedDB.open('dolphin_persist', 1);
+            req.onupgradeneeded = (e) => {
+                const db = e.target.result;
+                if (!db.objectStoreNames.contains('cache')) {
+                    db.createObjectStore('cache', { keyPath: 'key' });
+                }
+            };
+            req.onsuccess = (e) => { this._db = e.target.result; resolve(); };
+            req.onerror = () => reject(req.error);
+        });
+    }
+
+    async set(collection, data) {
+        await this._readyPromise;
+        const entry = {
+            data,
+            savedAt: Date.now(),
+            expiresAt: this.ttl ? Date.now() + this.ttl : null
+        };
+
+        if (this.driver === 'indexeddb') {
+            return new Promise((resolve, reject) => {
+                const tx = this._db.transaction('cache', 'readwrite');
+                tx.objectStore('cache').put({ key: this.prefix + collection, ...entry });
+                tx.oncomplete = resolve;
+                tx.onerror = reject;
+            });
+        } else {
+            try {
+                localStorage.setItem(this.prefix + collection, JSON.stringify(entry));
+            } catch (e) {
+                console.warn('[DolphinPersist] localStorage write failed:', e.message);
+            }
+        }
+    }
+
+    async get(collection) {
+        await this._readyPromise;
+        let entry = null;
+
+        if (this.driver === 'indexeddb') {
+            entry = await new Promise((resolve, reject) => {
+                const tx = this._db.transaction('cache', 'readonly');
+                const req = tx.objectStore('cache').get(this.prefix + collection);
+                req.onsuccess = () => resolve(req.result || null);
+                req.onerror = reject;
+            });
+        } else {
+            try {
+                const raw = localStorage.getItem(this.prefix + collection);
+                entry = raw ? JSON.parse(raw) : null;
+            } catch { entry = null; }
+        }
+
+        if (!entry) return null;
+
+        // TTL check
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            await this.clear(collection);
+            return null;
+        }
+
+        return entry.data;
+    }
+
+    async clear(collection) {
+        await this._readyPromise;
+        if (this.driver === 'indexeddb') {
+            return new Promise((resolve) => {
+                const tx = this._db.transaction('cache', 'readwrite');
+                tx.objectStore('cache').delete(this.prefix + collection);
+                tx.oncomplete = resolve;
+            });
+        } else {
+            localStorage.removeItem(this.prefix + collection);
+        }
+    }
+
+    async clearAll() {
+        await this._readyPromise;
+        if (this.driver === 'indexeddb') {
+            return new Promise((resolve) => {
+                const tx = this._db.transaction('cache', 'readwrite');
+                tx.objectStore('cache').clear();
+                tx.oncomplete = resolve;
+            });
+        } else {
+            const keysToRemove = [];
+            for (let i = 0; i < localStorage.length; i++) {
+                const k = localStorage.key(i);
+                if (k && k.startsWith(this.prefix)) keysToRemove.push(k);
+            }
+            keysToRemove.forEach(k => localStorage.removeItem(k));
+        }
+    }
+
+    /** Check what's cached */
+    async info(collection) {
+        await this._readyPromise;
+        const entry = await this.get(collection);
+        if (!entry) return null;
+        return {
+            collection,
+            items: entry.length,
+            driver: this.driver,
+            savedAt: new Date(entry.savedAt)
+        };
+    }
+}
+
+// ============================================
+// Extend DolphinStore to support persist plugin
+// ============================================
+
+/**
+ * Monkey-patches the DolphinStore to support .use(persist) plugin.
+ * Call this after DolphinClient is loaded.
+ */
+function enablePersist(storeInstance, persist) {
+    const originalFetch = storeInstance._fetchAndSync.bind(storeInstance);
+
+    storeInstance._fetchAndSync = async function(name) {
+        // 1. Load from cache first (instant render)
+        const cached = await persist.get(name);
+        if (cached && cached.length > 0) {
+            storeInstance.data.set(name, cached);
+            storeInstance._notify();
+            console.log(`[DolphinPersist] Loaded "${name}" from ${persist.driver} cache (${cached.length} items)`);
+        }
+
+        // 2. Fetch fresh from server
+        await originalFetch(name);
+
+        // 3. Save updated data to cache
+        const fresh = storeInstance.data.get(name) || [];
+        await persist.set(name, fresh);
+    };
+
+    // Also persist on every realtime update
+    const originalUpdate = storeInstance._handleRemoteUpdate.bind(storeInstance);
+    storeInstance._handleRemoteUpdate = async function(collection, update) {
+        originalUpdate(collection, update);
+        const updated = storeInstance.data.get(collection) || [];
+        await persist.set(collection, updated);
+    };
+
+    console.log(`[DolphinPersist] Persistence enabled using ${persist.driver}`);
+}
+
+// ============================================
+// Exports
+// ============================================
+
+if (typeof window !== 'undefined') {
+    window.DolphinPersist = DolphinPersist;
+    window.enablePersist = enablePersist;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { DolphinPersist, enablePersist };
+}