@suluk/drizzle 0.1.1 → 0.1.2

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.2",
   "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.7",
+"@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/index.ts

@@ -32,3 +32,10 @@ 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";

package/src/meta.ts

@@ -23,6 +23,8 @@ export interface ColumnMeta {
   hasDefault: boolean;
   /** Part of the (single-column) primary key. */
   primaryKey: 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[];
 }
@@ -31,6 +33,8 @@ 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 +47,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,6 +57,7 @@ export function tableMetadata(table: AnyTable): TableMeta {
       notNull: boolean;
       hasDefault: boolean;
       primary: boolean;
+      isUnique?: boolean;
       enumValues?: string[];
     };
     const meta: ColumnMeta = {
@@ -61,14 +67,16 @@ export function tableMetadata(table: AnyTable): TableMeta {
       notNull: !!c.notNull,
       hasDefault: !!c.hasDefault,
       primaryKey: !!c.primary,
+      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 } : {}),
     };
     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/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 });
+  });
+});