@tursodatabase/serverless 1.1.1 → 1.1.2-pre.1

package/dist/index.js

@@ -1,6 +1,1056 @@
-// Turso serverless driver entry point
-export { Connection, connect } from './connection.js';
-export { Statement } from './statement.js';
-export { Session } from './session.js';
-export { DatabaseError, TimeoutError } from './error.js';
-export { ENCRYPTION_KEY_HEADER } from './protocol.js';
+// src/async-lock.ts
+var AsyncLock = class {
+  constructor() {
+    this.locked = false;
+    this.queue = [];
+  }
+  async acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return;
+    }
+    return new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+  release() {
+    const next = this.queue.shift();
+    if (next) {
+      next();
+    } else {
+      this.locked = false;
+    }
+  }
+};
+
+// src/error.ts
+var DatabaseError = class _DatabaseError extends Error {
+  constructor(message, code, rawCode, cause) {
+    super(message);
+    this.name = "DatabaseError";
+    this.code = code;
+    this.rawCode = rawCode;
+    this.cause = cause;
+    Object.setPrototypeOf(this, _DatabaseError.prototype);
+  }
+};
+var TimeoutError = class _TimeoutError extends DatabaseError {
+  constructor(message = "Query timed out", cause) {
+    super(message, "TIMEOUT", void 0, cause);
+    this.name = "TimeoutError";
+    Object.setPrototypeOf(this, _TimeoutError.prototype);
+  }
+};
+
+// src/protocol.ts
+function encodeValue(value) {
+  if (value === null || value === void 0) {
+    return { type: "null" };
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("Only finite numbers (not Infinity or NaN) can be passed as arguments");
+    }
+    if (Number.isInteger(value)) {
+      return { type: "integer", value: value.toString() };
+    }
+    return { type: "float", value };
+  }
+  if (typeof value === "bigint") {
+    return { type: "integer", value: value.toString() };
+  }
+  if (typeof value === "boolean") {
+    return { type: "integer", value: value ? "1" : "0" };
+  }
+  if (typeof value === "string") {
+    return { type: "text", value };
+  }
+  if (value instanceof ArrayBuffer || value instanceof Uint8Array) {
+    const base64 = btoa(String.fromCharCode(...new Uint8Array(value)));
+    return { type: "blob", base64 };
+  }
+  return { type: "text", value: String(value) };
+}
+function decodeValue(value, safeIntegers = false) {
+  switch (value.type) {
+    case "null":
+      return null;
+    case "integer":
+      if (safeIntegers) {
+        return BigInt(value.value);
+      }
+      return parseInt(value.value, 10);
+    case "float":
+      return value.value;
+    case "text":
+      return value.value;
+    case "blob":
+      if (value.base64 !== void 0 && value.base64 !== null) {
+        let b64 = value.base64;
+        while (b64.length % 4 !== 0) {
+          b64 += "=";
+        }
+        const binaryString = atob(b64);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+          bytes[i] = binaryString.charCodeAt(i);
+        }
+        return Buffer.from(bytes);
+      }
+      return Buffer.alloc(0);
+    default:
+      return null;
+  }
+}
+var ENCRYPTION_KEY_HEADER = "x-turso-encryption-key";
+function wrapAbortError(error) {
+  if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) {
+    throw new TimeoutError("Query timed out");
+  }
+  throw error;
+}
+async function executeCursor(url, authToken, request, remoteEncryptionKey, signal) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (authToken) {
+    headers["Authorization"] = `Bearer ${authToken}`;
+  }
+  if (remoteEncryptionKey) {
+    headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
+  }
+  let response;
+  try {
+    response = await fetch(`${url}/v3/cursor`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request),
+      signal
+    });
+  } catch (error) {
+    wrapAbortError(error);
+  }
+  if (!response.ok) {
+    let errorMessage = `HTTP error! status: ${response.status}`;
+    try {
+      const errorBody = await response.text();
+      const errorData = JSON.parse(errorBody);
+      if (errorData.message) {
+        errorMessage = errorData.message;
+      }
+    } catch {
+    }
+    throw new DatabaseError(errorMessage);
+  }
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new DatabaseError("No response body");
+  }
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let cursorResponse;
+  try {
+    while (!cursorResponse) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex !== -1) {
+        const line = buffer.slice(0, newlineIndex).trim();
+        buffer = buffer.slice(newlineIndex + 1);
+        if (line) {
+          cursorResponse = JSON.parse(line);
+          break;
+        }
+      }
+    }
+  } catch (error) {
+    reader.releaseLock();
+    wrapAbortError(error);
+  }
+  if (!cursorResponse) {
+    reader.releaseLock();
+    throw new DatabaseError("No cursor response received");
+  }
+  async function* parseEntries() {
+    try {
+      let newlineIndex;
+      while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newlineIndex).trim();
+        buffer = buffer.slice(newlineIndex + 1);
+        if (line) {
+          yield JSON.parse(line);
+        }
+      }
+      while (true) {
+        let readResult;
+        try {
+          readResult = await reader.read();
+        } catch (error) {
+          wrapAbortError(error);
+        }
+        if (readResult.done) break;
+        buffer += decoder.decode(readResult.value, { stream: true });
+        while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+          const line = buffer.slice(0, newlineIndex).trim();
+          buffer = buffer.slice(newlineIndex + 1);
+          if (line) {
+            yield JSON.parse(line);
+          }
+        }
+      }
+      if (buffer.trim()) {
+        yield JSON.parse(buffer.trim());
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  return { response: cursorResponse, entries: parseEntries() };
+}
+async function executePipeline(url, authToken, request, remoteEncryptionKey, signal) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (authToken) {
+    headers["Authorization"] = `Bearer ${authToken}`;
+  }
+  if (remoteEncryptionKey) {
+    headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
+  }
+  let response;
+  try {
+    response = await fetch(`${url}/v3/pipeline`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request),
+      signal
+    });
+  } catch (error) {
+    wrapAbortError(error);
+  }
+  if (!response.ok) {
+    throw new DatabaseError(`HTTP error! status: ${response.status}`);
+  }
+  return response.json();
+}
+
+// src/session.ts
+function normalizeUrl(url) {
+  return url.replace(/^libsql:\/\//, "https://");
+}
+function isValidIdentifier(str) {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(str);
+}
+var Session = class {
+  constructor(config) {
+    this.baton = null;
+    this.config = config;
+    this.baseUrl = normalizeUrl(config.url);
+  }
+  createAbortSignal(queryOptions) {
+    const timeout = queryOptions?.queryTimeout ?? this.config.defaultQueryTimeout;
+    if (timeout != null && timeout > 0) {
+      return AbortSignal.timeout(timeout);
+    }
+    return void 0;
+  }
+  /**
+   * Describe a SQL statement to get its column metadata.
+   * 
+   * @param sql - The SQL statement to describe
+   * @returns Promise resolving to the statement description
+   */
+  async describe(sql, queryOptions) {
+    const request = {
+      baton: this.baton,
+      requests: [{
+        type: "describe",
+        sql
+      }]
+    };
+    let response;
+    try {
+      response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
+    } catch (e) {
+      this.baton = null;
+      throw e;
+    }
+    this.baton = response.baton;
+    if (response.base_url) {
+      this.baseUrl = response.base_url;
+    }
+    if (response.results && response.results[0]) {
+      const result = response.results[0];
+      if (result.type === "error") {
+        throw new DatabaseError(result.error?.message || "Describe execution failed", result.error?.code);
+      }
+      if (result.response?.type === "describe" && result.response.result) {
+        return result.response.result;
+      }
+    }
+    throw new DatabaseError("Unexpected describe response");
+  }
+  /**
+   * Execute a SQL statement and return all results.
+   * 
+   * @param sql - The SQL statement to execute
+   * @param args - Optional array of parameter values or object with named parameters
+   * @param safeIntegers - Whether to return integers as BigInt
+   * @returns Promise resolving to the complete result set
+   */
+  async execute(sql, args = [], safeIntegers = false, queryOptions) {
+    const { response, entries } = await this.executeRaw(sql, args, queryOptions);
+    const result = await this.processCursorEntries(entries, safeIntegers);
+    return result;
+  }
+  /**
+   * Execute a SQL statement and return the raw response and entries.
+   * 
+   * @param sql - The SQL statement to execute
+   * @param args - Optional array of parameter values or object with named parameters
+   * @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 request = {
+      baton: this.baton,
+      batch: {
+        steps: [{
+          stmt: {
+            sql,
+            args: positionalArgs,
+            named_args: namedArgs,
+            want_rows: true
+          }
+        }]
+      }
+    };
+    let result;
+    try {
+      result = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
+    } catch (e) {
+      this.baton = null;
+      throw e;
+    }
+    const { response, entries } = result;
+    this.baton = response.baton;
+    if (response.base_url) {
+      this.baseUrl = response.base_url;
+    }
+    return { response, entries };
+  }
+  /**
+   * Process cursor entries into a structured result.
+   *
+   * @param entries - Async generator of cursor entries
+   * @returns Promise resolving to the processed result
+   */
+  async processCursorEntries(entries, safeIntegers = false) {
+    let columns = [];
+    let columnTypes = [];
+    let rows = [];
+    let rowsAffected = 0;
+    let lastInsertRowid;
+    for await (const entry of entries) {
+      switch (entry.type) {
+        case "step_begin":
+          if (entry.cols) {
+            columns = entry.cols.map((col) => col.name);
+            columnTypes = entry.cols.map((col) => col.decltype || "");
+          }
+          break;
+        case "row":
+          if (entry.row) {
+            const decodedRow = entry.row.map((value) => decodeValue(value, safeIntegers));
+            const rowObject = this.createRowObject(decodedRow, columns);
+            rows.push(rowObject);
+          }
+          break;
+        case "step_end":
+          if (entry.affected_row_count !== void 0) {
+            rowsAffected = 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);
+          }
+          break;
+        case "step_error":
+        case "error":
+          throw new DatabaseError(entry.error?.message || "SQL execution failed", entry.error?.code);
+      }
+    }
+    return {
+      columns,
+      columnTypes,
+      rows,
+      rowsAffected,
+      lastInsertRowid
+    };
+  }
+  /**
+   * Create a row object with both array and named property access.
+   * 
+   * @param values - Array of column values
+   * @param columns - Array of column names
+   * @returns Row object with dual access patterns
+   */
+  createRowObject(values, columns) {
+    const row = [...values];
+    columns.forEach((column, index) => {
+      if (column && isValidIdentifier(column)) {
+        Object.defineProperty(row, column, {
+          value: values[index],
+          enumerable: false,
+          writable: false,
+          configurable: true
+        });
+      }
+    });
+    return row;
+  }
+  /**
+   * Execute multiple SQL statements in a batch.
+   * 
+   * @param statements - Array of SQL statements to execute
+   * @returns Promise resolving to batch execution results
+   */
+  async batch(statements, queryOptions) {
+    const request = {
+      baton: this.baton,
+      batch: {
+        steps: statements.map((sql) => ({
+          stmt: {
+            sql,
+            args: [],
+            named_args: [],
+            want_rows: false
+          }
+        }))
+      }
+    };
+    let batchResult;
+    try {
+      batchResult = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
+    } catch (e) {
+      this.baton = null;
+      throw e;
+    }
+    const { response, entries } = batchResult;
+    this.baton = response.baton;
+    if (response.base_url) {
+      this.baseUrl = response.base_url;
+    }
+    let totalRowsAffected = 0;
+    let lastInsertRowid;
+    for await (const entry of entries) {
+      switch (entry.type) {
+        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);
+          }
+          break;
+        case "step_error":
+        case "error":
+          throw new DatabaseError(entry.error?.message || "Batch execution failed", entry.error?.code);
+      }
+    }
+    return {
+      rowsAffected: totalRowsAffected,
+      lastInsertRowid
+    };
+  }
+  /**
+   * Execute a sequence of SQL statements separated by semicolons.
+   * 
+   * @param sql - SQL string containing multiple statements separated by semicolons
+   * @returns Promise resolving when all statements are executed
+   */
+  async sequence(sql, queryOptions) {
+    const request = {
+      baton: this.baton,
+      requests: [{
+        type: "sequence",
+        sql
+      }]
+    };
+    let seqResponse;
+    try {
+      seqResponse = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
+    } catch (e) {
+      this.baton = null;
+      throw e;
+    }
+    this.baton = seqResponse.baton;
+    if (seqResponse.base_url) {
+      this.baseUrl = seqResponse.base_url;
+    }
+    if (seqResponse.results && seqResponse.results[0]) {
+      const result = seqResponse.results[0];
+      if (result.type === "error") {
+        throw new DatabaseError(result.error?.message || "Sequence execution failed", result.error?.code);
+      }
+    }
+  }
+  /**
+   * Close the session.
+   *
+   * This sends a close request to the server to properly clean up the stream
+   * before resetting the local state.
+   */
+  async close() {
+    if (this.baton) {
+      try {
+        const request = {
+          baton: this.baton,
+          requests: [{
+            type: "close"
+          }]
+        };
+        await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+      } catch {
+      }
+    }
+    this.baton = null;
+    this.baseUrl = "";
+  }
+};
+
+// src/statement.ts
+var Statement = class _Statement {
+  constructor(sessionConfig, sql, columns) {
+    this.presentationMode = "expanded";
+    this.safeIntegerMode = false;
+    this.session = new Session(sessionConfig);
+    this.sql = sql;
+    this.columnMetadata = columns || [];
+  }
+  /**
+   * Create a Statement that shares an existing session and serializes execution
+   * through the given lock. Used by Connection.prepare() so prepared statements
+   * participate in the connection's transaction scope.
+   */
+  static fromSession(session, sql, columns, execLock) {
+    const stmt = Object.create(_Statement.prototype);
+    stmt.session = session;
+    stmt.sql = sql;
+    stmt.columnMetadata = columns || [];
+    stmt.presentationMode = "expanded";
+    stmt.safeIntegerMode = false;
+    stmt.execLock = execLock;
+    return stmt;
+  }
+  /**
+   * Whether the prepared statement returns data.
+   *
+   * This is `true` for SELECT queries and statements with RETURNING clause,
+   * and `false` for INSERT, UPDATE, DELETE statements without RETURNING.
+   *
+   * @example
+   * ```typescript
+   * const stmt = await conn.prepare(sql);
+   * if (stmt.reader) {
+   *   return stmt.all(args);  // SELECT-like query
+   * } else {
+   *   return stmt.run(args);  // INSERT/UPDATE/DELETE
+   * }
+   * ```
+   */
+  get reader() {
+    return this.columnMetadata.length > 0;
+  }
+  /**
+   * Enable raw mode to return arrays instead of objects.
+   * 
+   * @param raw Enable or disable raw mode. If you don't pass the parameter, raw mode is enabled.
+   * @returns This statement instance for chaining
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+   * const row = await stmt.raw().get([1]);
+   * console.log(row); // [1, "Alice", "alice@example.org"]
+   * ```
+   */
+  raw(raw) {
+    this.presentationMode = raw === false ? "expanded" : "raw";
+    return this;
+  }
+  /**
+   * Enable pluck mode to return only the first column value from each row.
+   * 
+   * @param pluck Enable or disable pluck mode. If you don't pass the parameter, pluck mode is enabled.
+   * @returns This statement instance for chaining
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("SELECT id FROM users");
+   * const ids = await stmt.pluck().all();
+   * console.log(ids); // [1, 2, 3, ...]
+   * ```
+   */
+  pluck(pluck) {
+    this.presentationMode = pluck === false ? "expanded" : "pluck";
+    return this;
+  }
+  /**
+   * Sets safe integers mode for this statement.
+   * 
+   * @param toggle Whether to use safe integers. If you don't pass the parameter, safe integers mode is enabled.
+   * @returns This statement instance for chaining
+   */
+  safeIntegers(toggle) {
+    this.safeIntegerMode = toggle === false ? false : true;
+    return this;
+  }
+  /**
+   * Get column information for this statement.
+   * 
+   * @returns Array of column metadata objects matching the native bindings format
+   * 
+   * @example
+   * ```typescript
+   * const stmt = await client.prepare("SELECT id, name, email FROM users");
+   * const columns = stmt.columns();
+   * console.log(columns); // [{ name: 'id', type: 'INTEGER', column: null, database: null, table: null }, ...]
+   * ```
+   */
+  columns() {
+    return this.columnMetadata.map((col) => ({
+      name: col.name,
+      type: col.decltype
+    }));
+  }
+  async withLock(fn) {
+    if (!this.execLock) {
+      return await fn();
+    }
+    await this.execLock.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.execLock.release();
+    }
+  }
+  /**
+   * Executes the prepared statement.
+   * 
+   * @param args - Optional array of parameter values or object with named parameters
+   * @returns Promise resolving to the result of the statement
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("INSERT INTO users (name, email) VALUES (?, ?)");
+   * const result = await stmt.run(['John Doe', 'john.doe@example.com']);
+   * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
+   * ```
+   */
+  async run(args, queryOptions) {
+    return await this.withLock(async () => {
+      const normalizedArgs = this.normalizeArgs(args);
+      const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
+      return { changes: result.rowsAffected, lastInsertRowid: result.lastInsertRowid };
+    });
+  }
+  /**
+   * Execute the statement and return the first row.
+   * 
+   * @param args - Optional array of parameter values or object with named parameters
+   * @returns Promise resolving to the first row or undefined if no results
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+   * const user = await stmt.get([123]);
+   * if (user) {
+   *   console.log(user.name);
+   * }
+   * ```
+   */
+  async get(args, queryOptions) {
+    return await this.withLock(async () => {
+      const normalizedArgs = this.normalizeArgs(args);
+      const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
+      const row = result.rows[0];
+      if (!row) {
+        return void 0;
+      }
+      if (this.presentationMode === "pluck") {
+        return row[0];
+      }
+      if (this.presentationMode === "raw") {
+        return [...row];
+      }
+      const obj = {};
+      result.columns.forEach((col, i) => {
+        obj[col] = row[i];
+      });
+      return obj;
+    });
+  }
+  /**
+   * Execute the statement and return all rows.
+   * 
+   * @param args - Optional array of parameter values or object with named parameters
+   * @returns Promise resolving to an array of all result rows
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("SELECT * FROM users WHERE active = ?");
+   * const activeUsers = await stmt.all([true]);
+   * console.log(`Found ${activeUsers.length} active users`);
+   * ```
+   */
+  async all(args, queryOptions) {
+    return await this.withLock(async () => {
+      const normalizedArgs = this.normalizeArgs(args);
+      const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
+      if (this.presentationMode === "pluck") {
+        return result.rows.map((row) => row[0]);
+      }
+      if (this.presentationMode === "raw") {
+        return result.rows.map((row) => [...row]);
+      }
+      return result.rows.map((row) => {
+        const obj = {};
+        result.columns.forEach((col, i) => {
+          obj[col] = row[i];
+        });
+        return obj;
+      });
+    });
+  }
+  /**
+   * Execute the statement and return an async iterator for streaming results.
+   * 
+   * This method provides memory-efficient processing of large result sets
+   * by streaming rows one at a time instead of loading everything into memory.
+   * 
+   * @param args - Optional array of parameter values or object with named parameters
+   * @returns AsyncGenerator that yields individual rows
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("SELECT * FROM large_table WHERE category = ?");
+   * for await (const row of stmt.iterate(['electronics'])) {
+   *   // Process each row individually
+   *   console.log(row.id, row.name);
+   * }
+   * ```
+   */
+  async *iterate(args, queryOptions) {
+    if (this.execLock) {
+      const rows = await this.all(args, queryOptions);
+      for (const row of rows) {
+        yield row;
+      }
+      return;
+    }
+    const normalizedArgs = this.normalizeArgs(args);
+    const { entries } = await this.session.executeRaw(this.sql, normalizedArgs, queryOptions);
+    let columns = [];
+    for await (const entry of entries) {
+      switch (entry.type) {
+        case "step_begin":
+          if (entry.cols) {
+            columns = entry.cols.map((col) => col.name);
+          }
+          break;
+        case "row":
+          if (entry.row) {
+            const decodedRow = entry.row.map((value) => decodeValue(value, this.safeIntegerMode));
+            if (this.presentationMode === "pluck") {
+              yield decodedRow[0];
+            } else if (this.presentationMode === "raw") {
+              yield decodedRow;
+            } else {
+              const obj = {};
+              columns.forEach((col, i) => {
+                obj[col] = decodedRow[i];
+              });
+              yield obj;
+            }
+          }
+          break;
+        case "step_error":
+        case "error":
+          throw new DatabaseError(entry.error?.message || "SQL execution failed");
+      }
+    }
+  }
+  /**
+   * Normalize arguments to handle both single values and arrays.
+   * Matches the behavior of the native bindings.
+   */
+  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];
+  }
+};
+
+// src/connection.ts
+var Connection = class {
+  constructor(config) {
+    this.isOpen = true;
+    this.defaultSafeIntegerMode = false;
+    this._inTransaction = false;
+    this.execLock = new AsyncLock();
+    if (!config.url) {
+      throw new Error("invalid config: url is required");
+    }
+    this.config = config;
+    this.session = new Session(config);
+    Object.defineProperty(this, "inTransaction", {
+      get: () => this._inTransaction,
+      enumerable: true
+    });
+  }
+  /**
+   * Whether the database is currently in a transaction.
+   */
+  get inTransaction() {
+    return this._inTransaction;
+  }
+  /**
+   * Prepare a SQL statement for execution.
+   * 
+   * Prepared statements created from a Connection use the same underlying session so transaction boundaries are preserved.
+   * This method fetches column metadata using the describe functionality.
+   * 
+   * @param sql - The SQL statement to prepare
+   * @returns A Promise that resolves to a Statement object with column metadata
+   * 
+   * @example
+   * ```typescript
+   * const stmt = await client.prepare("SELECT * FROM users WHERE id = ?");
+   * const columns = stmt.columns();
+   * const user = await stmt.get([123]);
+   * ```
+   */
+  async prepare(sql) {
+    if (!this.isOpen) {
+      throw new TypeError("The database connection is not open");
+    }
+    const session = new Session(this.config);
+    const description = await session.describe(sql);
+    await session.close();
+    const stmt = Statement.fromSession(this.session, sql, description.cols, this.execLock);
+    if (this.defaultSafeIntegerMode) {
+      stmt.safeIntegers(true);
+    }
+    return stmt;
+  }
+  /**
+   * Execute a SQL statement and return all results.
+   * 
+   * @param sql - The SQL statement to execute
+   * @param args - Optional array of parameter values
+   * @returns Promise resolving to the complete result set
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.execute("SELECT * FROM users WHERE id = ?", [123]);
+   * console.log(result.rows);
+   * ```
+   */
+  async execute(sql, args, queryOptions) {
+    if (!this.isOpen) {
+      throw new TypeError("The database connection is not open");
+    }
+    await this.execLock.acquire();
+    try {
+      return await this.session.execute(sql, args || [], this.defaultSafeIntegerMode, queryOptions);
+    } finally {
+      this.execLock.release();
+    }
+  }
+  /**
+   * Execute a SQL statement and return all results.
+   * 
+   * @param sql - The SQL statement to execute
+   * @returns Promise resolving to the complete result set
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.exec("SELECT * FROM users");
+   * console.log(result.rows);
+   * ```
+   */
+  async exec(sql, queryOptions) {
+    if (!this.isOpen) {
+      throw new TypeError("The database connection is not open");
+    }
+    await this.execLock.acquire();
+    try {
+      return await this.session.sequence(sql, queryOptions);
+    } finally {
+      this.execLock.release();
+    }
+  }
+  /**
+   * 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
+   * 
+   * @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')"
+   * ]);
+   * ```
+   */
+  async batch(statements, mode, queryOptions) {
+    if (!this.isOpen) {
+      throw new TypeError("The database connection is not open");
+    }
+    await this.execLock.acquire();
+    try {
+      return await this.session.batch(statements, queryOptions);
+    } finally {
+      this.execLock.release();
+    }
+  }
+  /**
+   * Execute a pragma.
+   * 
+   * @param pragma - The pragma to execute
+   * @returns Promise resolving to the result of the pragma
+   */
+  async pragma(pragma, queryOptions) {
+    if (!this.isOpen) {
+      throw new TypeError("The database connection is not open");
+    }
+    await this.execLock.acquire();
+    try {
+      const sql = `PRAGMA ${pragma}`;
+      return await this.session.execute(sql, [], false, queryOptions);
+    } finally {
+      this.execLock.release();
+    }
+  }
+  /**
+   * Sets the default safe integers mode for all statements from this connection.
+   * 
+   * @param toggle - Whether to use safe integers by default.
+   */
+  defaultSafeIntegers(toggle) {
+    this.defaultSafeIntegerMode = toggle === false ? false : true;
+  }
+  /**
+   * Returns a function that executes the given function in a transaction.
+   * 
+   * @param fn - The function to wrap in a transaction
+   * @returns A function that will execute fn within a transaction
+   * 
+   * @example
+   * ```typescript
+   * const insert = await client.prepare("INSERT INTO users (name) VALUES (?)");
+   * const insertMany = client.transaction((users) => {
+   *   for (const user of users) {
+   *     insert.run([user]);
+   *   }
+   * });
+   * 
+   * await insertMany(['Alice', 'Bob', 'Charlie']);
+   * ```
+   */
+  transaction(fn) {
+    if (typeof fn !== "function") {
+      throw new TypeError("Expected first argument to be a function");
+    }
+    const db = this;
+    const wrapTxn = (mode) => {
+      return async (...bindParameters) => {
+        await db.exec("BEGIN " + mode);
+        db._inTransaction = true;
+        try {
+          const result = await fn(...bindParameters);
+          await db.exec("COMMIT");
+          db._inTransaction = false;
+          return result;
+        } catch (err) {
+          await db.exec("ROLLBACK");
+          db._inTransaction = false;
+          throw err;
+        }
+      };
+    };
+    const properties = {
+      default: { value: wrapTxn("") },
+      deferred: { value: wrapTxn("DEFERRED") },
+      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.immediate.value, properties);
+    Object.defineProperties(properties.exclusive.value, properties);
+    return properties.default.value;
+  }
+  /**
+   * Close the connection.
+   * 
+   * This sends a close request to the server to properly clean up the stream.
+   */
+  async close() {
+    this.isOpen = false;
+    await this.session.close();
+  }
+  async reconnect() {
+    try {
+      if (this.isOpen) {
+        await this.close();
+      }
+    } finally {
+      this.session = new Session(this.config);
+      this.isOpen = true;
+    }
+  }
+};
+function connect(config) {
+  return new Connection(config);
+}
+
+export { Connection, DatabaseError, ENCRYPTION_KEY_HEADER, Session, Statement, TimeoutError, connect };