@sapporta/server 0.0.1

package/src/schema/dynamic-builder.ts

@@ -0,0 +1,297 @@
+/**
+ * Dynamic Table Builder — constructs real Drizzle SQLite table objects from metadata rows.
+ *
+ * This is the core bridge between UI-managed table definitions (stored in
+ * _sapporta_tables / _sapporta_columns) and the runtime type system. Every
+ * Drizzle API surface — query builder, getTableConfig, FK references,
+ * extractSchemas, CRUD, validation — works identically with these runtime-
+ * constructed tables as with compile-time ones. The only caveat is compile-time
+ * type loss (SQLiteTableWithColumns<any>), which is harmless at runtime and
+ * matches the existing `as any` cast pattern used throughout the codebase.
+ */
+import { sqliteTable, text, integer, real } from "drizzle-orm/sqlite-core";
+import { sql } from "drizzle-orm";
+import type { SchemaRegistry } from "./registry.js";
+import type { TableDef, SapportaMeta, SelectMeta, ColumnMeta as SapportaColumnMeta } from "./table.js";
+import { logger } from "../db/logger.js";
+
+// DDL generation is delegated to ddl.ts.
+// Re-export the DDL functions so callers that imported from here still work.
+export {
+  SQLITE_TYPE_MAP,
+  sqliteTypeForColumnType,
+  generateCreateTableDDL,
+  generateAddColumnDDL,
+  generateCheckConstraintDDL,
+} from "./ddl.js";
+import { SQLITE_TYPE_MAP } from "./ddl.js";
+
+const log = logger.child({ module: "schema" });
+
+// ─── Metadata Row Types ─────────────────────────────────────────────────────
+// These describe the rows stored in _sapporta_tables and _sapporta_columns.
+// They are the "source of truth" for UI-managed table definitions.
+
+export interface TableMeta {
+  name: string;
+  label?: string;
+  display_column?: string;
+  immutable?: boolean;
+  inferred?: boolean;
+  position?: number;
+}
+
+export interface ColumnMetaRow {
+  column_name: string;
+  /** Logical column type that determines both the Drizzle builder and SQLite DDL type.
+   *  Some types map to the same SQLite type but carry different UI semantics:
+   *  - "currency" / "percentage" → TEXT (exact decimal, not REAL)
+   *  - "email" / "url" → TEXT (UI-only distinction for validation)
+   *  - "select" → TEXT (validation via select_options, not a DB constraint)
+   *  - "link" → INTEGER + FK constraint (references another table's PK) */
+  column_type: string;
+  position: number;
+  not_null?: boolean;
+  is_unique?: boolean;
+  default_value?: string;
+  /** For "link" columns: the SQL name of the referenced table. */
+  references_table?: string;
+  /** For "select" columns: the allowed option values. */
+  select_options?: string[];
+  /** Arbitrary UI hints (display width, formatting, etc.) stored as JSON text. */
+  ui_hints?: Record<string, unknown>;
+}
+
+// ─── Column Type Validation ─────────────────────────────────────────────────
+// The set of valid column_type values accepted by the mutation API.
+// Derived from the SQLite type map so DDL generation and validation agree.
+
+/** The set of valid column_type values accepted by the mutation API. */
+export const VALID_COLUMN_TYPES = new Set(Object.keys(SQLITE_TYPE_MAP));
+
+// ─── Drizzle Column Builders ────────────────────────────────────────────────
+// Maps each logical type to the Drizzle builder function that constructs
+// the in-memory column definition used by the query builder and ORM.
+//
+// Critical SQLite-specific mappings:
+//   - boolean → integer({ mode: "boolean" }): Drizzle handles 0/1 ↔ true/false
+//   - date/timestamp → text(): ISO 8601 strings, no Date object conversion
+//   - currency/percentage → text(): exact decimal as text, not REAL (precision loss)
+//   - numeric → real(): only for user-defined "numeric" columns (aggregation use)
+
+type ColumnBuilder = (name: string) => any;
+
+const DRIZZLE_BUILDER_MAP: Record<string, ColumnBuilder> = {
+  text: (name) => text(name),
+  integer: (name) => integer(name),
+  numeric: (name) => real(name),
+  boolean: (name) => integer(name, { mode: "boolean" }),
+  date: (name) => text(name),           // ISO 8601 string
+  timestamp: (name) => text(name),      // ISO 8601 string
+  select: (name) => text(name),
+  link: (name) => integer(name),
+  currency: (name) => text(name),       // Exact decimal as text (see sqlite-ddl.ts C4)
+  percentage: (name) => text(name),     // Exact decimal as text (see sqlite-ddl.ts C4)
+  email: (name) => text(name),
+  url: (name) => text(name),
+};
+
+// ─── Intermediate Representation ──────────────────────────────────────────
+// A pure, self-contained description of a table — no Drizzle objects, no
+// registry lookups. Produced by planTable(), consumed by realizeTable().
+
+export interface ColumnSpec {
+  name: string;
+  /** Key into DRIZZLE_BUILDER_MAP (e.g. "text", "link", "currency") */
+  builderType: string;
+  notNull: boolean;
+  isUnique: boolean;
+  defaultValue: string | undefined;
+  /** For "link" columns: SQL name of FK target table. null otherwise. */
+  fkTarget: string | null;
+}
+
+export interface TableSpec {
+  sqlName: string;
+  /** User-defined only; system cols (id, created_at, updated_at) are implicit */
+  columns: ColumnSpec[];
+  meta: SapportaMeta;
+}
+
+// ─── Pure Layer ───────────────────────────────────────────────────────────
+
+/**
+ * Compute a TableSpec from raw metadata — pure function, no side effects.
+ *
+ * Unknown column types are skipped with a log.warn (the only impurity,
+ * and only in the degenerate case that should never occur after mutation
+ * API validation).
+ */
+export function planTable(
+  tableMeta: TableMeta,
+  columns: ColumnMetaRow[],
+): TableSpec {
+  const specs: ColumnSpec[] = [];
+
+  for (const col of columns) {
+    if (!DRIZZLE_BUILDER_MAP[col.column_type]) {
+      log.warn("Unknown column type, skipping", { table: tableMeta.name, column: col.column_name, type: col.column_type });
+      continue;
+    }
+
+    specs.push({
+      name: col.column_name,
+      builderType: col.column_type,
+      notNull: col.not_null ?? false,
+      isUnique: col.is_unique ?? false,
+      defaultValue: col.default_value !== undefined && col.default_value !== null
+        ? col.default_value
+        : undefined,
+      fkTarget: col.column_type === "link" && col.references_table
+        ? col.references_table
+        : null,
+    });
+  }
+
+  return {
+    sqlName: tableMeta.name,
+    columns: specs,
+    meta: buildSapportaMeta(tableMeta, columns),
+  };
+}
+
+// ─── Effectful Layer ──────────────────────────────────────────────────────
+
+/**
+ * Translate a TableSpec into a live Drizzle SQLite table + SapportaMeta.
+ *
+ * This is the only function that touches Drizzle builders and the registry.
+ *
+ * FK resolution strategy:
+ * - Uses Drizzle's lazy reference pattern: .references(() => target.id).
+ *   The callback is evaluated at query time, not definition time, so the
+ *   target just needs to exist in the registry by the time the first query runs.
+ * - If the target isn't in the registry, we skip .references() and log a
+ *   warning. The column is still created as integer() without the FK
+ *   constraint — boot validation will flag dangling links.
+ */
+export function realizeTable(
+  spec: TableSpec,
+  registry: SchemaRegistry,
+): TableDef {
+  // System columns — always present, never in the spec.
+  // SQLite uses INTEGER PRIMARY KEY AUTOINCREMENT instead of SERIAL.
+  // Timestamps are TEXT columns with ISO 8601 strings (no native timestamp type).
+  const columnDefs: Record<string, any> = {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    created_at: text("created_at").notNull().default(sql`(datetime('now'))`),
+    updated_at: text("updated_at").notNull().default(sql`(datetime('now'))`),
+  };
+
+  for (const col of spec.columns) {
+    let drizzleCol = DRIZZLE_BUILDER_MAP[col.builderType](col.name);
+
+    if (col.notNull) drizzleCol = drizzleCol.notNull();
+    if (col.isUnique) drizzleCol = drizzleCol.unique();
+    if (col.defaultValue !== undefined) drizzleCol = drizzleCol.default(col.defaultValue);
+
+    if (col.fkTarget) {
+      if (registry.has(col.fkTarget)) {
+        const targetName = col.fkTarget;
+        drizzleCol = drizzleCol.references(() => {
+          const entry = registry.get(targetName);
+          if (!entry) {
+            throw new Error(`FK target "${targetName}" not found in registry`);
+          }
+          return (entry.def.drizzle as any).id;
+        });
+      } else {
+        log.warn("FK target not found, creating as plain integer without FK constraint", {
+          table: spec.sqlName, column: col.name, target: col.fkTarget,
+        });
+      }
+    }
+
+    columnDefs[col.name] = drizzleCol;
+  }
+
+  return {
+    drizzle: sqliteTable(spec.sqlName, columnDefs),
+    sqlName: spec.sqlName,
+    meta: spec.meta,
+  };
+}
+
+// ─── Composed ─────────────────────────────────────────────────────────────
+
+/**
+ * Construct a real Drizzle SQLite table object from metadata rows.
+ * Composes planTable (pure) → realizeTable (effectful).
+ */
+export function buildDrizzleTable(
+  tableMeta: TableMeta,
+  columns: ColumnMetaRow[],
+  registry: SchemaRegistry,
+): TableDef {
+  const spec = planTable(tableMeta, columns);
+  return realizeTable(spec, registry);
+}
+
+// ─── SapportaMeta Construction ──────────────────────────────────────────────
+
+/**
+ * Build the SapportaMeta object from table + column metadata.
+ *
+ * The goal is to produce the same metadata structure that file-managed tables
+ * define statically in their table() calls, so the rest of Sapporta (CRUD,
+ * validation, schema API, etc.) treats both origins identically.
+ */
+function buildSapportaMeta(
+  tableMeta: TableMeta,
+  columns: ColumnMetaRow[],
+): SapportaMeta {
+  // Collect select column definitions for Zod validation
+  const selects: SelectMeta[] = columns
+    .filter((c) => c.column_type === "select" && c.select_options?.length)
+    .map((c) => ({
+      type: "select" as const,
+      column: c.column_name,
+      options: c.select_options!,
+    }));
+
+  // Build per-column metadata from ui_hints and type-specific info
+  const columnsMeta: Record<string, SapportaColumnMeta> = {};
+  for (const col of columns) {
+    const meta: SapportaColumnMeta = {};
+
+    // Always store the logical column type for UI-managed columns
+    meta.columnType = col.column_type;
+
+    // Currency columns get "money" type for right-aligned decimal formatting
+    if (col.column_type === "currency") {
+      meta.type = "money";
+    }
+
+    // Merge any explicit UI hints (width, header, hidden, etc.)
+    if (col.ui_hints) {
+      if (typeof col.ui_hints.header === "string") meta.header = col.ui_hints.header;
+      if (typeof col.ui_hints.hidden === "boolean") meta.hidden = col.ui_hints.hidden;
+      if (typeof col.ui_hints.width === "number") meta.width = col.ui_hints.width;
+      if (typeof col.ui_hints.minWidth === "number") meta.minWidth = col.ui_hints.minWidth;
+      if (typeof col.ui_hints.maxWidth === "number") meta.maxWidth = col.ui_hints.maxWidth;
+      if (typeof col.ui_hints.widthPx === "number") meta.widthPx = col.ui_hints.widthPx;
+      if (typeof col.ui_hints.notes === "string") meta.notes = col.ui_hints.notes;
+    }
+
+    columnsMeta[col.column_name] = meta;
+  }
+
+  return {
+    label: tableMeta.label,
+    displayColumn: tableMeta.display_column,
+    immutable: tableMeta.immutable ?? false,
+    inferred: tableMeta.inferred ?? false,
+    ...(selects.length > 0 ? { selects } : {}),
+    ...(Object.keys(columnsMeta).length > 0 ? { columns: columnsMeta } : {}),
+  };
+}

package/src/schema/extract.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect } from "vitest";
+import { Hono } from "hono";
+import {
+  sqliteTable,
+  text,
+  integer,
+  real,
+} from "drizzle-orm/sqlite-core";
+import { timestamp } from "./table.js";
+import { table } from "./table.js";
+import { schemaApi, extractSchemas, extractSchema } from "./extract.js";
+
+const accountsTable = sqliteTable("accounts", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull(),
+  type: text("type").notNull(),
+  balance: integer("balance"),
+  active: integer("active", { mode: "boolean" }).default(true),
+  created_at: timestamp("created_at").notNull().$defaultFn(() => new Date().toISOString()),
+});
+
+const accounts = table({
+  drizzle: accountsTable,
+  meta: {
+    label: "Accounts",
+    selects: [
+      {
+        type: "select",
+        column: "type",
+        options: ["asset", "liability", "equity", "revenue", "expense"],
+      },
+    ],
+  },
+});
+
+// Table with FK
+const invoicesTable = sqliteTable("invoices", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  account_id: integer("account_id")
+    .notNull()
+    .references(() => accountsTable.id),
+  amount: integer("amount").notNull(),
+});
+
+const invoices = table({
+  drizzle: invoicesTable,
+  meta: { label: "Invoices" },
+});
+
+// Immutable table
+const ledgerTable = sqliteTable("ledger", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  description: text("description").notNull(),
+});
+
+const ledger = table({
+  drizzle: ledgerTable,
+  meta: { immutable: true },
+});
+
+// Table with money columns
+const transactionsTable = sqliteTable("transactions", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  description: text("description").notNull(),
+  debit: real("debit"),
+  credit: real("credit"),
+});
+
+const transactions = table({
+  drizzle: transactionsTable,
+  meta: {
+    label: "Transactions",
+    columns: {
+      debit: { type: "money" },
+      credit: { type: "money" },
+    },
+  },
+});
+
+describe("extractSchemas", () => {
+  it("extracts table metadata correctly", () => {
+    const result = extractSchemas([accounts]);
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe("accounts");
+    expect(result[0].label).toBe("Accounts");
+    expect(result[0].immutable).toBe(false);
+  });
+
+  it("extracts column metadata", () => {
+    const result = extractSchemas([accounts]);
+    const cols = result[0].columns;
+
+    const idCol = cols.find((c) => c.name === "id")!;
+    expect(idCol.primary).toBe(true);
+    expect(idCol.hasDefault).toBe(true);
+    expect(idCol.dataType).toBe("number");
+
+    const nameCol = cols.find((c) => c.name === "name")!;
+    expect(nameCol.notNull).toBe(true);
+    expect(nameCol.dataType).toBe("string");
+    expect(nameCol.primary).toBe(false);
+
+    const balanceCol = cols.find((c) => c.name === "balance")!;
+    expect(balanceCol.notNull).toBe(false);
+    expect(balanceCol.dataType).toBe("number");
+  });
+
+  it("includes select metadata", () => {
+    const result = extractSchemas([accounts]);
+    const typeCol = result[0].columns.find((c) => c.name === "type")!;
+    expect(typeCol.select).toEqual({
+      options: ["asset", "liability", "equity", "revenue", "expense"],
+    });
+  });
+
+  it("detects foreign keys", () => {
+    const result = extractSchemas([invoices]);
+    const fkCol = result[0].columns.find((c) => c.name === "account_id")!;
+    expect(fkCol.foreignKey).toEqual({ table: "accounts", column: "id" });
+  });
+
+  it("marks immutable tables", () => {
+    const result = extractSchemas([ledger]);
+    expect(result[0].immutable).toBe(true);
+  });
+
+  it("defaults label to sqlName", () => {
+    const result = extractSchemas([ledger]);
+    expect(result[0].label).toBe("ledger");
+  });
+
+  it("marks money columns from column metadata", () => {
+    const result = extractSchemas([transactions]);
+    const cols = result[0].columns;
+
+    const debitCol = cols.find((c) => c.name === "debit")!;
+    expect(debitCol.money).toBe(true);
+
+    const creditCol = cols.find((c) => c.name === "credit")!;
+    expect(creditCol.money).toBe(true);
+
+    const descCol = cols.find((c) => c.name === "description")!;
+    expect(descCol.money).toBe(false);
+  });
+
+  it("defaults money to false when no column metadata", () => {
+    const result = extractSchemas([accounts]);
+    const cols = result[0].columns;
+    for (const col of cols) {
+      expect(col.money).toBe(false);
+    }
+  });
+
+  it("auto-hides created_at and updated_at columns", () => {
+    // Hidden by default so the UI table views don't show noisy timestamps.
+    const result = extractSchemas([accounts]);
+    const cols = result[0].columns;
+
+    const createdAt = cols.find((c) => c.name === "created_at")!;
+    expect(createdAt.hidden).toBe(true);
+
+    // Columns that aren't created_at/updated_at should not be auto-hidden
+    const nameCol = cols.find((c) => c.name === "name")!;
+    expect(nameCol.hidden).toBeUndefined();
+  });
+
+  it("allows meta.columns to override auto-hidden timestamps", () => {
+    const customTable = sqliteTable("audit", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      created_at: timestamp("created_at").notNull().$defaultFn(() => new Date().toISOString()),
+    });
+    const audit = table({
+      drizzle: customTable,
+      meta: {
+        columns: {
+          created_at: { hidden: false },
+        },
+      },
+    });
+
+    const result = extractSchemas([audit]);
+    const createdAt = result[0].columns.find((c) => c.name === "created_at")!;
+    expect(createdAt.hidden).toBe(false);
+  });
+
+  it("resolves children from parent table's meta.children", () => {
+    const ordersTable = sqliteTable("orders", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      customer: text("customer").notNull(),
+      created_at: timestamp("created_at"),
+      updated_at: timestamp("updated_at"),
+    });
+    const lineItemsTable = sqliteTable("line_items", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      order_id: integer("order_id").notNull().references(() => ordersTable.id),
+      product: text("product").notNull(),
+      quantity: integer("quantity").notNull(),
+      created_at: timestamp("created_at"),
+      updated_at: timestamp("updated_at"),
+    });
+
+    const orders = table({
+      drizzle: ordersTable,
+      meta: {
+        label: "Orders",
+        children: [
+          { table: "line_items", foreignKey: "order_id" },
+        ],
+      },
+    });
+    const lineItems = table({
+      drizzle: lineItemsTable,
+      meta: { label: "Line Items" },
+    });
+
+    const result = extractSchemas([orders, lineItems]);
+    const orderSchema = result.find((s) => s.name === "orders")!;
+
+    expect(orderSchema.children).toHaveLength(1);
+    const child = orderSchema.children[0];
+    expect(child.table).toBe("line_items");
+    expect(child.foreignKey).toBe("order_id");
+    expect(child.label).toBe("Line Items");
+
+    // Auto-resolved columns should exclude: id, order_id, created_at, updated_at
+    expect(child.columns).toContain("product");
+    expect(child.columns).toContain("quantity");
+    expect(child.columns).not.toContain("id");
+    expect(child.columns).not.toContain("order_id");
+    expect(child.columns).not.toContain("created_at");
+    expect(child.columns).not.toContain("updated_at");
+  });
+});
+
+describe("extractSchema (single-table lookup)", () => {
+  it("returns schema for a known table", () => {
+    const result = extractSchema([accounts, invoices], "accounts");
+    expect(result).toBeDefined();
+    expect(result!.name).toBe("accounts");
+    expect(result!.label).toBe("Accounts");
+  });
+
+  it("returns undefined for unknown table", () => {
+    const result = extractSchema([accounts], "nonexistent");
+    expect(result).toBeUndefined();
+  });
+});
+
+describe("GET /meta/tables", () => {
+  it("returns schema metadata via HTTP", async () => {
+    const app = new Hono();
+    app.route("/meta/tables", schemaApi([accounts, invoices]));
+
+    const res = await app.request("/meta/tables");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.tables).toHaveLength(2);
+    expect(json.tables[0].name).toBe("accounts");
+    expect(json.tables[1].name).toBe("invoices");
+  });
+});