@tursodatabase/serverless 0.1.0

package/dist/connection.js

@@ -0,0 +1,86 @@
+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.
+ */
+export class Connection {
+    constructor(config) {
+        this.config = config;
+        this.session = new Session(config);
+    }
+    /**
+     * Prepare a SQL statement for execution.
+     *
+     * Each prepared statement gets its own session to avoid conflicts during concurrent execution.
+     *
+     * @param sql - The SQL statement to prepare
+     * @returns A Statement object that can be executed multiple ways
+     *
+     * @example
+     * ```typescript
+     * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+     * const user = await stmt.get([123]);
+     * const allUsers = await stmt.all();
+     * ```
+     */
+    prepare(sql) {
+        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
+     * ```typescript
+     * const result = await client.execute("SELECT * FROM users");
+     * console.log(result.rows);
+     * ```
+     */
+    async execute(sql, args = []) {
+        return this.session.execute(sql, args);
+    }
+    /**
+     * 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) {
+        return this.session.batch(statements);
+    }
+}
+/**
+ * Create a new connection to a Turso database.
+ *
+ * @param config - Configuration object with database URL and auth token
+ * @returns A new Connection instance
+ *
+ * @example
+ * ```typescript
+ * import { connect } from "@tursodatabase/serverless";
+ *
+ * const client = connect({
+ *   url: process.env.TURSO_DATABASE_URL,
+ *   authToken: process.env.TURSO_AUTH_TOKEN
+ * });
+ * ```
+ */
+export function connect(config) {
+    return new Connection(config);
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/protocol.d.ts

@@ -0,0 +1,89 @@
+export interface Value {
+    type: 'null' | 'integer' | 'float' | 'text' | 'blob';
+    value?: string | number;
+    base64?: string;
+}
+export interface Column {
+    name: string;
+    decltype: string;
+}
+export interface ExecuteResult {
+    cols: Column[];
+    rows: Value[][];
+    affected_row_count: number;
+    last_insert_rowid?: string;
+}
+export interface ExecuteRequest {
+    type: 'execute';
+    stmt: {
+        sql: string;
+        args: Value[];
+        named_args: Value[];
+        want_rows: boolean;
+    };
+}
+export interface BatchStep {
+    stmt: {
+        sql: string;
+        args: Value[];
+        want_rows: boolean;
+    };
+    condition?: {
+        type: 'ok';
+        step: number;
+    };
+}
+export interface BatchRequest {
+    type: 'batch';
+    batch: {
+        steps: BatchStep[];
+    };
+}
+export interface PipelineRequest {
+    baton: string | null;
+    requests: (ExecuteRequest | BatchRequest)[];
+}
+export interface PipelineResponse {
+    baton: string | null;
+    base_url: string | null;
+    results: Array<{
+        type: 'ok' | 'error';
+        response?: {
+            type: 'execute' | 'batch';
+            result: ExecuteResult;
+        };
+        error?: {
+            message: string;
+            code: string;
+        };
+    }>;
+}
+export declare function encodeValue(value: any): Value;
+export declare function decodeValue(value: Value): any;
+export interface CursorRequest {
+    baton: string | null;
+    batch: {
+        steps: BatchStep[];
+    };
+}
+export interface CursorResponse {
+    baton: string | null;
+    base_url: string | null;
+}
+export interface CursorEntry {
+    type: 'step_begin' | 'step_end' | 'step_error' | 'row' | 'error';
+    step?: number;
+    cols?: Column[];
+    row?: Value[];
+    affected_row_count?: number;
+    last_insert_rowid?: string;
+    error?: {
+        message: string;
+        code: string;
+    };
+}
+export declare function executeCursor(url: string, authToken: string, request: CursorRequest): Promise<{
+    response: CursorResponse;
+    entries: AsyncGenerator<CursorEntry>;
+}>;
+export declare function executePipeline(url: string, authToken: string, request: PipelineRequest): Promise<PipelineResponse>;

package/dist/protocol.js

@@ -0,0 +1,128 @@
+export function encodeValue(value) {
+    if (value === null || value === undefined) {
+        return { type: 'null' };
+    }
+    if (typeof value === 'number') {
+        if (Number.isInteger(value)) {
+            return { type: 'integer', value: value.toString() };
+        }
+        return { type: 'float', value };
+    }
+    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) };
+}
+export function decodeValue(value) {
+    switch (value.type) {
+        case 'null':
+            return null;
+        case 'integer':
+            return parseInt(value.value, 10);
+        case 'float':
+            return value.value;
+        case 'text':
+            return value.value;
+        case 'blob':
+            if (value.base64) {
+                const binaryString = atob(value.base64);
+                const bytes = new Uint8Array(binaryString.length);
+                for (let i = 0; i < binaryString.length; i++) {
+                    bytes[i] = binaryString.charCodeAt(i);
+                }
+                return bytes;
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+export async function executeCursor(url, authToken, request) {
+    const response = await fetch(`${url}/v3/cursor`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${authToken}`,
+        },
+        body: JSON.stringify(request),
+    });
+    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 {
+            // If we can't parse the error body, use the default HTTP error message
+        }
+        throw new Error(errorMessage);
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+        throw new Error('No response body');
+    }
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let isFirstLine = true;
+    let cursorResponse;
+    async function* parseEntries() {
+        try {
+            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);
+                        }
+                    }
+                }
+            }
+        }
+        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 };
+}
+export async function executePipeline(url, authToken, request) {
+    const response = await fetch(`${url}/v3/pipeline`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${authToken}`,
+        },
+        body: JSON.stringify(request),
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    return response.json();
+}

package/dist/session.d.ts

@@ -0,0 +1,63 @@
+import { type CursorResponse, type CursorEntry } from './protocol.js';
+/**
+ * Configuration options for a session.
+ */
+export interface SessionConfig {
+    /** Database URL */
+    url: string;
+    /** Authentication token */
+    authToken: string;
+}
+/**
+ * A database session that manages the connection state and baton.
+ *
+ * Each session maintains its own connection state and can execute SQL statements
+ * independently without interfering with other sessions.
+ */
+export declare class Session {
+    private config;
+    private baton;
+    private baseUrl;
+    constructor(config: SessionConfig);
+    /**
+     * 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
+     */
+    execute(sql: string, args?: 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
+     * @returns Promise resolving to the raw response and cursor entries
+     */
+    executeRaw(sql: string, args?: any[]): Promise<{
+        response: CursorResponse;
+        entries: AsyncGenerator<CursorEntry>;
+    }>;
+    /**
+     * Process cursor entries into a structured result.
+     *
+     * @param entries - Async generator of cursor entries
+     * @returns Promise resolving to the processed result
+     */
+    processCursorEntries(entries: AsyncGenerator<CursorEntry>): Promise<any>;
+    /**
+     * 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: any[], columns: string[]): any;
+    /**
+     * Execute multiple SQL statements in a batch.
+     *
+     * @param statements - Array of SQL statements to execute
+     * @returns Promise resolving to batch execution results
+     */
+    batch(statements: string[]): Promise<any>;
+}

package/dist/session.js

@@ -0,0 +1,176 @@
+import { executeCursor, encodeValue, decodeValue } from './protocol.js';
+function normalizeUrl(url) {
+    return url.replace(/^libsql:\/\//, 'https://');
+}
+function isValidIdentifier(str) {
+    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(str);
+}
+/**
+ * A database session that manages the connection state and baton.
+ *
+ * Each session maintains its own connection state and can execute SQL statements
+ * independently without interfering with other sessions.
+ */
+export class Session {
+    constructor(config) {
+        this.baton = null;
+        this.config = config;
+        this.baseUrl = normalizeUrl(config.url);
+    }
+    /**
+     * 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
+     */
+    async execute(sql, args = []) {
+        const { response, entries } = await this.executeRaw(sql, args);
+        const result = await this.processCursorEntries(entries);
+        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
+     * @returns Promise resolving to the raw response and cursor entries
+     */
+    async executeRaw(sql, args = []) {
+        const request = {
+            baton: this.baton,
+            batch: {
+                steps: [{
+                        stmt: {
+                            sql,
+                            args: args.map(encodeValue),
+                            want_rows: true
+                        }
+                    }]
+            }
+        };
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request);
+        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) {
+        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(decodeValue);
+                        const rowObject = this.createRowObject(decodedRow, columns);
+                        rows.push(rowObject);
+                    }
+                    break;
+                case 'step_end':
+                    if (entry.affected_row_count !== undefined) {
+                        rowsAffected = entry.affected_row_count;
+                    }
+                    if (entry.last_insert_rowid) {
+                        lastInsertRowid = parseInt(entry.last_insert_rowid, 10);
+                    }
+                    break;
+                case 'step_error':
+                case 'error':
+                    throw new Error(entry.error?.message || 'SQL execution failed');
+            }
+        }
+        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];
+        // Add column name properties to the array as non-enumerable
+        // Only add valid identifier names to avoid conflicts
+        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) {
+        const request = {
+            baton: this.baton,
+            batch: {
+                steps: statements.map(sql => ({
+                    stmt: {
+                        sql,
+                        args: [],
+                        want_rows: false
+                    }
+                }))
+            }
+        };
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request);
+        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 !== undefined) {
+                        totalRowsAffected += entry.affected_row_count;
+                    }
+                    if (entry.last_insert_rowid) {
+                        lastInsertRowid = parseInt(entry.last_insert_rowid, 10);
+                    }
+                    break;
+                case 'step_error':
+                case 'error':
+                    throw new Error(entry.error?.message || 'Batch execution failed');
+            }
+        }
+        return {
+            rowsAffected: totalRowsAffected,
+            lastInsertRowid
+        };
+    }
+}

package/dist/statement.d.ts

@@ -0,0 +1,64 @@
+import { type SessionConfig } from './session.js';
+/**
+ * A prepared SQL statement that can be executed in multiple ways.
+ *
+ * Each statement has its own session to avoid conflicts during concurrent execution.
+ * Provides three execution modes:
+ * - `get(args?)`: Returns the first row or null
+ * - `all(args?)`: Returns all rows as an array
+ * - `iterate(args?)`: Returns an async iterator for streaming results
+ */
+export declare class Statement {
+    private session;
+    private sql;
+    constructor(sessionConfig: SessionConfig, sql: string);
+    /**
+     * Execute the statement and return the first row.
+     *
+     * @param args - Optional array of parameter values for the SQL statement
+     * @returns Promise resolving to the first row or null 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);
+     * }
+     * ```
+     */
+    get(args?: any[]): Promise<any>;
+    /**
+     * Execute the statement and return all rows.
+     *
+     * @param args - Optional array of parameter values for the SQL statement
+     * @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`);
+     * ```
+     */
+    all(args?: any[]): Promise<any[]>;
+    /**
+     * 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 for the SQL statement
+     * @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);
+     * }
+     * ```
+     */
+    iterate(args?: any[]): AsyncGenerator<any>;
+}