@suluk/drizzle 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/drizzle",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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"

package/src/cas.ts

@@ -0,0 +1,42 @@
+/**
+ * Once-only WRITE primitives — the concurrency-correctness skeleton a money/state-machine path needs, made
+ * driver-agnostic. `rowsChanged` normalizes the affected-row count across drivers (bun:sqlite `.changes`, D1
+ * `.meta.changes`, others `.rowsAffected`); `claimOnce` runs a CONDITIONAL update and reports whether THIS call
+ * won the transition (changed a row) — the compare-and-set that makes "pending→paid", "paid→refunded", an
+ * atomic latch flip, or a claim-then-notify sweep fire exactly once under concurrent delivery. The state machine
+ * (which transitions, which side-effects) stays in the app; this owns only the race-safe claim, behind a port.
+ */
+import type { SQL } from "drizzle-orm";
+
+/** A drizzle `.run()` result across drivers (bun:sqlite / D1 / better-sqlite3). */
+export type WriteResult = { changes?: number; rowsAffected?: number; meta?: { changes?: number } } | unknown;
+
+/** The number of rows a write affected, normalized across drivers (0 when unknown). */
+export function rowsChanged(result: WriteResult): number {
+  const r = result as { changes?: number; rowsAffected?: number; meta?: { changes?: number } } | null | undefined;
+  return Number(r?.meta?.changes ?? r?.changes ?? r?.rowsAffected ?? 0) || 0;
+}
+
+/** Minimal drizzle handle for a conditional update (bun:sqlite sync or D1 async — both awaited). */
+export interface ClaimDb { update: (table: unknown) => { set: (values: Record<string, unknown>) => { where: (cond: SQL) => { run: () => unknown | Promise<unknown>; returning: () => unknown | Promise<unknown> } } } }
+
+/**
+ * Atomically CLAIM a transition: `UPDATE table SET set WHERE where`, returning true iff this call changed a row.
+ * The `where` MUST include the FROM-state guard (e.g. `and(eq(id, n), eq(status, "pending"))`) so a re-delivery /
+ * concurrent caller finds the row already transitioned and changes nothing → returns false. The single point that
+ * makes a once-only side-effect (charge, refund, decrement, email) safe to run when, and only when, the claim wins.
+ */
+export async function claimOnce(db: ClaimDb, table: unknown, where: SQL, set: Record<string, unknown>): Promise<boolean> {
+  const res = await db.update(table).set(set).where(where).run();
+  return rowsChanged(res) > 0;
+}
+
+/**
+ * Atomically CLAIM a SET of rows and RETURN them: `UPDATE table SET set WHERE where RETURNING *`. The claim-then-act
+ * variant of {@link claimOnce} — for a batch sweep (mark a waitlist notified / a cart-recovery emailed) where each
+ * row must be handled exactly once even if the sweep overlaps: a concurrent run's UPDATE claims a DISJOINT set, so
+ * the side-effect (email, notify) fires once per row. Returns the rows THIS call won; act only on those.
+ */
+export async function claimRows<T = Record<string, unknown>>(db: ClaimDb, table: unknown, where: SQL, set: Record<string, unknown>): Promise<T[]> {
+  return (await db.update(table).set(set).where(where).returning()) as T[];
+}

package/src/index.ts

@@ -44,3 +44,6 @@ 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";
+// once-only WRITE primitives — the race-safe compare-and-set skeleton for money/state-machine paths (normalize the
+// affected-row count across drivers; claim a transition exactly once). The transitions/side-effects stay in the app.
+export { rowsChanged, claimOnce, claimRows, type WriteResult, type ClaimDb } from "./cas";

package/test/cas.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Once-only WRITE primitives. rowsChanged normalizes every driver's result shape; claimOnce makes a conditional
+ * transition fire exactly once — the second claim of the same transition wins nothing (the money-path guarantee).
+ */
+import { test, expect, describe, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { drizzle, type BunSQLiteDatabase } from "drizzle-orm/bun-sqlite";
+import { sqliteTable, integer, text } from "drizzle-orm/sqlite-core";
+import { and, eq } from "drizzle-orm";
+import { rowsChanged, claimOnce, claimRows, schemaDDL, type ClaimDb } from "../src/index";
+
+describe("rowsChanged", () => {
+  test("normalizes bun:sqlite .changes, D1 .meta.changes, others .rowsAffected; 0 when unknown", () => {
+    expect(rowsChanged({ changes: 1 })).toBe(1);            // bun:sqlite / better-sqlite3
+    expect(rowsChanged({ meta: { changes: 2 } })).toBe(2);  // D1
+    expect(rowsChanged({ rowsAffected: 3 })).toBe(3);       // some drivers
+    expect(rowsChanged({})).toBe(0);
+    expect(rowsChanged(null)).toBe(0);
+    expect(rowsChanged(undefined)).toBe(0);
+  });
+});
+
+const order = sqliteTable("order", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  status: text("status").notNull().default("pending"),
+});
+
+describe("claimOnce — atomic compare-and-set", () => {
+  let db: BunSQLiteDatabase;
+  beforeEach(() => { const s = new Database(":memory:"); s.exec(schemaDDL([order])); db = drizzle(s); db.insert(order).values({ status: "pending" }).run(); });
+
+  test("first claim of pending→paid wins; the second (re-delivery) changes nothing", async () => {
+    const won1 = await claimOnce(db as unknown as ClaimDb, order, and(eq(order.id, 1), eq(order.status, "pending"))!, { status: "paid" });
+    const won2 = await claimOnce(db as unknown as ClaimDb, order, and(eq(order.id, 1), eq(order.status, "pending"))!, { status: "paid" });
+    expect(won1).toBe(true);
+    expect(won2).toBe(false); // already paid — the FROM-state guard fails, no row changed
+    expect(db.select().from(order).where(eq(order.id, 1)).get()!.status).toBe("paid");
+  });
+
+  test("a transition whose FROM-state doesn't match claims nothing", async () => {
+    // row is pending; try to claim paid→cancelled → no match
+    expect(await claimOnce(db as unknown as ClaimDb, order, and(eq(order.id, 1), eq(order.status, "paid"))!, { status: "cancelled" })).toBe(false);
+    expect(db.select().from(order).where(eq(order.id, 1)).get()!.status).toBe("pending"); // untouched
+  });
+});
+
+describe("claimRows — claim a set + return exactly the rows this call won", () => {
+  let db: BunSQLiteDatabase;
+  beforeEach(() => { const s = new Database(":memory:"); s.exec(schemaDDL([order])); db = drizzle(s); for (let i = 0; i < 3; i++) db.insert(order).values({ status: "pending" }).run(); });
+
+  test("claims matching rows once; a re-run claims a disjoint (empty) set", async () => {
+    const first = await claimRows<{ id: number }>(db as unknown as ClaimDb, order, eq(order.status, "pending"), { status: "paid" });
+    expect(first.map((r) => r.id).sort()).toEqual([1, 2, 3]); // returned the rows it flipped
+    const second = await claimRows(db as unknown as ClaimDb, order, eq(order.status, "pending"), { status: "paid" });
+    expect(second.length).toBe(0); // already paid → nothing left to claim (no double-handling)
+  });
+});