@sapporta/server 0.0.1

package/src/data/crud.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Hono } from "hono";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { table } from "../schema/table.js";
+import { crud } from "./crud.js";
+import { createTestDb } from "../testing/test-utils.js";
+
+const accountsTable = sqliteTable("accounts", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull(),
+  type: text("type").notNull(),
+  balance: integer("balance"),
+});
+
+const accounts = table({
+  drizzle: accountsTable,
+  meta: {
+    selects: [
+      {
+        type: "select",
+        column: "type",
+        options: ["asset", "liability", "equity", "revenue", "expense"],
+      },
+    ],
+  },
+});
+
+describe("CRUD sub-app", () => {
+  let app: Hono;
+
+  beforeEach(async () => {
+    const { db, sqlite } = createTestDb();
+    sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS accounts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL,
+        balance INTEGER
+      )
+    `);
+
+    app = new Hono();
+    app.route("/api/accounts", crud(accounts, db));
+  });
+
+  it("POST / creates a record", async () => {
+    const res = await app.request("/api/accounts", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Cash", type: "asset" }),
+    });
+
+    expect(res.status).toBe(201);
+    const json = await res.json();
+    expect(json.data.name).toBe("Cash");
+    expect(json.data.type).toBe("asset");
+    expect(json.data.id).toBe(1);
+  });
+
+  it("POST / validates input", async () => {
+    const res = await app.request("/api/accounts", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Bad", type: "invalid" }),
+    });
+
+    expect(res.status).toBe(422);
+    const json = await res.json();
+    expect(json.error).toBe("Validation failed");
+  });
+
+  it("GET / lists records with pagination", async () => {
+    // Insert two records
+    await app.request("/api/accounts", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Cash", type: "asset" }),
+    });
+    await app.request("/api/accounts", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Revenue", type: "revenue" }),
+    });
+
+    const res = await app.request("/api/accounts");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data).toHaveLength(2);
+    expect(json.meta.total).toBe(2);
+    expect(json.meta.page).toBe(1);
+  });
+
+  it("GET /:id returns single record", async () => {
+    await app.request("/api/accounts", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Cash", type: "asset" }),
+    });
+
+    const res = await app.request("/api/accounts/1");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data.name).toBe("Cash");
+  });
+
+  it("GET /:id returns 404 for missing record", async () => {
+    const res = await app.request("/api/accounts/999");
+    expect(res.status).toBe(404);
+  });
+
+  it("PUT /:id updates a record", async () => {
+    await app.request("/api/accounts", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Cash", type: "asset" }),
+    });
+
+    const res = await app.request("/api/accounts/1", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Cash on Hand", type: "asset" }),
+    });
+
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data.name).toBe("Cash on Hand");
+  });
+
+  it("DELETE /:id removes a record", async () => {
+    await app.request("/api/accounts", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "Cash", type: "asset" }),
+    });
+
+    const res = await app.request("/api/accounts/1", { method: "DELETE" });
+    expect(res.status).toBe(200);
+
+    const check = await app.request("/api/accounts/1");
+    expect(check.status).toBe(404);
+  });
+
+  it("DELETE /:id returns 404 for missing record", async () => {
+    const res = await app.request("/api/accounts/999", { method: "DELETE" });
+    expect(res.status).toBe(404);
+  });
+});
+
+describe("CRUD immutable table", () => {
+  let app: Hono;
+
+  beforeEach(async () => {
+    const { db, sqlite } = createTestDb();
+    sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS ledger (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        description TEXT NOT NULL
+      )
+    `);
+
+    const ledgerTable = sqliteTable("ledger", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      description: text("description").notNull(),
+    });
+
+    const ledger = table({
+      drizzle: ledgerTable,
+      meta: { immutable: true },
+    });
+
+    app = new Hono();
+    app.route("/api/ledger", crud(ledger, db));
+  });
+
+  it("blocks PUT on immutable table", async () => {
+    const res = await app.request("/api/ledger/1", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ description: "updated" }),
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it("blocks DELETE on immutable table", async () => {
+    const res = await app.request("/api/ledger/1", { method: "DELETE" });
+    expect(res.status).toBe(403);
+  });
+});

package/src/data/crud.ts

@@ -0,0 +1,242 @@
+import { Hono } from "hono";
+import type { Context } from "hono";
+import { asc, eq, sql } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import type { TableDef } from "../schema/table.js";
+import type { SchemaRegistry } from "../schema/registry.js";
+import { savePipeline } from "./save-pipeline.js";
+import { parseQuery } from "./query-parser.js";
+import { ValidationError } from "../db/errors.js";
+import { logger } from "../db/logger.js";
+
+const log = logger.child({ module: "crud" });
+
+// ---------------------------------------------------------------------------
+// Standalone handler functions for CRUD operations.
+//
+// Called by the tables API router (tables-api.ts) which resolves the schema
+// from the registry on each request. Each handler computes config/pkCol per-call
+// rather than closing over them — the overhead is negligible (synchronous
+// property lookups on small arrays).
+// ---------------------------------------------------------------------------
+
+/** Resolve primary key column and its Drizzle reference, or return a 500 error. */
+function resolvePk(schema: TableDef, c: Context) {
+  const config = getTableConfig(schema.drizzle);
+  const pkCol = config.columns.find((col) => col.primary);
+  if (!pkCol) {
+    return { ok: false as const, response: c.json({ error: "No primary key" }, 500) };
+  }
+  const drizzlePk = (schema.drizzle as any)[pkCol.name];
+  return { ok: true as const, pkCol, drizzlePk };
+}
+
+/** GET / — list with filters, sort, pagination. */
+export async function handleList(schema: TableDef, db: any, c: Context): Promise<Response> {
+  const pk = resolvePk(schema, c);
+  if (!pk.ok) return pk.response;
+
+  const params = Object.fromEntries(
+    new URL(c.req.url).searchParams.entries(),
+  );
+  const query = parseQuery(params, schema);
+
+  let q = db.select().from(schema.drizzle);
+  if (query.where) {
+    q = q.where(query.where);
+  }
+
+  // Count total rows matching filters (before pagination)
+  const countResult = await db
+    .select({ count: sql<number>`count(*)` })
+    .from(schema.drizzle)
+    .where(query.where ?? sql`TRUE`);
+  const total = Number(countResult[0].count);
+
+  if (query.orderBy.length > 0) {
+    q = q.orderBy(...query.orderBy);
+  } else {
+    // Default to PK ascending so row order is stable across re-fetches.
+    // Without this, the DB may return rows in arbitrary order which shifts
+    // after UPDATEs, causing the grid to visually reorder rows on every
+    // inline cell edit.
+    q = q.orderBy(asc(pk.drizzlePk));
+  }
+
+  q = q.limit(query.limit).offset(query.offset);
+  const rows = await q;
+
+  return c.json({
+    data: rows,
+    meta: {
+      total,
+      page: Math.floor(query.offset / query.limit) + 1,
+      limit: query.limit,
+      pages: Math.ceil(total / query.limit),
+    },
+  });
+}
+
+/** GET /:id — single row by primary key. */
+export async function handleGet(schema: TableDef, db: any, c: Context, id: string): Promise<Response> {
+  const pk = resolvePk(schema, c);
+  if (!pk.ok) return pk.response;
+
+  const rows = await db
+    .select()
+    .from(schema.drizzle)
+    .where(eq(pk.drizzlePk, Number(id)));
+
+  if (rows.length === 0) {
+    return c.json({ error: "Not found" }, 404);
+  }
+  return c.json({ data: rows[0] });
+}
+
+/** POST / — create one or more records via the save pipeline.
+ *  Accepts a single object or an array of objects.
+ *  When the body includes a `$details` field, treats it as a master-detail insert
+ *  (requires registry to resolve the detail table's schema). */
+export async function handleCreate(
+  schema: TableDef,
+  db: any,
+  c: Context,
+  opts?: { registry?: SchemaRegistry },
+): Promise<Response> {
+  const body = await c.req.json();
+  log.debug("Create request", { table: schema.sqlName, body });
+  try {
+    // Master-detail insert: body has $details field
+    if (body.$details && !Array.isArray(body)) {
+      if (!opts?.registry) {
+        return c.json({ error: "Master-detail inserts require a schema registry" }, 500);
+      }
+      return await handleMasterDetailCreate(schema, db, c, body, opts.registry);
+    }
+
+    // Batch or single insert
+    const records = Array.isArray(body) ? body : [body];
+    const results = [];
+    for (const record of records) {
+      results.push(await savePipeline(schema, db, record));
+    }
+    return c.json({ data: results.length === 1 ? results[0] : results }, 201);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      log.warn("Create validation failed", { table: schema.sqlName, errors: err.errors });
+      return c.json({ error: "Validation failed", details: err.errors }, 422);
+    }
+    throw err;
+  }
+}
+
+/** Master-detail insert: insert master record, then detail records with FK backfill.
+ *  Everything runs inside a single Drizzle transaction. */
+async function handleMasterDetailCreate(
+  masterSchema: TableDef,
+  db: any,
+  c: Context,
+  body: Record<string, unknown>,
+  registry: SchemaRegistry,
+): Promise<Response> {
+  const { $details, ...masterData } = body;
+  const details = $details as { table: string; fk: string; rows: Record<string, unknown>[] };
+
+  if (!details.table || !details.fk || !Array.isArray(details.rows)) {
+    return c.json(
+      { error: "$details must have: table (string), fk (string), rows (array)" },
+      400,
+    );
+  }
+
+  // Resolve detail table schema from registry
+  const detailEntry = registry.get(details.table);
+  if (!detailEntry) {
+    return c.json({ error: `Detail table "${details.table}" not found` }, 404);
+  }
+  const detailSchema = detailEntry.def;
+
+  // Resolve master PK column name
+  const masterConfig = getTableConfig(masterSchema.drizzle);
+  const masterPkCol = masterConfig.columns.find((col) => col.primary);
+  if (!masterPkCol) {
+    return c.json({ error: "Master table has no primary key" }, 500);
+  }
+
+  // Run everything in a transaction
+  const result = await db.transaction(async (tx: any) => {
+    // Insert master record
+    const masterResult = await savePipeline(masterSchema, tx, masterData as Record<string, unknown>);
+    const masterPkValue = (masterResult as any)[masterPkCol.name];
+
+    // Insert detail records with FK backfill
+    const detailResults = [];
+    for (const row of details.rows) {
+      const detailRow = { ...row, [details.fk]: masterPkValue };
+      detailResults.push(await savePipeline(detailSchema, tx, detailRow));
+    }
+
+    return { master: masterResult, details: detailResults };
+  });
+
+  return c.json({ data: result }, 201);
+}
+
+/** PUT /:id — update an existing record. Rejects if table is immutable. */
+export async function handleUpdate(schema: TableDef, db: any, c: Context, id: string): Promise<Response> {
+  if (schema.meta.immutable) {
+    return c.json({ error: "Records in this table are immutable" }, 403);
+  }
+
+  const body = await c.req.json();
+  log.debug("Update request", { table: schema.sqlName, id, body });
+  try {
+    const result = await savePipeline(schema, db, body, Number(id));
+    return c.json({ data: result });
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      log.warn("Update validation failed", { table: schema.sqlName, id, errors: err.errors });
+      return c.json({ error: "Validation failed", details: err.errors }, 422);
+    }
+    if (err instanceof Error && err.message.includes("not found")) {
+      return c.json({ error: "Not found" }, 404);
+    }
+    throw err;
+  }
+}
+
+/** DELETE /:id — delete a record. Rejects if table is immutable. */
+export async function handleDelete(schema: TableDef, db: any, c: Context, id: string): Promise<Response> {
+  if (schema.meta.immutable) {
+    return c.json({ error: "Records in this table are immutable" }, 403);
+  }
+
+  const pk = resolvePk(schema, c);
+  if (!pk.ok) return pk.response;
+
+  const deleted = await db
+    .delete(schema.drizzle)
+    .where(eq(pk.drizzlePk, Number(id)))
+    .returning();
+
+  if (deleted.length === 0) {
+    return c.json({ error: "Not found" }, 404);
+  }
+  return c.json({ data: deleted[0] });
+}
+
+/**
+ * Create a CRUD sub-app for a table schema (convenience wrapper for tests).
+ * Production routing uses the dynamic router which calls handlers directly.
+ */
+export function crud(schema: TableDef, db: any) {
+  const app = new Hono();
+
+  app.get("/", (c) => handleList(schema, db, c));
+  app.get("/:id", (c) => handleGet(schema, db, c, c.req.param("id")));
+  app.post("/", (c) => handleCreate(schema, db, c));
+  app.put("/:id", (c) => handleUpdate(schema, db, c, c.req.param("id")));
+  app.delete("/:id", (c) => handleDelete(schema, db, c, c.req.param("id")));
+
+  return app;
+}

package/src/data/lookup.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Hono } from "hono";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { table } from "../schema/table.js";
+import { lookupEndpoint, findDisplayColumn } from "./lookup.js";
+import { createTestDb } from "../testing/test-utils.js";
+
+const accountsTable = sqliteTable("accounts", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull(),
+  type: text("type").notNull(),
+});
+
+const accounts = table({
+  drizzle: accountsTable,
+  meta: { label: "Accounts" },
+});
+
+describe("findDisplayColumn", () => {
+  it("returns first text non-PK column", () => {
+    expect(findDisplayColumn(accounts)).toBe("name");
+  });
+
+  it("skips FK columns", () => {
+    const invoicesTable = sqliteTable("invoices", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      account_id: integer("account_id")
+        .notNull()
+        .references(() => accountsTable.id),
+      description: text("description").notNull(),
+    });
+    const invoices = table({ drizzle: invoicesTable, meta: {} });
+    expect(findDisplayColumn(invoices)).toBe("description");
+  });
+
+  it("returns null when no text column exists", () => {
+    const numbersTable = sqliteTable("numbers", {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      value: integer("value").notNull(),
+    });
+    const numbers = table({ drizzle: numbersTable, meta: {} });
+    expect(findDisplayColumn(numbers)).toBeNull();
+  });
+});
+
+describe("GET /_lookup", () => {
+  let app: Hono;
+
+  beforeEach(async () => {
+    const { db, sqlite } = createTestDb();
+    sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS accounts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL
+      )
+    `);
+    // Insert test data
+    sqlite.exec(`
+      INSERT INTO accounts (name, type) VALUES ('Cash', 'asset');
+      INSERT INTO accounts (name, type) VALUES ('Revenue', 'revenue');
+      INSERT INTO accounts (name, type) VALUES ('Rent', 'expense');
+    `);
+
+    app = new Hono();
+    app.route("/api/accounts/_lookup", lookupEndpoint(accounts, db));
+  });
+
+  it("returns display values for given IDs", async () => {
+    const res = await app.request("/api/accounts/_lookup?ids=1,2");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data).toEqual({ "1": "Cash", "2": "Revenue" });
+  });
+
+  it("returns all display values when ids param is absent", async () => {
+    const res = await app.request("/api/accounts/_lookup");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data).toEqual({ "1": "Cash", "2": "Revenue", "3": "Rent" });
+  });
+
+  it("returns empty object for empty ids", async () => {
+    const res = await app.request("/api/accounts/_lookup?ids=");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data).toEqual({});
+  });
+
+  it("skips IDs that do not exist", async () => {
+    const res = await app.request("/api/accounts/_lookup?ids=1,999");
+    expect(res.status).toBe(200);
+    const json = await res.json();
+    expect(json.data).toEqual({ "1": "Cash" });
+  });
+});

package/src/data/lookup.ts

@@ -0,0 +1,104 @@
+import { Hono } from "hono";
+import type { Context } from "hono";
+import { inArray } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import type { TableDef } from "../schema/table.js";
+
+/**
+ * Find the "display" column for a table — the column whose value is shown
+ * as the human-readable label in FK dropdowns and lookup responses.
+ *
+ * Checks `meta.displayColumn` first (explicit override), then falls back
+ * to a heuristic: first text column that is neither the PK nor a FK.
+ */
+export function findDisplayColumn(schema: TableDef): string | null {
+  if (schema.meta.displayColumn) {
+    return schema.meta.displayColumn;
+  }
+
+  // Heuristic: first text column that's not PK or FK
+  const config = getTableConfig(schema.drizzle);
+
+  const fkColumns = new Set<string>();
+  for (const fk of config.foreignKeys) {
+    const ref = fk.reference();
+    if (ref.columns[0]) fkColumns.add(ref.columns[0].name);
+  }
+
+  for (const col of config.columns) {
+    if (col.primary) continue;
+    if (fkColumns.has(col.name)) continue;
+    if (col.dataType === "string") return col.name;
+  }
+
+  return null;
+}
+
+/**
+ * Handle a lookup request: GET /?ids=1,2,3
+ * Returns { data: { "1": "Display Value", ... } }
+ * Without `ids`, returns all display values (for FK dropdowns).
+ */
+export async function handleLookup(schema: TableDef, db: any, c: Context): Promise<Response> {
+  const config = getTableConfig(schema.drizzle);
+  const pkCol = config.columns.find((col) => col.primary);
+
+  if (!pkCol) {
+    return c.json({ error: `Table ${config.name} has no primary key` }, 500);
+  }
+
+  const drizzlePk = (schema.drizzle as any)[pkCol.name];
+  const displayColName = findDisplayColumn(schema);
+
+  const idsParam = c.req.query("ids");
+  if (idsParam === undefined) {
+    // No ids filter — return all display values
+    const rows = await db.select().from(schema.drizzle);
+    const result: Record<string, string> = {};
+    for (const row of rows) {
+      const id = String(row[pkCol.name]);
+      if (displayColName && row[displayColName] != null) {
+        result[id] = String(row[displayColName]);
+      } else {
+        result[id] = id;
+      }
+    }
+    return c.json({ data: result });
+  }
+
+  const ids = idsParam
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map(Number)
+    .filter((n) => !isNaN(n));
+
+  if (ids.length === 0) {
+    return c.json({ data: {} });
+  }
+
+  const rows = await db
+    .select()
+    .from(schema.drizzle)
+    .where(inArray(drizzlePk, ids));
+
+  const result: Record<string, string> = {};
+  for (const row of rows) {
+    const id = String(row[pkCol.name]);
+    if (displayColName && row[displayColName] != null) {
+      result[id] = String(row[displayColName]);
+    } else {
+      // Fallback to PK as display
+      result[id] = id;
+    }
+  }
+
+  return c.json({ data: result });
+}
+
+/** Create a lookup sub-app (convenience wrapper for tests). */
+export function lookupEndpoint(schema: TableDef, db: any) {
+  const app = new Hono();
+  app.get("/", (c) => handleLookup(schema, db, c));
+  return app;
+}

package/src/data/query-parser.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { timestamp } from "../schema/table.js";
+import { table } from "../schema/table.js";
+import { parseQuery } from "./query-parser.js";
+
+const ordersTable = sqliteTable("orders", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  customer: text("customer").notNull(),
+  amount: integer("amount").notNull(),
+  status: text("status").notNull(),
+  created_at: timestamp("created_at").notNull(),
+});
+
+const orders = table({ drizzle: ordersTable });
+
+describe("parseQuery()", () => {
+  it("defaults to page 1, limit 50", () => {
+    const q = parseQuery({}, orders);
+    expect(q.limit).toBe(50);
+    expect(q.offset).toBe(0);
+    expect(q.where).toBeUndefined();
+    expect(q.orderBy).toEqual([]);
+  });
+
+  it("parses page and limit", () => {
+    const q = parseQuery({ page: "3", limit: "25" }, orders);
+    expect(q.limit).toBe(25);
+    expect(q.offset).toBe(50); // (3-1) * 25
+  });
+
+  it("caps limit at 1000", () => {
+    const q = parseQuery({ limit: "5000" }, orders);
+    expect(q.limit).toBe(1000);
+  });
+
+  it("parses simple filter", () => {
+    const q = parseQuery({ "filter[status]": "paid" }, orders);
+    expect(q.where).toBeDefined();
+  });
+
+  it("parses operator filters", () => {
+    const q = parseQuery({ "filter[amount][gt]": "100" }, orders);
+    expect(q.where).toBeDefined();
+  });
+
+  it("parses sort ascending", () => {
+    const q = parseQuery({ sort: "customer" }, orders);
+    expect(q.orderBy).toHaveLength(1);
+  });
+
+  it("parses sort descending", () => {
+    const q = parseQuery({ sort: "-created_at" }, orders);
+    expect(q.orderBy).toHaveLength(1);
+  });
+
+  it("parses multiple sort fields", () => {
+    const q = parseQuery({ sort: "-amount,customer" }, orders);
+    expect(q.orderBy).toHaveLength(2);
+  });
+
+  it("ignores unknown columns", () => {
+    const q = parseQuery({ "filter[unknown]": "val", sort: "unknown" }, orders);
+    expect(q.where).toBeUndefined();
+    expect(q.orderBy).toEqual([]);
+  });
+});