@rdbms-erd/core 0.1.1 → 0.1.2

package/README.md

@@ -1,67 +1,134 @@
-# @rdbms-erd/core
-
-Core model and SQL utilities for relational ERD tooling.
-
-## Installation
-
-```bash
-npm i @rdbms-erd/core
-```
-
-## What This Package Provides
-
-- Design document types (`DesignDocument`, `DesignModel`, `TableModel`, `ColumnModel`, ...)
-- Document lifecycle helpers (`createEmptyDesign`, `serializeDesign`, `parseDesign`, `validateDesignDocument`)
-- SQL generation (`generateDdl`, `generateIndexDdl`)
-- Diagnostic helpers (`analyzeDdlDocument`, `generateDdlWithDiagnostics`, `formatDdlDiagnostics`)
-- Canvas alignment utility (`alignNodePositions`)
-- Large sample generator (`createLargeDesign`)
-
-## Quick Example
-
-```ts
-import {
-  createEmptyDesign,
-  createColumn,
-  generateDdl,
-  type DesignDocument,
-} from "@rdbms-erd/core";
-
-const doc: DesignDocument = createEmptyDesign("postgres");
-
-doc.model.tables.push({
-  id: "table-users",
-  logicalName: "Users",
-  physicalName: "users",
-  columns: [
-    createColumn("postgres", {
-      id: "col-users-id",
-      logicalName: "ID",
-      physicalName: "id",
-      logicalType: "NUMBER",
-      nullable: false,
-      isPrimaryKey: true,
-    }),
-    createColumn("postgres", {
-      id: "col-users-email",
-      logicalName: "Email",
-      physicalName: "email",
-      logicalType: "TEXT",
-      nullable: false,
-    }),
-  ],
-});
-
-const sql = generateDdl(doc);
-console.log(sql);
-```
-
-## API Reference
-
-See the repository docs for symbol-level details:
-
-- `docs/API.md`
-
-## License
-
-MIT
+# @rdbms-erd/core
+
+`@rdbms-erd/core` is the headless model/DDL package for rdbms-erd.
+It provides document types, validation/serialization, logical->physical type defaults,
+DDL generation, diagnostics, and host-extensible database metadata.
+
+## Installation
+
+```bash
+npm i @rdbms-erd/core
+```
+
+## Quick Start
+
+```ts
+import { createEmptyDesign, createColumn, generateDdl } from "@rdbms-erd/core";
+
+const doc = createEmptyDesign("postgres");
+doc.model.tables.push({
+    id: "table-users",
+    logicalName: "Users",
+    physicalName: "users",
+    columns: [
+        createColumn("postgres", {
+            id: "col-users-id",
+            logicalName: "ID",
+            physicalName: "id",
+            logicalType: "NUMBER",
+            nullable: false,
+            isPrimaryKey: true,
+        }),
+    ],
+});
+
+console.log(generateDdl(doc));
+```
+
+## Core Concepts
+
+- `DesignDocument`: ER JSON source of truth
+- `RdbmsDialect`: dialect id stored in document
+- `LogicalDataType`: normalized logical type ids
+- `DialectMetaJson`: host-overridable per-dialect metadata
+- `DdlGeneratorHook`: optional per-dialect SQL generation hook
+
+## Relationship Model Notes
+
+`RelationshipModel` supports canvas-specific rendering state used by the designer:
+
+- `cardinality?: "1:1" | "1:N"`
+- `canvasLineHidden?: boolean`
+- `linePivotRatio?: number` (middle vertical segment ratio)
+- `sourceLineY?: number` (source edge absolute Y inside table)
+- `sourceLineRatio?: number` (legacy fallback; kept for compatibility)
+
+## Host-Extensible DB Metadata
+
+### 1) Override/append dialect metadata with JSON
+
+Use `hostMetas` in options. Merge policy:
+
+- same `id`: override builtin
+- new `id`: append
+
+```ts
+import { resolveDialectMetas } from "@rdbms-erd/core";
+
+const metas = resolveDialectMetas({
+    hostMetas: [
+        {
+            id: "acme",
+            label: "AcmeDB",
+            supportsSchema: true,
+            logicalTypes: [
+                { id: "TEXT", defaultPhysicalType: "STRING(255)" },
+                { id: "NUMBER", defaultPhysicalType: "INT64" },
+            ],
+            ddlStyle: { quote: "double", boolLiteral: "oneZero" },
+        },
+    ],
+});
+```
+
+### 2) Optional per-dialect DDL function hook
+
+If a dialect DDL is complex, provide a function in `hostDdlGenerators`.
+If omitted, style-based builtin SQL generation is used.
+
+```ts
+import {
+    generateDdlForSelection,
+    type DdlGenerateInput,
+} from "@rdbms-erd/core";
+
+const sql = generateDdlForSelection(doc, ["table-users"], {
+    hostDdlGenerators: {
+        acme: (input: DdlGenerateInput) => {
+            // input.scope.kind: "all" | "selected"
+            return { sql: "-- custom acme ddl" };
+        },
+    },
+    fallbackOnHookError: true,
+}).sql;
+```
+
+## Main APIs
+
+- Document lifecycle:
+    - `createEmptyDesign`
+    - `serializeDesign`, `parseDesign`, `validateDesignDocument`, `roundTripDesign`
+- Type defaults:
+    - `defaultPhysicalType`
+    - `createColumn`
+    - `applyLogicalTypeChange`
+    - `convertDesignDialect`
+- DDL:
+    - `generateDdl`
+    - `generateDdlForSelection`
+    - `generateIndexDdl`
+    - `generateDdlWithDiagnostics`
+    - `generateIndexDdlWithDiagnostics`
+- Metadata:
+    - `resolveDialectMetas`
+    - `mergeDialectMetas`
+    - `createDefaultDbMetaAdapter` (legacy/advanced adapter path)
+
+## Notes
+
+- DDL function hooks are runtime values and are **not serialized** in `DesignDocument`.
+- `DesignDocument` stores only dialect id and model data.
+
+## License
+
+MIT

package/package.json

@@ -1,11 +1,19 @@
-{
-    "name": "@rdbms-erd/core",
-    "version": "0.1.1",
-    "license": "MIT",
-    "type": "module",
-    "main": "./src/index.ts",
-    "types": "./src/index.ts",
-    "exports": {
-        ".": "./src/index.ts"
-    }
-}
+{
+    "name": "@rdbms-erd/core",
+    "version": "0.1.2",
+    "license": "MIT",
+    "keywords": [
+        "erd",
+        "database",
+        "schema",
+        "ddl",
+        "sql",
+        "rdbms"
+    ],
+    "type": "module",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": "./src/index.ts"
+    }
+}

package/src/__tests__/alignment.test.ts

@@ -1,19 +1,19 @@
-import { describe, expect, it } from "vitest";
-import { alignNodePositions } from "../alignment";
-
-describe("alignNodePositions", () => {
-  it("aligns left to min x", () => {
-    const positions = { a: { x: 10, y: 0 }, b: { x: 50, y: 0 } };
-    const out = alignNodePositions(["a", "b"], positions, "left");
-    expect(out.a.x).toBe(10);
-    expect(out.b.x).toBe(10);
-  });
-
-  it("distributes horizontal gap", () => {
-    const positions = { a: { x: 0, y: 0 }, b: { x: 100, y: 0 }, c: { x: 200, y: 0 } };
-    const out = alignNodePositions(["a", "b", "c"], positions, "h-gap");
-    expect(out.a.x).toBe(0);
-    expect(out.b.x).toBe(100);
-    expect(out.c.x).toBe(200);
-  });
-});
+import { describe, expect, it } from "vitest";
+import { alignNodePositions } from "../alignment";
+
+describe("alignNodePositions", () => {
+  it("aligns left to min x", () => {
+    const positions = { a: { x: 10, y: 0 }, b: { x: 50, y: 0 } };
+    const out = alignNodePositions(["a", "b"], positions, "left");
+    expect(out.a.x).toBe(10);
+    expect(out.b.x).toBe(10);
+  });
+
+  it("distributes horizontal gap", () => {
+    const positions = { a: { x: 0, y: 0 }, b: { x: 100, y: 0 }, c: { x: 200, y: 0 } };
+    const out = alignNodePositions(["a", "b", "c"], positions, "h-gap");
+    expect(out.a.x).toBe(0);
+    expect(out.b.x).toBe(100);
+    expect(out.c.x).toBe(200);
+  });
+});

package/src/__tests__/benchmark.test.ts

@@ -1,14 +1,14 @@
-import { describe, expect, it } from "vitest";
-import { createLargeDesign, roundTripDesign, serializeDesign } from "../index";
-
-describe("large model (500 tables)", () => {
-  it("serializes and round-trips within reasonable time", () => {
-    const doc = createLargeDesign(500, "postgres");
-    const t0 = performance.now();
-    const json = serializeDesign(doc);
-    const parsed = roundTripDesign(JSON.parse(json) as typeof doc);
-    const ms = performance.now() - t0;
-    expect(parsed.model.tables).toHaveLength(500);
-    expect(ms).toBeLessThan(8000);
-  });
-});
+import { describe, expect, it } from "vitest";
+import { createLargeDesign, roundTripDesign, serializeDesign } from "../index";
+
+describe("large model (500 tables)", () => {
+  it("serializes and round-trips within reasonable time", () => {
+    const doc = createLargeDesign(500, "postgres");
+    const t0 = performance.now();
+    const json = serializeDesign(doc);
+    const parsed = roundTripDesign(JSON.parse(json) as typeof doc);
+    const ms = performance.now() - t0;
+    expect(parsed.model.tables).toHaveLength(500);
+    expect(ms).toBeLessThan(8000);
+  });
+});

package/src/__tests__/db-meta-adapter.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import {
+  createColumn,
+  createDefaultDbMetaAdapter,
+  createEmptyDesign,
+  generateDdl,
+  generateDdlForSelection,
+  LOGICAL_DATA_TYPES,
+  resolveDialectMetas,
+  serializeDesign,
+  validateDesignDocument,
+  type DdlGenerateInput,
+  type DdlGenerateOutput,
+  type DbMetaAdapter,
+  type DialectMetaJson,
+  type DialectMeta,
+  type LogicalDataType
+} from "../index";
+
+function createAcmeAdapter(): DbMetaAdapter {
+  const base = createDefaultDbMetaAdapter();
+  const acmeTypeMap: Record<LogicalDataType, string> = {
+    TEXT: "STRING(255)",
+    DATE: "DATE",
+    TIME: "TIME",
+    DATETIME: "TIMESTAMP",
+    NUMBER: "INT64",
+    DECIMAL: "DECIMAL(10,2)",
+    FLOAT: "DOUBLE",
+    BOOLEAN: "BOOL",
+    JSON: "JSON",
+    UUID: "UUID",
+    BINARY: "BYTES"
+  };
+  const acmeMeta: DialectMeta = {
+    id: "acme",
+    label: "AcmeDB",
+    capabilities: { supportsSchema: true },
+    logicalTypes: LOGICAL_DATA_TYPES,
+    defaultPhysicalTypeMap: acmeTypeMap
+  };
+  return {
+    listDialects: () => [...base.listDialects(), acmeMeta],
+    getDialectMeta: (dialect) => (dialect === "acme" ? acmeMeta : base.getDialectMeta(dialect)),
+    getDefaultPhysicalType: (dialect, logicalType) =>
+      dialect === "acme" ? acmeTypeMap[logicalType] : base.getDefaultPhysicalType(dialect, logicalType),
+    getDdlRules: (dialect) =>
+      dialect === "acme"
+        ? {
+            ...base.getDdlRules(dialect),
+            quoteIdentifier: (_d, id) => `<${id}>`
+          }
+        : base.getDdlRules(dialect)
+  };
+}
+
+describe("db meta adapter", () => {
+  it("allows host dialect for createColumn default physical type", () => {
+    const adapter = createAcmeAdapter();
+    const col = createColumn(
+      "acme",
+      {
+        id: "c1",
+        logicalName: "name",
+        logicalType: "TEXT"
+      },
+      { dbMetaAdapter: adapter }
+    );
+    expect(col.physicalType).toBe("STRING(255)");
+  });
+
+  it("applies host quote rule and schema support to DDL", () => {
+    const adapter = createAcmeAdapter();
+    const doc = createEmptyDesign("acme");
+    doc.model.tables.push({
+      id: "t1",
+      logicalName: "사용자",
+      physicalName: "users",
+      schemaName: "core",
+      columns: [
+        createColumn(
+          "acme",
+          {
+            id: "id1",
+            logicalName: "id",
+            physicalName: "id",
+            logicalType: "NUMBER",
+            nullable: false,
+            isPrimaryKey: true
+          },
+          { dbMetaAdapter: adapter }
+        )
+      ]
+    });
+
+    const sql = generateDdl(doc, { dbMetaAdapter: adapter });
+    expect(sql).toContain("CREATE TABLE <core>.<users>");
+    expect(sql).toContain("<id> INT64");
+  });
+
+  it("validates custom dialect when adapter provides it", () => {
+    const adapter = createAcmeAdapter();
+    const doc = createEmptyDesign("acme");
+    const raw = JSON.parse(serializeDesign(doc));
+    expect(() => validateDesignDocument(raw, { dbMetaAdapter: adapter })).not.toThrow();
+  });
+
+  it("merges host metas by id (override/append)", () => {
+    const hostMetas: DialectMetaJson[] = [
+      {
+        id: "postgres",
+        label: "Postgres Override",
+        supportsSchema: true,
+        logicalTypes: [{ id: "TEXT", defaultPhysicalType: "TEXT" }]
+      },
+      {
+        id: "acme_json",
+        label: "Acme JSON",
+        supportsSchema: true,
+        logicalTypes: [{ id: "TEXT", defaultPhysicalType: "STRING(255)" }]
+      }
+    ];
+    const resolved = resolveDialectMetas({ hostMetas });
+    expect(resolved.find((m) => m.id === "postgres")?.label).toBe("Postgres Override");
+    expect(resolved.some((m) => m.id === "acme_json")).toBe(true);
+  });
+
+  it("calls host ddl generator with selected scope", () => {
+    const doc = createEmptyDesign("postgres");
+    doc.model.tables.push(
+      { id: "t1", logicalName: "A", physicalName: "a", columns: [createColumn("postgres", { id: "c1", logicalName: "id", logicalType: "NUMBER", nullable: false, isPrimaryKey: true })] },
+      { id: "t2", logicalName: "B", physicalName: "b", columns: [createColumn("postgres", { id: "c2", logicalName: "id", logicalType: "NUMBER", nullable: false, isPrimaryKey: true })] }
+    );
+    const calls: DdlGenerateInput[] = [];
+    const hostGenerator = (input: DdlGenerateInput): DdlGenerateOutput => {
+      calls.push(input);
+      return { sql: "-- custom" };
+    };
+    const out = generateDdlForSelection(doc, ["t1"], {
+      hostDdlGenerators: { postgres: hostGenerator }
+    });
+    expect(out.sql).toBe("-- custom");
+    expect(calls).toHaveLength(1);
+    expect(calls[0].scope.kind).toBe("selected");
+  });
+
+  it("falls back to style generator when host hook throws", () => {
+    const doc = createEmptyDesign("postgres");
+    doc.model.tables.push({
+      id: "t1",
+      logicalName: "사용자",
+      physicalName: "users",
+      columns: [createColumn("postgres", { id: "c1", logicalName: "id", logicalType: "NUMBER", nullable: false, isPrimaryKey: true })]
+    });
+    const sql = generateDdl(doc, {
+      hostDdlGenerators: {
+        postgres: () => {
+          throw new Error("boom");
+        }
+      },
+      fallbackOnHookError: true
+    });
+    expect(sql).toContain("CREATE TABLE");
+    expect(sql).toContain("\"users\"");
+  });
+});

package/src/__tests__/ddl-diagnostics.test.ts

@@ -1,52 +1,52 @@
-import { describe, expect, it } from "vitest";
-import { analyzeDdlDocument, createColumn, createEmptyDesign, formatDdlDiagnostic, generateDdlWithDiagnostics } from "../index";
-
-describe("analyzeDdlDocument / formatDdlDiagnostic", () => {
-  it("formats diagnostics with unified template", () => {
-    const line = formatDdlDiagnostic({
-      severity: "warning",
-      code: "DDL_REL_MISSING_COLUMNS",
-      message: "소스/타겟 컬럼이 지정되지 않아 FK DDL을 생략한다.",
-      context: "relationship:r1"
-    });
-    expect(line).toBe(
-      "[WARN][DDL_REL_MISSING_COLUMNS] 소스/타겟 컬럼이 지정되지 않아 FK DDL을 생략한다. | relationship:r1"
-    );
-  });
-
-  it("warns on relationship without column ids", () => {
-    const doc = createEmptyDesign("postgres");
-    doc.model.tables.push({
-      id: "a",
-      logicalName: "A",
-      physicalName: "TA",
-      columns: [createColumn("postgres", { id: "c1", logicalName: "x", logicalType: "TEXT" })]
-    });
-    doc.model.tables.push({
-      id: "b",
-      logicalName: "B",
-      physicalName: "TB",
-      columns: [createColumn("postgres", { id: "c2", logicalName: "y", logicalType: "TEXT" })]
-    });
-    doc.model.relationships.push({
-      id: "r1",
-      sourceTableId: "a",
-      targetTableId: "b"
-    });
-    const d = analyzeDdlDocument(doc);
-    expect(d.some((x) => x.code === "DDL_REL_MISSING_COLUMNS")).toBe(true);
-  });
-
-  it("generateDdlWithDiagnostics returns sql and same analyze list", () => {
-    const doc = createEmptyDesign("mysql");
-    doc.model.tables.push({
-      id: "t1",
-      logicalName: "T",
-      physicalName: "TT",
-      columns: [createColumn("mysql", { id: "c1", logicalName: "id", logicalType: "NUMBER", nullable: false })]
-    });
-    const { sql, diagnostics } = generateDdlWithDiagnostics(doc);
-    expect(sql).toContain("CREATE TABLE");
-    expect(diagnostics.length).toBeGreaterThanOrEqual(0);
-  });
-});
+import { describe, expect, it } from "vitest";
+import { analyzeDdlDocument, createColumn, createEmptyDesign, formatDdlDiagnostic, generateDdlWithDiagnostics } from "../index";
+
+describe("analyzeDdlDocument / formatDdlDiagnostic", () => {
+  it("formats diagnostics with unified template", () => {
+    const line = formatDdlDiagnostic({
+      severity: "warning",
+      code: "DDL_REL_MISSING_COLUMNS",
+      message: "소스/타겟 컬럼이 지정되지 않아 FK DDL을 생략한다.",
+      context: "relationship:r1"
+    });
+    expect(line).toBe(
+      "[WARN][DDL_REL_MISSING_COLUMNS] 소스/타겟 컬럼이 지정되지 않아 FK DDL을 생략한다. | relationship:r1"
+    );
+  });
+
+  it("warns on relationship without column ids", () => {
+    const doc = createEmptyDesign("postgres");
+    doc.model.tables.push({
+      id: "a",
+      logicalName: "A",
+      physicalName: "TA",
+      columns: [createColumn("postgres", { id: "c1", logicalName: "x", logicalType: "TEXT" })]
+    });
+    doc.model.tables.push({
+      id: "b",
+      logicalName: "B",
+      physicalName: "TB",
+      columns: [createColumn("postgres", { id: "c2", logicalName: "y", logicalType: "TEXT" })]
+    });
+    doc.model.relationships.push({
+      id: "r1",
+      sourceTableId: "a",
+      targetTableId: "b"
+    });
+    const d = analyzeDdlDocument(doc);
+    expect(d.some((x) => x.code === "DDL_REL_MISSING_COLUMNS")).toBe(true);
+  });
+
+  it("generateDdlWithDiagnostics returns sql and same analyze list", () => {
+    const doc = createEmptyDesign("mysql");
+    doc.model.tables.push({
+      id: "t1",
+      logicalName: "T",
+      physicalName: "TT",
+      columns: [createColumn("mysql", { id: "c1", logicalName: "id", logicalType: "NUMBER", nullable: false })]
+    });
+    const { sql, diagnostics } = generateDdlWithDiagnostics(doc);
+    expect(sql).toContain("CREATE TABLE");
+    expect(diagnostics.length).toBeGreaterThanOrEqual(0);
+  });
+});