@geolonia/geonicdb-sdk 0.3.0 → 0.5.0

package/README.md

@@ -176,6 +176,71 @@ await db.connect();
 | `reconnecting` | `{ attempt, delay }` | Auto-reconnect starting |
 | `error` | `Error` | Error occurred |
 | `tokenRefresh` | `RefreshedCredentials` | Bearer token was refreshed |
+| `cacheHit` | `CacheEvent` | Request served from in-memory cache (304 received) |
+| `cacheMiss` | `CacheEvent` | Cache miss — fresh response fetched from origin |
+| `cacheInvalidated` | `CacheEvent` | Cache entry dropped via explicit `clearCache()`. WebSocket entity events do **not** trigger cache invalidation — see "Client-side Cache & Polling" |
+
+## Client-side Cache & Polling
+
+The SDK includes an in-memory cache that handles `ETag` / `If-None-Match`
+negotiation transparently. Subsequent reads of an unchanged resource are
+served as `304 Not Modified` — the SDK presents them to your code as a normal
+`200` response with the cached body.
+
+```typescript
+// First call: fresh fetch, ETag stored
+const rooms1 = await db.getEntities({ type: 'Room' });
+
+// Second call: server returns 304, SDK returns the cached body
+const rooms2 = await db.getEntities({ type: 'Room' });
+
+// Concurrent calls to the same path are deduplicated:
+const [a, b, c] = await Promise.all([
+  db.getEntities({ type: 'Room' }),
+  db.getEntities({ type: 'Room' }),
+  db.getEntities({ type: 'Room' }),
+]);  // → only one HTTP request hits the network
+```
+
+Cache is enabled by default; pass `cache: false` to opt out.
+
+### Cache lifetime under WebSocket activity
+
+WebSocket entity events (`entityCreated` / `entityUpdated` / `entityDeleted`)
+do **not** automatically invalidate the SDK cache. This is intentional:
+
+- Data endpoints respond with `Cache-Control: private, no-cache`, so every
+  cached read already revalidates with the origin via `If-None-Match`.
+- If the entity actually changed, the server's freshly computed `ETag` will
+  not match the client's `If-None-Match` → server returns `200` with the
+  fresh body → SDK replaces the cache entry.
+- If the WebSocket event was noisy / unrelated to a particular cached query
+  (or the data hasn't propagated to the read replica yet), the server returns
+  `304 Not Modified` → SDK serves the cached body with no body bytes
+  transferred.
+
+Deleting cache entries on every WebSocket event would force the next read to
+miss the cache and fetch a full `200` body — defeating the bandwidth-saving
+`304` path. To force a full reset (e.g. on auth change), call `clearCache()`
+explicitly.
+
+### Polling
+
+`db.poll(params, options)` repeats `getEntities()` at an interval and reports
+back whether the data actually changed. Internally it leverages the cache's
+ETag negotiation, so unchanged ticks transfer almost no bytes.
+
+```typescript
+const handle = db.poll({ type: 'Room' }, {
+  interval: 5000,
+  onData: (rooms) => render(rooms),
+  onNoChange: () => {},  // server returned 304
+  onError: (err) => console.error(err),
+});
+
+// Stop later
+handle.stop();
+```
 
 ## API Reference
 
@@ -194,6 +259,8 @@ await db.connect();
 | `baseUrl` | `string` | No | API base URL (auto-detected from script `src` if omitted) |
 | `wsEndpoint` | `string` | No | WebSocket endpoint URL (auto-detected from `baseUrl` if omitted) |
 | `debug` | `boolean` | No | Enable debug logging to console (default: `false`) |
+| `cache` | `boolean` | No | Enable in-memory cache with ETag/304 + request dedup (default: `true`) |
+| `cacheMaxEntries` | `number` | No | LRU cache capacity when `cache` is enabled (default: `1000`) |
 
 ### Authentication
 
@@ -278,6 +345,35 @@ await db.connect();
 | `request(method, path, body?)` | `string, string, unknown` | `Promise<unknown>` | Authenticated request with automatic JSON parsing |
 | `requestRaw(method, path, body?)` | `string, string, unknown` | `Promise<Response>` | Authenticated request returning raw `Response` (for accessing headers) |
 
+### Cache & Polling
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `poll(params, options)` | `GetEntitiesParams \| undefined, PollOptions<T>` | `PollHandle` | ETag-based polling — fires `onData` only when the data actually changes. `options` is **required** (`onData` must be specified to receive data) |
+| `clearCache()` | — | `void` | Drop all cached responses |
+
+#### `PollOptions<T>`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `interval` | `number` | Polling interval in milliseconds (default: `5000`) |
+| `onData` | `(data: T) => void` | Called whenever the server returns fresh data (200) |
+| `onNoChange` | `() => void` | Called when the server returns 304 Not Modified |
+| `onError` | `(err: Error) => void` | Called on any fetch/parse failure |
+
+#### `PollHandle`
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `stop()` | — | `void` | Stop the polling timer |
+
+#### `CacheEvent`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | `string` | Cache key (`METHOD:path`) |
+| `path` | `string` | Request path |
+
 ### WebSocket
 
 | Method | Parameters | Returns | Description |

package/geonicdb.cjs

@@ -180,6 +180,8 @@ var RECONNECT_MAX_ATTEMPTS = 10;
 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 @@ function createErrorFromResponse(status, body, fallbackMessage) {
   }
 }
 
+// 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 _AuthManager = class _AuthManager {
     __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 _AuthManager = class _AuthManager {
   _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 _AuthManager = class _AuthManager {
     this._tokenExpiry = Date.now() + (data.expiresIn - 60) * 1e3;
     this._tokenType = "Bearer";
     this._refreshToken = data.refreshToken;
+    this._invalidateAuthScopedState();
     return data;
   }
   /**
@@ -325,6 +441,7 @@ var _AuthManager = class _AuthManager {
     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 _AuthManager = class _AuthManager {
     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 _AuthManager = class _AuthManager {
   }
   /**
    * 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 _AuthManager = class _AuthManager {
       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 _AuthManager = class _AuthManager {
       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 GeonicDB = class extends EventEmitter {
       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 GeonicDB = class extends EventEmitter {
   }
   /** 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,4 +1337,13 @@ var index_default = GeonicDB;
 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";
+}
 //# sourceMappingURL=geonicdb.cjs.map