@tursodatabase/serverless 0.2.4 → 1.1.0-pre.1

package/README.md

@@ -16,8 +16,6 @@
 
 A serverless database driver for Turso Cloud, using only `fetch()`. Connect to your database from serverless and edge functions, such as Cloudflare Workers and Vercel.
 
-> **⚠️ Warning:** This software is in BETA. It may still contain bugs and unexpected behavior. Use caution with production data and ensure you have backups.
-
 ## Installation
 
 ```bash

package/dist/connection.d.ts

@@ -1,5 +1,6 @@
 import { type SessionConfig } from './session.js';
 import { Statement } from './statement.js';
+import { type QueryOptions } from './protocol.js';
 /**
  * Configuration options for connecting to a Turso database.
  */
@@ -91,7 +92,7 @@ export declare class Connection {
      * console.log(result.rows);
      * ```
      */
-    execute(sql: string, args?: any[]): Promise<any>;
+    execute(sql: string, args?: any[], queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a SQL statement and return all results.
      *
@@ -104,7 +105,7 @@ export declare class Connection {
      * console.log(result.rows);
      * ```
      */
-    exec(sql: string): Promise<any>;
+    exec(sql: string, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute multiple SQL statements in a batch.
      *
@@ -121,14 +122,14 @@ export declare class Connection {
      * ]);
      * ```
      */
-    batch(statements: string[], mode?: string): Promise<any>;
+    batch(statements: string[], mode?: string, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a pragma.
      *
      * @param pragma - The pragma to execute
      * @returns Promise resolving to the result of the pragma
      */
-    pragma(pragma: string): Promise<any>;
+    pragma(pragma: string, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Sets the default safe integers mode for all statements from this connection.
      *

package/dist/connection.js

@@ -111,13 +111,13 @@ export class Connection {
      * console.log(result.rows);
      * ```
      */
-    async execute(sql, args) {
+    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);
+            return await this.session.execute(sql, args || [], this.defaultSafeIntegerMode, queryOptions);
         }
         finally {
             this.execLock.release();
@@ -135,13 +135,13 @@ export class Connection {
      * console.log(result.rows);
      * ```
      */
-    async exec(sql) {
+    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);
+            return await this.session.sequence(sql, queryOptions);
         }
         finally {
             this.execLock.release();
@@ -163,13 +163,13 @@ export class Connection {
      * ]);
      * ```
      */
-    async batch(statements, mode) {
+    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);
+            return await this.session.batch(statements, queryOptions);
         }
         finally {
             this.execLock.release();
@@ -181,14 +181,14 @@ export class Connection {
      * @param pragma - The pragma to execute
      * @returns Promise resolving to the result of the pragma
      */
-    async pragma(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);
+            return await this.session.execute(sql, [], false, queryOptions);
         }
         finally {
             this.execLock.release();

package/dist/error.d.ts

@@ -7,3 +7,13 @@ export declare class DatabaseError extends Error {
     cause?: Error;
     constructor(message: string, code?: string, rawCode?: number, cause?: Error);
 }
+/**
+ * Error thrown when a query exceeds the configured timeout.
+ *
+ * This is a subclass of `DatabaseError` with `code` set to `"TIMEOUT"`.
+ * Catch this type to distinguish timeouts from other database errors
+ * and decide whether to retry or fail gracefully.
+ */
+export declare class TimeoutError extends DatabaseError {
+    constructor(message?: string, cause?: Error);
+}

package/dist/error.js

@@ -8,3 +8,17 @@ export class DatabaseError extends Error {
         Object.setPrototypeOf(this, DatabaseError.prototype);
     }
 }
+/**
+ * Error thrown when a query exceeds the configured timeout.
+ *
+ * This is a subclass of `DatabaseError` with `code` set to `"TIMEOUT"`.
+ * Catch this type to distinguish timeouts from other database errors
+ * and decide whether to retry or fail gracefully.
+ */
+export class TimeoutError extends DatabaseError {
+    constructor(message = 'Query timed out', cause) {
+        super(message, 'TIMEOUT', undefined, cause);
+        this.name = 'TimeoutError';
+        Object.setPrototypeOf(this, TimeoutError.prototype);
+    }
+}

package/dist/index.d.ts

@@ -1,5 +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';
+export { DatabaseError, TimeoutError } from './error.js';
+export { type Column, type QueryOptions, ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/index.js

@@ -2,5 +2,5 @@
 export { Connection, connect } from './connection.js';
 export { Statement } from './statement.js';
 export { Session } from './session.js';
-export { DatabaseError } from './error.js';
+export { DatabaseError, TimeoutError } from './error.js';
 export { ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/protocol.d.ts

@@ -108,8 +108,13 @@ export interface CursorEntry {
 }
 /** HTTP header key for the encryption key */
 export declare const ENCRYPTION_KEY_HEADER = "x-turso-encryption-key";
-export declare function executeCursor(url: string, authToken: string | undefined, request: CursorRequest, remoteEncryptionKey?: string): Promise<{
+/** Per-query timeout options. Overrides defaultQueryTimeout for this call. */
+export interface QueryOptions {
+    /** Per-query timeout in milliseconds. Overrides defaultQueryTimeout for this call. */
+    queryTimeout?: number;
+}
+export declare function executeCursor(url: string, authToken: string | undefined, request: CursorRequest, remoteEncryptionKey?: string, signal?: AbortSignal): Promise<{
     response: CursorResponse;
     entries: AsyncGenerator<CursorEntry>;
 }>;
-export declare function executePipeline(url: string, authToken: string | undefined, request: PipelineRequest, remoteEncryptionKey?: string): Promise<PipelineResponse>;
+export declare function executePipeline(url: string, authToken: string | undefined, request: PipelineRequest, remoteEncryptionKey?: string, signal?: AbortSignal): Promise<PipelineResponse>;

package/dist/protocol.js

@@ -1,4 +1,4 @@
-import { DatabaseError } from './error.js';
+import { DatabaseError, TimeoutError } from './error.js';
 export function encodeValue(value) {
     if (value === null || value === undefined) {
         return { type: 'null' };
@@ -53,7 +53,13 @@ export function decodeValue(value, safeIntegers = false) {
 }
 /** HTTP header key for the encryption key */
 export const ENCRYPTION_KEY_HEADER = 'x-turso-encryption-key';
-export async function executeCursor(url, authToken, request, remoteEncryptionKey) {
+function wrapAbortError(error) {
+    if (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError')) {
+        throw new TimeoutError('Query timed out');
+    }
+    throw error;
+}
+export async function executeCursor(url, authToken, request, remoteEncryptionKey, signal) {
     const headers = {
         'Content-Type': 'application/json',
     };
@@ -63,11 +69,18 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
     if (remoteEncryptionKey) {
         headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
     }
-    const response = await fetch(`${url}/v3/cursor`, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(request),
-    });
+    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 {
@@ -90,22 +103,29 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
     let buffer = '';
     let cursorResponse;
     // First, read until we get the cursor response (first line)
-    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);
+    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() {
@@ -121,10 +141,16 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
             }
             // Continue reading from the stream
             while (true) {
-                const { done, value } = await reader.read();
-                if (done)
+                let readResult;
+                try {
+                    readResult = await reader.read();
+                }
+                catch (error) {
+                    wrapAbortError(error);
+                }
+                if (readResult.done)
                     break;
-                buffer += decoder.decode(value, { stream: true });
+                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);
@@ -144,7 +170,7 @@ export async function executeCursor(url, authToken, request, remoteEncryptionKey
     }
     return { response: cursorResponse, entries: parseEntries() };
 }
-export async function executePipeline(url, authToken, request, remoteEncryptionKey) {
+export async function executePipeline(url, authToken, request, remoteEncryptionKey, signal) {
     const headers = {
         'Content-Type': 'application/json',
     };
@@ -154,11 +180,18 @@ export async function executePipeline(url, authToken, request, remoteEncryptionK
     if (remoteEncryptionKey) {
         headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
     }
-    const response = await fetch(`${url}/v3/pipeline`, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(request),
-    });
+    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}`);
     }

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-import { type CursorResponse, type CursorEntry, type DescribeResult } from './protocol.js';
+import { type CursorResponse, type CursorEntry, type DescribeResult, type QueryOptions } from './protocol.js';
 /**
  * Configuration options for a session.
  */
@@ -12,6 +12,8 @@ export interface SessionConfig {
      * to enable access to encrypted Turso Cloud databases.
      */
     remoteEncryptionKey?: string;
+    /** Default maximum query execution time in milliseconds before interruption. */
+    defaultQueryTimeout?: number;
 }
 /**
  * A database session that manages the connection state and baton.
@@ -24,13 +26,14 @@ export declare class Session {
     private baton;
     private baseUrl;
     constructor(config: SessionConfig);
+    private createAbortSignal;
     /**
      * Describe a SQL statement to get its column metadata.
      *
      * @param sql - The SQL statement to describe
      * @returns Promise resolving to the statement description
      */
-    describe(sql: string): Promise<DescribeResult>;
+    describe(sql: string, queryOptions?: QueryOptions): Promise<DescribeResult>;
     /**
      * Execute a SQL statement and return all results.
      *
@@ -39,7 +42,7 @@ export declare class Session {
      * @param safeIntegers - Whether to return integers as BigInt
      * @returns Promise resolving to the complete result set
      */
-    execute(sql: string, args?: any[] | Record<string, any>, safeIntegers?: boolean): Promise<any>;
+    execute(sql: string, args?: any[] | Record<string, any>, safeIntegers?: boolean, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute a SQL statement and return the raw response and entries.
      *
@@ -47,7 +50,7 @@ export declare class Session {
      * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to the raw response and cursor entries
      */
-    executeRaw(sql: string, args?: any[] | Record<string, any>): Promise<{
+    executeRaw(sql: string, args?: any[] | Record<string, any>, queryOptions?: QueryOptions): Promise<{
         response: CursorResponse;
         entries: AsyncGenerator<CursorEntry>;
     }>;
@@ -72,14 +75,14 @@ export declare class Session {
      * @param statements - Array of SQL statements to execute
      * @returns Promise resolving to batch execution results
      */
-    batch(statements: string[]): Promise<any>;
+    batch(statements: string[], queryOptions?: QueryOptions): Promise<any>;
     /**
      * 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
      */
-    sequence(sql: string): Promise<void>;
+    sequence(sql: string, queryOptions?: QueryOptions): Promise<void>;
     /**
      * Close the session.
      *

package/dist/session.js

@@ -18,13 +18,20 @@ export class Session {
         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 undefined;
+    }
     /**
      * 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) {
+    async describe(sql, queryOptions) {
         const request = {
             baton: this.baton,
             requests: [{
@@ -32,7 +39,7 @@ export class Session {
                     sql: sql
                 }]
         };
-        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -57,8 +64,8 @@ export class Session {
      * @param safeIntegers - Whether to return integers as BigInt
      * @returns Promise resolving to the complete result set
      */
-    async execute(sql, args = [], safeIntegers = false) {
-        const { response, entries } = await this.executeRaw(sql, args);
+    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;
     }
@@ -69,7 +76,7 @@ export class Session {
      * @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 = []) {
+    async executeRaw(sql, args = [], queryOptions) {
         let positionalArgs = [];
         let namedArgs = [];
         if (Array.isArray(args)) {
@@ -118,7 +125,7 @@ export class Session {
                     }]
             }
         };
-        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -202,7 +209,7 @@ export class Session {
      * @param statements - Array of SQL statements to execute
      * @returns Promise resolving to batch execution results
      */
-    async batch(statements) {
+    async batch(statements, queryOptions) {
         const request = {
             baton: this.baton,
             batch: {
@@ -216,7 +223,7 @@ export class Session {
                 }))
             }
         };
-        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -249,7 +256,7 @@ export class Session {
      * @param sql - SQL string containing multiple statements separated by semicolons
      * @returns Promise resolving when all statements are executed
      */
-    async sequence(sql) {
+    async sequence(sql, queryOptions) {
         const request = {
             baton: this.baton,
             requests: [{
@@ -257,7 +264,7 @@ export class Session {
                     sql: sql
                 }]
         };
-        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey, this.createAbortSignal(queryOptions));
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -288,9 +295,9 @@ export class Session {
                 };
                 await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
             }
-            catch (error) {
-                // Ignore errors during close, as the connection might already be closed
-                console.error('Error closing session:', error);
+            catch {
+                // Ignore errors during close — the connection might already be closed
+                // or the baton may be stale after a timeout.
             }
         }
         // Reset local state

package/dist/statement.d.ts

@@ -1,4 +1,4 @@
-import { type Column } from './protocol.js';
+import { type Column, type QueryOptions } from './protocol.js';
 import { type SessionConfig } from './session.js';
 /**
  * A prepared SQL statement that can be executed in multiple ways.
@@ -94,7 +94,7 @@ export declare class Statement {
      * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
      * ```
      */
-    run(args?: any): Promise<any>;
+    run(args?: any, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute the statement and return the first row.
      *
@@ -110,7 +110,7 @@ export declare class Statement {
      * }
      * ```
      */
-    get(args?: any): Promise<any>;
+    get(args?: any, queryOptions?: QueryOptions): Promise<any>;
     /**
      * Execute the statement and return all rows.
      *
@@ -124,7 +124,7 @@ export declare class Statement {
      * console.log(`Found ${activeUsers.length} active users`);
      * ```
      */
-    all(args?: any): Promise<any[]>;
+    all(args?: any, queryOptions?: QueryOptions): Promise<any[]>;
     /**
      * Execute the statement and return an async iterator for streaming results.
      *
@@ -143,7 +143,7 @@ export declare class Statement {
      * }
      * ```
      */
-    iterate(args?: any): AsyncGenerator<any>;
+    iterate(args?: any, queryOptions?: QueryOptions): AsyncGenerator<any>;
     /**
      * Normalize arguments to handle both single values and arrays.
      * Matches the behavior of the native bindings.

package/dist/statement.js

@@ -112,9 +112,9 @@ export class Statement {
      * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
      * ```
      */
-    async run(args) {
+    async run(args, queryOptions) {
         const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
+        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
         return { changes: result.rowsAffected, lastInsertRowid: result.lastInsertRowid };
     }
     /**
@@ -132,9 +132,9 @@ export class Statement {
      * }
      * ```
      */
-    async get(args) {
+    async get(args, queryOptions) {
         const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
+        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
         const row = result.rows[0];
         if (!row) {
             return undefined;
@@ -168,9 +168,9 @@ export class Statement {
      * console.log(`Found ${activeUsers.length} active users`);
      * ```
      */
-    async all(args) {
+    async all(args, queryOptions) {
         const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
+        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode, queryOptions);
         if (this.presentationMode === 'pluck') {
             // In pluck mode, return only the first column value from each row
             return result.rows.map((row) => row[0]);
@@ -205,9 +205,9 @@ export class Statement {
      * }
      * ```
      */
-    async *iterate(args) {
+    async *iterate(args, queryOptions) {
         const normalizedArgs = this.normalizeArgs(args);
-        const { response, entries } = await this.session.executeRaw(this.sql, normalizedArgs);
+        const { response, entries } = await this.session.executeRaw(this.sql, normalizedArgs, queryOptions);
         let columns = [];
         for await (const entry of entries) {
             switch (entry.type) {

package/package.json

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