@geolonia/geonicdb-sdk 0.11.1 → 0.13.0

package/README.md

@@ -326,6 +326,38 @@ const [a, b, c] = await Promise.all([
 
 Cache is enabled by default; pass `cache: false` to opt out.
 
+### Persistence across reloads
+
+In the browser the cache (validators + bodies) is **persisted to IndexedDB** so
+it survives a page reload. A reloaded SPA can therefore send `If-None-Match` on
+its very first request and get a `304` instead of always cold-starting into a
+full `200` body.
+
+```typescript
+// First load: fetched in full and saved to IndexedDB.
+await db.getEntities({ type: 'AedLocation' });
+
+// After a page reload, restore the session — the cache rehydrates with it:
+if (await db.restoreSession()) {
+  await db.getEntities({ type: 'AedLocation' });
+  // → If-None-Match sent; unchanged data comes back as 304 (near-zero bytes).
+}
+```
+
+- Persistence is tied to `rememberSession`: it is active only for sessions that
+  themselves survive a reload (`login({ rememberSession: true })` →
+  `restoreSession()`), sharing the exact lifecycle of the persisted DPoP session.
+- Entries are namespaced by tenant **and authenticated principal**, so a
+  different subject sharing the same origin/tenant (another tab, another SDK
+  instance, a later login) never reads entries written by a previous principal.
+  They are dropped on every credential change (`login()`, `setCredentials()`,
+  `logout()`) and only read back by the same principal that wrote them, via
+  `restoreSession()`.
+- Capacity / LRU follow `cacheMaxEntries`, the same as the in-memory cache.
+- In non-browser runtimes (Node, CLI) without IndexedDB the cache stays
+  in-memory only — fully backward compatible.
+- `clearCache()` flushes the persisted store as well as the in-memory cache.
+
 ### Cache lifetime under WebSocket activity
 
 WebSocket entity events (`entityCreated` / `entityUpdated` / `entityDeleted`)
@@ -558,6 +590,55 @@ try {
 | `RateLimitError` | 429 | Rate limited (`retryAfter` property) |
 | `NetworkError` | — | Fetch failure, DNS error, timeout |
 
+## React Hooks (`@geolonia/geonicdb-sdk/react`)
+
+Optional React integration, shipped as a separate subpath so the core SDK stays
+framework-agnostic. Requires React 18 or 19 (declared as an **optional peer
+dependency** — core consumers are unaffected).
+
+```tsx
+import GeonicDB from '@geolonia/geonicdb-sdk';
+import { useLdEntities, useTemporalData, GeonicDbMap } from '@geolonia/geonicdb-sdk/react';
+
+const db = new GeonicDB({ baseUrl, tenant });
+
+function Rooms() {
+  const { entities, loading, error, refetch } = useLdEntities(db, { type: 'Room', limit: 100 });
+  if (loading) return <p>Loading…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <GeonicDbMap entities={entities} apiKey="YOUR-GEOLONIA-KEY" />;
+}
+```
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useLdEntities(client, options?)` | hook | NGSI-LD エンティティ取得。`{ entities, loading, error, refetch }` を返す。`options`: `type` / `limit` / `attrs` / `q` / `scopeQ` |
+| `useTemporalData(client, options)` | hook | Temporal API 取得。`{ data, loading, error, refetch }` を返す。`options.id` 指定時は単一エンティティ、`options.enabled === false` で取得スキップ |
+| `GeonicDbMap` | component | Geolonia 地図にエンティティをマーカー描画。`@geolonia/embed`（optional peer）を動的 import |
+
+両 hook は in-flight リクエストを世代管理しており、`options` 変更やアンマウント時に古いレスポンスが新しい結果を上書きしない。`GeonicDbMap` のポップアップは `entity.id` / `entity.type` を HTML エスケープして描画する。
+
+## NGSIv2 Client (`@geolonia/geonicdb-sdk/ngsi-v2`)
+
+NGSIv2 (`/v2/entities`) を叩く軽量クライアント。NGSI-LD を使うコア SDK とは独立した
+サブパスで、NGSIv2 のみを使う利用者向け。
+
+```ts
+import { createNgsiV2Client } from '@geolonia/geonicdb-sdk/ngsi-v2';
+
+const client = createNgsiV2Client({ baseUrl: 'https://geonicdb.example.com', apiKey: 'KEY', service: 'mytenant' });
+const rooms = await client.getEntities({ type: 'Room', limit: 20 });
+```
+
+| Method | Description |
+|--------|-------------|
+| `createNgsiV2Client(config)` | `NgsiV2Client` を生成。`config`: `baseUrl`（必須）/ `apiKey` / `service` |
+| `getEntities(options?)` | エンティティ一覧（`type` / `q` / `limit` / `offset` / `attrs` / `options`） |
+| `getEntity(id, options?)` | 単一エンティティ取得 |
+| `createEntity(entity)` | エンティティ作成 |
+| `updateEntityAttributes(id, attrs)` | 属性の部分更新 |
+| `deleteEntity(id)` | エンティティ削除 |
+
 ## License
 
 MIT

package/geonicdb.cjs

@@ -85,6 +85,9 @@ var SDK_POLL_INTERVAL_MS_DEFAULT = 5e3;
 var DPOP_IDB_NAME = "geonicdb-sdk";
 var DPOP_IDB_STORE = "dpop-sessions";
 var DPOP_IDB_VERSION = 1;
+var SDK_CACHE_IDB_NAME = "geonicdb-sdk-cache";
+var SDK_CACHE_IDB_STORE = "responses";
+var SDK_CACHE_IDB_VERSION = 1;
 
 // src/sdk/dpop.ts
 var dpopSupported = typeof crypto !== "undefined" && !!crypto.subtle && !!crypto.subtle.generateKey;
@@ -364,11 +367,97 @@ var SdkCache = class {
   constructor(maxEntries = SDK_CACHE_MAX_ENTRIES_DEFAULT) {
     __publicField(this, "_store", /* @__PURE__ */ new Map());
     __publicField(this, "_maxEntries");
+    /**
+     * Optional persistent backing store (IndexedDB) so cached validators survive
+     * a page reload (#1262). `null` in non-browser runtimes — the cache then
+     * behaves as a pure in-memory LRU.
+     */
+    __publicField(this, "_persistence", null);
+    /**
+     * Auth-scope namespace for persisted entries. The auth layer sets this to a
+     * tenant + authenticated-principal identifier so that entries written by one
+     * principal are never read back by another sharing the same origin/tenant
+     * (different tabs / SDK instances each scope to their own principal).
+     */
+    __publicField(this, "_scope", "");
+    /**
+     * Whether write-through persistence is currently active. Driven by the auth
+     * layer: enabled only for remembered sessions, so persisted entries belong to
+     * exactly one principal and are dropped on every credential change.
+     */
+    __publicField(this, "_persistEnabled", false);
+    /**
+     * Serialises persistence writes so they complete in call order (#1262
+     * review). `set`/`delete`/`clearPersisted` are otherwise independent
+     * fire-and-forget ops; if a late `put()` resolved after a `remove()` /
+     * `clearScope()`, an evicted/deleted/logged-out entry could reappear in
+     * IndexedDB. Chaining them keeps the persisted store consistent with the
+     * in-memory state and with the auth-boundary flush.
+     */
+    __publicField(this, "_persistQueue", Promise.resolve());
     if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
       throw new Error(`SdkCache maxEntries must be a positive integer, got ${String(maxEntries)}`);
     }
     this._maxEntries = maxEntries;
   }
+  /** Wire a persistence backend (called once at construction when available). */
+  attachPersistence(persistence) {
+    this._persistence = persistence;
+  }
+  /** Whether a persistence backend is attached. */
+  hasPersistence() {
+    return this._persistence !== null;
+  }
+  /** Set the auth-scope namespace used for persisted reads/writes. */
+  setScope(scope) {
+    this._scope = scope;
+  }
+  /** Enable or disable write-through persistence (driven by `rememberSession`). */
+  setPersistEnabled(enabled) {
+    this._persistEnabled = enabled && this._persistence !== null;
+  }
+  /** True when set/delete should propagate to the persistent store. */
+  get _persisting() {
+    return this._persistEnabled && this._persistence !== null;
+  }
+  /**
+   * Append a persistence operation to the serialised queue. The backend and
+   * scope are captured at enqueue time so a later scope change cannot retarget
+   * an already-queued op. A failing op is swallowed (persistence is
+   * best-effort) and does not stall the chain. Returns the tail so callers that
+   * need ordering (`clearPersisted`) can await it.
+   */
+  _enqueuePersist(op) {
+    const persistence = this._persistence;
+    if (!persistence) return this._persistQueue;
+    const scope = this._scope;
+    this._persistQueue = this._persistQueue.catch(() => void 0).then(() => op(persistence, scope)).catch(() => void 0);
+    return this._persistQueue;
+  }
+  /**
+   * Load persisted entries for the current scope into memory, oldest first so
+   * the in-memory LRU recency order is preserved. Best-effort and idempotent —
+   * a no-op when no backend is attached. Called after a remembered session is
+   * restored so the very first request after a reload can send `If-None-Match`.
+   */
+  async hydrate() {
+    if (!this._persistence) return;
+    const entries = await this._persistence.loadScope(this._scope, this._maxEntries);
+    for (const { key, entry } of entries) {
+      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);
+    }
+  }
+  /** Drop every persisted entry for the current scope (auth change / flush). */
+  async clearPersisted() {
+    if (!this._persistence) return;
+    await this._enqueuePersist((persistence, scope) => persistence.clearScope(scope));
+  }
   /** 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}`;
@@ -387,15 +476,27 @@ var SdkCache = class {
       this._store.delete(key);
     }
     this._store.set(key, entry);
+    const evicted = [];
     while (this._store.size > this._maxEntries) {
       const oldest = this._store.keys().next().value;
       if (oldest === void 0) break;
       this._store.delete(oldest);
+      evicted.push(oldest);
+    }
+    if (this._persisting) {
+      void this._enqueuePersist(async (persistence, scope) => {
+        await persistence.put(scope, key, entry);
+        if (evicted.length > 0) await persistence.remove(scope, evicted);
+      });
     }
   }
   /** Delete a specific entry. Returns whether anything was removed. */
   delete(key) {
-    return this._store.delete(key);
+    const removed = this._store.delete(key);
+    if (removed && this._persisting) {
+      void this._enqueuePersist((persistence, scope) => persistence.remove(scope, [key]));
+    }
+    return removed;
   }
   /**
    * Delete every entry whose key matches a predicate. Returns the array of
@@ -533,6 +634,49 @@ var _AuthManager = class _AuthManager {
   /** Wire an SdkCache instance (called by GeonicDB constructor when caching is enabled). */
   setCache(cache) {
     this._cache = cache;
+    cache?.setScope(this._cacheScope());
+  }
+  /**
+   * #1262: persistence scope for the SDK cache — tenant + authenticated
+   * principal (email when available). Keying on the principal, not just the
+   * tenant, prevents a different subject sharing the same origin/tenant (another
+   * tab, another SDK instance, a later login) from reading entries written by a
+   * previous principal. The principal segment is empty for sessions without a
+   * known email; such sessions never persist (persistence is gated on a
+   * remembered DPoP session that always carries an email), so the empty segment
+   * is not reachable as a write scope in practice.
+   */
+  _cacheScope() {
+    return `${this._tenant}
${this._email ?? ""}`;
+  }
+  /**
+   * #1262: enable write-through persistence for the SDK cache so it survives a
+   * reload. Always re-scopes to the current tenant + principal first.
+   *
+   * `clearFirst` drops any persisted entries left by a previous session of the
+   * same principal — used on a fresh `login()`. It is `false` on
+   * `restoreSession()`, where the persisted entries belong to the very session
+   * being restored and are about to be rehydrated.
+   */
+  async _enablePersistentCache(clearFirst) {
+    if (!this._cache) return;
+    this._cache.setScope(this._cacheScope());
+    if (clearFirst) await this._cache.clearPersisted();
+    this._cache.setPersistEnabled(true);
+  }
+  /**
+   * #1262: disable write-through persistence and drop the persisted cache for
+   * the current principal. Called on credential changes that do not persist a
+   * session (`setCredentials()`, non-remembered `login()`, `logout()`),
+   * mirroring the in-memory invalidation so a stale body can never outlive its
+   * principal. Callers that null out `_email` must invoke this **before** doing
+   * so, otherwise the scope no longer resolves to the principal being dropped.
+   */
+  _disablePersistentCache() {
+    if (!this._cache) return;
+    this._cache.setScope(this._cacheScope());
+    this._cache.setPersistEnabled(false);
+    void this._cache.clearPersisted();
   }
   /** Provide the cache event emitter (forwarded to the GeonicDB EventEmitter). */
   setCacheEventEmitter(emitter) {
@@ -587,6 +731,7 @@ var _AuthManager = class _AuthManager {
     this._email = email;
     this._rememberSession = wantsRemember;
     this._invalidateAuthScopedState();
+    this._cache?.setPersistEnabled(false);
     if (!wantsRemember && this._tenant) {
       void clearDPoPSession(this._tenant);
     }
@@ -596,6 +741,9 @@ var _AuthManager = class _AuthManager {
         const bound = await this._bindDpopSession();
         if (this._rememberSession) {
           await this._persistDpopSession();
+          await this._enablePersistentCache(true);
+        } else {
+          this._disablePersistentCache();
         }
         return bound;
       } catch (err) {
@@ -604,12 +752,18 @@ var _AuthManager = class _AuthManager {
         this._tokenType = "Bearer";
         this._refreshToken = null;
         this._tokenPromise = null;
+        this._invalidateAuthScopedState();
+        this._disablePersistentCache();
         this._rememberSession = false;
         this._email = null;
-        this._invalidateAuthScopedState();
         throw err;
       }
     }
+    this._rememberSession = false;
+    if (this._tenant) {
+      void clearDPoPSession(this._tenant);
+    }
+    this._disablePersistentCache();
     return data;
   }
   /**
@@ -694,6 +848,12 @@ var _AuthManager = class _AuthManager {
     this._refreshToken = opts.refreshToken || null;
     this._tokenPromise = null;
     this._invalidateAuthScopedState();
+    this._disablePersistentCache();
+    this._rememberSession = false;
+    this._email = null;
+    if (this._tenant) {
+      void clearDPoPSession(this._tenant);
+    }
   }
   /** Clear all credentials. */
   logout() {
@@ -701,6 +861,7 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = 0;
     this._refreshToken = null;
     this._tokenPromise = null;
+    this._disablePersistentCache();
     this._email = null;
     if (this._tenant) {
       void clearDPoPSession(this._tenant);
@@ -746,6 +907,8 @@ var _AuthManager = class _AuthManager {
     this._email = persisted.email ?? null;
     this._tokenPromise = null;
     this._invalidateAuthScopedState();
+    await this._enablePersistentCache(false);
+    await this._cache?.hydrate();
     return true;
   }
   /**
@@ -1368,6 +1531,140 @@ var WebSocketManager = class {
   }
 };
 
+// src/sdk/cache-persistence.ts
+var cachePersistenceSupported = typeof globalThis.indexedDB !== "undefined" && typeof structuredClone !== "undefined";
+var SCOPE_SEP = "\0";
+var SCOPE_RANGE_END = "\uFFFF";
+function openCacheDB() {
+  return new Promise((resolve, reject) => {
+    const req = globalThis.indexedDB.open(
+      SDK_CACHE_IDB_NAME,
+      SDK_CACHE_IDB_VERSION
+    );
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(SDK_CACHE_IDB_STORE)) {
+        db.createObjectStore(SDK_CACHE_IDB_STORE, { keyPath: "id" });
+      }
+    };
+    req.onsuccess = () => {
+      resolve(req.result);
+    };
+    req.onerror = () => {
+      reject(req.error ?? new Error("IndexedDB open failed"));
+    };
+    req.onblocked = () => {
+      reject(req.error ?? new Error("IndexedDB open blocked"));
+    };
+  });
+}
+function recordId(scope, key) {
+  return scope + SCOPE_SEP + key;
+}
+var IdbCachePersistence = class {
+  async loadScope(scope, limit) {
+    let db = null;
+    try {
+      db = await openCacheDB();
+      const records = await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readonly");
+        const range = globalThis.IDBKeyRange.bound(
+          scope + SCOPE_SEP,
+          scope + SCOPE_SEP + SCOPE_RANGE_END
+        );
+        const req = tx.objectStore(SDK_CACHE_IDB_STORE).getAll(range);
+        req.onsuccess = () => {
+          resolve(req.result ?? []);
+        };
+        req.onerror = () => {
+          reject(req.error ?? new Error("IndexedDB getAll failed"));
+        };
+      });
+      return records.filter((r) => r && r.scope === scope && typeof r.key === "string" && r.entry).sort((a, b) => (a.entry.cachedAt ?? 0) - (b.entry.cachedAt ?? 0)).slice(-limit).map((r) => ({ key: r.key, entry: r.entry }));
+    } catch {
+      return [];
+    } finally {
+      db?.close();
+    }
+  }
+  async put(scope, key, entry) {
+    let db = null;
+    try {
+      db = await openCacheDB();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readwrite");
+        const record = { id: recordId(scope, key), scope, key, entry };
+        tx.objectStore(SDK_CACHE_IDB_STORE).put(record);
+        tx.oncomplete = () => {
+          resolve();
+        };
+        tx.onerror = () => {
+          reject(tx.error ?? new Error("IndexedDB put failed"));
+        };
+        tx.onabort = () => {
+          reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+        };
+      });
+    } catch {
+    } finally {
+      db?.close();
+    }
+  }
+  async remove(scope, keys) {
+    if (keys.length === 0) return;
+    let db = null;
+    try {
+      db = await openCacheDB();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readwrite");
+        const store = tx.objectStore(SDK_CACHE_IDB_STORE);
+        for (const key of keys) store.delete(recordId(scope, key));
+        tx.oncomplete = () => {
+          resolve();
+        };
+        tx.onerror = () => {
+          reject(tx.error ?? new Error("IndexedDB delete failed"));
+        };
+        tx.onabort = () => {
+          reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+        };
+      });
+    } catch {
+    } finally {
+      db?.close();
+    }
+  }
+  async clearScope(scope) {
+    let db = null;
+    try {
+      db = await openCacheDB();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readwrite");
+        const range = globalThis.IDBKeyRange.bound(
+          scope + SCOPE_SEP,
+          scope + SCOPE_SEP + SCOPE_RANGE_END
+        );
+        tx.objectStore(SDK_CACHE_IDB_STORE).delete(range);
+        tx.oncomplete = () => {
+          resolve();
+        };
+        tx.onerror = () => {
+          reject(tx.error ?? new Error("IndexedDB clear failed"));
+        };
+        tx.onabort = () => {
+          reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+        };
+      });
+    } catch {
+    } finally {
+      db?.close();
+    }
+  }
+};
+function createCachePersistence() {
+  return cachePersistenceSupported ? new IdbCachePersistence() : null;
+}
+
 // src/sdk/index.ts
 var GeonicDB = class extends EventEmitter {
   constructor(options) {
@@ -1397,6 +1694,8 @@ var GeonicDB = class extends EventEmitter {
     };
     if (opts.cache !== false) {
       const cache = new SdkCache(opts.cacheMaxEntries ?? SDK_CACHE_MAX_ENTRIES_DEFAULT);
+      const persistence = createCachePersistence();
+      if (persistence) cache.attachPersistence(persistence);
       this._auth.setCache(cache);
       this._auth.setCacheEventEmitter((name, payload) => this.emit(name, payload));
     }
@@ -1425,6 +1724,7 @@ var GeonicDB = class extends EventEmitter {
     for (const key of removed) {
       this._auth.emitCacheEvent("cacheInvalidated", { key, path: key.split(":").slice(1).join(":") });
     }
+    void cache.clearPersisted();
   }
   // --- Authentication ---
   /**