@suluk/drizzle 0.1.5 → 0.1.6

package/package.json

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

@@ -18,7 +18,7 @@ export function rowsChanged(result: WriteResult): number {
 }
 
 /** 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> } } } }
+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.
@@ -30,3 +30,13 @@ export async function claimOnce(db: ClaimDb, table: unknown, where: SQL, set: Re
   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

@@ -46,4 +46,4 @@ export { tableDDL, schemaDDL, type DdlOptions } from "./ddl";
 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, type WriteResult, type ClaimDb } from "./cas";
+export { rowsChanged, claimOnce, claimRows, type WriteResult, type ClaimDb } from "./cas";

package/test/cas.test.ts

@@ -7,7 +7,7 @@ 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, schemaDDL, type ClaimDb } from "../src/index";
+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", () => {
@@ -43,3 +43,15 @@ describe("claimOnce — atomic compare-and-set", () => {
     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)
+  });
+});