@sapporta/server 0.0.1

package/src/schema/metadata-io.ts

@@ -0,0 +1,161 @@
+// ============================================================================
+// SQLite Metadata I/O — JSON serialization and query helpers
+// ============================================================================
+//
+// Centralized JSON serialization for metadata table reads/writes.
+// Prevents scattered JSON.parse()/JSON.stringify() calls across the codebase.
+//
+// SQLite stores arrays and objects as TEXT (JSON strings), unlike Postgres
+// which has native JSONB and TEXT[] types. This module is the single point
+// where that encoding boundary is crossed:
+//
+//   Read path:  deserializeColumnRow() — JSON.parse select_options/ui_hints
+//   Write path: serializeColumnValues() — JSON.stringify select_options/ui_hints
+//   Merge path: mergeUiHints() — read-modify-write for partial updates
+//   Query path: buildSetClause() — construct parameterized UPDATE SET clauses
+//
+// The Postgres codebase doesn't need these because:
+//   - TEXT[] ↔ native array (postgres.js handles encoding)
+//   - JSONB ↔ native object (postgres.js handles encoding)
+//   - tx(obj) builds SET clauses dynamically (postgres.js feature)
+
+import type Database from "better-sqlite3";
+import type { ColumnMetaRow } from "./dynamic-builder.js";
+
+// ─── Deserialization (read path) ────────────────────────────────────────────
+
+/**
+ * Row shape from _sapporta_columns before deserialization.
+ * All fields are SQLite native types (TEXT for JSON, INTEGER for booleans).
+ */
+export interface RawMetadataColumnRow {
+  table_name: string;
+  column_name: string;
+  column_type: string;
+  position: number;
+  not_null: number; // SQLite INTEGER (0/1)
+  is_unique: number; // SQLite INTEGER (0/1)
+  default_value: string | null;
+  references_table: string | null;
+  select_options: string | null; // JSON-encoded string[]
+  ui_hints: string; // JSON-encoded Record<string, unknown>
+}
+
+/**
+ * Deserialize a raw metadata column row from SQLite into the application type.
+ *
+ * Converts:
+ *   - select_options: JSON string → string[] | undefined
+ *   - ui_hints: JSON string → Record<string, unknown>
+ *   - not_null/is_unique: INTEGER (0/1) → boolean
+ */
+export function deserializeColumnRow(
+  raw: RawMetadataColumnRow,
+): ColumnMetaRow {
+  return {
+    column_name: raw.column_name,
+    column_type: raw.column_type,
+    position: raw.position,
+    not_null: raw.not_null === 1,
+    is_unique: raw.is_unique === 1,
+    default_value: raw.default_value ?? undefined,
+    references_table: raw.references_table ?? undefined,
+    select_options: raw.select_options
+      ? JSON.parse(raw.select_options)
+      : undefined,
+    ui_hints: raw.ui_hints ? JSON.parse(raw.ui_hints) : {},
+  };
+}
+
+// ─── Serialization (write path) ─────────────────────────────────────────────
+
+/**
+ * Serialize column metadata values for INSERT/UPDATE into _sapporta_columns.
+ *
+ * Converts:
+ *   - select_options: string[] → JSON string
+ *   - ui_hints: Record<string, unknown> → JSON string
+ *
+ * Only serializes fields that are present in the input. Callers can pass
+ * partial objects for UPDATE operations.
+ */
+export function serializeColumnValues(
+  col: Partial<ColumnMetaRow>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...col };
+
+  if (col.select_options !== undefined) {
+    out.select_options = col.select_options
+      ? JSON.stringify(col.select_options)
+      : null;
+  }
+
+  if (col.ui_hints !== undefined) {
+    out.ui_hints = JSON.stringify(col.ui_hints ?? {});
+  }
+
+  return out;
+}
+
+// ─── JSONB merge (application-level) ────────────────────────────────────────
+
+/**
+ * Application-level JSONB merge for ui_hints.
+ *
+ * Replaces the Postgres pattern:
+ *   UPDATE _sapporta_columns SET ui_hints = COALESCE(ui_hints, '{}'::jsonb) || $val::jsonb
+ *
+ * SQLite has no native JSONB merge operator, so we read-modify-write.
+ * This must be called within a transaction to avoid lost updates from
+ * concurrent requests. In practice, better-sqlite3's synchronous nature
+ * means only one JS operation runs at a time, but using a transaction
+ * is still correct for atomicity if the caller batches multiple writes.
+ */
+export function mergeUiHints(
+  sqlite: Database.Database,
+  tableName: string,
+  columnName: string,
+  merge: Record<string, unknown>,
+): void {
+  const row = sqlite
+    .prepare(
+      `SELECT ui_hints FROM _sapporta_columns
+       WHERE table_name = ? AND column_name = ?`,
+    )
+    .get(tableName, columnName) as { ui_hints: string } | undefined;
+
+  const current = row?.ui_hints ? JSON.parse(row.ui_hints) : {};
+  const merged = { ...current, ...merge };
+
+  sqlite
+    .prepare(
+      `UPDATE _sapporta_columns SET ui_hints = ?
+       WHERE table_name = ? AND column_name = ?`,
+    )
+    .run(JSON.stringify(merged), tableName, columnName);
+}
+
+// ─── Query helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Build a parameterized SET clause from an object.
+ *
+ * Replaces the postgres.js tx(obj) dynamic SET pattern which constructs
+ * SET clauses from objects automatically. SQLite's better-sqlite3 has
+ * no equivalent, so we build it manually.
+ *
+ * Example:
+ *   buildSetClause({ label: "Foo", position: 3 })
+ *   → { clause: '"label" = ?, "position" = ?', values: ["Foo", 3] }
+ *
+ * Column names are double-quoted to handle reserved words safely.
+ * Values are parameterized (never interpolated) to prevent injection.
+ */
+export function buildSetClause(
+  obj: Record<string, unknown>,
+): { clause: string; values: unknown[] } {
+  const keys = Object.keys(obj);
+  const clause = keys.map((k) => `"${k}" = ?`).join(", ");
+  const values = keys.map((k) => obj[k]);
+  return { clause, values };
+}