@tursodatabase/serverless 0.2.2 → 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/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/package.json

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