@gobing-ai/ts-db 0.4.6 → 0.4.8

package/README.md

@@ -14,7 +14,7 @@ Application code imports only `@gobing-ai/ts-db` — never `drizzle-orm`. drizzl
 
 | Component | Purpose |
 |-----------|---------|
-| `createDbAdapter` / `DbAdapter` | Construction + lifecycle + string-SQL escape; exposes an internal typed db to the DAO layer only |
+| `createDbAdapter` / `DbAdapter` | Construction + lifecycle + string-SQL escape + atomic batch; exposes an internal typed db to the DAO layer only |
 | `BunSqliteAdapter` | Bun SQLite implementation with statement caching and WAL pragmas (`@gobing-ai/ts-db/bun-sqlite`) |
 | `D1Adapter` | Cloudflare D1 implementation (no `@cloudflare/workers-types` dependency) |
 | `BaseDao` | Raw tier — `query`/`one`/`tx`, drizzle-free signatures |
@@ -52,6 +52,7 @@ classDiagram
         +run(sql, ...params) void
         +queryFirst(sql, ...params) T?
         +queryAll(sql, ...params) T[]
+        +batch(operations) void
         +close() void
     }
 
@@ -177,6 +178,13 @@ const user = await adapter.queryFirst<{ name: string }>('SELECT name FROM users
 const all = await adapter.queryAll<{ name: string }>('SELECT name FROM users');
 ```
 
+```ts
+// Atomic multi-statement batch — all succeed or all roll back (ADR-020)
+await adapter.batch([
+    { sql: 'INSERT INTO users VALUES (?, ?)', params: ['u2', 'Bob'] },
+    { sql: 'UPDATE counters SET count = count + 1 WHERE name = ?', params: ['users'] },
+]);
+```
 ### EntityDao — CRUD with soft delete
 
 Define a Drizzle table, extend `EntityDao`, get full CRUD for free:

package/dist/adapter.d.ts

@@ -40,9 +40,28 @@ export interface DbAdapter {
     queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
     /** Parameterized read returning all rows. */
     queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    /**
+     * Execute a batch of parameterized writes atomically — either all commit or
+     * none do. Used by adapters that need to persist multiple related rows in a
+     * single transaction (e.g. workflow transition + state snapshot + phase write).
+     * Each entry is a `{ sql, params }` tuple applied in order. Adapters must
+     * uphold all-or-nothing semantics for multi-statement batches or **throw**;
+     * silently degrading to non-atomic sequential writes is not allowed. A
+     * single-statement batch may execute directly (trivially atomic).
+     */
+    batch(operations: readonly DbBatchOp[]): Promise<void>;
     /** Close the underlying connection. */
     close(): void;
 }
+/**
+ * A single write operation inside a {@link DbAdapter.batch} call.
+ */
+export interface DbBatchOp {
+    /** SQL statement (INSERT/UPDATE/DELETE). */
+    sql: string;
+    /** Bind parameters for the statement. */
+    params: readonly unknown[];
+}
 /**
  * Discriminated-union config for creating a database adapter (bun-sqlite or D1).
  */

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;GAEG;AACH,UAAU,SAAS;IACf,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEjH;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,gEAAgE;IAChE,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzE,6CAA6C;IAC7C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D,uCAAuC;IACvC,KAAK,IAAI,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACrB;IACI,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACL,GACD;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3C;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAcjF"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;GAEG;AACH,UAAU,SAAS;IACf,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEjH;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,gEAAgE;IAChE,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzE,6CAA6C;IAC7C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D;;;;;;;;OAQG;IACH,KAAK,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,uCAAuC;IACvC,KAAK,IAAI,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACrB;IACI,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACL,GACD;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3C;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAcjF"}

package/dist/adapters/bun-sqlite.d.ts

@@ -1,5 +1,5 @@
 import { type BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
-import type { DbAdapter, InternalDb } from '../adapter';
+import type { DbAdapter, DbBatchOp, InternalDb } from '../adapter';
 import * as schema from '../schema/runtime';
 /**
  * Configuration options for the bun:sqlite adapter (path, pragmas).
@@ -36,6 +36,7 @@ export declare class BunSqliteAdapter implements DbAdapter {
     run(sql: string, ...params: unknown[]): Promise<void>;
     queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
     queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    batch(operations: readonly DbBatchOp[]): Promise<void>;
     close(): void;
 }
 //# sourceMappingURL=bun-sqlite.d.ts.map

package/dist/adapters/bun-sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun-sqlite.d.ts","sourceRoot":"","sources":["../../src/adapters/bun-sqlite.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,iBAAiB,EAAW,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAS5C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACL;AAUD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAC9C,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAmC;IACpD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IAEpE,OAAO,CAAC,YAAY;gBAUR,OAAO,CAAC,EAAE,gBAAgB;IAkBtC,+EAA+E;IAC/E,IAAI,EAAE,IAAI,UAAU,CAEnB;IAED,wEAAwE;IACxE,YAAY,IAAI,iBAAiB,CAAC,OAAO,MAAM,CAAC;IAI1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAKlE,KAAK,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"bun-sqlite.d.ts","sourceRoot":"","sources":["../../src/adapters/bun-sqlite.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,iBAAiB,EAAW,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAS5C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACL;AAUD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAC9C,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAmC;IACpD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IAEpE,OAAO,CAAC,YAAY;gBAUR,OAAO,CAAC,EAAE,gBAAgB;IAkBtC,+EAA+E;IAC/E,IAAI,EAAE,IAAI,UAAU,CAEnB;IAED,wEAAwE;IACxE,YAAY,IAAI,iBAAiB,CAAC,OAAO,MAAM,CAAC;IAI1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAK5D,KAAK,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5D,KAAK,IAAI,IAAI;CAGhB"}

package/dist/adapters/bun-sqlite.js

@@ -65,6 +65,16 @@ export class BunSqliteAdapter {
         const stmt = this.getStatement(sql);
         return stmt.all(...params) ?? [];
     }
+    async batch(operations) {
+        if (operations.length === 0)
+            return;
+        this.sqlite.transaction(() => {
+            for (const op of operations) {
+                const stmt = this.getStatement(op.sql);
+                stmt.run(...op.params);
+            }
+        })();
+    }
     close() {
         this.sqlite.close();
     }

package/dist/adapters/d1.d.ts

@@ -1,5 +1,5 @@
 import { type DrizzleD1Database } from 'drizzle-orm/d1';
-import type { DbAdapter, InternalDb } from '../adapter';
+import type { DbAdapter, DbBatchOp, InternalDb } from '../adapter';
 import * as schema from '../schema/runtime';
 /**
  * Minimal D1 binding interface — avoids depending on @cloudflare/workers-types.
@@ -14,6 +14,14 @@ export interface D1Binding {
         }>;
     };
     exec(sql: string): Promise<void>;
+    /**
+     * Run multiple statements as a single atomic batch (D1's native `batch()`
+     * API). Optional for single-statement test doubles only: when absent,
+     * {@link D1Adapter.batch} runs a lone statement directly (trivially atomic)
+     * and **throws** for multi-statement batches rather than silently degrading
+     * atomicity. Real D1 bindings always provide `batch()`.
+     */
+    batch?(statements: D1BoundStatement[]): Promise<unknown[]>;
 }
 interface D1BoundStatement {
     all<T>(): Promise<{
@@ -47,6 +55,7 @@ export declare class D1Adapter implements DbAdapter {
     run(sql: string, ...params: unknown[]): Promise<void>;
     queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
     queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    batch(operations: readonly DbBatchOp[]): Promise<void>;
     close(): void;
 }
 export {};

package/dist/adapters/d1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"d1.d.ts","sourceRoot":"","sources":["../../src/adapters/d1.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAW,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAClB,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC;QAC7C,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/B,GAAG,CAAC,IAAI,OAAO,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;KAC7D,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,UAAU,gBAAgB;IACtB,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtD,GAAG,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzD,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACvB,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,SAAS;IACvC,OAAO,CAAC,OAAO,CAAY;IAC3B,OAAO,CAAC,SAAS,CAAmC;gBAExC,OAAO,EAAE,SAAS;IAK9B,kEAAkE;IAClE,IAAI,EAAE,IAAI,UAAU,CAEnB;IAED,wEAAwE;IACxE,YAAY,IAAI,iBAAiB,CAAC,OAAO,MAAM,CAAC;IAIhD,qEAAqE;IACrE,UAAU,IAAI,SAAS;IAIjB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAQxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAOlE,KAAK,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"d1.d.ts","sourceRoot":"","sources":["../../src/adapters/d1.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAW,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAClB,IAAI,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC;QAC7C,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/B,GAAG,CAAC,IAAI,OAAO,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;KAC7D,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,UAAU,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAC9D;AAED,UAAU,gBAAgB;IACtB,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtD,GAAG,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzD,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACvB,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,SAAS;IACvC,OAAO,CAAC,OAAO,CAAY;IAC3B,OAAO,CAAC,SAAS,CAAmC;gBAExC,OAAO,EAAE,SAAS;IAK9B,kEAAkE;IAClE,IAAI,EAAE,IAAI,UAAU,CAEnB;IAED,wEAAwE;IACxE,YAAY,IAAI,iBAAiB,CAAC,OAAO,MAAM,CAAC;IAIhD,qEAAqE;IACrE,UAAU,IAAI,SAAS;IAIjB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAQxE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAO5D,KAAK,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5D,KAAK,IAAI,IAAI;CAGhB"}

package/dist/adapters/d1.js

@@ -44,6 +44,28 @@ export class D1Adapter {
         const result = await bound.all();
         return result.results ?? [];
     }
+    async batch(operations) {
+        if (operations.length === 0)
+            return;
+        // A single statement is atomic on its own, so a binding without native
+        // batch() may run it directly. Multiple statements without native batch()
+        // cannot be made atomic — fail loud rather than silently break the
+        // all-or-nothing contract (real D1 bindings always provide batch()).
+        if (this.binding.batch === undefined && operations.length > 1) {
+            throw new Error(`D1 binding has no batch() — cannot execute ${operations.length} statements atomically; ` +
+                'provide a binding with native batch() support');
+        }
+        const boundStmts = operations.map((op) => {
+            const stmt = this.binding.prepare(op.sql);
+            return op.params.length > 0 ? stmt.bind(...op.params) : stmt.bind();
+        });
+        if (this.binding.batch !== undefined) {
+            await this.binding.batch(boundStmts);
+        }
+        else {
+            await boundStmts[0]?.run();
+        }
+    }
     close() {
         // D1 bindings are managed by the Workers runtime -- no-op
     }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type InternalDb } from './adapter';
+export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type DbBatchOp, type InternalDb } from './adapter';
 export { D1Adapter } from './adapters/d1';
 export { BaseDao, type TxHandle } from './base-dao';
 export { type EmbeddedMigration, embeddedMigrations } from './embedded-migrations';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,KAAK,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EACH,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,cAAc,EACd,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,SAAS,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpF,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACnH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,KAAK,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EACH,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,cAAc,EACd,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,SAAS,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpF,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-db",
-    "version": "0.4.6",
+    "version": "0.4.8",
     "description": "@gobing-ai/ts-db — a drizzle-free database facade: typed DAOs over Bun SQLite / Cloudflare D1, a small predicate query spec, single-source-of-truth tables, and migrations. Drizzle stays an internal detail.",
     "keywords": [
         "typescript",
@@ -66,8 +66,8 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-db-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-runtime": "^0.4.6",
-        "@gobing-ai/ts-utils": "^0.4.6"
+        "@gobing-ai/ts-runtime": "^0.4.8",
+        "@gobing-ai/ts-utils": "^0.4.8"
     },
     "peerDependencies": {
         "drizzle-orm": ">=0.38.0",

package/src/adapter.ts

@@ -43,10 +43,30 @@ export interface DbAdapter {
     queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
     /** Parameterized read returning all rows. */
     queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    /**
+     * Execute a batch of parameterized writes atomically — either all commit or
+     * none do. Used by adapters that need to persist multiple related rows in a
+     * single transaction (e.g. workflow transition + state snapshot + phase write).
+     * Each entry is a `{ sql, params }` tuple applied in order. Adapters must
+     * uphold all-or-nothing semantics for multi-statement batches or **throw**;
+     * silently degrading to non-atomic sequential writes is not allowed. A
+     * single-statement batch may execute directly (trivially atomic).
+     */
+    batch(operations: readonly DbBatchOp[]): Promise<void>;
     /** Close the underlying connection. */
     close(): void;
 }
 
+/**
+ * A single write operation inside a {@link DbAdapter.batch} call.
+ */
+export interface DbBatchOp {
+    /** SQL statement (INSERT/UPDATE/DELETE). */
+    sql: string;
+    /** Bind parameters for the statement. */
+    params: readonly unknown[];
+}
+
 /**
  * Discriminated-union config for creating a database adapter (bun-sqlite or D1).
  */

package/src/adapters/bun-sqlite.ts

@@ -1,7 +1,7 @@
 import { isAbsolutePath, resolvePath } from '@gobing-ai/ts-runtime';
 import { Database } from '@gobing-ai/ts-runtime/bun-sqlite';
 import { type BunSQLiteDatabase, drizzle } from 'drizzle-orm/bun-sqlite';
-import type { DbAdapter, InternalDb } from '../adapter';
+import type { DbAdapter, DbBatchOp, InternalDb } from '../adapter';
 import * as schema from '../schema/runtime';
 
 type SqliteStatementLike = {
@@ -103,6 +103,16 @@ export class BunSqliteAdapter implements DbAdapter {
         return ((stmt as unknown as { all: (...p: unknown[]) => T[] }).all(...params) as T[]) ?? [];
     }
 
+    async batch(operations: readonly DbBatchOp[]): Promise<void> {
+        if (operations.length === 0) return;
+        this.sqlite.transaction(() => {
+            for (const op of operations) {
+                const stmt = this.getStatement(op.sql);
+                stmt.run(...op.params);
+            }
+        })();
+    }
+
     close(): void {
         this.sqlite.close();
     }

package/src/adapters/d1.ts

@@ -1,5 +1,5 @@
 import { type DrizzleD1Database, drizzle } from 'drizzle-orm/d1';
-import type { DbAdapter, InternalDb } from '../adapter';
+import type { DbAdapter, DbBatchOp, InternalDb } from '../adapter';
 import * as schema from '../schema/runtime';
 
 /**
@@ -12,6 +12,14 @@ export interface D1Binding {
         run?(): Promise<{ results: unknown[]; success: boolean }>;
     };
     exec(sql: string): Promise<void>;
+    /**
+     * Run multiple statements as a single atomic batch (D1's native `batch()`
+     * API). Optional for single-statement test doubles only: when absent,
+     * {@link D1Adapter.batch} runs a lone statement directly (trivially atomic)
+     * and **throws** for multi-statement batches rather than silently degrading
+     * atomicity. Real D1 bindings always provide `batch()`.
+     */
+    batch?(statements: D1BoundStatement[]): Promise<unknown[]>;
 }
 
 interface D1BoundStatement {
@@ -76,6 +84,29 @@ export class D1Adapter implements DbAdapter {
         return result.results ?? [];
     }
 
+    async batch(operations: readonly DbBatchOp[]): Promise<void> {
+        if (operations.length === 0) return;
+        // A single statement is atomic on its own, so a binding without native
+        // batch() may run it directly. Multiple statements without native batch()
+        // cannot be made atomic — fail loud rather than silently break the
+        // all-or-nothing contract (real D1 bindings always provide batch()).
+        if (this.binding.batch === undefined && operations.length > 1) {
+            throw new Error(
+                `D1 binding has no batch() — cannot execute ${operations.length} statements atomically; ` +
+                    'provide a binding with native batch() support',
+            );
+        }
+        const boundStmts: D1BoundStatement[] = operations.map((op) => {
+            const stmt = this.binding.prepare(op.sql);
+            return op.params.length > 0 ? stmt.bind(...op.params) : stmt.bind();
+        });
+        if (this.binding.batch !== undefined) {
+            await this.binding.batch(boundStmts);
+        } else {
+            await boundStmts[0]?.run();
+        }
+    }
+
     close(): void {
         // D1 bindings are managed by the Workers runtime -- no-op
     }

package/src/index.ts

@@ -1,4 +1,4 @@
-export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type InternalDb } from './adapter';
+export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type DbBatchOp, type InternalDb } from './adapter';
 export { D1Adapter } from './adapters/d1';
 export { BaseDao, type TxHandle } from './base-dao';