@geolonia/geonicdb-sdk 0.7.0 → 0.8.0

package/README.md

@@ -33,6 +33,29 @@ await db.createEntity({
 });
 ```
 
+### TypeScript
+
+The SDK ships type definitions (`geonicdb.d.ts`) in the published package. Named imports of error classes and types resolve cleanly even under strict tsconfig settings (`strict`, `verbatimModuleSyntax`, etc.):
+
+```typescript
+import GeonicDB, {
+  AuthorizationError,
+  AuthenticationError,
+  type EntityEvent,
+  type RefreshedCredentials,
+} from '@geolonia/geonicdb-sdk';
+
+try {
+  await db.deleteEntity(entityId);
+} catch (err) {
+  if (err instanceof AuthorizationError) {
+    // Type-safe branch on XACML denial.
+  }
+}
+```
+
+See **Error Handling** below for the full list of exported error classes.
+
 ### Browser (script tag)
 
 ```html
@@ -123,8 +146,20 @@ await db.createEntity({ id: 'urn:ngsi-ld:Room:001', type: 'Room', ... });
 // Read
 const entity = await db.getEntity('urn:ngsi-ld:Room:001');
 
-// Query
-const entities = await db.getEntities({ type: 'Room', limit: 10 });
+// Query (NGSI-LD §5.7.2 のクエリパラメータを網羅)
+const entities = await db.getEntities({
+  type: 'Room',
+  limit: 10,
+  // scopeQ: '/OpenData;/OpenData/#',     // exact + descendants
+  // georel: 'near;maxDistance==1000',
+  // geometry: 'Point',
+  // coordinates: '139.7,35.6',
+  // attrs: 'name,location',
+  // pick: 'name', omit: 'createdAt',
+  // lang: 'ja',
+  // orderBy: 'modifiedAt', orderDirection: 'desc',
+  // count: true,
+});
 
 // Update
 await db.updateEntity('urn:ngsi-ld:Room:001', { temperature: { type: 'Property', value: 25 } });

package/geonicdb.cjs

@@ -31,6 +31,7 @@ __export(index_exports, {
   NotFoundError: () => NotFoundError,
   RateLimitError: () => RateLimitError,
   ValidationError: () => ValidationError,
+  buildPathWithParams: () => buildPathWithParams,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -872,6 +873,7 @@ var WebSocketManager = class {
     if (options) {
       if (options.entityTypes) msg.entityTypes = options.entityTypes;
       if (options.idPattern) msg.idPattern = options.idPattern;
+      if (options.scopeQ) msg.scopeQ = options.scopeQ;
     }
     this._subscription = msg;
     if (this._pendingSubscription) return;
@@ -1224,14 +1226,14 @@ var GeonicDB = class extends EventEmitter {
   }
   /** Count entities matching the given filters. */
   async count(params) {
-    const parts = ["count=true", "limit=0"];
-    if (params?.type) parts.push("type=" + encodeURIComponent(params.type));
-    if (params?.q) parts.push("q=" + encodeURIComponent(params.q));
-    const qs = "?" + parts.join("&");
-    const res = await this._auth.request(
-      "GET",
-      "/ngsi-ld/v1/entities" + qs
-    );
+    const path = buildPathWithParams("/ngsi-ld/v1/entities", {
+      count: true,
+      limit: 0,
+      type: params?.type,
+      q: params?.q,
+      scopeQ: params?.scopeQ
+    });
+    const res = await this._auth.request("GET", path);
     if (!res.ok) {
       const e = await res.json().catch(() => ({}));
       throw createErrorFromResponse(res.status, e, "Count failed");
@@ -1290,24 +1292,11 @@ var GeonicDB = class extends EventEmitter {
   // --- Temporal API ---
   /** Query temporal entities. */
   async getTemporalEntities(params) {
-    let qs = "";
-    if (params) {
-      const parts = [];
-      if (params.type) parts.push("type=" + encodeURIComponent(params.type));
-      if (params.id) parts.push("id=" + encodeURIComponent(params.id));
-      if (params.idPattern) parts.push("idPattern=" + encodeURIComponent(params.idPattern));
-      if (params.attrs) parts.push("attrs=" + encodeURIComponent(params.attrs));
-      if (params.q) parts.push("q=" + encodeURIComponent(params.q));
-      if (params.timeproperty) parts.push("timeproperty=" + encodeURIComponent(params.timeproperty));
-      if (params.timeAt) parts.push("timeAt=" + encodeURIComponent(params.timeAt));
-      if (params.endTimeAt) parts.push("endTimeAt=" + encodeURIComponent(params.endTimeAt));
-      if (params.timerel) parts.push("timerel=" + encodeURIComponent(params.timerel));
-      if (params.limit != null) parts.push("limit=" + params.limit);
-      if (params.offset != null) parts.push("offset=" + params.offset);
-      if (parts.length) qs = "?" + parts.join("&");
-    }
     return this._jsonGet(
-      "/ngsi-ld/v1/temporal/entities" + qs,
+      buildPathWithParams(
+        "/ngsi-ld/v1/temporal/entities",
+        params
+      ),
       "Temporal query failed"
     );
   }
@@ -1375,6 +1364,11 @@ var GeonicDB = class extends EventEmitter {
   /**
    * Make an authenticated API request.
    * Automatically checks response status, parses JSON, and throws on error.
+   *
+   * Empty bodies (`Content-Length: 0` 含む) は Content-Type に関係なく `null`
+   * を返す (#1145)。NGSI-LD の POST / DELETE / PATCH 系は仕様上ボディが
+   * 空だが、サーバ実装が `Content-Type: application/ld+json` を付けて返す
+   * ケースがあり、そこで `res.json()` が SyntaxError を投げて止まっていた。
    */
   async request(method, path, body) {
     const res = await this._auth.request(method, path, body);
@@ -1382,9 +1376,15 @@ var GeonicDB = class extends EventEmitter {
       const e = await res.json().catch(() => ({}));
       throw createErrorFromResponse(res.status, e, "Request failed: " + res.status);
     }
+    if (res.status === 204) return null;
+    if (res.headers.get("Content-Length") === "0") return null;
     const ct = res.headers.get("Content-Type") || "";
-    if (res.status === 204 || !ct) return null;
-    if (ct.indexOf("json") !== -1) return res.json();
+    if (!ct) return null;
+    if (ct.indexOf("json") !== -1) {
+      const text = await res.text();
+      if (!text) return null;
+      return JSON.parse(text);
+    }
     return res.text();
   }
   /**
@@ -1421,12 +1421,28 @@ 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 buildPathWithParams(
+    "/ngsi-ld/v1/entities",
+    params
+  );
+}
+function buildPathWithParams(path, params) {
+  if (!params) return path;
+  const sp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    if (typeof value === "boolean") {
+      sp.append(key, value ? "true" : "false");
+    } else if (typeof value === "number") {
+      sp.append(key, String(value));
+    } else if (typeof value === "string") {
+      if (value === "") continue;
+      sp.append(key, value);
+    } else {
+      continue;
+    }
+  }
+  const qs = sp.toString();
+  return qs ? `${path}?${qs}` : path;
 }
 //# sourceMappingURL=geonicdb.cjs.map