feat: support uniqueConstraints on custom data models (#136)

本体 geonicdb#1268 の一意制約（複合ユニーク）に CLI を追従させる。

- models create/update: uniqueConstraints を JSON ペイロードで指定可能
  (パススルー)。ヘルプ・examples に宣言例と全置換セマンティクスを追記
- models get/list: table 形式で uniqueConstraints を
  「制約名(フィールド, ...)」の可読形式で表示
- 409 AlreadyExists: サーバーの違反制約名入りメッセージを表示し、
  一意制約違反時は models get で制約を確認するヒントを stderr に出力
- types.ts に UniqueConstraint 型を追加
- README に一意制約の使い方・エラー表示例を追記

Author: miya0001

CHANGELOG.md

@@ -7,6 +7,13 @@
 
 ## [Unreleased]
 
+### 2026-07-15
+- **Feat**: カスタムデータモデルの一意制約（複合ユニーク, geonicdb#1268）に対応 (#136)
+  - `models create` / `models update` の JSON ペイロードで `uniqueConstraints` を指定可能に（本体へパススルー）。ヘルプ・examples に宣言例と全置換 (`[]` で全削除) のセマンティクスを追記
+  - `models get` / `models list` の table 形式で `uniqueConstraints` を `制約名(フィールド, ...)` の可読形式で表示（json 形式は従来通りそのまま出力）
+  - 409 AlreadyExists のエラー表示を改善 — サーバーが返す違反制約名入りメッセージをそのまま表示し、一意制約違反の場合は `geonic models get <type>` で制約を確認するヒントを stderr に表示
+  - `UniqueConstraint` 型を `types.ts` に追加
+
 ### 2026-07-14
 - **Fix**: list 系コマンドがサーバーのデフォルトページサイズ (20件) で結果を暗黙に切り捨てていた問題を修正 (#141)
   - `--limit`/`--offset` 未指定時は `X-Total-Count` に従って全ページを自動取得するように変更。対象: `admin users/tenants/policies/api-keys/oauth-clients list`, `me api-keys/oauth-clients/policies list`, `rules list`, `custom-data-models list`, `catalog datasets list`

README.md

@@ -440,6 +440,40 @@ Temporal entityOperations query supports: `--aggr-methods`, `--aggr-period`.
 
 `models` is available as an alias for `custom-data-models`.
 
+#### 一意制約（複合ユニーク）
+
+データモデルに `uniqueConstraints` を宣言すると、指定した属性の組み合わせの一意性がサーバ側（DB レベル）で強制されます。重複するエンティティの作成・更新は `409 AlreadyExists` となり、違反した制約名がエラーメッセージに含まれます。
+
+```console
+$ geonic models create '{
+  "type": "RoomReservation",
+  "domain": "building",
+  "description": "Room reservation",
+  "propertyDetails": {
+    "room": {"ngsiType": "Property", "valueType": "string", "example": "R1"},
+    "date": {"ngsiType": "Property", "valueType": "string", "example": "2026-07-15"},
+    "startTime": {"ngsiType": "Property", "valueType": "string", "example": "10:00"}
+  },
+  "uniqueConstraints": [
+    {"name": "no-double-booking", "fields": ["room", "date", "startTime"]}
+  ]
+}'
+```
+
+- `fields` は `propertyDetails` に定義済みの scalar 型属性（string / number / integer / boolean / uri / datetime）のみ指定できます（1 制約 1〜8 個、モデルあたり最大 10 制約）
+- 制約は宣言フィールドを**すべて**持つエンティティにのみ適用されます
+- `models update` の `uniqueConstraints` は全置換です（`[]` で全削除）
+- 既存エンティティが重複している状態で制約を追加すると `400` になります（先に重複を解消してください）
+- 定義済みの制約は `geonic models get <type>` で確認できます（table 形式では `制約名(フィールド, ...)` 表記）
+
+重複作成時のエラー表示例:
+
+```console
+$ geonic entities create '{"id":"urn:ngsi-ld:RoomReservation:002","type":"RoomReservation","room":{"type":"Property","value":"R1"},"date":{"type":"Property","value":"2026-07-15"},"startTime":{"type":"Property","value":"10:00"}}'
+Error: Entity already exists: violates unique constraint 'no-double-booking' on fields [room, date, startTime]
+Hint: inspect the model's unique constraints with `geonic models get <type>`.
+```
+
 ### catalog — DCAT-AP catalog
 
 | Subcommand | Description |

src/commands/models.ts

@@ -43,7 +43,7 @@ export function registerModelsCommand(program: Command): void {
   // models get
   const get = models
     .command("get <id>")
-    .description("Get a data model's full schema including property definitions and constraints")
+    .description("Get a data model's full schema including property definitions, validation rules, and unique constraints")
     .action(
       withErrorHandler(async (id: unknown, _opts: unknown, cmd: Command) => {
         const client = createClient(cmd);
@@ -81,7 +81,11 @@ export function registerModelsCommand(program: Command): void {
         '    "propertyDetails": {\n' +
         '      "temperature": {"ngsiType": "Property", "valueType": "Number", "example": 25}\n' +
         "    }\n" +
-        "  }",
+        "  }\n\n" +
+        "Optional uniqueConstraints (composite unique, enforced server-side):\n" +
+        '  "uniqueConstraints": [{"name": "no-double-booking", "fields": ["room", "date", "startTime"]}]\n' +
+        "  Fields must be declared in propertyDetails with a scalar valueType.\n" +
+        "  Duplicate entities are rejected with 409 AlreadyExists (constraint name in the message).",
     )
     .action(
       withErrorHandler(async (json: unknown, _opts: unknown, cmd: Command) => {
@@ -107,6 +111,10 @@ export function registerModelsCommand(program: Command): void {
       description: "Create from stdin pipe",
       command: "cat model.json | geonic models create",
     },
+    {
+      description: "Create with a composite unique constraint (no double booking)",
+      command: `geonic models create '{"type":"RoomReservation","domain":"building","description":"Room reservation","propertyDetails":{"room":{"ngsiType":"Property","valueType":"string","example":"R1"},"date":{"ngsiType":"Property","valueType":"string","example":"2026-07-15"},"startTime":{"ngsiType":"Property","valueType":"string","example":"10:00"}},"uniqueConstraints":[{"name":"no-double-booking","fields":["room","date","startTime"]}]}'`,
+    },
   ]);
 
   // models update
@@ -116,7 +124,9 @@ export function registerModelsCommand(program: Command): void {
     .description(
       "Update a model\n\n" +
         "JSON payload: only specified fields are updated.\n" +
-        '  e.g. {"description": "Updated model"}',
+        '  e.g. {"description": "Updated model"}\n\n' +
+        "uniqueConstraints replaces the whole constraint list (send [] to remove all).\n" +
+        "Adding a constraint fails with 400 if existing entities already violate it.",
     )
     .action(
       withErrorHandler(
@@ -148,6 +158,14 @@ export function registerModelsCommand(program: Command): void {
       description: "Update from stdin pipe",
       command: "cat model.json | geonic models update <model-id>",
     },
+    {
+      description: "Replace unique constraints",
+      command: `geonic models update RoomReservation '{"uniqueConstraints":[{"name":"no-double-booking","fields":["room","date","startTime"]}]}'`,
+    },
+    {
+      description: "Remove all unique constraints",
+      command: `geonic models update RoomReservation '{"uniqueConstraints":[]}'`,
+    },
   ]);
 
   // models delete

src/helpers.ts

@@ -201,6 +201,12 @@ export function withErrorHandler<T extends unknown[]>(fn: (...args: T) => Promis
         } else {
           printError(err.message);
         }
+      } else if (err instanceof GdbClientError && err.status === 409) {
+        // 409 AlreadyExists — サーバのメッセージに違反した一意制約名が含まれる (#136)
+        printError(err.message);
+        if (/violates unique constraint/i.test(err.message)) {
+          printWarning("Hint: inspect the model's unique constraints with `geonic models get <type>`.");
+        }
       } else if (err instanceof Error) {
         printError(err.message);
       } else {

src/output.ts

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import type { OutputFormat } from "./types.js";
+import type { OutputFormat, UniqueConstraint } from "./types.js";
 
 export function formatOutput(data: unknown, format: OutputFormat): string {
   switch (format) {
@@ -132,12 +132,36 @@ function isGeoJSON(v: unknown): boolean {
   return typeof o.type === "string" && "coordinates" in o;
 }
 
+/**
+ * カスタムデータモデルの uniqueConstraints 形式 ({name, fields[]} の配列) か判定する (#136)
+ */
+function isUniqueConstraintArray(val: unknown): val is UniqueConstraint[] {
+  return (
+    Array.isArray(val) &&
+    val.length > 0 &&
+    val.every(
+      (v) =>
+        typeof v === "object" &&
+        v !== null &&
+        typeof (v as Record<string, unknown>).name === "string" &&
+        Array.isArray((v as Record<string, unknown>).fields) &&
+        ((v as Record<string, unknown>).fields as unknown[]).every((f) => typeof f === "string") &&
+        Object.keys(v as object).length === 2,
+    )
+  );
+}
+
 function cellValue(val: unknown): string {
   if (val === undefined || val === null) return "";
   if (typeof val !== "object") return String(val);
   if (Array.isArray(val)) {
     const scalarArray = val.every((v) => v === null || typeof v !== "object");
-    return scalarArray ? val.map(String).join(", ") : JSON.stringify(val);
+    if (scalarArray) return val.map(String).join(", ");
+    // uniqueConstraints は「制約名(フィールド, ...)」の可読形式で表示 (#136)
+    if (isUniqueConstraintArray(val)) {
+      return val.map((c) => `${c.name}(${c.fields.join(", ")})`).join("; ");
+    }
+    return JSON.stringify(val);
   }
   const obj = val as Record<string, unknown>;
   if (isGeoJSON(obj)) return formatGeoJSON(obj);

src/types.ts

@@ -58,6 +58,12 @@ export interface ClientResponse<T = unknown> {
   count?: number;
 }
 
+/** カスタムデータモデルの一意制約（複合ユニーク, geonicdb#1268 / #136） */
+export interface UniqueConstraint {
+  name: string;
+  fields: string[];
+}
+
 export interface NgsiError {
   error?: string;
   description?: string;

tests/helpers.test.ts

@@ -355,6 +355,36 @@ describe("helpers", () => {
       );
     });
 
+    it("prints server message and hint on 409 unique constraint violation (#136)", async () => {
+      const err = new GdbClientError(
+        "Entity already exists: violates unique constraint 'no-double-booking' on fields [room, date, startTime]",
+        409,
+        { error: "AlreadyExists" },
+      );
+      const fn = vi.fn().mockRejectedValue(err);
+      const wrapped = withErrorHandler(fn);
+      await expect(wrapped()).rejects.toThrow("process.exit");
+      expect(printError).toHaveBeenCalledWith(
+        expect.stringContaining("violates unique constraint 'no-double-booking'"),
+      );
+      expect(printWarning).toHaveBeenCalledWith(
+        expect.stringContaining("geonic models get"),
+      );
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it("prints plain message on 409 without unique constraint context", async () => {
+      const err = new GdbClientError("Entity already exists: urn:ngsi-ld:Room:001", 409, {
+        error: "AlreadyExists",
+      });
+      const fn = vi.fn().mockRejectedValue(err);
+      const wrapped = withErrorHandler(fn);
+      await expect(wrapped()).rejects.toThrow("process.exit");
+      expect(printError).toHaveBeenCalledWith("Entity already exists: urn:ngsi-ld:Room:001");
+      expect(printWarning).not.toHaveBeenCalled();
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
     it("prints generic message on 403 without entity type detail", async () => {
       const err = new GdbClientError("Access denied", 403, {
         detail: "insufficient permissions",

tests/models.test.ts

@@ -74,6 +74,27 @@ describe("models (custom-data-models) command", () => {
     });
   });
 
+  describe("create with uniqueConstraints (#136)", () => {
+    it("passes uniqueConstraints through in the request body", async () => {
+      const modelData = {
+        type: "RoomReservation",
+        domain: "building",
+        description: "Room reservation",
+        propertyDetails: {
+          room: { ngsiType: "Property", valueType: "string", example: "R1" },
+        },
+        uniqueConstraints: [{ name: "no-double-booking", fields: ["room", "date", "startTime"] }],
+      };
+      vi.mocked(parseJsonInput).mockResolvedValue(modelData);
+      mockClient.rawRequest.mockResolvedValue(mockResponse({ type: "RoomReservation" }, 201));
+
+      await runCommand(program, ["models", "create", JSON.stringify(modelData)]);
+
+      expect(mockClient.rawRequest).toHaveBeenCalledWith("POST", "/custom-data-models", { body: modelData });
+      expect(printSuccess).toHaveBeenCalledWith("Model created.");
+    });
+  });
+
   describe("update", () => {
     it("parses JSON and patches via rawRequest", async () => {
       const patchData = { name: "UpdatedModel" };
@@ -93,6 +114,36 @@ describe("models (custom-data-models) command", () => {
     });
   });
 
+  describe("update uniqueConstraints (#136)", () => {
+    it("replaces the constraint list via PATCH", async () => {
+      const patchData = { uniqueConstraints: [{ name: "unique-code", fields: ["code"] }] };
+      vi.mocked(parseJsonInput).mockResolvedValue(patchData);
+      mockClient.rawRequest.mockResolvedValue(mockResponse({ type: "Slot" }, 200));
+
+      await runCommand(program, ["models", "update", "Slot", JSON.stringify(patchData)]);
+
+      expect(mockClient.rawRequest).toHaveBeenCalledWith(
+        "PATCH",
+        `/custom-data-models/${encodeURIComponent("Slot")}`,
+        { body: patchData },
+      );
+    });
+
+    it("removes all constraints with an empty array", async () => {
+      const patchData = { uniqueConstraints: [] };
+      vi.mocked(parseJsonInput).mockResolvedValue(patchData);
+      mockClient.rawRequest.mockResolvedValue(mockResponse({ type: "Slot" }, 200));
+
+      await runCommand(program, ["models", "update", "Slot", JSON.stringify(patchData)]);
+
+      expect(mockClient.rawRequest).toHaveBeenCalledWith(
+        "PATCH",
+        `/custom-data-models/${encodeURIComponent("Slot")}`,
+        { body: patchData },
+      );
+    });
+  });
+
   describe("delete", () => {
     it("deletes model via rawRequest", async () => {
       mockClient.rawRequest.mockResolvedValue(mockResponse(undefined, 204));

tests/output.test.ts

@@ -56,6 +56,25 @@ describe("output", () => {
       expect(result).toContain("23.5");
     });
 
+    it("renders uniqueConstraints as name(fields) (#136)", () => {
+      const data = {
+        type: "RoomReservation",
+        uniqueConstraints: [
+          { name: "no-double-booking", fields: ["room", "date", "startTime"] },
+          { name: "unique-code", fields: ["code"] },
+        ],
+      };
+      const result = formatOutput(data, "table");
+      expect(result).toContain("no-double-booking(room, date, startTime)");
+      expect(result).toContain("unique-code(code)");
+    });
+
+    it("keeps JSON rendering for non-constraint object arrays", () => {
+      const data = { items: [{ name: "x", other: true }] };
+      const result = formatOutput(data, "table");
+      expect(result).toContain(JSON.stringify([{ name: "x", other: true }]));
+    });
+
     it("returns String(data) for non-array non-object data", () => {
       const result = formatOutput("hello-string", "table");
       expect(result).toBe("hello-string");