@suluk/drizzle 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/drizzle",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Drizzle ORM schema -> v4 'Suluk' contract: table -> Zod (drizzle-zod) -> v4 Schema Objects, DB metadata, and generated CRUD RouteContracts. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"
@@ -26,13 +26,15 @@
 "peerDependencies": {
 "drizzle-orm": "^0.4.0 || ^0.30.0 || ^0.40.0 || ^0.45.0",
 "drizzle-zod": "^0.8.0",
-"zod": "^4.0.0"
+"zod": "^4.0.0",
+"hono": "^4.0.0"
 },
 "devDependencies": {
 "@types/bun": "latest",
 "drizzle-orm": "^0.45.2",
 "drizzle-zod": "^0.8.3",
-"zod": "^4.4.3"
+"zod": "^4.4.3",
+"hono": "^4.12.25"
 },
 "scripts": {
 "test": "bun test",

package/src/handlers.ts

@@ -0,0 +1,116 @@
+/**
+ * Generic gated CRUD HANDLERS for a drizzle table — written ONCE, driver-agnostic, so a dev server (bun:sqlite,
+ * synchronous) and a Workers runtime (D1, async) share ONE implementation instead of two hand-copied twins that
+ * drift. The db is injected as a RESOLVER `(c) => drizzle-instance` (dev: `() => db`; worker: `(c) => drizzle(c.env.DB)`),
+ * and every query uses an explicit awaited terminal (`.all()/.get()/.returning()/.run()`) that BOTH drivers support
+ * — `await` is transparent over bun:sqlite's synchronous results, so one async factory serves both.
+ *
+ * ACCESS is the @suluk/hono row-level engine: each entity's mode → per-op {@link gate} decision (anon→401 on an
+ * owner/admin op, non-admin→403 on an admin op) + owner-scoping (a signed-in caller only sees/mutates their rows).
+ * Optional `redact` strips private columns from non-admin reads; optional `afterUpdate` fires a post-update hook.
+ */
+import { and, eq, asc, desc, getTableName, type SQL } from "drizzle-orm";
+import type { Context } from "hono";
+import type { SQLiteColumn, SQLiteTable } from "drizzle-orm/sqlite-core";
+import { gate, policyFor, type AccessMode, type Policy } from "@suluk/hono";
+import { parseListQuery } from "./query";
+
+type AnyRow = Record<string, unknown>;
+/** Structural drizzle handle — the chainable builder API both bun:sqlite and D1 expose (loosely typed, like the app twins). */
+export interface CrudDb { select: (...a: unknown[]) => any; insert: (...a: unknown[]) => any; update: (...a: unknown[]) => any; delete: (...a: unknown[]) => any } // eslint-disable-line @typescript-eslint/no-explicit-any
+
+export interface CrudHandlers {
+  list: (c: Context) => Promise<Response>;
+  get: (c: Context) => Promise<Response>;
+  create: (c: Context) => Promise<Response>;
+  update: (c: Context) => Promise<Response>;
+  delete: (c: Context) => Promise<Response>;
+}
+
+export interface CrudHandlerOptions {
+  ownerCol?: string;
+  access?: AccessMode;
+  /** override the default mode→policy preset (passed through to @suluk/hono's policyFor). */
+  policies?: Record<AccessMode, Policy>;
+  /** resolve the drizzle instance for a request (dev: `() => db`; worker: `(c) => drizzle(c.env.DB)`). */
+  db: (c: Context) => CrudDb;
+  /** the verified caller id (token/session/x-user) — used for owner-scoping + the create owner-stamp. */
+  principal: (c: Context) => string | null;
+  /** whether the caller is an admin (e.g. `c.get("isAdmin") === true`). */
+  isAdmin: (c: Context) => boolean;
+  /** strip private columns from a row for a non-admin reader (no-op by default). */
+  redact?: (tableName: string, row: AnyRow, admin: boolean) => AnyRow;
+  /** post-update hook (e.g. back-in-stock on a restock); fires only for tables in `afterUpdateTables`. */
+  afterUpdate?: (tableName: string, c: Context, db: CrudDb, before: AnyRow, after: AnyRow) => Promise<void>;
+  afterUpdateTables?: ReadonlySet<string>;
+}
+
+const denied = (c: Context, g: { status?: 401 | 403 }) => c.json({ error: g.status === 401 ? "unauthorized" : "forbidden" }, g.status ?? 403);
+
+/** Build the five gated CRUD handlers for a drizzle table. The dev + worker callers differ ONLY in `opts.db`. */
+export function crudHandlers(table: SQLiteTable, opts: CrudHandlerOptions): CrudHandlers {
+  const cols = table as unknown as Record<string, SQLiteColumn>;
+  const pk = cols.id;
+  const policy = policyFor(opts.access, opts.ownerCol, opts.policies);
+  const tname = getTableName(table);
+  const redact = opts.redact ?? ((_t, row) => row);
+  const numId = (c: Context) => Number(c.req.param("id"));
+  const ident = (c: Context) => ({ isAdmin: opts.isAdmin(c), principal: opts.principal(c) });
+  // owner-scope (when the rule demands it) AND the pk filter (for one row).
+  const scoped = (c: Context, scopeOwner: boolean, withPk: boolean): SQL | undefined => {
+    const own = scopeOwner && opts.ownerCol ? eq(cols[opts.ownerCol], opts.principal(c)) : undefined;
+    const id = withPk ? eq(pk, numId(c)) : undefined;
+    return own && id ? and(id, own) : (id ?? own);
+  };
+  return {
+    list: async (c) => {
+      const g = gate(policy.list, ident(c)); if (!g.ok) return denied(c, g);
+      const own = scoped(c, g.scopeOwner, false);
+      // owner-scope AND per-column equality filters (parseListQuery returns REAL columns only — unknown keys dropped,
+      // so a filter can never widen past the owner scope).
+      const lq = parseListQuery(c.req.query(), table);
+      const conds: SQL[] = [];
+      if (own) conds.push(own);
+      for (const [col, val] of Object.entries(lq.filters)) if (cols[col]) conds.push(eq(cols[col], val));
+      const where = conds.length > 1 ? and(...conds) : conds[0];
+      let qb = opts.db(c).select().from(table).$dynamic();
+      if (where) qb = qb.where(where);
+      if (lq.orderBy && cols[lq.orderBy.column]) qb = qb.orderBy(lq.orderBy.dir === "desc" ? desc(cols[lq.orderBy.column]) : asc(cols[lq.orderBy.column]));
+      // pagination OPT-IN: bound the page only when page/perPage is passed — otherwise the full list.
+      const raw = c.req.query();
+      if (raw.page != null || raw.perPage != null) qb = qb.limit(lq.limit).offset(lq.offset);
+      const admin = opts.isAdmin(c);
+      return c.json(((await qb.all()) as AnyRow[]).map((row) => redact(tname, row, admin)));
+    },
+    get: async (c) => {
+      const g = gate(policy.get, ident(c)); if (!g.ok) return denied(c, g);
+      const r = (await opts.db(c).select().from(table).where(scoped(c, g.scopeOwner, true)!).get()) as AnyRow | undefined;
+      return r ? c.json(redact(tname, r, opts.isAdmin(c))) : c.json({ error: "not found" }, 404);
+    },
+    create: async (c) => {
+      const g = gate(policy.create, ident(c)); if (!g.ok) return denied(c, g);
+      const body = (await c.req.json().catch(() => ({}))) as AnyRow;
+      const owner = opts.ownerCol ? { [opts.ownerCol]: opts.principal(c) } : {}; // stamp the creator/owner
+      const r = (await opts.db(c).insert(table).values({ ...body, ...owner }).returning()) as AnyRow[];
+      return c.json(r[0], 201);
+    },
+    update: async (c) => {
+      const g = gate(policy.update, ident(c)); if (!g.ok) return denied(c, g);
+      const body = (await c.req.json().catch(() => ({}))) as AnyRow;
+      delete body.id; if (opts.ownerCol) delete body[opts.ownerCol]; // never let the client move a row's id or owner
+      const w = scoped(c, g.scopeOwner, true)!;
+      const db = opts.db(c);
+      const hooked = !!opts.afterUpdate && !!opts.afterUpdateTables?.has(tname); // pre-read before-row only when a hook needs it
+      const before = hooked ? ((await db.select().from(table).where(w).get()) as AnyRow | undefined) : undefined;
+      await db.update(table).set(body).where(w).run();
+      const r = (await db.select().from(table).where(w).get()) as AnyRow | undefined;
+      if (hooked && before && r) await opts.afterUpdate!(tname, c, db, before, r);
+      return r ? c.json(r) : c.json({ error: "not found" }, 404);
+    },
+    delete: async (c) => {
+      const g = gate(policy.delete, ident(c)); if (!g.ok) return denied(c, g);
+      await opts.db(c).delete(table).where(scoped(c, g.scopeOwner, true)!).run();
+      return c.body(null, 204);
+    },
+  };
+}

package/src/index.ts

@@ -41,3 +41,6 @@ export {
 } 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";
+// Driver-agnostic gated CRUD HANDLERS (the @suluk/hono gate engine over a drizzle table) — ONE impl for dev (bun:sqlite,
+// sync) + worker (D1, async); the db is injected as a resolver, so the two runtimes share one factory, no twin drift.
+export { crudHandlers, type CrudHandlers, type CrudHandlerOptions, type CrudDb } from "./handlers";

package/test/handlers.test.ts

@@ -0,0 +1,103 @@
+/**
+ * crudHandlers — the driver-agnostic gated CRUD factory. Driven through a real Hono app over a bun:sqlite drizzle
+ * instance (so the awaited terminals .all()/.get()/.returning()/.run() are exercised exactly as the Worker runs them
+ * on D1). Covers owner-scoping, the access modes' gate (anon→401, non-admin→403), redaction, the afterUpdate hook,
+ * list filters + pagination, and create owner-stamp + update id/owner strip.
+ */
+import { test, expect, describe, beforeEach } from "bun:test";
+import { Hono, type Context } from "hono";
+import { Database } from "bun:sqlite";
+import { drizzle, type BunSQLiteDatabase } from "drizzle-orm/bun-sqlite";
+import { sqliteTable, integer, text } from "drizzle-orm/sqlite-core";
+import { crudHandlers, schemaDDL, type CrudDb } from "../src/index";
+
+const thing = sqliteTable("thing", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  ownerId: text("owner_id"),
+  name: text("name").notNull(),
+  secret: text("secret"), // a "private" column redacted from non-admin reads
+});
+
+let sqlite: Database, db: BunSQLiteDatabase;
+function appFor(access: "owned" | "public" | "admin", hook?: { fired: string[] }) {
+  const app = new Hono();
+  const h = crudHandlers(thing, {
+    access, ownerCol: access === "owned" ? "ownerId" : undefined,
+    db: () => db as unknown as CrudDb,
+    principal: (c: Context) => c.req.header("x-user") ?? null,
+    isAdmin: (c: Context) => c.req.header("x-admin") === "1",
+    redact: (_t, row, admin) => { if (admin) return row; const { secret, ...rest } = row; return rest; },
+    afterUpdate: async (_t, _c, _db, before, after) => { hook?.fired.push(`${before.name}->${after.name}`); },
+    afterUpdateTables: new Set(["thing"]),
+  });
+  app.get("/thing", h.list); app.get("/thing/:id", h.get); app.post("/thing", h.create);
+  app.patch("/thing/:id", h.update); app.delete("/thing/:id", h.delete);
+  return app;
+}
+const J = (extra: Record<string, string> = {}) => ({ headers: { "content-type": "application/json", ...extra } });
+
+beforeEach(() => { sqlite = new Database(":memory:"); sqlite.exec(schemaDDL([thing])); db = drizzle(sqlite); });
+
+describe("owned access — owner-scoping + gate", () => {
+  test("anon list/create → 401; owner sees only own rows; admin sees all", async () => {
+    const app = appFor("owned");
+    expect((await app.request("/thing")).status).toBe(401); // owner op, anon
+    expect((await app.request("/thing", { method: "POST", ...J({ "x-user": "A" }), body: '{"name":"a1","ownerId":"HACK"}' })).status).toBe(201);
+    await app.request("/thing", { method: "POST", ...J({ "x-user": "B" }), body: '{"name":"b1"}' });
+    const aList = await (await app.request("/thing", { headers: { "x-user": "A" } })).json();
+    expect(aList.length).toBe(1); expect(aList[0].name).toBe("a1");
+    expect(aList[0].ownerId).toBe("A"); // create STAMPED the owner from principal, ignoring the body's "HACK"
+    const bList = await (await app.request("/thing", { headers: { "x-user": "B" } })).json();
+    expect(bList.length).toBe(1); expect(bList[0].name).toBe("b1");
+    const adminList = await (await app.request("/thing", { headers: { "x-admin": "1", "x-user": "Z" } })).json();
+    expect(adminList.length).toBe(2); // admin sees all
+  });
+
+  test("get/update/delete are owner-scoped (B can't touch A's row)", async () => {
+    const app = appFor("owned");
+    await app.request("/thing", { method: "POST", ...J({ "x-user": "A" }), body: '{"name":"a1"}' });
+    expect((await app.request("/thing/1", { headers: { "x-user": "A" } })).status).toBe(200);
+    expect((await app.request("/thing/1", { headers: { "x-user": "B" } })).status).toBe(404); // scoped away
+    expect((await app.request("/thing/1", { method: "PATCH", ...J({ "x-user": "B" }), body: '{"name":"hax"}' })).status).toBe(404);
+    expect((await app.request("/thing/1", { method: "DELETE", headers: { "x-user": "A" } })).status).toBe(204);
+  });
+});
+
+describe("redaction + afterUpdate hook", () => {
+  test("non-admin reads omit the private column; admin sees it", async () => {
+    const app = appFor("public");
+    await app.request("/thing", { method: "POST", ...J({ "x-admin": "1", "x-user": "admin" }), body: '{"name":"p","secret":"sssh"}' });
+    const anon = await (await app.request("/thing")).json();
+    expect(anon[0]).not.toHaveProperty("secret");
+    const admin = await (await app.request("/thing", { headers: { "x-admin": "1", "x-user": "admin" } })).json();
+    expect(admin[0].secret).toBe("sssh");
+  });
+
+  test("update fires the afterUpdate hook with before/after + strips id/owner from the body", async () => {
+    const fired: string[] = []; const app = appFor("owned", { fired });
+    await app.request("/thing", { method: "POST", ...J({ "x-user": "A" }), body: '{"name":"old"}' });
+    const res = await app.request("/thing/1", { method: "PATCH", ...J({ "x-user": "A" }), body: '{"name":"new","id":999,"ownerId":"HACK"}' });
+    const row = await res.json();
+    expect(row.id).toBe(1); expect(row.ownerId).toBe("A"); expect(row.name).toBe("new"); // id/owner not moved
+    expect(fired).toEqual(["old->new"]);
+  });
+});
+
+describe("public + admin modes + list features", () => {
+  test("public: anon reads, admin writes", async () => {
+    const app = appFor("public");
+    expect((await app.request("/thing")).status).toBe(200); // anyone reads
+    expect((await app.request("/thing", { method: "POST", ...J(), body: '{"name":"x"}' })).status).toBe(401); // create=admin, anon
+    expect((await app.request("/thing", { method: "POST", ...J({ "x-user": "u" }), body: '{"name":"x"}' })).status).toBe(403); // signed-in non-admin
+    expect((await app.request("/thing", { method: "POST", ...J({ "x-admin": "1", "x-user": "admin" }), body: '{"name":"x"}' })).status).toBe(201);
+  });
+
+  test("list filters by a real column + paginates opt-in", async () => {
+    const app = appFor("public");
+    for (const n of ["k", "k", "z"]) await app.request("/thing", { method: "POST", ...J({ "x-admin": "1", "x-user": "admin" }), body: JSON.stringify({ name: n }) });
+    const filtered = await (await app.request("/thing?name=k")).json();
+    expect(filtered.length).toBe(2);
+    const page = await (await app.request("/thing?perPage=1&page=1")).json();
+    expect(page.length).toBe(1);
+  });
+});