@tursodatabase/serverless 1.1.3 → 1.2.0-pre.2

package/dist/index.cjs

@@ -237,6 +237,67 @@ async function executePipeline(url, authToken, request, remoteEncryptionKey, sig
   return response.json();
 }
 
+// src/args.ts
+function normalizeArgs(args) {
+  if (args === void 0) return [];
+  if (Array.isArray(args)) return args;
+  if (args !== null && typeof args === "object" && args.constructor === Object) {
+    return args;
+  }
+  return [args];
+}
+function isQueryOptions(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, "queryTimeout");
+}
+function splitBindParameters(bindParameters) {
+  if (bindParameters.length === 0) {
+    return { params: void 0, queryOptions: void 0 };
+  }
+  if (isQueryOptions(bindParameters[bindParameters.length - 1])) {
+    if (bindParameters.length === 1) {
+      return { params: void 0, queryOptions: bindParameters[0] };
+    }
+    return {
+      params: bindParameters.length === 2 ? bindParameters[0] : bindParameters.slice(0, -1),
+      queryOptions: bindParameters[bindParameters.length - 1]
+    };
+  }
+  return {
+    params: bindParameters.length === 1 ? bindParameters[0] : bindParameters,
+    queryOptions: void 0
+  };
+}
+function encodeSqlArgs(args = []) {
+  let positionalArgs = [];
+  let namedArgs = [];
+  if (Array.isArray(args)) {
+    positionalArgs = args.map(encodeValue);
+  } else {
+    const keys = Object.keys(args);
+    const isNumericKeys = keys.length > 0 && keys.every((key) => /^\d+$/.test(key));
+    if (isNumericKeys) {
+      const sortedKeys = keys.sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
+      const maxIndex = parseInt(sortedKeys[sortedKeys.length - 1], 10);
+      positionalArgs = new Array(maxIndex);
+      for (const key of sortedKeys) {
+        const index = parseInt(key, 10) - 1;
+        positionalArgs[index] = encodeValue(args[key]);
+      }
+      for (let i = 0; i < positionalArgs.length; i++) {
+        if (positionalArgs[i] === void 0) {
+          positionalArgs[i] = { type: "null" };
+        }
+      }
+    } else {
+      namedArgs = Object.entries(args).map(([name, value]) => ({
+        name,
+        value: encodeValue(value)
+      }));
+    }
+  }
+  return { args: positionalArgs, namedArgs };
+}
+
 // src/session.ts
 function normalizeUrl(url) {
   return url.replace(/^libsql:\/\//, "https://");
@@ -314,41 +375,15 @@ var Session = class {
    * @returns Promise resolving to the raw response and cursor entries
    */
   async executeRaw(sql, args = [], queryOptions) {
-    let positionalArgs = [];
-    let namedArgs = [];
-    if (Array.isArray(args)) {
-      positionalArgs = args.map(encodeValue);
-    } else {
-      const keys = Object.keys(args);
-      const isNumericKeys = keys.length > 0 && keys.every((key) => /^\d+$/.test(key));
-      if (isNumericKeys) {
-        const sortedKeys = keys.sort((a, b) => parseInt(a) - parseInt(b));
-        const maxIndex = parseInt(sortedKeys[sortedKeys.length - 1]);
-        positionalArgs = new Array(maxIndex);
-        for (const key of sortedKeys) {
-          const index = parseInt(key) - 1;
-          positionalArgs[index] = encodeValue(args[key]);
-        }
-        for (let i = 0; i < positionalArgs.length; i++) {
-          if (positionalArgs[i] === void 0) {
-            positionalArgs[i] = { type: "null" };
-          }
-        }
-      } else {
-        namedArgs = Object.entries(args).map(([name, value]) => ({
-          name,
-          value: encodeValue(value)
-        }));
-      }
-    }
+    const encodedArgs = encodeSqlArgs(args);
     const request = {
       baton: this.baton,
       batch: {
         steps: [{
           stmt: {
             sql,
-            args: positionalArgs,
-            named_args: namedArgs,
+            args: encodedArgs.args,
+            named_args: encodedArgs.namedArgs,
             want_rows: true
           }
         }]
@@ -439,23 +474,76 @@ var Session = class {
   }
   /**
    * Execute multiple SQL statements in a batch.
-   * 
-   * @param statements - Array of SQL statements to execute
-   * @returns Promise resolving to batch execution results
+   *
+   * When `mode` is set, the batch is sent as a single Hrana request that
+   * also carries `BEGIN <mode>` / `COMMIT` / `ROLLBACK` steps using the
+   * server-side condition chain, giving atomic execution in one round-trip.
+   * When `mode` is omitted, the user statements are sent as-is and run
+   * under autocommit (or whatever transaction is already active on this
+   * stream).
+   *
+   * @param statements - Array of SQL statements to execute.
+   * @param mode - Optional locking mode; when set, the batch executes
+   *   atomically. Accepts the same values as `Database.transaction(...)`
+   *   variants: `"deferred"`, `"immediate"`, `"exclusive"`, `"concurrent"`.
+   * @returns Promise resolving to batch execution results.
    */
-  async batch(statements, queryOptions) {
+  async batch(statements, mode, queryOptions) {
+    const userSteps = statements.map((statement) => {
+      if (typeof statement === "string") {
+        return {
+          stmt: { sql: statement, args: [], named_args: [], want_rows: false }
+        };
+      }
+      const encodedArgs = encodeSqlArgs(statement.args ?? []);
+      return {
+        stmt: {
+          sql: statement.sql,
+          args: encodedArgs.args,
+          named_args: encodedArgs.namedArgs,
+          want_rows: false
+        }
+      };
+    });
+    let steps;
+    let firstUserStepIdx = 0;
+    let lastUserStepIdx = userSteps.length - 1;
+    let beginIdx = -1;
+    let commitIdx = -1;
+    let rollbackIdx = -1;
+    if (mode === void 0) {
+      steps = userSteps;
+    } else {
+      beginIdx = 0;
+      firstUserStepIdx = 1;
+      lastUserStepIdx = userSteps.length;
+      commitIdx = lastUserStepIdx + 1;
+      rollbackIdx = commitIdx + 1;
+      steps = [
+        { stmt: { sql: `BEGIN ${mode.toUpperCase()}`, args: [], named_args: [], want_rows: false } },
+        ...userSteps.map((step, i) => ({
+          ...step,
+          condition: { type: "ok", step: i === 0 ? beginIdx : firstUserStepIdx + i - 1 }
+        })),
+        {
+          stmt: { sql: "COMMIT", args: [], named_args: [], want_rows: false },
+          condition: { type: "ok", step: lastUserStepIdx }
+        },
+        {
+          stmt: { sql: "ROLLBACK", args: [], named_args: [], want_rows: false },
+          condition: {
+            type: "and",
+            conds: [
+              { type: "ok", step: beginIdx },
+              { type: "not", cond: { type: "ok", step: commitIdx } }
+            ]
+          }
+        }
+      ];
+    }
     const request = {
       baton: this.baton,
-      batch: {
-        steps: statements.map((sql) => ({
-          stmt: {
-            sql,
-            args: [],
-            named_args: [],
-            want_rows: false
-          }
-        }))
-      }
+      batch: { steps }
     };
     let batchResult;
     try {
@@ -471,21 +559,46 @@ var Session = class {
     }
     let totalRowsAffected = 0;
     let lastInsertRowid;
+    let deferredError = null;
+    let currentStep;
+    const isUserStep = (step) => {
+      if (mode === void 0) {
+        return true;
+      }
+      return step !== void 0 && step >= firstUserStepIdx && step <= lastUserStepIdx;
+    };
     for await (const entry of entries) {
       switch (entry.type) {
+        case "step_begin":
+          currentStep = entry.step;
+          break;
         case "step_end":
-          if (entry.affected_row_count !== void 0) {
-            totalRowsAffected += entry.affected_row_count;
-          }
-          if (entry.last_insert_rowid !== void 0 && entry.last_insert_rowid !== null) {
-            lastInsertRowid = typeof entry.last_insert_rowid === "number" ? entry.last_insert_rowid : parseInt(entry.last_insert_rowid, 10);
+          if (isUserStep(currentStep)) {
+            if (entry.affected_row_count !== void 0) {
+              totalRowsAffected += entry.affected_row_count;
+            }
+            if (entry.last_insert_rowid !== void 0 && entry.last_insert_rowid !== null) {
+              lastInsertRowid = typeof entry.last_insert_rowid === "number" ? entry.last_insert_rowid : parseInt(entry.last_insert_rowid, 10);
+            }
           }
+          currentStep = void 0;
           break;
         case "step_error":
+          if (mode === void 0) {
+            throw new DatabaseError(entry.error?.message || "Batch execution failed", entry.error?.code);
+          }
+          if (deferredError === null && entry.step !== rollbackIdx) {
+            deferredError = new DatabaseError(entry.error?.message || "Batch execution failed", entry.error?.code);
+          }
+          currentStep = void 0;
+          break;
         case "error":
           throw new DatabaseError(entry.error?.message || "Batch execution failed", entry.error?.code);
       }
     }
+    if (deferredError !== null) {
+      throw deferredError;
+    }
     return {
       rowsAffected: totalRowsAffected,
       lastInsertRowid
@@ -547,37 +660,6 @@ var Session = class {
   }
 };
 
-// src/args.ts
-function normalizeArgs(args) {
-  if (args === void 0) return [];
-  if (Array.isArray(args)) return args;
-  if (args !== null && typeof args === "object" && args.constructor === Object) {
-    return args;
-  }
-  return [args];
-}
-function isQueryOptions(value) {
-  return value != null && typeof value === "object" && !Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, "queryTimeout");
-}
-function splitBindParameters(bindParameters) {
-  if (bindParameters.length === 0) {
-    return { params: void 0, queryOptions: void 0 };
-  }
-  if (isQueryOptions(bindParameters[bindParameters.length - 1])) {
-    if (bindParameters.length === 1) {
-      return { params: void 0, queryOptions: bindParameters[0] };
-    }
-    return {
-      params: bindParameters.length === 2 ? bindParameters[0] : bindParameters.slice(0, -1),
-      queryOptions: bindParameters[bindParameters.length - 1]
-    };
-  }
-  return {
-    params: bindParameters.length === 1 ? bindParameters[0] : bindParameters,
-    queryOptions: void 0
-  };
-}
-
 // src/statement.ts
 var Statement = class _Statement {
   constructor(sessionConfig, sql, columns) {
@@ -1009,20 +1091,61 @@ var Connection = class {
     }
   }
   /**
-   * Execute multiple SQL statements in a batch.
-   * 
-   * @param statements - Array of SQL statements to execute
-   * @param mode - Optional transaction mode (currently unused)
-   * @returns Promise resolving to batch execution results
-   * 
+   * Executes a batch of SQL statements over this connection.
+   *
+   * By default, batch() is not transactional: each statement runs in its
+   * own autocommit step, so a failure mid-batch leaves earlier successful
+   * statements committed. Pass a `mode` to make the batch atomic — the
+   * statements are wrapped in `BEGIN <mode>` / `COMMIT` (with `ROLLBACK`
+   * on failure) and dispatched as a single Hrana request, so the whole
+   * batch completes in one round-trip. When called from inside a
+   * `connection.transaction(...)` callback the `mode` argument is ignored
+   * and the surrounding transaction is reused.
+   *
+   * When `mode` is set, `batch()` owns the surrounding
+   * `BEGIN`/`COMMIT`/`ROLLBACK`, so the `statements` array must not
+   * contain its own transaction-control SQL (`BEGIN`, `COMMIT`,
+   * `ROLLBACK`, `SAVEPOINT`, `RELEASE`). The input is not validated
+   * for that — a user-supplied `COMMIT` will close the wrapper
+   * transaction mid-batch and leave earlier statements committed,
+   * defeating the all-or-nothing contract.
+   *
+   * @param statements - An array of SQL strings or `{ sql, args }` objects.
+   * @param mode - When set, makes the batch atomic. Accepts the same
+   *   values as `connection.transaction(...)` variants: `"deferred"`,
+   *   `"immediate"`, `"exclusive"`, `"concurrent"`. Ignored when already
+   *   inside a transaction.
+   * @returns An object with `rowsAffected` (sum of affected rows) and
+   *   `lastInsertRowid` (rowid of the last successful insert).
+   *
    * @example
-   * ```typescript
-   * await client.batch([
-   *   "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
-   *   "INSERT INTO users (name) VALUES ('Alice')",
-   *   "INSERT INTO users (name) VALUES ('Bob')"
+   * // Plain SQL strings (non-atomic).
+   * await db.batch([
+   *   "INSERT INTO users(name) VALUES ('Alice')",
+   *   "INSERT INTO users(name) VALUES ('Bob')",
    * ]);
-   * ```
+   *
+   * @example
+   * // Positional and named bind parameters.
+   * await db.batch([
+   *   { sql: "INSERT INTO users(name, email) VALUES (?, ?)", args: ["Carol", "carol@example.net"] },
+   *   { sql: "INSERT INTO users(name, email) VALUES (:name, :email)", args: { name: "Dave", email: "dave@example.net" } },
+   * ]);
+   *
+   * @example
+   * // Atomic via the mode parameter.
+   * await db.batch([
+   *   { sql: "INSERT INTO users(name) VALUES (?)", args: ["Eve"] },
+   *   { sql: "INSERT INTO users(name) VALUES (?)", args: ["Frank"] },
+   * ], "immediate");
+   *
+   * @example
+   * // Atomic via the transaction() API for mixed workloads.
+   * const txn = db.transaction(async () => {
+   *   await db.batch([{ sql: "INSERT INTO users(name) VALUES (?)", args: ["Eve"] }]);
+   *   await db.execute("UPDATE counters SET n = n + 1");
+   * });
+   * await txn.immediate();
    */
   async batch(statements, mode, queryOptions) {
     if (!this.isOpen) {
@@ -1030,7 +1153,8 @@ var Connection = class {
     }
     await this.execLock.acquire();
     try {
-      return await this.session.batch(statements, queryOptions);
+      const effectiveMode = this._inTransaction ? void 0 : mode;
+      return await this.session.batch(statements, effectiveMode, queryOptions);
     } finally {
       this.execLock.release();
     }
@@ -1103,12 +1227,14 @@ var Connection = class {
     const properties = {
       default: { value: wrapTxn("") },
       deferred: { value: wrapTxn("DEFERRED") },
+      concurrent: { value: wrapTxn("CONCURRENT") },
       immediate: { value: wrapTxn("IMMEDIATE") },
       exclusive: { value: wrapTxn("EXCLUSIVE") },
       database: { value: this, enumerable: true }
     };
     Object.defineProperties(properties.default.value, properties);
     Object.defineProperties(properties.deferred.value, properties);
+    Object.defineProperties(properties.concurrent.value, properties);
     Object.defineProperties(properties.immediate.value, properties);
     Object.defineProperties(properties.exclusive.value, properties);
     return properties.default.value;

package/dist/index.d.cts

@@ -39,6 +39,11 @@ interface QueryOptions {
     queryTimeout?: number;
 }
 
+/**
+ * Locking mode for atomic `batch()` execution. Accepts the same values
+ * as the variants of `Connection.transaction(...)`.
+ */
+type BatchMode = 'deferred' | 'immediate' | 'exclusive' | 'concurrent';
 /**
  * Configuration options for a session.
  */
@@ -112,10 +117,23 @@ declare class Session {
     /**
      * Execute multiple SQL statements in a batch.
      *
-     * @param statements - Array of SQL statements to execute
-     * @returns Promise resolving to batch execution results
+     * When `mode` is set, the batch is sent as a single Hrana request that
+     * also carries `BEGIN <mode>` / `COMMIT` / `ROLLBACK` steps using the
+     * server-side condition chain, giving atomic execution in one round-trip.
+     * When `mode` is omitted, the user statements are sent as-is and run
+     * under autocommit (or whatever transaction is already active on this
+     * stream).
+     *
+     * @param statements - Array of SQL statements to execute.
+     * @param mode - Optional locking mode; when set, the batch executes
+     *   atomically. Accepts the same values as `Database.transaction(...)`
+     *   variants: `"deferred"`, `"immediate"`, `"exclusive"`, `"concurrent"`.
+     * @returns Promise resolving to batch execution results.
      */
-    batch(statements: string[], queryOptions?: QueryOptions): Promise<any>;
+    batch(statements: Array<string | {
+        sql: string;
+        args?: any[] | Record<string, any>;
+    }>, mode?: BatchMode, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a sequence of SQL statements separated by semicolons.
      *
@@ -298,6 +316,10 @@ declare class Statement {
  */
 interface Config extends SessionConfig {
 }
+type BatchStatement = string | {
+    sql: string;
+    args?: any[] | Record<string, any>;
+};
 /**
  * A connection to a Turso database.
  *
@@ -418,22 +440,63 @@ declare class Connection {
      */
     exec(sql: string, queryOptions?: QueryOptions): Promise<any>;
     /**
-     * Execute multiple SQL statements in a batch.
+     * Executes a batch of SQL statements over this connection.
+     *
+     * By default, batch() is not transactional: each statement runs in its
+     * own autocommit step, so a failure mid-batch leaves earlier successful
+     * statements committed. Pass a `mode` to make the batch atomic — the
+     * statements are wrapped in `BEGIN <mode>` / `COMMIT` (with `ROLLBACK`
+     * on failure) and dispatched as a single Hrana request, so the whole
+     * batch completes in one round-trip. When called from inside a
+     * `connection.transaction(...)` callback the `mode` argument is ignored
+     * and the surrounding transaction is reused.
+     *
+     * When `mode` is set, `batch()` owns the surrounding
+     * `BEGIN`/`COMMIT`/`ROLLBACK`, so the `statements` array must not
+     * contain its own transaction-control SQL (`BEGIN`, `COMMIT`,
+     * `ROLLBACK`, `SAVEPOINT`, `RELEASE`). The input is not validated
+     * for that — a user-supplied `COMMIT` will close the wrapper
+     * transaction mid-batch and leave earlier statements committed,
+     * defeating the all-or-nothing contract.
+     *
+     * @param statements - An array of SQL strings or `{ sql, args }` objects.
+     * @param mode - When set, makes the batch atomic. Accepts the same
+     *   values as `connection.transaction(...)` variants: `"deferred"`,
+     *   `"immediate"`, `"exclusive"`, `"concurrent"`. Ignored when already
+     *   inside a transaction.
+     * @returns An object with `rowsAffected` (sum of affected rows) and
+     *   `lastInsertRowid` (rowid of the last successful insert).
      *
-     * @param statements - Array of SQL statements to execute
-     * @param mode - Optional transaction mode (currently unused)
-     * @returns Promise resolving to batch execution results
+     * @example
+     * // Plain SQL strings (non-atomic).
+     * await db.batch([
+     *   "INSERT INTO users(name) VALUES ('Alice')",
+     *   "INSERT INTO users(name) VALUES ('Bob')",
+     * ]);
      *
      * @example
-     * ```typescript
-     * await client.batch([
-     *   "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
-     *   "INSERT INTO users (name) VALUES ('Alice')",
-     *   "INSERT INTO users (name) VALUES ('Bob')"
+     * // Positional and named bind parameters.
+     * await db.batch([
+     *   { sql: "INSERT INTO users(name, email) VALUES (?, ?)", args: ["Carol", "carol@example.net"] },
+     *   { sql: "INSERT INTO users(name, email) VALUES (:name, :email)", args: { name: "Dave", email: "dave@example.net" } },
      * ]);
-     * ```
+     *
+     * @example
+     * // Atomic via the mode parameter.
+     * await db.batch([
+     *   { sql: "INSERT INTO users(name) VALUES (?)", args: ["Eve"] },
+     *   { sql: "INSERT INTO users(name) VALUES (?)", args: ["Frank"] },
+     * ], "immediate");
+     *
+     * @example
+     * // Atomic via the transaction() API for mixed workloads.
+     * const txn = db.transaction(async () => {
+     *   await db.batch([{ sql: "INSERT INTO users(name) VALUES (?)", args: ["Eve"] }]);
+     *   await db.execute("UPDATE counters SET n = n + 1");
+     * });
+     * await txn.immediate();
      */
-    batch(statements: string[], mode?: string, queryOptions?: QueryOptions): Promise<any>;
+    batch(statements: BatchStatement[], mode?: BatchMode, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a pragma.
      *
@@ -527,4 +590,4 @@ declare class TimeoutError extends DatabaseError {
     constructor(message?: string, cause?: Error);
 }
 
-export { type Column, type Config, Connection, DatabaseError, ENCRYPTION_KEY_HEADER, type QueryOptions, Session, type SessionConfig, Statement, TimeoutError, connect };
+export { type BatchStatement, type Column, type Config, Connection, DatabaseError, ENCRYPTION_KEY_HEADER, type QueryOptions, Session, type SessionConfig, Statement, TimeoutError, connect };

package/dist/index.d.ts

@@ -39,6 +39,11 @@ interface QueryOptions {
     queryTimeout?: number;
 }
 
+/**
+ * Locking mode for atomic `batch()` execution. Accepts the same values
+ * as the variants of `Connection.transaction(...)`.
+ */
+type BatchMode = 'deferred' | 'immediate' | 'exclusive' | 'concurrent';
 /**
  * Configuration options for a session.
  */
@@ -112,10 +117,23 @@ declare class Session {
     /**
      * Execute multiple SQL statements in a batch.
      *
-     * @param statements - Array of SQL statements to execute
-     * @returns Promise resolving to batch execution results
+     * When `mode` is set, the batch is sent as a single Hrana request that
+     * also carries `BEGIN <mode>` / `COMMIT` / `ROLLBACK` steps using the
+     * server-side condition chain, giving atomic execution in one round-trip.
+     * When `mode` is omitted, the user statements are sent as-is and run
+     * under autocommit (or whatever transaction is already active on this
+     * stream).
+     *
+     * @param statements - Array of SQL statements to execute.
+     * @param mode - Optional locking mode; when set, the batch executes
+     *   atomically. Accepts the same values as `Database.transaction(...)`
+     *   variants: `"deferred"`, `"immediate"`, `"exclusive"`, `"concurrent"`.
+     * @returns Promise resolving to batch execution results.
      */
-    batch(statements: string[], queryOptions?: QueryOptions): Promise<any>;
+    batch(statements: Array<string | {
+        sql: string;
+        args?: any[] | Record<string, any>;
+    }>, mode?: BatchMode, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a sequence of SQL statements separated by semicolons.
      *
@@ -298,6 +316,10 @@ declare class Statement {
  */
 interface Config extends SessionConfig {
 }
+type BatchStatement = string | {
+    sql: string;
+    args?: any[] | Record<string, any>;
+};
 /**
  * A connection to a Turso database.
  *
@@ -418,22 +440,63 @@ declare class Connection {
      */
     exec(sql: string, queryOptions?: QueryOptions): Promise<any>;
     /**
-     * Execute multiple SQL statements in a batch.
+     * Executes a batch of SQL statements over this connection.
+     *
+     * By default, batch() is not transactional: each statement runs in its
+     * own autocommit step, so a failure mid-batch leaves earlier successful
+     * statements committed. Pass a `mode` to make the batch atomic — the
+     * statements are wrapped in `BEGIN <mode>` / `COMMIT` (with `ROLLBACK`
+     * on failure) and dispatched as a single Hrana request, so the whole
+     * batch completes in one round-trip. When called from inside a
+     * `connection.transaction(...)` callback the `mode` argument is ignored
+     * and the surrounding transaction is reused.
+     *
+     * When `mode` is set, `batch()` owns the surrounding
+     * `BEGIN`/`COMMIT`/`ROLLBACK`, so the `statements` array must not
+     * contain its own transaction-control SQL (`BEGIN`, `COMMIT`,
+     * `ROLLBACK`, `SAVEPOINT`, `RELEASE`). The input is not validated
+     * for that — a user-supplied `COMMIT` will close the wrapper
+     * transaction mid-batch and leave earlier statements committed,
+     * defeating the all-or-nothing contract.
+     *
+     * @param statements - An array of SQL strings or `{ sql, args }` objects.
+     * @param mode - When set, makes the batch atomic. Accepts the same
+     *   values as `connection.transaction(...)` variants: `"deferred"`,
+     *   `"immediate"`, `"exclusive"`, `"concurrent"`. Ignored when already
+     *   inside a transaction.
+     * @returns An object with `rowsAffected` (sum of affected rows) and
+     *   `lastInsertRowid` (rowid of the last successful insert).
      *
-     * @param statements - Array of SQL statements to execute
-     * @param mode - Optional transaction mode (currently unused)
-     * @returns Promise resolving to batch execution results
+     * @example
+     * // Plain SQL strings (non-atomic).
+     * await db.batch([
+     *   "INSERT INTO users(name) VALUES ('Alice')",
+     *   "INSERT INTO users(name) VALUES ('Bob')",
+     * ]);
      *
      * @example
-     * ```typescript
-     * await client.batch([
-     *   "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
-     *   "INSERT INTO users (name) VALUES ('Alice')",
-     *   "INSERT INTO users (name) VALUES ('Bob')"
+     * // Positional and named bind parameters.
+     * await db.batch([
+     *   { sql: "INSERT INTO users(name, email) VALUES (?, ?)", args: ["Carol", "carol@example.net"] },
+     *   { sql: "INSERT INTO users(name, email) VALUES (:name, :email)", args: { name: "Dave", email: "dave@example.net" } },
      * ]);
-     * ```
+     *
+     * @example
+     * // Atomic via the mode parameter.
+     * await db.batch([
+     *   { sql: "INSERT INTO users(name) VALUES (?)", args: ["Eve"] },
+     *   { sql: "INSERT INTO users(name) VALUES (?)", args: ["Frank"] },
+     * ], "immediate");
+     *
+     * @example
+     * // Atomic via the transaction() API for mixed workloads.
+     * const txn = db.transaction(async () => {
+     *   await db.batch([{ sql: "INSERT INTO users(name) VALUES (?)", args: ["Eve"] }]);
+     *   await db.execute("UPDATE counters SET n = n + 1");
+     * });
+     * await txn.immediate();
      */
-    batch(statements: string[], mode?: string, queryOptions?: QueryOptions): Promise<any>;
+    batch(statements: BatchStatement[], mode?: BatchMode, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a pragma.
      *
@@ -527,4 +590,4 @@ declare class TimeoutError extends DatabaseError {
     constructor(message?: string, cause?: Error);
 }
 
-export { type Column, type Config, Connection, DatabaseError, ENCRYPTION_KEY_HEADER, type QueryOptions, Session, type SessionConfig, Statement, TimeoutError, connect };
+export { type BatchStatement, type Column, type Config, Connection, DatabaseError, ENCRYPTION_KEY_HEADER, type QueryOptions, Session, type SessionConfig, Statement, TimeoutError, connect };