@geolonia/geonicdb-sdk 0.3.0 → 0.5.0

package/geonicdb.iife.js

@@ -180,6 +180,8 @@ var GeonicDBModule = (() => {
   var RECONNECT_BASE_MS = 1e3;
   var RECONNECT_MAX_DELAY_MS = 3e4;
   var SUB_PROTOCOL = "access_token";
+  var SDK_CACHE_MAX_ENTRIES_DEFAULT = 1e3;
+  var SDK_POLL_INTERVAL_MS_DEFAULT = 5e3;
 
   // src/sdk/errors.ts
   var GeonicDBError = class extends Error {
@@ -256,6 +258,93 @@ var GeonicDBModule = (() => {
     }
   }
 
+  // src/sdk/cache.ts
+  var SdkCache = class {
+    constructor(maxEntries = SDK_CACHE_MAX_ENTRIES_DEFAULT) {
+      __publicField(this, "_store", /* @__PURE__ */ new Map());
+      __publicField(this, "_maxEntries");
+      if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+        throw new Error(`SdkCache maxEntries must be a positive integer, got ${String(maxEntries)}`);
+      }
+      this._maxEntries = maxEntries;
+    }
+    /** Build a stable cache key. Method is upper-cased so casing differences do not produce duplicate entries. */
+    static keyFor(method, path) {
+      return `${method.toUpperCase()}:${path}`;
+    }
+    /** Returns the entry and bumps it to most-recent position, or `undefined`. */
+    get(key) {
+      const entry = this._store.get(key);
+      if (!entry) return void 0;
+      this._store.delete(key);
+      this._store.set(key, entry);
+      return entry;
+    }
+    /** Insert or replace an entry. Evicts the LRU entry when over capacity. */
+    set(key, entry) {
+      if (this._store.has(key)) {
+        this._store.delete(key);
+      }
+      this._store.set(key, entry);
+      while (this._store.size > this._maxEntries) {
+        const oldest = this._store.keys().next().value;
+        if (oldest === void 0) break;
+        this._store.delete(oldest);
+      }
+    }
+    /** Delete a specific entry. Returns whether anything was removed. */
+    delete(key) {
+      return this._store.delete(key);
+    }
+    /**
+     * Delete every entry whose key matches a predicate. Returns the array of
+     * removed keys so callers can emit `cacheInvalidated` events.
+     */
+    deleteWhere(predicate) {
+      const removed = [];
+      for (const [key, entry] of this._store) {
+        if (predicate(key, entry)) {
+          this._store.delete(key);
+          removed.push(key);
+        }
+      }
+      return removed;
+    }
+    /** Drop everything. */
+    clear() {
+      this._store.clear();
+    }
+    /** Current entry count. Useful for tests / metrics. */
+    size() {
+      return this._store.size;
+    }
+  };
+  var HEADERS_TO_PERSIST = [
+    "content-type",
+    "etag",
+    "last-modified",
+    "cache-control",
+    "vary",
+    "link",
+    "ngsild-results-count",
+    "fiware-total-count",
+    "x-total-count",
+    "ngsild-next",
+    "fiware-next-token"
+  ];
+  function snapshotHeaders(headers) {
+    const out = {};
+    for (const name of HEADERS_TO_PERSIST) {
+      const value = headers.get(name);
+      if (value !== null) out[name] = value;
+    }
+    return out;
+  }
+  function isCacheableMethod(method) {
+    const upper = method.toUpperCase();
+    return upper === "GET" || upper === "HEAD";
+  }
+
   // src/sdk/auth.ts
   var _AuthManager = class _AuthManager {
     constructor(baseUrl, apiKey, tenant, debug = false) {
@@ -273,6 +362,16 @@ var GeonicDBModule = (() => {
       __publicField(this, "_tokenPromise", null);
       /** Callback to emit tokenRefresh events. Set by GeonicDB class. */
       __publicField(this, "onTokenRefresh", null);
+      /**
+       * SDK-level cache (#991 Phase A). When set, cacheable GET requests are
+       * served via ETag/304 with automatic If-None-Match negotiation, and
+       * concurrent requests to the same path are deduplicated.
+       */
+      __publicField(this, "_cache", null);
+      /** Emitter for cacheHit / cacheMiss / cacheInvalidated events. */
+      __publicField(this, "_emitCacheEvent", null);
+      /** In-flight request map keyed by `${METHOD}:${path}` for request deduplication. */
+      __publicField(this, "_inFlight", /* @__PURE__ */ new Map());
       this._baseUrl = baseUrl;
       this._apiKey = apiKey;
       this._tenant = tenant;
@@ -288,6 +387,22 @@ var GeonicDBModule = (() => {
     _log(...args) {
       if (this._debug) console.log("[GeonicDB]", ...args);
     }
+    /** Wire an SdkCache instance (called by GeonicDB constructor when caching is enabled). */
+    setCache(cache) {
+      this._cache = cache;
+    }
+    /** Provide the cache event emitter (forwarded to the GeonicDB EventEmitter). */
+    setCacheEventEmitter(emitter) {
+      this._emitCacheEvent = emitter;
+    }
+    /** Expose the cache for invalidation (e.g. WebSocket entity events). */
+    getCache() {
+      return this._cache;
+    }
+    /** Emit a cache event if a listener is wired. */
+    emitCacheEvent(name, payload) {
+      this._emitCacheEvent?.(name, payload);
+    }
     /** Login with email and password (Bearer JWT). */
     async login(email, password) {
       this._log("login", email);
@@ -311,6 +426,7 @@ var GeonicDBModule = (() => {
       this._tokenExpiry = Date.now() + (data.expiresIn - 60) * 1e3;
       this._tokenType = "Bearer";
       this._refreshToken = data.refreshToken;
+      this._invalidateAuthScopedState();
       return data;
     }
     /**
@@ -325,6 +441,7 @@ var GeonicDBModule = (() => {
       this._tokenExpiry = opts.expiresIn != null ? Date.now() + (opts.expiresIn - 60) * 1e3 : Date.now() + DEFAULT_TOKEN_TTL_SEC * 1e3;
       this._refreshToken = opts.refreshToken || null;
       this._tokenPromise = null;
+      this._invalidateAuthScopedState();
     }
     /** Clear all credentials. */
     logout() {
@@ -332,6 +449,17 @@ var GeonicDBModule = (() => {
       this._tokenExpiry = 0;
       this._refreshToken = null;
       this._tokenPromise = null;
+      this._invalidateAuthScopedState();
+    }
+    /**
+     * Drop everything that may have been associated with the previous auth
+     * context. Called on `login()` (after token assignment), `setCredentials()`,
+     * and `logout()`. Without this, a cached body or in-flight Response from
+     * user A could be returned to user B after a credentials swap.
+     */
+    _invalidateAuthScopedState() {
+      this._cache?.clear();
+      this._inFlight.clear();
     }
     /** Ensure a valid token is available, refreshing or acquiring as needed. */
     async ensureToken() {
@@ -451,15 +579,89 @@ var GeonicDBModule = (() => {
     }
     /**
      * Make an authenticated HTTP request with automatic token refresh and DPoP.
+     *
+     * When the SDK cache is enabled and the request is cacheable
+     * (GET / HEAD without a body), this method:
+     *   - Sends `If-None-Match` / `If-Modified-Since` derived from a previously
+     *     cached entry, if any.
+     *   - Returns the cached body wrapped in a synthesized `200` Response when
+     *     the server replies `304 Not Modified`.
+     *   - Persists fresh `200` responses (with their ETag/Last-Modified) into
+     *     the cache.
+     *   - Deduplicates concurrent in-flight requests to the same path.
      */
     async request(method, path, body) {
       this._log(method, path);
+      if (!this._cache || !isCacheableMethod(method) || body !== void 0) {
+        const token = await this.ensureToken();
+        const res = await this._doAuthenticatedRequest(method, path, body, token);
+        this._log(method, path, "\u2192", res.status);
+        return res;
+      }
+      const key = SdkCache.keyFor(method, path);
+      const inFlight = this._inFlight.get(key);
+      if (inFlight) {
+        return inFlight.then((res) => res.clone());
+      }
+      const promise = this._cachedRequest(method, path, key);
+      this._inFlight.set(key, promise);
+      try {
+        return await promise;
+      } finally {
+        this._inFlight.delete(key);
+      }
+    }
+    async _cachedRequest(method, path, key) {
+      const cache = this._cache;
+      if (!cache) {
+        const token2 = await this.ensureToken();
+        return this._doAuthenticatedRequest(method, path, void 0, token2);
+      }
+      const cached = cache.get(key);
+      const conditional = {};
+      if (cached?.etag) conditional["If-None-Match"] = cached.etag;
+      if (cached?.lastModified) conditional["If-Modified-Since"] = cached.lastModified;
       const token = await this.ensureToken();
-      const res = await this._doAuthenticatedRequest(method, path, body, token);
+      const res = await this._doAuthenticatedRequest(method, path, void 0, token, 0, conditional);
       this._log(method, path, "\u2192", res.status);
+      if (res.status === 304 && cached) {
+        const refreshedHeaders = { ...cached.headers, ...snapshotHeaders(res.headers) };
+        const refreshedEtag = res.headers.get("etag") ?? cached.etag;
+        const refreshedLastModified = res.headers.get("last-modified") ?? cached.lastModified;
+        cache.set(key, {
+          ...cached,
+          etag: refreshedEtag,
+          lastModified: refreshedLastModified,
+          headers: refreshedHeaders,
+          cachedAt: Date.now()
+        });
+        this.emitCacheEvent("cacheHit", { key, path });
+        const body = typeof cached.data === "string" ? cached.data : JSON.stringify(cached.data);
+        return new Response(body, { status: 200, headers: refreshedHeaders });
+      }
+      if (res.status === 200) {
+        const etag = res.headers.get("etag") ?? void 0;
+        const lastModified = res.headers.get("last-modified") ?? void 0;
+        if (etag || lastModified) {
+          const text = await res.clone().text();
+          let data = text;
+          try {
+            data = JSON.parse(text);
+          } catch {
+          }
+          cache.set(key, {
+            etag,
+            lastModified,
+            data,
+            headers: snapshotHeaders(res.headers),
+            cachedAt: Date.now()
+          });
+          this.emitCacheEvent("cacheMiss", { key, path });
+        }
+      }
       return res;
     }
-    async _doAuthenticatedRequest(method, path, body, token, retryCount = 0) {
+    async _doAuthenticatedRequest(method, path, body, token, retryCount = 0, extraHeaders = {}) {
       const url = this._baseUrl + path;
       const isDPoP = this._tokenType === "DPoP" && !!this._dpopKeyPair;
       const bodyStr = body !== void 0 ? JSON.stringify(body) : void 0;
@@ -475,7 +677,8 @@ var GeonicDBModule = (() => {
         const headers = {
           Authorization: (reqIsDPoP ? "DPoP " : "Bearer ") + reqToken,
           "Content-Type": "application/ld+json",
-          Accept: "application/ld+json"
+          Accept: "application/ld+json",
+          ...extraHeaders
         };
         if (dpopProof) headers["DPoP"] = dpopProof;
         if (this._tenant) headers["Fiware-Service"] = this._tenant;
@@ -511,7 +714,7 @@ var GeonicDBModule = (() => {
         if (retryNonce) this._dpopNonce = retryNonce;
         const delay = parseInt(res.headers.get("Retry-After") || "1", 10) * 1e3;
         await new Promise((resolve) => setTimeout(resolve, delay));
-        return this._doAuthenticatedRequest(method, path, body, currentToken, retryCount + 1);
+        return this._doAuthenticatedRequest(method, path, body, currentToken, retryCount + 1, extraHeaders);
       }
       return res;
     }
@@ -787,14 +990,37 @@ var GeonicDBModule = (() => {
         this.onTokenRefresh?.(creds);
         this.emit("tokenRefresh", creds);
       };
+      if (opts.cache !== false) {
+        const cache = new SdkCache(opts.cacheMaxEntries ?? SDK_CACHE_MAX_ENTRIES_DEFAULT);
+        this._auth.setCache(cache);
+        this._auth.setCacheEventEmitter((name, payload) => this.emit(name, payload));
+      }
       this._ws = new WebSocketManager(
         this._auth,
         baseUrl,
         tenant,
-        (event, data) => this.emit(event, data),
+        (event, data) => {
+          this.emit(event, data);
+        },
         opts.wsEndpoint
       );
     }
+    /**
+     * Drop every cached response. Useful in tests and on manual auth changes.
+     *
+     * Emits a `cacheInvalidated` event for each removed entry so listeners can
+     * track explicit flushes (the WebSocket-driven auto-invalidation was removed
+     * in #1060 to preserve the ETag/304 revalidation path; `clearCache()` is now
+     * the only path that emits this event).
+     */
+    clearCache() {
+      const cache = this._auth.getCache();
+      if (!cache) return;
+      const removed = cache.deleteWhere(() => true);
+      for (const key of removed) {
+        this._auth.emitCacheEvent("cacheInvalidated", { key, path: key.split(":").slice(1).join(":") });
+      }
+    }
     // --- Authentication ---
     /** Login with email and password (Bearer JWT). */
     async login(email, password) {
@@ -837,25 +1063,82 @@ var GeonicDBModule = (() => {
     }
     /** Query entities with optional filters. */
     async getEntities(params) {
-      let qs = "";
-      if (params) {
-        const parts = [];
-        if (params.type) parts.push("type=" + encodeURIComponent(params.type));
-        if (params.limit != null) parts.push("limit=" + params.limit);
-        if (params.offset != null) parts.push("offset=" + params.offset);
-        if (params.q) parts.push("q=" + encodeURIComponent(params.q));
-        if (parts.length) qs = "?" + parts.join("&");
-      }
-      const res = await this._auth.request(
-        "GET",
-        "/ngsi-ld/v1/entities" + qs
-      );
+      const res = await this._auth.request("GET", buildEntitiesPath(params));
       if (!res.ok) {
         const e = await res.json().catch(() => ({}));
         throw createErrorFromResponse(res.status, e, "Query failed");
       }
       return await res.json();
     }
+    /**
+     * Poll for entity list changes using ETag-based revalidation (#991 Phase A).
+     *
+     * The handle's `stop()` ends the loop. Each tick performs a normal
+     * `getEntities()` call; the SDK's cache layer issues `If-None-Match`
+     * automatically. The poll detects "no change" by comparing the previous
+     * ETag with the response's ETag (the cache exposes the cached ETag on 304
+     * replays as well, so the comparison stays valid in both 200 and 304
+     * paths).
+     *
+     * @example
+     * ```typescript
+     * const handle = db.poll({ type: 'Room' }, {
+     *   interval: 5000,
+     *   onData: (rooms) => render(rooms),
+     *   onNoChange: () => {},
+     * });
+     * // ...later
+     * handle.stop();
+     * ```
+     */
+    poll(params, options) {
+      const interval = options.interval ?? SDK_POLL_INTERVAL_MS_DEFAULT;
+      if (!Number.isFinite(interval) || interval <= 0) {
+        throw new Error(`poll interval must be a positive number (got ${String(interval)})`);
+      }
+      let stopped = false;
+      let timer = null;
+      let prevEtag;
+      let prevPath;
+      const buildPath = () => buildEntitiesPath(params);
+      const tick = async () => {
+        if (stopped) return;
+        try {
+          const path = prevPath ?? (prevPath = buildPath());
+          const res = await this._auth.request("GET", path);
+          if (stopped) return;
+          const etag = res.headers.get("etag") ?? void 0;
+          if (prevEtag !== void 0 && etag !== void 0 && prevEtag === etag) {
+            options.onNoChange?.();
+          } else {
+            if (!res.ok) {
+              throw createErrorFromResponse(res.status, {}, "Poll request failed");
+            }
+            const data = await res.json();
+            prevEtag = etag;
+            options.onData?.(data);
+          }
+        } catch (err) {
+          options.onError?.(err);
+        } finally {
+          if (!stopped) {
+            timer = setTimeout(() => {
+              void tick();
+            }, interval);
+          }
+        }
+      };
+      void tick();
+      return {
+        stop() {
+          stopped = true;
+          if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+          }
+        }
+      };
+    }
     /** Count entities matching the given filters. */
     async count(params) {
       const parts = ["count=true", "limit=0"];
@@ -1054,6 +1337,15 @@ var GeonicDBModule = (() => {
   if (typeof window !== "undefined") {
     window.GeonicDB = GeonicDB;
   }
+  function buildEntitiesPath(params) {
+    if (!params) return "/ngsi-ld/v1/entities";
+    const parts = [];
+    if (params.type) parts.push("type=" + encodeURIComponent(params.type));
+    if (params.limit != null) parts.push("limit=" + params.limit);
+    if (params.offset != null) parts.push("offset=" + params.offset);
+    if (params.q) parts.push("q=" + encodeURIComponent(params.q));
+    return parts.length > 0 ? "/ngsi-ld/v1/entities?" + parts.join("&") : "/ngsi-ld/v1/entities";
+  }
   return __toCommonJS(index_exports);
 })();
 if(typeof window!=="undefined"){window.GeonicDB=GeonicDBModule.GeonicDB||GeonicDBModule.default}