@tursodatabase/serverless 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,22 @@
-# Turso serverless JavaScript driver
+<p align="center">
+  <h1 align="center">Turso Serverless Driver for JavaScript</h1>
+</p>
+
+<p align="center">
+  <a title="JavaScript" target="_blank" href="https://www.npmjs.com/package/@tursodatabase/serverless"><img alt="npm" src="https://img.shields.io/npm/v/@tursodatabase/serverless"></a>
+  <a title="MIT" target="_blank" href="https://github.com/tursodatabase/turso/blob/main/LICENSE.md"><img src="http://img.shields.io/badge/license-MIT-orange.svg?style=flat-square"></a>
+</p>
+<p align="center">
+  <a title="Users Discord" target="_blank" href="https://tur.so/discord"><img alt="Chat with other users of Turso on Discord" src="https://img.shields.io/discord/933071162680958986?label=Discord&logo=Discord&style=social"></a>
+</p>
+
+---
+
+## About
 
 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.
 
-> [!NOTE]
-> This driver is experimental and, therefore, subject to change at any time.
+> **📝 Note:** This driver is experimental and, therefore, subject to change at any time.
 
 ## Installation
 
@@ -11,7 +24,9 @@ A serverless database driver for Turso Cloud, using only `fetch()`. Connect to y
 npm install @tursodatabase/serverless
 ```
 
-## Usage
+## Getting Started
+
+### Basic Usage
 
 ```javascript
 import { connect } from "@tursodatabase/serverless";
@@ -36,7 +51,11 @@ console.log(rows);
 for await (const row of stmt.iterate([123])) {
   console.log(row);
 }
+```
+
+### Batch Operations
 
+```javascript
 // Execute multiple statements in a batch
 await conn.batch([
   "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)",
@@ -45,9 +64,9 @@ await conn.batch([
 ]);
 ```
 
-### Compatibility layer for libSQL API
+### libSQL Compatibility Layer
 
-This driver supports the libSQL API as a compatibility layer.
+For existing libSQL applications, use the compatibility layer:
 
 ```javascript
 import { createClient } from "@tursodatabase/serverless/compat";
@@ -73,6 +92,21 @@ await client.batch([
 
 Check out the `examples/` directory for complete usage examples.
 
+## API Reference
+
+For complete API documentation, see [JavaScript API Reference](../../docs/javascript-api-reference.md).
+
+## Related Packages
+
+* The [@tursodatabase/database](https://www.npmjs.com/package/@tursodatabase/database) package provides the Turso in-memory database, compatible with SQLite.
+* The [@tursodatabase/sync](https://www.npmjs.com/package/@tursodatabase/sync) package provides bidirectional sync between a local Turso database and Turso Cloud. 
+
 ## License
 
-MIT
+This project is licensed under the [MIT license](../../LICENSE.md).
+
+## Support
+
+- [GitHub Issues](https://github.com/tursodatabase/turso/issues)
+- [Documentation](https://docs.turso.tech)
+- [Discord Community](https://tur.so/discord)

package/dist/compat.js

@@ -1,4 +1,4 @@
-import { connect } from './connection.js';
+import { Session } from './session.js';
 /**
  * libSQL-compatible error class with error codes.
  */
@@ -14,11 +14,11 @@ class LibSQLClient {
     constructor(config) {
         this._closed = false;
         this.validateConfig(config);
-        const tursoConfig = {
+        const sessionConfig = {
             url: config.url,
             authToken: config.authToken || ''
         };
-        this.connection = connect(tursoConfig);
+        this.session = new Session(sessionConfig);
     }
     validateConfig(config) {
         // Check for unsupported config options
@@ -108,8 +108,15 @@ class LibSQLClient {
             else {
                 normalizedStmt = this.normalizeStatement(stmtOrSql);
             }
-            const result = await this.connection.execute(normalizedStmt.sql, normalizedStmt.args);
-            return this.convertResult(result);
+            await this.session.sequence(normalizedStmt.sql);
+            // Return empty result set for sequence execution
+            return this.convertResult({
+                columns: [],
+                columnTypes: [],
+                rows: [],
+                rowsAffected: 0,
+                lastInsertRowid: undefined
+            });
         }
         catch (error) {
             throw new LibsqlError(error.message, "EXECUTE_ERROR");
@@ -124,7 +131,7 @@ class LibSQLClient {
                 const normalized = this.normalizeStatement(stmt);
                 return normalized.sql; // For now, ignore args in batch
             });
-            const result = await this.connection.batch(sqlStatements, mode);
+            const result = await this.session.batch(sqlStatements);
             // Return array of result sets (simplified - actual implementation would be more complex)
             return [this.convertResult(result)];
         }
@@ -140,13 +147,26 @@ class LibSQLClient {
         throw new LibsqlError("Transactions not implemented", "NOT_IMPLEMENTED");
     }
     async executeMultiple(sql) {
-        throw new LibsqlError("Execute multiple not implemented", "NOT_IMPLEMENTED");
+        try {
+            if (this._closed) {
+                throw new LibsqlError("Client is closed", "CLIENT_CLOSED");
+            }
+            await this.session.sequence(sql);
+        }
+        catch (error) {
+            throw new LibsqlError(error.message, "EXECUTE_MULTIPLE_ERROR");
+        }
     }
     async sync() {
         throw new LibsqlError("Sync not supported for remote databases", "NOT_SUPPORTED");
     }
     close() {
         this._closed = true;
+        // Note: The libSQL client interface expects synchronous close,
+        // but our underlying session needs async close. We'll fire and forget.
+        this.session.close().catch(error => {
+            console.error('Error closing session:', error);
+        });
     }
 }
 /**

package/dist/connection.d.ts

@@ -14,6 +14,7 @@ export interface Config extends SessionConfig {
 export declare class Connection {
     private config;
     private session;
+    private isOpen;
     constructor(config: Config);
     /**
      * Prepare a SQL statement for execution.
@@ -35,7 +36,6 @@ export declare class Connection {
      * 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
@@ -44,7 +44,7 @@ export declare class Connection {
      * console.log(result.rows);
      * ```
      */
-    execute(sql: string, args?: any[]): Promise<any>;
+    exec(sql: string): Promise<any>;
     /**
      * Execute multiple SQL statements in a batch.
      *
@@ -62,6 +62,19 @@ export declare class Connection {
      * ```
      */
     batch(statements: string[], mode?: string): 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>;
+    /**
+     * Close the connection.
+     *
+     * This sends a close request to the server to properly clean up the stream.
+     */
+    close(): Promise<void>;
 }
 /**
  * Create a new connection to a Turso database.

package/dist/connection.js

@@ -8,6 +8,10 @@ import { Statement } from './statement.js';
  */
 export class Connection {
     constructor(config) {
+        this.isOpen = true;
+        if (!config.url) {
+            throw new Error("invalid config: url is required");
+        }
         this.config = config;
         this.session = new Session(config);
     }
@@ -27,13 +31,15 @@ export class Connection {
      * ```
      */
     prepare(sql) {
+        if (!this.isOpen) {
+            throw new TypeError("The database connection is not open");
+        }
         return new Statement(this.config, sql);
     }
     /**
      * 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
@@ -42,8 +48,11 @@ export class Connection {
      * console.log(result.rows);
      * ```
      */
-    async execute(sql, args = []) {
-        return this.session.execute(sql, args);
+    async exec(sql) {
+        if (!this.isOpen) {
+            throw new TypeError("The database connection is not open");
+        }
+        return this.session.sequence(sql);
     }
     /**
      * Execute multiple SQL statements in a batch.
@@ -64,6 +73,28 @@ export class Connection {
     async batch(statements, mode) {
         return this.session.batch(statements);
     }
+    /**
+     * Execute a pragma.
+     *
+     * @param pragma - The pragma to execute
+     * @returns Promise resolving to the result of the pragma
+     */
+    async pragma(pragma) {
+        if (!this.isOpen) {
+            throw new TypeError("The database connection is not open");
+        }
+        const sql = `PRAGMA ${pragma}`;
+        return this.session.execute(sql);
+    }
+    /**
+     * 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();
+    }
 }
 /**
  * Create a new connection to a Turso database.

package/dist/error.d.ts

@@ -0,0 +1,3 @@
+export declare class DatabaseError extends Error {
+    constructor(message: string);
+}

package/dist/error.js

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

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { Connection, connect, type Config } from './connection.js';
 export { Statement } from './statement.js';
+export { DatabaseError } from './error.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 // Turso serverless driver entry point
 export { Connection, connect } from './connection.js';
 export { Statement } from './statement.js';
+export { DatabaseError } from './error.js';

package/dist/protocol.d.ts

@@ -13,12 +13,16 @@ export interface ExecuteResult {
     affected_row_count: number;
     last_insert_rowid?: string;
 }
+export interface NamedArg {
+    name: string;
+    value: Value;
+}
 export interface ExecuteRequest {
     type: 'execute';
     stmt: {
         sql: string;
         args: Value[];
-        named_args: Value[];
+        named_args: NamedArg[];
         want_rows: boolean;
     };
 }
@@ -26,6 +30,7 @@ export interface BatchStep {
     stmt: {
         sql: string;
         args: Value[];
+        named_args?: NamedArg[];
         want_rows: boolean;
     };
     condition?: {
@@ -39,9 +44,16 @@ export interface BatchRequest {
         steps: BatchStep[];
     };
 }
+export interface SequenceRequest {
+    type: 'sequence';
+    sql: string;
+}
+export interface CloseRequest {
+    type: 'close';
+}
 export interface PipelineRequest {
     baton: string | null;
-    requests: (ExecuteRequest | BatchRequest)[];
+    requests: (ExecuteRequest | BatchRequest | SequenceRequest | CloseRequest)[];
 }
 export interface PipelineResponse {
     baton: string | null;
@@ -49,8 +61,8 @@ export interface PipelineResponse {
     results: Array<{
         type: 'ok' | 'error';
         response?: {
-            type: 'execute' | 'batch';
-            result: ExecuteResult;
+            type: 'execute' | 'batch' | 'sequence' | 'close';
+            result?: ExecuteResult;
         };
         error?: {
             message: string;

package/dist/protocol.js

@@ -1,3 +1,4 @@
+import { DatabaseError } from './error.js';
 export function encodeValue(value) {
     if (value === null || value === undefined) {
         return { type: 'null' };
@@ -62,55 +63,69 @@ export async function executeCursor(url, authToken, request) {
         catch {
             // If we can't parse the error body, use the default HTTP error message
         }
-        throw new Error(errorMessage);
+        throw new DatabaseError(errorMessage);
     }
     const reader = response.body?.getReader();
     if (!reader) {
-        throw new Error('No response body');
+        throw new DatabaseError('No response body');
     }
     const decoder = new TextDecoder();
     let buffer = '';
-    let isFirstLine = true;
     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);
+                break;
+            }
+        }
+    }
+    if (!cursorResponse) {
+        throw new DatabaseError('No cursor response received');
+    }
     async function* parseEntries() {
         try {
+            // Process any remaining data in the buffer
+            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);
+                }
+            }
+            // Continue reading from the stream
             while (true) {
                 const { done, value } = await reader.read();
                 if (done)
                     break;
                 buffer += decoder.decode(value, { stream: true });
-                let newlineIndex;
                 while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
                     const line = buffer.slice(0, newlineIndex).trim();
                     buffer = buffer.slice(newlineIndex + 1);
                     if (line) {
-                        if (isFirstLine) {
-                            cursorResponse = JSON.parse(line);
-                            isFirstLine = false;
-                        }
-                        else {
-                            yield JSON.parse(line);
-                        }
+                        yield JSON.parse(line);
                     }
                 }
             }
+            // Process any remaining data in the buffer
+            if (buffer.trim()) {
+                yield JSON.parse(buffer.trim());
+            }
         }
         finally {
             reader.releaseLock();
         }
     }
-    const entries = parseEntries();
-    // Get the first entry to parse the cursor response
-    const firstEntry = await entries.next();
-    if (!firstEntry.done) {
-        // Put the first entry back
-        const generator = (async function* () {
-            yield firstEntry.value;
-            yield* entries;
-        })();
-        return { response: cursorResponse, entries: generator };
-    }
-    return { response: cursorResponse, entries };
+    return { response: cursorResponse, entries: parseEntries() };
 }
 export async function executePipeline(url, authToken, request) {
     const response = await fetch(`${url}/v3/pipeline`, {
@@ -122,7 +137,7 @@ export async function executePipeline(url, authToken, request) {
         body: JSON.stringify(request),
     });
     if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
+        throw new DatabaseError(`HTTP error! status: ${response.status}`);
     }
     return response.json();
 }

package/dist/session.d.ts

@@ -23,18 +23,18 @@ export declare class Session {
      * Execute a SQL statement and return all results.
      *
      * @param sql - The SQL statement to execute
-     * @param args - Optional array of parameter values
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to the complete result set
      */
-    execute(sql: string, args?: any[]): Promise<any>;
+    execute(sql: string, args?: any[] | Record<string, any>): Promise<any>;
     /**
      * 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
+     * @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[]): Promise<{
+    executeRaw(sql: string, args?: any[] | Record<string, any>): Promise<{
         response: CursorResponse;
         entries: AsyncGenerator<CursorEntry>;
     }>;
@@ -60,4 +60,18 @@ export declare class Session {
      * @returns Promise resolving to batch execution results
      */
     batch(statements: string[]): 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>;
+    /**
+     * Close the session.
+     *
+     * This sends a close request to the server to properly clean up the stream
+     * before resetting the local state.
+     */
+    close(): Promise<void>;
 }

package/dist/session.js

@@ -1,4 +1,5 @@
-import { executeCursor, encodeValue, decodeValue } from './protocol.js';
+import { executeCursor, executePipeline, encodeValue, decodeValue } from './protocol.js';
+import { DatabaseError } from './error.js';
 function normalizeUrl(url) {
     return url.replace(/^libsql:\/\//, 'https://');
 }
@@ -21,7 +22,7 @@ export class Session {
      * Execute a SQL statement and return all results.
      *
      * @param sql - The SQL statement to execute
-     * @param args - Optional array of parameter values
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to the complete result set
      */
     async execute(sql, args = []) {
@@ -33,17 +34,53 @@ export class Session {
      * 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
+     * @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 = []) {
+        let positionalArgs = [];
+        let namedArgs = [];
+        if (Array.isArray(args)) {
+            positionalArgs = args.map(encodeValue);
+        }
+        else {
+            // Check if this is an object with numeric keys (for ?1, ?2 style parameters)
+            const keys = Object.keys(args);
+            const isNumericKeys = keys.length > 0 && keys.every(key => /^\d+$/.test(key));
+            if (isNumericKeys) {
+                // Convert numeric-keyed object to positional args
+                // Sort keys numerically to ensure correct order
+                const sortedKeys = keys.sort((a, b) => parseInt(a) - parseInt(b));
+                const maxIndex = parseInt(sortedKeys[sortedKeys.length - 1]);
+                // Create array with undefined for missing indices
+                positionalArgs = new Array(maxIndex);
+                for (const key of sortedKeys) {
+                    const index = parseInt(key) - 1; // Convert to 0-based index
+                    positionalArgs[index] = encodeValue(args[key]);
+                }
+                // Fill any undefined values with null
+                for (let i = 0; i < positionalArgs.length; i++) {
+                    if (positionalArgs[i] === undefined) {
+                        positionalArgs[i] = { type: 'null' };
+                    }
+                }
+            }
+            else {
+                // Convert object with named parameters to NamedArg array
+                namedArgs = Object.entries(args).map(([name, value]) => ({
+                    name,
+                    value: encodeValue(value)
+                }));
+            }
+        }
         const request = {
             baton: this.baton,
             batch: {
                 steps: [{
                         stmt: {
                             sql,
-                            args: args.map(encodeValue),
+                            args: positionalArgs,
+                            named_args: namedArgs,
                             want_rows: true
                         }
                     }]
@@ -93,7 +130,7 @@ export class Session {
                     break;
                 case 'step_error':
                 case 'error':
-                    throw new Error(entry.error?.message || 'SQL execution failed');
+                    throw new DatabaseError(entry.error?.message || 'SQL execution failed');
             }
         }
         return {
@@ -141,6 +178,7 @@ export class Session {
                     stmt: {
                         sql,
                         args: [],
+                        named_args: [],
                         want_rows: false
                     }
                 }))
@@ -165,7 +203,7 @@ export class Session {
                     break;
                 case 'step_error':
                 case 'error':
-                    throw new Error(entry.error?.message || 'Batch execution failed');
+                    throw new DatabaseError(entry.error?.message || 'Batch execution failed');
             }
         }
         return {
@@ -173,4 +211,58 @@ export class Session {
             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) {
+        const request = {
+            baton: this.baton,
+            requests: [{
+                    type: "sequence",
+                    sql: sql
+                }]
+        };
+        const response = await executePipeline(this.baseUrl, this.config.authToken, request);
+        this.baton = response.baton;
+        if (response.base_url) {
+            this.baseUrl = response.base_url;
+        }
+        // Check for errors in the response
+        if (response.results && response.results[0]) {
+            const result = response.results[0];
+            if (result.type === "error") {
+                throw new DatabaseError(result.error?.message || 'Sequence execution failed');
+            }
+        }
+    }
+    /**
+     * Close the session.
+     *
+     * This sends a close request to the server to properly clean up the stream
+     * before resetting the local state.
+     */
+    async close() {
+        // Only send close request if we have an active baton
+        if (this.baton) {
+            try {
+                const request = {
+                    baton: this.baton,
+                    requests: [{
+                            type: "close"
+                        }]
+                };
+                await executePipeline(this.baseUrl, this.config.authToken, request);
+            }
+            catch (error) {
+                // Ignore errors during close, as the connection might already be closed
+                console.error('Error closing session:', error);
+            }
+        }
+        // Reset local state
+        this.baton = null;
+        this.baseUrl = '';
+    }
 }