dolphin-client 1.1.2 → 1.1.4

package/dist/dolphin-client.js

@@ -453,20 +453,178 @@ var DolphinModule = (() => {
   };
 
   // src/store.ts
+  var DataEngine = class {
+    _src = [];
+    _filtered = null;
+    _filters = /* @__PURE__ */ new Map();
+    _sortFn = null;
+    _version = 0;
+    constructor(initialData = []) {
+      this._src = [...initialData];
+    }
+    _invalidate() {
+      this._filtered = null;
+      this._version++;
+    }
+    getVersion() {
+      return this._version;
+    }
+    // ── Filters ──────────────────────────────────────────────
+    /** Text search across fields (case-insensitive) */
+    search(term, fields = []) {
+      if (!term || !term.trim()) {
+        this._filters.delete("__search__");
+      } else {
+        const t = term.trim().toLowerCase();
+        this._filters.set("__search__", (item) => {
+          const keys = fields.length ? fields : Object.keys(item);
+          return keys.some((k) => String(item[k] ?? "").toLowerCase().includes(t));
+        });
+      }
+      this._invalidate();
+      return this;
+    }
+    /** Exact value filter on a field */
+    filter(field, value) {
+      const key = `__filter_${String(field)}__`;
+      if (value === void 0 || value === null || value === "") {
+        this._filters.delete(key);
+      } else {
+        this._filters.set(key, (item) => item[field] === value);
+      }
+      this._invalidate();
+      return this;
+    }
+    /** Numeric range filter */
+    range(field, min, max) {
+      const key = `__range_${String(field)}__`;
+      this._filters.set(key, (item) => {
+        const v = Number(item[field]);
+        return !isNaN(v) && v >= min && v <= max;
+      });
+      this._invalidate();
+      return this;
+    }
+    /** Sort by field ascending or descending */
+    sort(field, asc = true) {
+      this._sortFn = (a, b) => {
+        const va = a[field], vb = b[field];
+        if (va == null && vb == null) return 0;
+        if (va == null) return asc ? 1 : -1;
+        if (vb == null) return asc ? -1 : 1;
+        if (typeof va === "number" && typeof vb === "number") {
+          return asc ? va - vb : vb - va;
+        }
+        return String(va).localeCompare(String(vb)) * (asc ? 1 : -1);
+      };
+      this._invalidate();
+      return this;
+    }
+    /** Clear all filters and sort */
+    clearFilters() {
+      this._filters.clear();
+      this._sortFn = null;
+      this._invalidate();
+      return this;
+    }
+    // ── Data Access ──────────────────────────────────────────
+    /** Get filtered + sorted results (lazy, cached) */
+    get() {
+      if (this._filtered !== null) return this._filtered;
+      let result = this._src;
+      for (const fn of this._filters.values()) {
+        result = result.filter(fn);
+      }
+      if (this._sortFn) {
+        result = [...result].sort(this._sortFn);
+      }
+      this._filtered = result;
+      return result;
+    }
+    /** Paginate the filtered result */
+    page(pageNum = 1, size = 10) {
+      const all = this.get();
+      const start = (pageNum - 1) * size;
+      const pages = Math.ceil(all.length / size);
+      return {
+        data: all.slice(start, start + size),
+        total: all.length,
+        page: pageNum,
+        size,
+        pages,
+        hasNext: pageNum < pages,
+        hasPrev: pageNum > 1
+      };
+    }
+    get length() {
+      return this.get().length;
+    }
+    get total() {
+      return this._src.length;
+    }
+    // ── CRUD ─────────────────────────────────────────────────
+    setSource(newData) {
+      this._src = [...newData];
+      this._invalidate();
+      return this;
+    }
+    add(item) {
+      this._src = [...this._src, item];
+      this._invalidate();
+      return this;
+    }
+    push(...items) {
+      this._src = [...this._src, ...items];
+      this._invalidate();
+      return this;
+    }
+    updateById(id, updates, key = "id") {
+      this._src = this._src.map(
+        (item) => item[key] === id ? { ...item, ...updates } : item
+      );
+      this._invalidate();
+      return this;
+    }
+    removeById(id, key = "id") {
+      this._src = this._src.filter((item) => item[key] !== id);
+      this._invalidate();
+      return this;
+    }
+    remove(predicate) {
+      this._src = this._src.filter((item, i) => !predicate(item, i));
+      this._invalidate();
+      return this;
+    }
+    /** Get raw source (unfiltered) */
+    getSource() {
+      return this._src;
+    }
+  };
   var DolphinStore = class {
     client;
     data;
     listeners;
     subscribed;
-    /** @fix: Store unsubscribe functions so destroy() can clean up WS subscriptions (was: subscriptions never removed) */
+    /** @fix: Store unsubscribe functions so destroy() can clean up WS subscriptions */
     _unsubscribers;
-    /** @param {DolphinClient} client */
+    /** @fix: Race condition guard — tracks in-flight fetches */
+    _fetching;
+    /** Batch notification flag */
+    _batchPending;
+    /** Per-collection DataEngine instances */
+    _engines;
+    /** Per-item loading tracking: collectionName → Set of IDs being processed */
+    _trackingIds;
     constructor(client) {
       this.client = client;
       this.data = /* @__PURE__ */ new Map();
       this.listeners = /* @__PURE__ */ new Set();
       this.subscribed = /* @__PURE__ */ new Set();
       this._unsubscribers = /* @__PURE__ */ new Map();
+      this._fetching = /* @__PURE__ */ new Set();
+      this._batchPending = false;
+      this._engines = /* @__PURE__ */ new Map();
+      this._trackingIds = /* @__PURE__ */ new Map();
       return new Proxy(this, {
         get: (target, prop) => {
           if (prop in target) return target[prop];
@@ -474,9 +632,12 @@ var DolphinModule = (() => {
         }
       });
     }
+    // ── Collection Access ────────────────────────────────────
     /** @private */
     _getCollection(name) {
       if (!this.data.has(name)) {
+        const engine = new DataEngine([]);
+        this._engines.set(name, engine);
         const collection = {
           _rawItems: [],
           items: [],
@@ -485,21 +646,130 @@ var DolphinModule = (() => {
           success: false,
           _filter: null,
           _sort: null,
+          // ── Legacy chainable API (storetutorial.md compatibility) ──
           where: (fn) => {
             collection._filter = fn;
-            this._applyTransform(collection);
+            this._applyTransform(collection, engine);
             return collection;
           },
           orderBy: (key, direction = "asc") => {
             collection._sort = { key, direction };
-            this._applyTransform(collection);
+            this._applyTransform(collection, engine);
             return collection;
           },
           reset: () => {
             collection._filter = null;
             collection._sort = null;
-            this._applyTransform(collection);
+            engine.clearFilters();
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          // ── DataEngine powered API ──
+          search: (term, fields) => {
+            engine.search(term, fields);
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          filter: (field, value) => {
+            engine.filter(field, value);
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          range: (field, min, max) => {
+            engine.range(field, min, max);
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          sort: (field, asc = true) => {
+            engine.sort(field, asc);
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          clearFilters: () => {
+            engine.clearFilters();
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          page: (pageNum = 1, size = 10) => {
+            return engine.page(pageNum, size);
+          },
+          add: (item) => {
+            engine.add(item);
+            collection._rawItems = engine.getSource();
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          updateById: (id, updates, key = "id") => {
+            engine.updateById(id, updates, key);
+            collection._rawItems = engine.getSource();
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          deleteById: (id, key = "id") => {
+            engine.removeById(id, key);
+            collection._rawItems = engine.getSource();
+            this._applyTransform(collection, engine);
+            return collection;
+          },
+          // ── Optimistic Updates ──
+          /**
+           * Instantly removes item from UI, rolls back if API fails.
+           * @example await store.products.optimisticDelete(42, () => client.api.delete('/products/42'))
+           */
+          optimisticDelete: async (id, apiFn, key = "id") => {
+            const snapshot = [...collection._rawItems];
+            engine.removeById(id, key);
+            collection._rawItems = engine.getSource();
+            this._applyTransform(collection, engine);
+            try {
+              await apiFn();
+            } catch (err) {
+              engine.setSource(snapshot);
+              collection._rawItems = snapshot;
+              this._applyTransform(collection, engine);
+              throw err;
+            }
+          },
+          /**
+           * Instantly updates item in UI, rolls back if API fails.
+           * @example await store.products.optimisticUpdate(42, { price: 99 }, () => client.api.put('/products/42', { price: 99 }))
+           */
+          optimisticUpdate: async (id, updates, apiFn, key = "id") => {
+            const snapshot = [...collection._rawItems];
+            engine.updateById(id, updates, key);
+            collection._rawItems = engine.getSource();
+            this._applyTransform(collection, engine);
+            try {
+              await apiFn();
+            } catch (err) {
+              engine.setSource(snapshot);
+              collection._rawItems = snapshot;
+              this._applyTransform(collection, engine);
+              throw err;
+            }
+          },
+          // ── Per-item loading tracking ──
+          /**
+           * Track that a specific item ID is being processed (loading).
+           * @example store.products.trackStart(42) ... store.products.trackEnd(42)
+           */
+          trackStart: (id) => {
+            this._trackStart(name, id);
+            return collection;
+          },
+          trackEnd: (id) => {
+            this._trackEnd(name, id);
             return collection;
+          },
+          /** Returns true if this specific item ID is being processed */
+          isLoading: (id) => {
+            return this._isTracking(name, id);
+          },
+          get length() {
+            return engine.length;
+          },
+          get total() {
+            return engine.total;
           }
         };
         this.data.set(name, collection);
@@ -507,21 +777,70 @@ var DolphinModule = (() => {
       }
       return this.data.get(name);
     }
-    /** @private */
-    async _fetchAndSync(name) {
+    // ── Internal Helpers ─────────────────────────────────────
+    /** 
+     * @private — apply legacy where/orderBy + DataEngine filters.
+     * engine is optional: if not provided (e.g. tests set data manually),
+     * falls back to state._rawItems directly.
+     */
+    _applyTransform(state, engine) {
+      let result = engine ? engine.get() : [...state._rawItems || []];
+      if (state._filter) {
+        result = result.filter(state._filter);
+      }
+      if (state._sort) {
+        const { key, direction } = state._sort;
+        result = [...result].sort((a, b) => {
+          if (a[key] === b[key]) return 0;
+          return (a[key] > b[key] ? 1 : -1) * (direction === "asc" ? 1 : -1);
+        });
+      }
+      state.items = result;
+      this._batchNotify();
+    }
+    /**
+     * @private — Batch multiple rapid store updates into a single DOM notify.
+     * Uses queueMicrotask in production for batching.
+     * In test environments (Jest), calls notify synchronously so assertions work.
+     */
+    _batchNotify() {
+      if (typeof process !== "undefined" && false) {
+        this._notify();
+        return;
+      }
+      if (this._batchPending) return;
+      this._batchPending = true;
+      const schedule = typeof queueMicrotask !== "undefined" ? queueMicrotask : (fn) => Promise.resolve().then(fn);
+      schedule(() => {
+        this._batchPending = false;
+        this._notify();
+      });
+    }
+    /**
+     * @private — Fetch from API and subscribe to WebSocket sync.
+     * @fix Bug 2: _fetching guard prevents race condition / double-fetch.
+     */
+    async _fetchAndSync(name, attempt = 0) {
+      if (this._fetching.has(name)) return;
+      this._fetching.add(name);
       const state = this.data.get(name);
+      const engine = this._engines.get(name);
       try {
         const res = await this.client.api.get(`/${name.toLowerCase()}`);
-        state._rawItems = Array.isArray(res) ? res : res.data || [];
+        const rawItems = Array.isArray(res) ? res : res?.data ?? [];
+        state._rawItems = rawItems;
         state.loading = false;
         state.success = true;
         state.error = null;
-        this._applyTransform(state);
+        engine.setSource(rawItems);
+        this._applyTransform(state, engine);
         if (!this.subscribed.has(name)) {
-          const unsubscribe = () => this.client.unsubscribe(`db:sync/${name.toLowerCase()}`, updateHandler);
           const updateHandler = (update) => {
             this._handleRemoteUpdate(name, update);
           };
+          const unsubscribe = () => {
+            this.client.unsubscribe(`db:sync/${name.toLowerCase()}`, updateHandler);
+          };
           this.client.subscribe(`db:sync/${name.toLowerCase()}`, updateHandler);
           this._unsubscribers.set(name, unsubscribe);
           this.subscribed.add(name);
@@ -529,60 +848,102 @@ var DolphinModule = (() => {
       } catch (e) {
         state.loading = false;
         state.success = false;
-        state.error = e.data?.error || e.message || "Fetch failed";
-        this._notify();
-      }
-    }
-    /** @private */
-    _applyTransform(state) {
-      let result = [...state._rawItems];
-      if (state._filter) result = result.filter(state._filter);
-      if (state._sort) {
-        const { key, direction } = state._sort;
-        result.sort((a, b) => {
-          if (a[key] === b[key]) return 0;
-          return (a[key] > b[key] ? 1 : -1) * (direction === "asc" ? 1 : -1);
-        });
+        state.error = e?.data?.error || e?.message || "Fetch failed";
+        this._batchNotify();
+        if (attempt < 3) {
+          const delay = Math.pow(2, attempt) * 1e3;
+          if (this.client.options?.debug) {
+            console.warn(`[Dolphin Store] Retrying "${name}" in ${delay}ms (attempt ${attempt + 1}/3)`);
+          }
+          setTimeout(() => {
+            this._fetching.delete(name);
+            this._fetchAndSync(name, attempt + 1);
+          }, delay);
+          return;
+        }
+      } finally {
+        if (attempt >= 3 || !state.error) {
+          this._fetching.delete(name);
+        }
       }
-      state.items = result;
-      this._notify();
     }
-    /** @private */
+    // _applyTransform_legacy removed — _applyTransform now handles both cases (engine optional)
+    /** @private — Handle WebSocket real-time update for a collection */
     _handleRemoteUpdate(collection, update) {
       const state = this.data.get(collection);
       if (!state) return;
+      let engine = this._engines.get(collection);
+      if (!engine) {
+        engine = new DataEngine(state._rawItems || []);
+        this._engines.set(collection, engine);
+      } else {
+        if (engine.total !== (state._rawItems || []).length) {
+          engine.setSource(state._rawItems || []);
+        }
+      }
       const { type, data } = update;
-      let items = state._rawItems;
       if (type === "create") {
-        items = [...items, data];
+        engine.push(data);
       } else if (type === "update") {
-        items = items.map((i) => i.id === data.id || i._id === data._id ? { ...i, ...data } : i);
+        const idKey = data.id != null ? "id" : "_id";
+        engine.updateById(data[idKey], data, idKey);
       } else if (type === "delete") {
-        items = items.filter((i) => {
-          if (data.id != null && i.id === data.id) return false;
-          if (data._id != null && i._id === data._id) return false;
-          return true;
-        });
+        if (data.id != null) {
+          engine.removeById(data.id, "id");
+        } else if (data._id != null) {
+          engine.removeById(data._id, "_id");
+        }
+      }
+      state._rawItems = engine.getSource();
+      this._applyTransform(state, engine);
+    }
+    // ── Per-item Loading Tracking ────────────────────────────
+    /** @private */
+    _trackStart(collection, id) {
+      if (!this._trackingIds.has(collection)) {
+        this._trackingIds.set(collection, /* @__PURE__ */ new Set());
       }
-      state._rawItems = items;
-      this._applyTransform(state);
+      this._trackingIds.get(collection).add(id);
+      this._batchNotify();
+    }
+    /** @private */
+    _trackEnd(collection, id) {
+      this._trackingIds.get(collection)?.delete(id);
+      this._batchNotify();
+    }
+    /** @private */
+    _isTracking(collection, id) {
+      return this._trackingIds.get(collection)?.has(id) ?? false;
     }
-    /** Subscribe for React useSyncExternalStore */
+    // ── React useSyncExternalStore compatibility ─────────────
+    /** Subscribe for React useSyncExternalStore or external listeners */
     subscribe(listener) {
       this.listeners.add(listener);
       return () => this.listeners.delete(listener);
     }
-    /** @param {string} collection */
+    /** Get snapshot of a collection (for useSyncExternalStore) */
     getSnapshot(collection) {
-      return this.data.get(collection) || { items: [], loading: false, error: null, success: false };
+      return this.data.get(collection) || {
+        items: [],
+        loading: false,
+        error: null,
+        success: false
+      };
     }
     /** @private */
     _notify() {
-      this.listeners.forEach((l) => l());
+      this.listeners.forEach((l) => {
+        try {
+          l();
+        } catch {
+        }
+      });
     }
+    // ── Cleanup ──────────────────────────────────────────────
     /**
      * Clean up all WebSocket subscriptions and listeners.
      * Call this when the store is no longer needed to prevent resource leaks.
+     * @fix: Properly unsubscribes because updateHandler is now captured correctly.
      */
     destroy() {
       this._unsubscribers.forEach((unsub) => {
@@ -595,6 +956,9 @@ var DolphinModule = (() => {
       this.subscribed.clear();
       this.listeners.clear();
       this.data.clear();
+      this._engines.clear();
+      this._trackingIds.clear();
+      this._fetching.clear();
     }
   };
 
@@ -1381,6 +1745,73 @@ var DolphinModule = (() => {
     };
     clientProto._scanStoreBinds = function() {
       if (typeof document === "undefined") return;
+      const storeElements = document.querySelectorAll("dolphin-store");
+      storeElements.forEach((el) => {
+        if (typeof el.getAttribute !== "function") return;
+        const storeName = el.getAttribute("name") || el.getAttribute("data-store");
+        if (!storeName) return;
+        const hasChildren = el.children && el.children.length > 0;
+        if (hasChildren) {
+          if (typeof el.setAttribute === "function") {
+            el.setAttribute("data-rt-bind", `store/${storeName}`);
+            el.setAttribute("data-rt-type", "context");
+          }
+        } else {
+          if (el.style) {
+            el.style.display = "none";
+          }
+        }
+        if (!hasChildren) {
+          const content = el.textContent ? el.textContent.trim() : "";
+          if (content && content.startsWith("{")) {
+            try {
+              const parsed = JSON.parse(content);
+              if (parsed && typeof parsed === "object") {
+                Object.keys(parsed).forEach((key) => {
+                  this.setStoreState(storeName, key, parsed[key]);
+                });
+              }
+            } catch (err) {
+              console.error(`[Dolphin Store Init Error] Failed to parse JSON inside <dolphin-store name="${storeName}">:`, err);
+            }
+          }
+        }
+        const templateSelector = el.getAttribute("template");
+        if (el.attributes) {
+          const excludeAttrs = ["name", "data-store", "style", "data-rt-bind", "data-rt-type", "template"];
+          Array.from(el.attributes).forEach((attr) => {
+            if (!excludeAttrs.includes(attr.name)) {
+              let val = attr.value;
+              if (val === "true") val = true;
+              else if (val === "false") val = false;
+              else if (val === "null") val = null;
+              else if (!isNaN(Number(val)) && val.trim() !== "") val = Number(val);
+              this.setStoreState(storeName, attr.name, val);
+            }
+          });
+        }
+        if (templateSelector && !hasChildren && el.parentNode && typeof document !== "undefined") {
+          const markerId = `_ds_${storeName}_${templateSelector.replace(/[^a-z0-9]/gi, "_")}`;
+          let wrapper = document.querySelector(`[data-ds-wired="${markerId}"]`);
+          if (!wrapper) {
+            wrapper = document.createElement("div");
+            wrapper.setAttribute("data-rt-bind", `store/${storeName}`);
+            wrapper.setAttribute("data-rt-template", templateSelector);
+            wrapper.setAttribute("data-ds-wired", markerId);
+            el.parentNode.insertBefore(wrapper, el.nextSibling);
+          }
+          if (typeof this._updateDOM === "function") {
+            this.uiStores = this.uiStores || /* @__PURE__ */ new Map();
+            const currentStore = this.uiStores.get(storeName) || {};
+            this._updateDOM(`store/${storeName}`, currentStore);
+          }
+        }
+        if (hasChildren && typeof this._updateDOM === "function") {
+          this.uiStores = this.uiStores || /* @__PURE__ */ new Map();
+          const currentStore = this.uiStores.get(storeName) || {};
+          this._updateDOM(`store/${storeName}`, currentStore);
+        }
+      });
       const writeEls = document.querySelectorAll("[data-store-write]");
       writeEls.forEach((el) => {
         const writeBind = el.getAttribute("data-store-write");
@@ -1463,6 +1894,51 @@ var DolphinModule = (() => {
                 }
               };
             }
+            if (this.store && this.store.data && typeof this.store.data.has === "function" && this.store.data.has(prop)) {
+              const collection = this.store.data.get(prop);
+              const self = this;
+              const collectionName = prop;
+              const RENDER_METHODS = /* @__PURE__ */ new Set([
+                "search",
+                "filter",
+                "range",
+                "sort",
+                "clearFilters",
+                "where",
+                "orderBy",
+                "reset",
+                "add",
+                "updateById",
+                "deleteById",
+                "optimisticDelete",
+                "optimisticUpdate",
+                "trackStart",
+                "trackEnd"
+              ]);
+              return new Proxy(collection, {
+                get(target2, method) {
+                  if (typeof target2[method] === "function") {
+                    return (...args) => {
+                      const result = target2[method](...args);
+                      if (RENDER_METHODS.has(method) && typeof self._updateDOM === "function") {
+                        const triggerRender = () => {
+                          if (typeof self._updateDOM === "function") {
+                            self._updateDOM(`store/${collectionName}`, collection);
+                          }
+                        };
+                        if (result && typeof result.then === "function") {
+                          result.then(triggerRender).catch(triggerRender);
+                        } else {
+                          triggerRender();
+                        }
+                      }
+                      return result;
+                    };
+                  }
+                  return target2[method];
+                }
+              });
+            }
             if (parentCtx && parentCtx[prop] !== void 0) {
               return parentCtx[prop];
             }
@@ -2786,6 +3262,32 @@ var DolphinModule = (() => {
   }
 
   // src/testing.ts
+  function createMockFn() {
+    if (typeof jest !== "undefined" && typeof jest.fn === "function") {
+      return jest.fn();
+    }
+    const fn = (...args) => {
+      fn.mock.calls.push(args);
+      if (fn._implementation) {
+        return fn._implementation(...args);
+      }
+      return fn._returnValue;
+    };
+    fn.mock = {
+      calls: []
+    };
+    fn._returnValue = void 0;
+    fn._implementation = null;
+    fn.mockReturnValue = (val) => {
+      fn._returnValue = val;
+      return fn;
+    };
+    fn.mockImplementation = (impl) => {
+      fn._implementation = impl;
+      return fn;
+    };
+    return fn;
+  }
   var DolphinTestUtils = class {
     static render(html) {
       if (typeof document === "undefined") {
@@ -2812,11 +3314,11 @@ var DolphinModule = (() => {
         send: (data) => {
           sentMessages.push(data);
         },
-        close: jest.fn(),
-        onopen: jest.fn(),
-        onmessage: jest.fn(),
-        onclose: jest.fn(),
-        onerror: jest.fn(),
+        close: createMockFn(),
+        onopen: createMockFn(),
+        onmessage: createMockFn(),
+        onclose: createMockFn(),
+        onerror: createMockFn(),
         sentMessages
       };
       global.WebSocket = class {
@@ -2851,8 +3353,8 @@ var DolphinModule = (() => {
     static simulateClick(el) {
       const clickEvt = {
         target: el,
-        preventDefault: jest.fn(),
-        stopPropagation: jest.fn()
+        preventDefault: createMockFn(),
+        stopPropagation: createMockFn()
       };
       const clickListeners = global.document._listeners?.["click"] || [];
       clickListeners.forEach((listener) => listener(clickEvt));
@@ -2861,8 +3363,8 @@ var DolphinModule = (() => {
       el.value = value;
       const changeEvt = {
         target: el,
-        preventDefault: jest.fn(),
-        stopPropagation: jest.fn()
+        preventDefault: createMockFn(),
+        stopPropagation: createMockFn()
       };
       const changeListeners = global.document._listeners?.["change"] || [];
       changeListeners.forEach((listener) => listener(changeEvt));