@suluk/drizzle 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@suluk/drizzle",
+  "version": "0.1.0",
+  "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"
+},
+"dependencies": {
+"@suluk/core": "0.1.0",
+"@suluk/zod": "0.1.0",
+"@suluk/hono": "0.1.0"
+},
+"peerDependencies": {
+"drizzle-orm": "^0.4.0 || ^0.30.0 || ^0.40.0 || ^0.45.0",
+"drizzle-zod": "^0.8.0",
+"zod": "^4.0.0"
+},
+"devDependencies": {
+"@types/bun": "latest",
+"drizzle-orm": "^0.45.2",
+"drizzle-zod": "^0.8.3",
+"zod": "^4.4.3"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/crud.ts

@@ -0,0 +1,90 @@
+/**
+ * Drizzle table → CRUD RouteContracts (the @suluk/hono shape). This closes the floor-to-contract chain:
+ * Drizzle (data) → Hono RouteContract (interface) → emitV4 → v4 document. We generate the conventional five
+ * REST operations from the table's select/insert/update Zod schemas. Nothing here is opinionated about the
+ * handler — these are pure contract shapes, derivable into a v4 doc with no running server. CANDIDATE tooling.
+ */
+import * as z from "zod";
+import { getTableName } from "drizzle-orm";
+import type { RouteContract, RouteResponse } from "@suluk/hono";
+import { tableSchemas } from "./schemas";
+import { pascalCase, type AnyTable } from "./meta";
+
+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;
+}
+
+/**
+ * Generate the five conventional CRUD RouteContracts for a drizzle table:
+ *   - list   GET    {base}            → 200 array(select)
+ *   - get    GET    {base}/:id        → 200 select, 404
+ *   - create POST   {base}            (json insert) → 201 select
+ *   - update PATCH  {base}/:id        (json update) → 200 select
+ *   - delete DELETE {base}/:id        → 204
+ * Names are list<Pascal>/get<Pascal>/create<Pascal>/update<Pascal>/delete<Pascal> (C009 by-name handles).
+ * `:id` is typed as a string param (path params arrive as strings; the DB layer coerces).
+ */
+export function crudRoutes(table: AnyTable, opts: CrudOptions = {}): RouteContract[] {
+  const tableName = getTableName(table);
+  const base = opts.basePath ?? `/${tableName}`;
+  const idParam = opts.idParam ?? "id";
+  const Pascal = pascalCase(tableName);
+  const { select, insert, update } = tableSchemas(table);
+
+  // path-param object — `:id` (and any future composite key) is a string in the URI template.
+  const idParams = z.object({ [idParam]: z.string() });
+  const itemPath = `${base}/:${idParam}`;
+
+  const ok = (status: number, schema: z.ZodType, description: string): RouteResponse => ({ status, schema, description });
+  const bare = (status: number, description: string): RouteResponse => ({ status, description });
+
+  return [
+    {
+      method: "get",
+      path: base,
+      name: `list${Pascal}`,
+      summary: `List ${tableName}`,
+      tags: [tableName],
+      responses: [ok(200, z.array(select), `A page of ${tableName}.`)],
+    },
+    {
+      method: "get",
+      path: itemPath,
+      name: `get${Pascal}`,
+      summary: `Fetch one ${tableName} row by ${idParam}`,
+      tags: [tableName],
+      request: { params: idParams },
+      responses: [ok(200, select, `The ${tableName} row.`), bare(404, "Not found.")],
+    },
+    {
+      method: "post",
+      path: base,
+      name: `create${Pascal}`,
+      summary: `Create a ${tableName} row`,
+      tags: [tableName],
+      request: { json: insert },
+      responses: [ok(201, select, `The created ${tableName} row.`)],
+    },
+    {
+      method: "patch",
+      path: itemPath,
+      name: `update${Pascal}`,
+      summary: `Update a ${tableName} row by ${idParam}`,
+      tags: [tableName],
+      request: { params: idParams, json: update },
+      responses: [ok(200, select, `The updated ${tableName} row.`), bare(404, "Not found.")],
+    },
+    {
+      method: "delete",
+      path: itemPath,
+      name: `delete${Pascal}`,
+      summary: `Delete a ${tableName} row by ${idParam}`,
+      tags: [tableName],
+      request: { params: idParams },
+      responses: [bare(204, "Deleted.")],
+    },
+  ];
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @suluk/drizzle — the DATA floor of the Suluk cycle: a Drizzle ORM table is the system of record, and this
+ * package projects it into the v4 "Suluk" contract. The chain is
+ *
+ *   Drizzle table
+ *     → Zod (drizzle-zod: select / insert / update)        [tableSchemas]
+ *     → v4 Schema Objects (@suluk/zod zodToV4)              [tableToV4, tableComponents]
+ *     → Hono RouteContracts (the @suluk/hono interface)    [crudRoutes]
+ *     → v4 document (@suluk/hono emitV4)                    [closes the floor-to-contract chain]
+ *
+ * Plus the honest DB metadata read straight off the column descriptors [tableMetadata]. Losses are never
+ * silent: the v4 conversion surfaces zodToV4 warnings (tableToV4Warnings) and component-name collisions
+ * (tableComponentsAudit). CANDIDATE tooling (not official OAS).
+ */
+export {
+  tableMetadata,
+  pascalCase,
+  tableComponentName,
+  type AnyTable,
+  type ColumnMeta,
+  type TableMeta,
+} from "./meta";
+
+export {
+  tableSchemas,
+  tableToV4,
+  tableToV4Warnings,
+  tableComponents,
+  tableComponentsAudit,
+  type TableZodSchemas,
+  type TableV4Schemas,
+} from "./schemas";
+
+export { crudRoutes, type CrudOptions } from "./crud";

package/src/meta.ts

@@ -0,0 +1,82 @@
+/**
+ * Drizzle table → metadata + naming. The "DATA floor" reads the table's column descriptors directly
+ * (drizzle-orm's getTableColumns) — the source of truth about nullability, defaults, primary keys, and
+ * SQL-level enums — and lifts them into a small, JSON-friendly record the rest of the package projects from.
+ * CANDIDATE tooling (not official OAS).
+ */
+import { getTableColumns, getTableName } from "drizzle-orm";
+
+/** Any drizzle table object accepted by getTableColumns/getTableName. We stay structural — the concrete
+ *  dialect type (SQLite/Pg/MySQL) is irrelevant here; we only read the column descriptor surface. */
+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 {
+  name: string;
+  /** drizzle's coarse JS dataType, e.g. "string" | "number" | "boolean" | "date". */
+  dataType: string;
+  /** drizzle's concrete column type tag, e.g. "SQLiteText" | "SQLiteInteger". */
+  columnType: string;
+  /** NOT NULL at the SQL level. */
+  notNull: boolean;
+  /** Has a DB-side default (also true for autoincrement PKs) ⇒ optional on insert. */
+  hasDefault: boolean;
+  /** Part of the (single-column) primary key. */
+  primaryKey: boolean;
+  /** SQL CHECK/enum allowed values when the column was declared with `{ enum: [...] }`. */
+  enumValues?: string[];
+}
+
+export interface TableMeta {
+  name: string;
+  /** Column names flagged `primary` (ordered as drizzle reports the columns). */
+  primaryKey: string[];
+  columns: ColumnMeta[];
+}
+
+/**
+ * Read a drizzle table's metadata. This is the honest floor: every value comes from the column descriptor,
+ * nothing is inferred. `enumValues` is only present when the underlying column actually carries one — we
+ * don't synthesize an empty array (that would be a silent invention).
+ */
+export function tableMetadata(table: AnyTable): TableMeta {
+  const cols = getTableColumns(table);
+  const columns: ColumnMeta[] = [];
+  const primaryKey: string[] = [];
+
+  for (const [name, col] of Object.entries(cols)) {
+    // drizzle's descriptor surface — read defensively (any dialect, any version in our peer range).
+    const c = col as unknown as {
+      dataType: string;
+      columnType: string;
+      notNull: boolean;
+      hasDefault: boolean;
+      primary: boolean;
+      enumValues?: string[];
+    };
+    const meta: ColumnMeta = {
+      name,
+      dataType: c.dataType,
+      columnType: c.columnType,
+      notNull: !!c.notNull,
+      hasDefault: !!c.hasDefault,
+      primaryKey: !!c.primary,
+      // 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);
+  }
+
+  return { name: getTableName(table), primaryKey, columns };
+}
+
+/** "user_accounts" / "users" → "UserAccounts" / "Users". The v4 component key (C009 by-name). */
+export function pascalCase(s: string): string {
+  return s.replace(/(^|[-_\s]+)(\w)/g, (_m, _sep, ch: string) => ch.toUpperCase());
+}
+
+/** A drizzle table's PascalCase component name, derived from its SQL name. */
+export function tableComponentName(table: AnyTable): string {
+  return pascalCase(getTableName(table));
+}

package/src/schemas.ts

@@ -0,0 +1,95 @@
+/**
+ * Drizzle table → Zod → v4 Schema Objects. The chain is: table --drizzle-zod--> Zod (select/insert/update)
+ * --@suluk/zod zodToV4--> v4 Schema Object (= JSON Schema 2020-12). drizzle-zod already encodes the DB's
+ * shape correctly — insert makes notNull-AND-no-default columns required (e.g. "email"), leaves autoincrement
+ * PKs and defaulted columns optional, and makes nullable columns `.nullable()`. We do not re-derive any of
+ * that; we only compose the three projections and lift them to v4. CANDIDATE tooling (not official OAS).
+ */
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { zodToV4 } from "@suluk/zod";
+import type * as z from "zod";
+import type { Schema } from "@suluk/core";
+import { tableComponentName, type AnyTable } from "./meta";
+
+/** The three Zod projections of a table. */
+export interface TableZodSchemas {
+  /** Full row shape — every column required (createSelectSchema). */
+  select: z.ZodType;
+  /** Write shape — notNull-AND-no-default columns required; PK/defaulted/nullable relaxed (createInsertSchema). */
+  insert: z.ZodType;
+  /** Partial write shape — every insert field optional (insert.partial()), for PATCH. */
+  update: z.ZodType;
+}
+
+/** The three v4 Schema Objects, mirroring {@link TableZodSchemas}. */
+export interface TableV4Schemas {
+  select: Schema;
+  insert: Schema;
+  update: Schema;
+}
+
+/**
+ * Build the select / insert / update Zod schemas for a table.
+ * update = insert.partial() — the canonical PATCH body (any subset of writable columns).
+ */
+export function tableSchemas(table: AnyTable): TableZodSchemas {
+  const select = createSelectSchema(table) as unknown as z.ZodType;
+  const insert = createInsertSchema(table) as unknown as z.ZodType;
+  // .partial() exists on the Zod object createInsertSchema returns; cast through to keep the public type clean.
+  const update = (insert as unknown as { partial(): z.ZodType }).partial();
+  return { select, insert, update };
+}
+
+/**
+ * Lift a table's three Zod schemas to v4 Schema Objects via zodToV4. drizzle-zod produces plain object
+ * schemas (no .transform/.refine), so this is lossless here — but we still honor the house rule and surface
+ * any zodToV4 warnings rather than dropping them silently (see {@link tableToV4Warnings}).
+ */
+export function tableToV4(table: AnyTable): TableV4Schemas {
+  const { select, insert, update } = tableSchemas(table);
+  return {
+    select: zodToV4(select).schema,
+    insert: zodToV4(insert).schema,
+    update: zodToV4(update).schema,
+  };
+}
+
+/**
+ * Same conversion as {@link tableToV4} but also returns the enumerated lossy boundary (per-projection
+ * zodToV4 warnings). Empty arrays ⇒ fully lossless. Callers wanting the honest-loss accounting use this.
+ */
+export function tableToV4Warnings(table: AnyTable): {
+  schemas: TableV4Schemas;
+  warnings: { select: string[]; insert: string[]; update: string[] };
+} {
+  const { select, insert, update } = tableSchemas(table);
+  const s = zodToV4(select), i = zodToV4(insert), u = zodToV4(update);
+  return {
+    schemas: { select: s.schema, insert: i.schema, update: u.schema },
+    warnings: { select: s.warnings, insert: i.warnings, update: u.warnings },
+  };
+}
+
+/**
+ * Build a v4 components.schemas record from a set of tables: { [PascalName]: select-v4-schema }.
+ * Keyed by the table's PascalCase name (C009 by-name). Collisions (two tables mapping to the same Pascal
+ * name) are NOT silently merged — the last writer wins AND a warning is surfaced via {@link tableComponentsAudit}.
+ */
+export function tableComponents(tables: readonly AnyTable[]): Record<string, Schema> {
+  return tableComponentsAudit(tables).schemas;
+}
+
+/** Like {@link tableComponents} but enumerates name collisions instead of dropping them silently. */
+export function tableComponentsAudit(tables: readonly AnyTable[]): {
+  schemas: Record<string, Schema>;
+  collisions: string[];
+} {
+  const schemas: Record<string, Schema> = {};
+  const collisions: string[] = [];
+  for (const table of tables) {
+    const key = tableComponentName(table);
+    if (key in schemas) collisions.push(`component name collision: '${key}' produced by more than one table`);
+    schemas[key] = tableToV4(table).select;
+  }
+  return { schemas, collisions };
+}

package/test/drizzle.test.ts

@@ -0,0 +1,185 @@
+/**
+ * @suluk/drizzle tests — prove the DATA floor: drizzle-zod's required/nullable accounting survives the lift
+ * to v4, metadata reads honestly off the column descriptors, crudRoutes emits the five conventional ops, and
+ * the whole Drizzle → Hono → v4 chain produces a STRUCTURALLY VALID v4 document. CANDIDATE tooling.
+ */
+import { test, expect, describe } from "bun:test";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { emitV4 } from "@suluk/hono";
+import { validateDocument } from "@suluk/core";
+import {
+  tableSchemas,
+  tableToV4,
+  tableToV4Warnings,
+  tableMetadata,
+  tableComponents,
+  tableComponentsAudit,
+  crudRoutes,
+} from "../src/index";
+
+// The example table the spec calls for: autoinc PK, a required (notNull, no-default) email, two nullables,
+// and a notNull-with-default enum. drizzle-zod's required-set should be exactly ["email"] on insert.
+const users = sqliteTable("users", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  email: text("email").notNull(),
+  name: text("name"),
+  age: integer("age"),
+  role: text("role", { enum: ["admin", "user"] }).notNull().default("user"),
+});
+
+/** A v4 Schema Object can be a boolean (true/false) per JSON Schema; narrow to the object form for tests. */
+function obj(schema: unknown): Record<string, unknown> {
+  expect(typeof schema).toBe("object");
+  return schema as Record<string, unknown>;
+}
+
+/** Pull the `required` array off a v4 object Schema (JSON Schema 2020-12). */
+function required(schema: unknown): string[] {
+  return (obj(schema).required as string[] | undefined) ?? [];
+}
+
+describe("tableSchemas / tableToV4", () => {
+  test("insert requires only notNull-AND-no-default columns (email); PK + defaulted + nullable are optional", () => {
+    const { insert } = tableToV4(users);
+    expect(required(insert).sort()).toEqual(["email"]);
+  });
+
+  test("select requires ALL columns (the full row shape)", () => {
+    const { select } = tableToV4(users);
+    expect(required(select).sort()).toEqual(["age", "email", "id", "name", "role"]);
+  });
+
+  test("update (insert.partial) requires NO columns", () => {
+    const { update } = tableToV4(users);
+    expect(required(update)).toEqual([]);
+    // and it's a usable Zod schema — an empty patch parses.
+    expect(() => tableSchemas(users).update.parse({})).not.toThrow();
+  });
+
+  test("nullable columns lift to a null-tolerant v4 schema", () => {
+    const { select } = tableToV4(users);
+    const props = obj(select).properties as Record<string, { anyOf?: { type?: string }[] }>;
+    const nameTypes = (props.name.anyOf ?? []).map((s) => s.type);
+    expect(nameTypes).toContain("null");
+  });
+
+  test("the v4 lift is lossless here — no dropped Zod effects", () => {
+    const { warnings } = tableToV4Warnings(users);
+    expect(warnings.select).toEqual([]);
+    expect(warnings.insert).toEqual([]);
+    expect(warnings.update).toEqual([]);
+  });
+});
+
+describe("tableMetadata", () => {
+  const meta = tableMetadata(users);
+
+  test("name + primaryKey are read off the descriptors", () => {
+    expect(meta.name).toBe("users");
+    expect(meta.primaryKey).toEqual(["id"]);
+  });
+
+  test("the role enum's allowed values are surfaced", () => {
+    const role = meta.columns.find((c) => c.name === "role")!;
+    expect(role.enumValues).toEqual(["admin", "user"]);
+    expect(role.notNull).toBe(true);
+    expect(role.hasDefault).toBe(true);
+  });
+
+  test("non-enum columns carry no enumValues (no silent invention)", () => {
+    const email = meta.columns.find((c) => c.name === "email")!;
+    expect(email.enumValues).toBeUndefined();
+    expect(email.notNull).toBe(true);
+    expect(email.hasDefault).toBe(false);
+    expect(email.primaryKey).toBe(false);
+  });
+
+  test("every column is reported with its drizzle descriptor fields", () => {
+    expect(meta.columns.map((c) => c.name).sort()).toEqual(["age", "email", "id", "name", "role"]);
+    const id = meta.columns.find((c) => c.name === "id")!;
+    expect(id.primaryKey).toBe(true);
+    expect(id.columnType).toBe("SQLiteInteger");
+    expect(id.dataType).toBe("number");
+  });
+});
+
+describe("tableComponents", () => {
+  test("keys by PascalCase table name, value is the select v4 schema", () => {
+    const comps = tableComponents([users]);
+    expect(Object.keys(comps)).toEqual(["Users"]);
+    expect(required(comps.Users).sort()).toEqual(["age", "email", "id", "name", "role"]);
+  });
+
+  test("collisions are enumerated, not dropped silently", () => {
+    // two tables with the same SQL name both map to "Users".
+    const usersB = sqliteTable("users", { id: integer("id").primaryKey() });
+    const { collisions } = tableComponentsAudit([users, usersB]);
+    expect(collisions.length).toBe(1);
+    expect(collisions[0]).toContain("Users");
+  });
+});
+
+describe("crudRoutes", () => {
+  const routes = crudRoutes(users);
+
+  test("emits the five conventional CRUD operations with by-name handles", () => {
+    expect(routes.length).toBe(5);
+    expect(routes.map((r) => r.name)).toEqual([
+      "listUsers",
+      "getUsers",
+      "createUsers",
+      "updateUsers",
+      "deleteUsers",
+    ]);
+  });
+
+  test("methods + paths follow REST convention; basePath defaults to /<table>", () => {
+    const byName = Object.fromEntries(routes.map((r) => [r.name!, r]));
+    expect(byName.listUsers.method).toBe("get");
+    expect(byName.listUsers.path).toBe("/users");
+    expect(byName.getUsers.method).toBe("get");
+    expect(byName.getUsers.path).toBe("/users/:id");
+    expect(byName.createUsers.method).toBe("post");
+    expect(byName.updateUsers.method).toBe("patch");
+    expect(byName.deleteUsers.method).toBe("delete");
+  });
+
+  test("statuses: list 200, get 200+404, create 201, update 200+404, delete 204", () => {
+    const byName = Object.fromEntries(routes.map((r) => [r.name!, r]));
+    const statuses = (name: string) =>
+      (byName[name].responses as { status: number }[]).map((x) => x.status).sort((a, b) => a - b);
+    expect(statuses("listUsers")).toEqual([200]);
+    expect(statuses("getUsers")).toEqual([200, 404]);
+    expect(statuses("createUsers")).toEqual([201]);
+    expect(statuses("updateUsers")).toEqual([200, 404]);
+    expect(statuses("deleteUsers")).toEqual([204]);
+  });
+
+  test("create body is the insert schema (email required); get/update carry the :id path param", () => {
+    const byName = Object.fromEntries(routes.map((r) => [r.name!, r]));
+    expect(byName.createUsers.request?.json).toBeDefined();
+    expect(byName.getUsers.request?.params).toBeDefined();
+    expect(byName.updateUsers.request?.json).toBeDefined();
+    expect(byName.updateUsers.request?.params).toBeDefined();
+  });
+
+  test("opts.basePath + opts.idParam are honored", () => {
+    const r = crudRoutes(users, { basePath: "/v1/people", idParam: "userId" });
+    expect(r[0].path).toBe("/v1/people");
+    expect(r[1].path).toBe("/v1/people/:userId");
+  });
+});
+
+describe("end-to-end: Drizzle → Hono → v4 (floor-to-contract)", () => {
+  test("emitV4(crudRoutes(users)) yields a STRUCTURALLY VALID v4 document", () => {
+    const { document, diagnostics } = emitV4(crudRoutes(users));
+    // no provable signature collisions among the five distinct ops.
+    expect(diagnostics.filter((d) => d.kind === "collision")).toEqual([]);
+    const result = validateDocument(document);
+    if (!result.valid) console.error("validation errors:", result.errors);
+    expect(result.valid).toBe(true);
+    // sanity: the five operations made it into the paths.
+    const opNames = Object.values(document.paths).flatMap((pi) => Object.keys(pi.requests));
+    expect(opNames.sort()).toEqual(["createUsers", "deleteUsers", "getUsers", "listUsers", "updateUsers"]);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "types": ["bun"] },
+  "include": ["src", "test"]
+}