@geolonia/geonicdb-sdk 0.12.0 → 0.14.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`)
@@ -601,12 +633,39 @@ 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`） |
+| `getEntities(options?)` | エンティティ一覧（`type` / `q` / `limit` / `offset` / `attrs` / `options` / `georel` / `geometry` / `coords`） |
 | `getEntity(id, options?)` | 単一エンティティ取得 |
 | `createEntity(entity)` | エンティティ作成 |
 | `updateEntityAttributes(id, attrs)` | 属性の部分更新 |
 | `deleteEntity(id)` | エンティティ削除 |
 
+### Geospatial query (`georel` / `geometry` / `coords`)
+
+NGSIv2 の地理空間クエリに対応。`georel`・`geometry`・`coords` は 3 つ揃えて指定する（部分指定は Orion 側で `400`）。
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `georel` | `string` | 地理的関係。複合形も可（例: `near;maxDistance:1000`, `coveredBy`） |
+| `geometry` | `'point' \| 'line' \| 'polygon' \| 'box'` | ジオメトリ種別 |
+| `coords` | `string` | WGS84 座標。複数点はセミコロン区切り（例: `35.6,139.7`） |
+
+```ts
+// 指定座標から半径 1km 以内
+const nearby = await client.getEntities({
+  type: 'PublicFacility',
+  georel: 'near;maxDistance:1000',
+  geometry: 'point',
+  coords: '35.6,139.7',
+});
+
+// ポリゴン内に含まれるエンティティ
+const inArea = await client.getEntities({
+  georel: 'coveredBy',
+  geometry: 'polygon',
+  coords: '0,0;1,0;1,1;0,1;0,0',
+});
+```
+
 ## 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 ---
   /**