@tursodatabase/serverless 0.2.1 → 0.2.3

package/dist/async-lock.d.ts

@@ -0,0 +1,6 @@
+export declare class AsyncLock {
+    private locked;
+    private queue;
+    acquire(): Promise<void>;
+    release(): void;
+}

package/dist/async-lock.js

@@ -0,0 +1,22 @@
+export class AsyncLock {
+    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;
+        }
+    }
+}

package/dist/compat.d.ts

@@ -76,11 +76,15 @@ export interface ResultSet {
  * libSQL-compatible error class with error codes.
  */
 export declare class LibsqlError extends Error {
-    /** Machine-readable error code */
+    /** Machine-readable error code (e.g., "SQLITE_CONSTRAINT") */
     code: string;
+    /** Extended error code with more specific information (e.g., "SQLITE_CONSTRAINT_PRIMARYKEY") */
+    extendedCode?: string;
     /** Raw numeric error code (if available) */
     rawCode?: number;
-    constructor(message: string, code: string, rawCode?: number);
+    /** Original error that caused this error */
+    cause?: Error;
+    constructor(message: string, code: string, extendedCode?: string, rawCode?: number, cause?: Error);
 }
 /**
  * Interactive transaction interface (not implemented in serverless mode).

package/dist/compat.js

@@ -1,13 +1,16 @@
 import { Session } from './session.js';
+import { DatabaseError } from './error.js';
 /**
  * libSQL-compatible error class with error codes.
  */
 export class LibsqlError extends Error {
-    constructor(message, code, rawCode) {
+    constructor(message, code, extendedCode, rawCode, cause) {
         super(message);
         this.name = 'LibsqlError';
         this.code = code;
+        this.extendedCode = extendedCode;
         this.rawCode = rawCode;
+        this.cause = cause;
     }
 }
 class LibSQLClient {
@@ -114,7 +117,10 @@ class LibSQLClient {
             return this.convertResult(result);
         }
         catch (error) {
-            throw new LibsqlError(error.message, "EXECUTE_ERROR");
+            if (error instanceof LibsqlError) {
+                throw error;
+            }
+            throw mapDatabaseError(error, "EXECUTE_ERROR");
         }
     }
     async batch(stmts, mode) {
@@ -131,7 +137,10 @@ class LibSQLClient {
             return [this.convertResult(result)];
         }
         catch (error) {
-            throw new LibsqlError(error.message, "BATCH_ERROR");
+            if (error instanceof LibsqlError) {
+                throw error;
+            }
+            throw mapDatabaseError(error, "BATCH_ERROR");
         }
     }
     async migrate(stmts) {
@@ -149,7 +158,10 @@ class LibSQLClient {
             await this.session.sequence(sql);
         }
         catch (error) {
-            throw new LibsqlError(error.message, "EXECUTE_MULTIPLE_ERROR");
+            if (error instanceof LibsqlError) {
+                throw error;
+            }
+            throw mapDatabaseError(error, "EXECUTE_MULTIPLE_ERROR");
         }
     }
     async sync() {
@@ -190,3 +202,63 @@ class LibSQLClient {
 export function createClient(config) {
     return new LibSQLClient(config);
 }
+// Known SQLite base error code names, used to split extended codes like
+// "SQLITE_CONSTRAINT_PRIMARYKEY" into base ("SQLITE_CONSTRAINT") and extended.
+const sqliteBaseErrorCodes = new Set([
+    "SQLITE_ERROR",
+    "SQLITE_INTERNAL",
+    "SQLITE_PERM",
+    "SQLITE_ABORT",
+    "SQLITE_BUSY",
+    "SQLITE_LOCKED",
+    "SQLITE_NOMEM",
+    "SQLITE_READONLY",
+    "SQLITE_INTERRUPT",
+    "SQLITE_IOERR",
+    "SQLITE_CORRUPT",
+    "SQLITE_NOTFOUND",
+    "SQLITE_FULL",
+    "SQLITE_CANTOPEN",
+    "SQLITE_PROTOCOL",
+    "SQLITE_EMPTY",
+    "SQLITE_SCHEMA",
+    "SQLITE_TOOBIG",
+    "SQLITE_CONSTRAINT",
+    "SQLITE_MISMATCH",
+    "SQLITE_MISUSE",
+    "SQLITE_NOLFS",
+    "SQLITE_AUTH",
+    "SQLITE_FORMAT",
+    "SQLITE_RANGE",
+    "SQLITE_NOTADB",
+    "SQLITE_NOTICE",
+    "SQLITE_WARNING",
+]);
+/**
+ * Parse a protocol error code into base and extended codes.
+ *
+ * The server may send either a base code ("SQLITE_CONSTRAINT") or an extended
+ * code ("SQLITE_CONSTRAINT_PRIMARYKEY"). This function splits them so that
+ * `code` is always the base code and `extendedCode` carries the full detail.
+ */
+function parseErrorCode(serverCode) {
+    if (sqliteBaseErrorCodes.has(serverCode)) {
+        return { code: serverCode };
+    }
+    // Try to find a base code prefix (e.g. "SQLITE_CONSTRAINT" in "SQLITE_CONSTRAINT_PRIMARYKEY")
+    for (const base of sqliteBaseErrorCodes) {
+        if (serverCode.startsWith(base + "_")) {
+            return { code: base, extendedCode: serverCode };
+        }
+    }
+    // Unknown code — return as-is
+    return { code: serverCode };
+}
+function mapDatabaseError(error, fallbackCode) {
+    if (error instanceof DatabaseError && error.code) {
+        const { code, extendedCode } = parseErrorCode(error.code);
+        return new LibsqlError(error.message, code, extendedCode, error.rawCode, error);
+    }
+    const cause = error instanceof Error ? error : undefined;
+    return new LibsqlError(error.message ?? String(error), fallbackCode, undefined, undefined, cause);
+}

package/dist/connection.d.ts

@@ -9,7 +9,45 @@ export interface Config extends SessionConfig {
  * A connection to a Turso database.
  *
  * Provides methods for executing SQL statements and managing prepared statements.
- * Uses the SQL over HTTP protocol with streaming cursor support for optimal performance.
+ * Uses the SQL over HTTP protocol with streaming cursor support.
+ *
+ * ## Concurrency model
+ *
+ * A Connection is **single-stream**: it can only run one statement at a time.
+ * This is not an implementation quirk — it follows from the SQL over HTTP protocol,
+ * where each request carries a baton from the previous response to sequence operations
+ * on the server. Concurrent calls on the same connection would race on that baton
+ * and corrupt the stream. This is the same model as SQLite itself (one execution
+ * at a time per connection).
+ *
+ * If you call `execute()` while another is in flight, the call automatically
+ * waits for the previous one to finish — just like the native
+ * `@tursodatabase/database` binding.
+ *
+ * ## Parallel queries
+ *
+ * For parallelism, create multiple connections. `connect()` is cheap — it just
+ * allocates a config object. No TCP connection is opened until the first `execute()`,
+ * and the underlying `fetch()` runtime automatically pools and reuses TCP/TLS
+ * connections to the same origin.
+ *
+ * ```typescript
+ * import { connect } from "@tursodatabase/serverless";
+ *
+ * const config = { url: process.env.TURSO_URL, authToken: process.env.TURSO_TOKEN };
+ *
+ * // Option 1: one connection per parallel query
+ * const [users, orders] = await Promise.all([
+ *   connect(config).execute("SELECT * FROM users WHERE active = 1"),
+ *   connect(config).execute("SELECT * FROM orders WHERE status = 'pending'"),
+ * ]);
+ *
+ * // Option 2: reusable pool for repeated parallel work
+ * const pool = Array.from({ length: 4 }, () => connect(config));
+ * const results = await Promise.all(
+ *   queries.map((sql, i) => pool[i % pool.length].execute(sql))
+ * );
+ * ```
  */
 export declare class Connection {
     private config;
@@ -17,6 +55,7 @@ export declare class Connection {
     private isOpen;
     private defaultSafeIntegerMode;
     private _inTransaction;
+    private execLock;
     constructor(config: Config);
     /**
      * Whether the database is currently in a transaction.
@@ -126,17 +165,32 @@ export declare class Connection {
 /**
  * Create a new connection to a Turso database.
  *
- * @param config - Configuration object with database URL and auth token
- * @returns A new Connection instance
+ * This is a lightweight operation — it only allocates a config object. No network
+ * I/O happens until the first query. The underlying `fetch()` implementation
+ * automatically pools TCP/TLS connections to the same origin, so creating many
+ * connections is cheap.
+ *
+ * Each connection is single-stream: concurrent calls on the same connection are
+ * automatically serialized. For true parallelism, create multiple connections:
  *
- * @example
  * ```typescript
  * import { connect } from "@tursodatabase/serverless";
  *
- * const client = connect({
- *   url: process.env.TURSO_DATABASE_URL,
- *   authToken: process.env.TURSO_AUTH_TOKEN
- * });
+ * const config = { url: process.env.TURSO_URL, authToken: process.env.TURSO_TOKEN };
+ *
+ * // Sequential (single connection is fine)
+ * const conn = connect(config);
+ * const a = await conn.execute("SELECT 1");
+ * const b = await conn.execute("SELECT 2");
+ *
+ * // Parallel (use separate connections)
+ * const [x, y] = await Promise.all([
+ *   connect(config).execute("SELECT 1"),
+ *   connect(config).execute("SELECT 2"),
+ * ]);
  * ```
+ *
+ * @param config - Configuration object with database URL and auth token
+ * @returns A new Connection instance
  */
 export declare function connect(config: Config): Connection;

package/dist/connection.js

@@ -1,16 +1,56 @@
+import { AsyncLock } from './async-lock.js';
 import { Session } from './session.js';
 import { Statement } from './statement.js';
 /**
  * A connection to a Turso database.
  *
  * Provides methods for executing SQL statements and managing prepared statements.
- * Uses the SQL over HTTP protocol with streaming cursor support for optimal performance.
+ * Uses the SQL over HTTP protocol with streaming cursor support.
+ *
+ * ## Concurrency model
+ *
+ * A Connection is **single-stream**: it can only run one statement at a time.
+ * This is not an implementation quirk — it follows from the SQL over HTTP protocol,
+ * where each request carries a baton from the previous response to sequence operations
+ * on the server. Concurrent calls on the same connection would race on that baton
+ * and corrupt the stream. This is the same model as SQLite itself (one execution
+ * at a time per connection).
+ *
+ * If you call `execute()` while another is in flight, the call automatically
+ * waits for the previous one to finish — just like the native
+ * `@tursodatabase/database` binding.
+ *
+ * ## Parallel queries
+ *
+ * For parallelism, create multiple connections. `connect()` is cheap — it just
+ * allocates a config object. No TCP connection is opened until the first `execute()`,
+ * and the underlying `fetch()` runtime automatically pools and reuses TCP/TLS
+ * connections to the same origin.
+ *
+ * ```typescript
+ * import { connect } from "@tursodatabase/serverless";
+ *
+ * const config = { url: process.env.TURSO_URL, authToken: process.env.TURSO_TOKEN };
+ *
+ * // Option 1: one connection per parallel query
+ * const [users, orders] = await Promise.all([
+ *   connect(config).execute("SELECT * FROM users WHERE active = 1"),
+ *   connect(config).execute("SELECT * FROM orders WHERE status = 'pending'"),
+ * ]);
+ *
+ * // Option 2: reusable pool for repeated parallel work
+ * const pool = Array.from({ length: 4 }, () => connect(config));
+ * const results = await Promise.all(
+ *   queries.map((sql, i) => pool[i % pool.length].execute(sql))
+ * );
+ * ```
  */
 export class Connection {
     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");
         }
@@ -75,7 +115,13 @@ export class Connection {
         if (!this.isOpen) {
             throw new TypeError("The database connection is not open");
         }
-        return this.session.execute(sql, args || [], this.defaultSafeIntegerMode);
+        await this.execLock.acquire();
+        try {
+            return await this.session.execute(sql, args || [], this.defaultSafeIntegerMode);
+        }
+        finally {
+            this.execLock.release();
+        }
     }
     /**
      * Execute a SQL statement and return all results.
@@ -93,7 +139,13 @@ export class Connection {
         if (!this.isOpen) {
             throw new TypeError("The database connection is not open");
         }
-        return this.session.sequence(sql);
+        await this.execLock.acquire();
+        try {
+            return await this.session.sequence(sql);
+        }
+        finally {
+            this.execLock.release();
+        }
     }
     /**
      * Execute multiple SQL statements in a batch.
@@ -112,7 +164,16 @@ export class Connection {
      * ```
      */
     async batch(statements, mode) {
-        return this.session.batch(statements);
+        if (!this.isOpen) {
+            throw new TypeError("The database connection is not open");
+        }
+        await this.execLock.acquire();
+        try {
+            return await this.session.batch(statements);
+        }
+        finally {
+            this.execLock.release();
+        }
     }
     /**
      * Execute a pragma.
@@ -124,8 +185,14 @@ export class Connection {
         if (!this.isOpen) {
             throw new TypeError("The database connection is not open");
         }
-        const sql = `PRAGMA ${pragma}`;
-        return this.session.execute(sql);
+        await this.execLock.acquire();
+        try {
+            const sql = `PRAGMA ${pragma}`;
+            return await this.session.execute(sql);
+        }
+        finally {
+            this.execLock.release();
+        }
     }
     /**
      * Sets the default safe integers mode for all statements from this connection.
@@ -212,18 +279,33 @@ export class Connection {
 /**
  * Create a new connection to a Turso database.
  *
- * @param config - Configuration object with database URL and auth token
- * @returns A new Connection instance
+ * This is a lightweight operation — it only allocates a config object. No network
+ * I/O happens until the first query. The underlying `fetch()` implementation
+ * automatically pools TCP/TLS connections to the same origin, so creating many
+ * connections is cheap.
+ *
+ * Each connection is single-stream: concurrent calls on the same connection are
+ * automatically serialized. For true parallelism, create multiple connections:
  *
- * @example
  * ```typescript
  * import { connect } from "@tursodatabase/serverless";
  *
- * const client = connect({
- *   url: process.env.TURSO_DATABASE_URL,
- *   authToken: process.env.TURSO_AUTH_TOKEN
- * });
+ * const config = { url: process.env.TURSO_URL, authToken: process.env.TURSO_TOKEN };
+ *
+ * // Sequential (single connection is fine)
+ * const conn = connect(config);
+ * const a = await conn.execute("SELECT 1");
+ * const b = await conn.execute("SELECT 2");
+ *
+ * // Parallel (use separate connections)
+ * const [x, y] = await Promise.all([
+ *   connect(config).execute("SELECT 1"),
+ *   connect(config).execute("SELECT 2"),
+ * ]);
  * ```
+ *
+ * @param config - Configuration object with database URL and auth token
+ * @returns A new Connection instance
  */
 export function connect(config) {
     return new Connection(config);

package/dist/error.d.ts

@@ -1,3 +1,9 @@
 export declare class DatabaseError extends Error {
-    constructor(message: string);
+    /** Machine-readable error code (e.g., "SQLITE_CONSTRAINT") */
+    code?: string;
+    /** Raw numeric error code */
+    rawCode?: number;
+    /** Original error that caused this error */
+    cause?: Error;
+    constructor(message: string, code?: string, rawCode?: number, cause?: Error);
 }

package/dist/error.js

@@ -1,7 +1,10 @@
 export class DatabaseError extends Error {
-    constructor(message) {
+    constructor(message, code, rawCode, cause) {
         super(message);
         this.name = 'DatabaseError';
+        this.code = code;
+        this.rawCode = rawCode;
+        this.cause = cause;
         Object.setPrototypeOf(this, DatabaseError.prototype);
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { Connection, connect, type Config } from './connection.js';
 export { Statement } from './statement.js';
+export { Session, type SessionConfig } from './session.js';
 export { DatabaseError } from './error.js';
 export { type Column, ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 // Turso serverless driver entry point
 export { Connection, connect } from './connection.js';
 export { Statement } from './statement.js';
+export { Session } from './session.js';
 export { DatabaseError } from './error.js';
 export { ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/session.js

@@ -41,7 +41,7 @@ export class Session {
         if (response.results && response.results[0]) {
             const result = response.results[0];
             if (result.type === "error") {
-                throw new DatabaseError(result.error?.message || 'Describe execution failed');
+                throw new DatabaseError(result.error?.message || 'Describe execution failed', result.error?.code);
             }
             if (result.response?.type === "describe" && result.response.result) {
                 return result.response.result;
@@ -162,7 +162,7 @@ export class Session {
                     break;
                 case 'step_error':
                 case 'error':
-                    throw new DatabaseError(entry.error?.message || 'SQL execution failed');
+                    throw new DatabaseError(entry.error?.message || 'SQL execution failed', entry.error?.code);
             }
         }
         return {
@@ -235,7 +235,7 @@ export class Session {
                     break;
                 case 'step_error':
                 case 'error':
-                    throw new DatabaseError(entry.error?.message || 'Batch execution failed');
+                    throw new DatabaseError(entry.error?.message || 'Batch execution failed', entry.error?.code);
             }
         }
         return {
@@ -266,7 +266,7 @@ export class Session {
         if (response.results && response.results[0]) {
             const result = response.results[0];
             if (result.type === "error") {
-                throw new DatabaseError(result.error?.message || 'Sequence execution failed');
+                throw new DatabaseError(result.error?.message || 'Sequence execution failed', result.error?.code);
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tursodatabase/serverless",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",