@suluk/drizzle 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <a href="https://github.com/MahmoodKhalil57/suluk">
+    <img src="https://raw.githubusercontent.com/MahmoodKhalil57/suluk/main/branding/export/wordmark.png" alt="Suluk" width="360" />
+  </a>
+</p>
+
+<h1 align="center">@suluk/drizzle</h1>
+
+<p align="center"><b>Drizzle ORM schema -> v4 'Suluk' contract: table -> Zod (drizzle-zod) -> v4 Schema Objects, DB metadata, and generated CRUD RouteContracts.</b></p>
+
+<p align="center">
+  <em>Part of <a href="https://github.com/MahmoodKhalil57/suluk">Suluk</a> — one typed OpenAPI v4 contract projecting into every full-stack layer.</em>
+</p>
+
+---
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/drizzle
+```
+
+## The Suluk cycle
+
+`@suluk/drizzle` is one station on the Suluk walk — author one v4 source, then **validate · audit ·
+preview · generate · deploy** the whole stack from it. Explore the full toolchain in the
+[main repository](https://github.com/MahmoodKhalil57/suluk) or drive it from the [VS Code cockpit](https://marketplace.visualstudio.com/items?itemName=MahmoodKhalil.suluk-vscode).
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@suluk/drizzle",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Drizzle ORM schema -> v4 'Suluk' contract: table -> Zod (drizzle-zod) -> v4 Schema Objects, DB metadata, and generated CRUD RouteContracts. CANDIDATE tooling.",
-  "type": "module",
-  "main": "src/index.ts",
-  "exports": {
-  ".": "./src/index.ts"
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/drizzle"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/core": "0.1.0",
-"@suluk/zod": "0.1.0",
-"@suluk/hono": "0.1.0"
+"@suluk/core": "^0.1.11",
+"@suluk/zod": "^0.1.2",
+"@suluk/hono": "^0.1.2"
 },
 "peerDependencies": {
 "drizzle-orm": "^0.4.0 || ^0.30.0 || ^0.40.0 || ^0.45.0",

package/src/crud.ts

@@ -9,12 +9,25 @@ import { getTableName } from "drizzle-orm";
 import type { RouteContract, RouteResponse } from "@suluk/hono";
 import { tableSchemas } from "./schemas";
 import { pascalCase, type AnyTable } from "./meta";
+import { listQuerySchema, type ListQueryOptions } from "./query";
 
 export interface CrudOptions {
   /** Base path for the collection. Default "/" + tableName, e.g. "/users". */
   basePath?: string;
   /** Path-param name for the item id. Default "id" ⇒ ".../:id". */
   idParam?: string;
+  /** Declare list query params (page/perPage/sort/order/q) on the list route. Default true; pass options to scope. */
+  listQuery?: boolean | ListQueryOptions;
+  /**
+   * SOFT delete: DELETE marks the row (sets a deletedAt column) instead of removing it, so the projected DELETE
+   * returns the affected row (200), not 204. The patch is built at runtime by `softDeleteValues`.
+   */
+  softDelete?: boolean | { column?: string };
+  /**
+   * ANONYMIZE on delete (GDPR keep-record): DELETE redacts these columns instead of removing the row. Like
+   * softDelete, the projected DELETE returns the affected row (200). The patch comes from `anonymizeValues`.
+   */
+  anonymizeDelete?: { columns: string[] };
 }
 
 /**
@@ -41,6 +54,15 @@ export function crudRoutes(table: AnyTable, opts: CrudOptions = {}): RouteContra
   const ok = (status: number, schema: z.ZodType, description: string): RouteResponse => ({ status, schema, description });
   const bare = (status: number, description: string): RouteResponse => ({ status, description });
 
+  // a soft-delete / anonymize-delete keeps the row, so DELETE returns it (200) rather than 204.
+  const softening = opts.softDelete || opts.anonymizeDelete;
+  const deleteResponses: RouteResponse[] = softening
+    ? [ok(200, select, `The ${tableName} row, after a soft delete / anonymize.`), bare(404, "Not found.")]
+    : [bare(204, "Deleted.")];
+
+  const listQueryOpts: ListQueryOptions | undefined =
+    opts.listQuery === false ? undefined : typeof opts.listQuery === "object" ? opts.listQuery : {};
+
   return [
     {
       method: "get",
@@ -48,6 +70,7 @@ export function crudRoutes(table: AnyTable, opts: CrudOptions = {}): RouteContra
       name: `list${Pascal}`,
       summary: `List ${tableName}`,
       tags: [tableName],
+      ...(listQueryOpts ? { request: { query: listQuerySchema(table, listQueryOpts) } } : {}),
       responses: [ok(200, z.array(select), `A page of ${tableName}.`)],
     },
     {
@@ -81,10 +104,10 @@ export function crudRoutes(table: AnyTable, opts: CrudOptions = {}): RouteContra
       method: "delete",
       path: itemPath,
       name: `delete${Pascal}`,
-      summary: `Delete a ${tableName} row by ${idParam}`,
+      summary: `${softening ? "Soft-delete" : "Delete"} a ${tableName} row by ${idParam}`,
       tags: [tableName],
       request: { params: idParams },
-      responses: [bare(204, "Deleted.")],
+      responses: deleteResponses,
     },
   ];
 }

package/src/ddl.ts

@@ -0,0 +1,50 @@
+/**
+ * Emit SQLite `CREATE TABLE` DDL from a drizzle table's {@link tableMetadata} — the generator that lets a dev
+ * in-memory bun:sqlite DB be built FROM the Drizzle schema instead of a hand-mirrored SQL string that silently
+ * drifts. Reads only the honest metadata floor (types, notNull, defaults, PK/autoincrement); identifiers are
+ * quoted so reserved words (e.g. `order`) are safe. Booleans map to INTEGER (drizzle's storage), enums to plain
+ * TEXT (drizzle adds no CHECK). Prod migrations stay the source of truth for prod; this is the dev-schema twin.
+ */
+import { tableMetadata, type AnyTable, type ColumnMeta, type TableMeta } from "./meta";
+
+const SQLITE_TYPE: Record<string, string> = {
+  SQLiteInteger: "INTEGER", SQLiteBoolean: "INTEGER", SQLiteTimestamp: "INTEGER",
+  SQLiteText: "TEXT", SQLiteTextJson: "TEXT", SQLiteReal: "REAL", SQLiteNumeric: "NUMERIC", SQLiteBlob: "BLOB",
+};
+
+/** Double-quote an identifier (table/column) so reserved words + odd names are always safe. */
+const q = (id: string): string => `"${id.replace(/"/g, '""')}"`;
+/** A SQL literal for a static default: booleans → 0/1, numbers verbatim, strings single-quoted. */
+const lit = (v: string | number | boolean): string =>
+  typeof v === "boolean" ? (v ? "1" : "0") : typeof v === "number" ? String(v) : `'${String(v).replace(/'/g, "''")}'`;
+
+function columnDDL(c: ColumnMeta): string {
+  const parts = [q(c.sqlName), SQLITE_TYPE[c.columnType] ?? "TEXT"];
+  if (c.primaryKey) parts.push(c.autoIncrement ? "PRIMARY KEY AUTOINCREMENT" : "PRIMARY KEY");
+  else if (c.notNull) parts.push("NOT NULL");
+  if (c.defaultValue !== undefined) parts.push("DEFAULT " + lit(c.defaultValue));
+  return parts.join(" ");
+}
+
+export interface DdlOptions {
+  /** prefix with `IF NOT EXISTS` (default true). */
+  ifNotExists?: boolean;
+}
+
+/**
+ * `CREATE TABLE` DDL for one drizzle table (or its already-read metadata). Single-column primary keys only — a
+ * table-level composite `primaryKey({columns})` isn't visible on the column-descriptor floor (it needs
+ * dialect-specific `getTableConfig`, deferred like FK/relation projection); such a table emits its columns without
+ * the composite constraint, so declare those tables' DDL by hand for now.
+ */
+export function tableDDL(table: AnyTable | TableMeta, opts: DdlOptions = {}): string {
+  const m: TableMeta = "columns" in table ? table : tableMetadata(table);
+  const cols = m.columns.map(columnDDL).join(", ");
+  const exists = opts.ifNotExists === false ? "" : "IF NOT EXISTS ";
+  return `CREATE TABLE ${exists}${q(m.name)} (${cols});`;
+}
+
+/** `CREATE TABLE` DDL for many tables, newline-joined — the dev-schema twin of the prod migrations. */
+export function schemaDDL(tables: (AnyTable | TableMeta)[], opts: DdlOptions = {}): string {
+  return tables.map((t) => tableDDL(t, opts)).join("\n");
+}

package/src/index.ts

@@ -32,3 +32,12 @@ export {
 } from "./schemas";
 
 export { crudRoutes, type CrudOptions } from "./crud";
+// list query-param synthesis (Phase 1): declare page/perPage/sort/order/q + the pure parser the handler uses.
+export { listQuerySchema, parseListQuery, type ListQuery, type ListQueryOptions } from "./query";
+// CrudOptions runtime helpers (Phase 1): soft-delete / anonymize-on-delete (GDPR keep-record) / timestamps patches.
+export {
+  softDeleteValues, anonymizeValues, touchTimestamps, notSoftDeleted,
+  type SoftDeleteOptions, type TimestampOptions,
+} from "./mutations";
+// SQLite CREATE TABLE generator — build a dev in-memory schema FROM the Drizzle tables (no hand-mirrored SQL drift).
+export { tableDDL, schemaDDL, type DdlOptions } from "./ddl";

package/src/meta.ts

@@ -12,7 +12,10 @@ export type AnyTable = Parameters<typeof getTableColumns>[0];
 
 /** One column's metadata, lifted from drizzle's column descriptor (verified against drizzle-orm 0.45). */
 export interface ColumnMeta {
+  /** the JS property key on the table object (e.g. `reviewId`) — the v4 component property name. */
   name: string;
+  /** the SQL column name (e.g. `review_id`) — what DDL + raw SQL must use; differs from `name` under camel/snake. */
+  sqlName: string;
   /** drizzle's coarse JS dataType, e.g. "string" | "number" | "boolean" | "date". */
   dataType: string;
   /** drizzle's concrete column type tag, e.g. "SQLiteText" | "SQLiteInteger". */
@@ -23,14 +26,23 @@ export interface ColumnMeta {
   hasDefault: boolean;
   /** Part of the (single-column) primary key. */
   primaryKey: boolean;
+  /** An AUTOINCREMENT primary key (SQLite integer PK declared with autoIncrement). */
+  autoIncrement: boolean;
+  /** Carries a column-level UNIQUE constraint (drizzle's `.unique()` / `isUnique`). */
+  unique: boolean;
   /** SQL CHECK/enum allowed values when the column was declared with `{ enum: [...] }`. */
   enumValues?: string[];
+  /** The STATIC default value (number/string/boolean) when the column carries one — for DDL emit. Absent for a
+   *  runtime `$defaultFn` column (hasDefault true, no SQL-literal value) and for autoincrement PKs. */
+  defaultValue?: string | number | boolean;
 }
 
 export interface TableMeta {
   name: string;
   /** Column names flagged `primary` (ordered as drizzle reports the columns). */
   primaryKey: string[];
+  /** Column names carrying a UNIQUE constraint (the natural keys for upsert / by-field lookup). */
+  unique: string[];
   columns: ColumnMeta[];
 }
 
@@ -43,6 +55,7 @@ export function tableMetadata(table: AnyTable): TableMeta {
   const cols = getTableColumns(table);
   const columns: ColumnMeta[] = [];
   const primaryKey: string[] = [];
+  const unique: string[] = [];
 
   for (const [name, col] of Object.entries(cols)) {
     // drizzle's descriptor surface — read defensively (any dialect, any version in our peer range).
@@ -52,23 +65,33 @@ export function tableMetadata(table: AnyTable): TableMeta {
       notNull: boolean;
       hasDefault: boolean;
       primary: boolean;
+      autoIncrement?: boolean;
+      isUnique?: boolean;
       enumValues?: string[];
+      default?: unknown;
+      name?: string;
     };
+    const staticDefault = c.hasDefault && (typeof c.default === "string" || typeof c.default === "number" || typeof c.default === "boolean");
     const meta: ColumnMeta = {
       name,
+      sqlName: c.name ?? name, // drizzle's column descriptor carries the SQL name; fall back to the JS key
       dataType: c.dataType,
       columnType: c.columnType,
       notNull: !!c.notNull,
       hasDefault: !!c.hasDefault,
       primaryKey: !!c.primary,
+      autoIncrement: !!c.autoIncrement,
+      unique: !!c.isUnique,
       // enumValues is often an empty array on non-enum columns — only surface a non-empty one.
       ...(Array.isArray(c.enumValues) && c.enumValues.length ? { enumValues: c.enumValues } : {}),
+      ...(staticDefault ? { defaultValue: c.default as string | number | boolean } : {}),
     };
     columns.push(meta);
     if (meta.primaryKey) primaryKey.push(name);
+    if (meta.unique) unique.push(name);
   }
 
-  return { name: getTableName(table), primaryKey, columns };
+  return { name: getTableName(table), primaryKey, unique, columns };
 }
 
 /** "user_accounts" / "users" → "UserAccounts" / "Users". The v4 component key (C009 by-name). */

package/src/mutations.ts

@@ -0,0 +1,41 @@
+/**
+ * CrudOptions runtime helpers (saastarter-parity Phase 1): pure value-builders for soft-delete, anonymize-on-delete,
+ * and server-managed timestamps. The package projects CONTRACTS (it runs no SQL), so these produce the PATCH an
+ * app's Drizzle handler applies — keeping the policy (which column is `deletedAt`, which columns to redact) in one
+ * place. anonymizeValues is the row-level counterpart of @suluk/better-auth's GDPR erasure cascade (the keep-record,
+ * FK-safe posture).
+ */
+
+export interface SoftDeleteOptions {
+  /** the timestamp column set on delete (default "deletedAt"). */
+  column?: string;
+}
+
+export interface TimestampOptions {
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/** The patch a soft delete applies — sets the deletedAt column to `now` (default current time). */
+export function softDeleteValues(opts: SoftDeleteOptions = {}, now: Date = new Date()): Record<string, string> {
+  return { [opts.column ?? "deletedAt"]: now.toISOString() };
+}
+
+/** The patch an anonymize-on-delete applies — redacts each named column to `value` (null by default). Pair with a
+ *  soft-delete to keep the row (FK-safe right-to-be-forgotten). */
+export function anonymizeValues(columns: string[], value: string | null = null): Record<string, string | null> {
+  return Object.fromEntries(columns.map((c) => [c, value]));
+}
+
+/** The patch server-managed timestamps apply on write — `updatedAt` always, `createdAt` only when `creating`. */
+export function touchTimestamps(opts: TimestampOptions = {}, creating = false, now: Date = new Date()): Record<string, string> {
+  const iso = now.toISOString();
+  const out: Record<string, string> = { [opts.updatedAt ?? "updatedAt"]: iso };
+  if (creating) out[opts.createdAt ?? "createdAt"] = iso;
+  return out;
+}
+
+/** The implicit list filter for a soft-deleting table — exclude rows whose deletedAt is set (unless asked to include). */
+export function notSoftDeleted(column = "deletedAt"): { column: string; isNull: true } {
+  return { column, isNull: true };
+}

package/src/query.ts

@@ -0,0 +1,95 @@
+/**
+ * List query-param synthesis (saastarter-parity Phase 1). The list route today returns the whole collection; real
+ * lists are paginated, sortable, filterable, searchable. This DECLARES those query params (so they appear in the v4
+ * doc + the SDK + the conformance tests) AND ships a pure `parseListQuery` that normalizes a raw query string into
+ * `{ limit, offset, orderBy, filters, q }` the app's Drizzle handler builds its query from — one synthesis, both ends.
+ */
+import * as z from "zod";
+import { tableMetadata, type AnyTable } from "./meta";
+
+export interface ListQueryOptions {
+  /** sortable + filterable columns (default: all of the table's columns). */
+  columns?: string[];
+  /** default page size (default 20). */
+  defaultPerPage?: number;
+  /** max page size — `perPage` is clamped to it (default 100). */
+  maxPerPage?: number;
+}
+
+/** Reserved query keys (everything else that matches a column becomes an equality filter). */
+const RESERVED = new Set(["page", "perPage", "sort", "order", "q"]);
+
+/** The Zod query schema for a list route: page/perPage/sort/order/q (coerced from strings). Extra column filters
+ * are read by {@link parseListQuery} at runtime (OpenAPI query params are flat, so they aren't enumerated here).
+ * `table` is OPTIONAL: with a table (or `opts.columns`) `sort` is a column enum; without either it is a free string —
+ * so the contract-projection layer (@suluk/builder), which holds a Zod entity rather than a Drizzle table, can call
+ * `listQuerySchema()` and still emit the same five params into the v4 doc + SDK. */
+export function listQuerySchema(table?: AnyTable, opts: ListQueryOptions = {}): z.ZodType {
+  const cols = opts.columns ?? (table ? tableMetadata(table).columns.map((c) => c.name) : []);
+  const sort = cols.length ? z.enum(cols as [string, ...string[]]).optional() : z.string().optional();
+  return z.object({
+    page: z.coerce.number().int().min(1).optional(),
+    perPage: z.coerce.number().int().min(1).optional(),
+    sort,
+    order: z.enum(["asc", "desc"]).optional(),
+    q: z.string().optional(),
+  });
+}
+
+export interface ListQuery {
+  /** rows to return (= perPage). */
+  limit: number;
+  /** rows to skip (= (page-1)*perPage). */
+  offset: number;
+  orderBy?: { column: string; dir: "asc" | "desc" };
+  /** free-text search term. */
+  q?: string;
+  /** column → equality value. */
+  filters: Record<string, string>;
+  page: number;
+  perPage: number;
+}
+
+type RawQuery = Record<string, string | string[] | undefined>;
+const first = (v: string | string[] | undefined) => (Array.isArray(v) ? v[0] : v);
+const intOr = (v: string | undefined, fallback: number) => {
+  const n = v == null ? NaN : parseInt(v, 10);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+/**
+ * Normalize a raw query object into a {@link ListQuery} — pure, validating against the table's real columns:
+ * page/perPage are clamped (≥1, ≤maxPerPage); `sort` is honored only for a real column; any other key matching a
+ * column becomes an equality filter (unknown keys are ignored — no injection of arbitrary columns).
+ */
+export function parseListQuery(raw: RawQuery, table: AnyTable, opts: ListQueryOptions = {}): ListQuery {
+  const colSet = new Set(opts.columns ?? tableMetadata(table).columns.map((c) => c.name));
+  const defaultPer = opts.defaultPerPage ?? 20;
+  const maxPer = opts.maxPerPage ?? 100;
+
+  const page = Math.max(1, intOr(first(raw.page), 1));
+  const perPage = Math.min(maxPer, Math.max(1, intOr(first(raw.perPage), defaultPer)));
+
+  const sortCol = first(raw.sort);
+  const orderBy = sortCol && colSet.has(sortCol)
+    ? { column: sortCol, dir: (first(raw.order) === "desc" ? "desc" : "asc") as "asc" | "desc" }
+    : undefined;
+
+  const filters: Record<string, string> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    if (RESERVED.has(k)) continue;
+    const val = first(v);
+    if (colSet.has(k) && val != null) filters[k] = val;
+  }
+  const q = first(raw.q) || undefined;
+
+  return {
+    limit: perPage,
+    offset: (page - 1) * perPage,
+    ...(orderBy ? { orderBy } : {}),
+    ...(q ? { q } : {}),
+    filters,
+    page,
+    perPage,
+  };
+}

package/test/ddl.test.ts

@@ -0,0 +1,56 @@
+/**
+ * tableDDL / schemaDDL — generate SQLite CREATE TABLE from a Drizzle table. Asserts the type/default/PK mapping,
+ * reserved-word quoting, AND the SQL-column-name (snake_case) vs JS-key (camelCase) distinction, then round-trips:
+ * the generated DDL runs in a real bun:sqlite DB and accepts inserts that honor the defaults — proof the schema is
+ * valid + faithful, not just string-shaped.
+ */
+import { test, expect, describe } from "bun:test";
+import { Database } from "bun:sqlite";
+import { sqliteTable, integer, text } from "drizzle-orm/sqlite-core";
+import { tableDDL, schemaDDL } from "../src/index";
+
+// "order" is a SQLite reserved word; customer_id (camel JS key) exercises the SQL-name path; boolean+enum+defaults the mapping.
+const order = sqliteTable("order", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  customerId: text("customer_id"),                                  // camelCase key → snake_case SQL name
+  total: integer("total").notNull().default(0),
+  status: text("status", { enum: ["pending", "paid"] }).notNull().default("pending"),
+  paid: integer("paid", { mode: "boolean" }).notNull().default(false),
+  note: text("note"),
+});
+
+describe("tableDDL", () => {
+  const ddl = tableDDL(order);
+  test("quotes reserved table names + maps types + uses the SQL column name", () => {
+    expect(ddl).toContain('CREATE TABLE IF NOT EXISTS "order"');
+    expect(ddl).toContain('"customer_id" TEXT');   // SQL name, not the JS key "customerId"
+    expect(ddl).not.toContain("customerId");
+    expect(ddl).toContain('"total" INTEGER NOT NULL DEFAULT 0');
+    expect(ddl).toContain('"note" TEXT');           // nullable, no default
+    expect(ddl).not.toContain('"note" TEXT NOT NULL');
+  });
+  test("autoincrement PK, boolean→INTEGER 0/1, string defaults quoted", () => {
+    expect(ddl).toContain('"id" INTEGER PRIMARY KEY AUTOINCREMENT');
+    expect(ddl).toContain('"paid" INTEGER NOT NULL DEFAULT 0');     // boolean false → 0, type INTEGER
+    expect(ddl).toContain(`"status" TEXT NOT NULL DEFAULT 'pending'`);
+  });
+  test("ifNotExists:false drops the guard", () => {
+    expect(tableDDL(order, { ifNotExists: false })).toContain('CREATE TABLE "order"');
+  });
+});
+
+describe("round-trip in a real bun:sqlite DB", () => {
+  test("the generated DDL is valid SQL + applies the defaults under the SQL column names", () => {
+    const db = new Database(":memory:");
+    db.exec(schemaDDL([order]));
+    db.exec(`INSERT INTO "order" (customer_id, note) VALUES ('u1', 'hi')`); // rely on total/status/paid defaults
+    const row = db.query(`SELECT id, customer_id, total, status, paid, note FROM "order"`).get() as Record<string, unknown>;
+    expect(row.id).toBe(1);              // autoincrement
+    expect(row.customer_id).toBe("u1");  // snake_case column exists
+    expect(row.total).toBe(0);           // default 0
+    expect(row.status).toBe("pending");  // default 'pending'
+    expect(row.paid).toBe(0);            // boolean default false → 0
+    expect(row.note).toBe("hi");
+    db.close();
+  });
+});

package/test/depth.test.ts

@@ -0,0 +1,80 @@
+import { test, expect, describe } from "bun:test";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { emitV4 } from "@suluk/hono";
+import {
+  tableMetadata, crudRoutes,
+  listQuerySchema, parseListQuery,
+  softDeleteValues, anonymizeValues, touchTimestamps, notSoftDeleted,
+} from "../src/index";
+
+const users = sqliteTable("users", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  email: text("email").notNull().unique(),
+  name: text("name"),
+  deletedAt: text("deleted_at"),
+});
+
+describe("unique-index metadata", () => {
+  test("tableMetadata surfaces UNIQUE columns at the column + table level", () => {
+    const meta = tableMetadata(users);
+    expect(meta.unique).toEqual(["email"]);
+    expect(meta.columns.find((c) => c.name === "email")?.unique).toBe(true);
+    expect(meta.columns.find((c) => c.name === "name")?.unique).toBe(false);
+  });
+});
+
+describe("list query-param synthesis", () => {
+  test("listQuerySchema parses + coerces reserved params and validates sort against columns", () => {
+    const schema = listQuerySchema(users);
+    expect((schema as { parse: (v: unknown) => unknown }).parse({ page: "2", perPage: "10", sort: "email", order: "desc", q: "ab" }))
+      .toEqual({ page: 2, perPage: 10, sort: "email", order: "desc", q: "ab" });
+    // an unknown sort column is rejected
+    expect(() => (schema as { parse: (v: unknown) => unknown }).parse({ sort: "nope" })).toThrow();
+  });
+
+  test("parseListQuery normalizes to limit/offset/orderBy/filters (clamped, column-validated)", () => {
+    const q = parseListQuery({ page: "3", perPage: "10", sort: "name", order: "desc", q: "lina", email: "a@b.co", bogus: "x" }, users);
+    expect(q).toMatchObject({ limit: 10, offset: 20, page: 3, perPage: 10, orderBy: { column: "name", dir: "desc" }, q: "lina" });
+    expect(q.filters).toEqual({ email: "a@b.co" }); // only real columns become filters; `bogus` ignored
+  });
+
+  test("parseListQuery clamps perPage to maxPerPage and defaults page/perPage", () => {
+    expect(parseListQuery({ perPage: "9999" }, users, { maxPerPage: 50 }).limit).toBe(50);
+    expect(parseListQuery({}, users)).toMatchObject({ page: 1, perPage: 20, offset: 0 });
+    // a sort on a non-existent column is dropped (no injection)
+    expect(parseListQuery({ sort: "evil" }, users).orderBy).toBeUndefined();
+  });
+});
+
+describe("soft-delete / anonymize / timestamp CrudOptions", () => {
+  test("a soft-deleting table's DELETE returns the row (200), not 204; summary says soft-delete", () => {
+    const routes = crudRoutes(users, { softDelete: true });
+    const del = routes.find((r) => r.name === "deleteUsers")!;
+    const statuses = (Array.isArray(del.responses) ? del.responses : []).map((r) => r.status);
+    expect(statuses).toContain(200);
+    expect(statuses).not.toContain(204);
+    expect(del.summary).toContain("Soft-delete");
+  });
+
+  test("the list route declares query params when listQuery is on (default)", () => {
+    const list = crudRoutes(users).find((r) => r.name === "listUsers")!;
+    expect(list.request?.query).toBeDefined();
+    expect(crudRoutes(users, { listQuery: false }).find((r) => r.name === "listUsers")!.request?.query).toBeUndefined();
+  });
+
+  test("the extended CRUD still projects to a valid v4 document", () => {
+    const { document } = emitV4(crudRoutes(users, { softDelete: true }));
+    expect(document.paths["users"].requests.listUsers).toBeDefined();
+  });
+
+  test("runtime helpers build the right patches (pure, time-injected)", () => {
+    const now = new Date("2026-06-11T00:00:00.000Z");
+    expect(softDeleteValues({}, now)).toEqual({ deletedAt: "2026-06-11T00:00:00.000Z" });
+    expect(softDeleteValues({ column: "removed_at" }, now)).toEqual({ removed_at: "2026-06-11T00:00:00.000Z" });
+    expect(anonymizeValues(["email", "name"])).toEqual({ email: null, name: null });
+    expect(anonymizeValues(["email"], "[redacted]")).toEqual({ email: "[redacted]" });
+    expect(touchTimestamps({}, true, now)).toEqual({ updatedAt: "2026-06-11T00:00:00.000Z", createdAt: "2026-06-11T00:00:00.000Z" });
+    expect(touchTimestamps({}, false, now)).toEqual({ updatedAt: "2026-06-11T00:00:00.000Z" });
+    expect(notSoftDeleted()).toEqual({ column: "deletedAt", isNull: true });
+  });
+});