@tursodatabase/serverless 1.2.0-pre.2 → 1.2.0

package/dist/session.js

@@ -0,0 +1,307 @@
+import { executeCursor, executePipeline, encodeValue, decodeValue } from './protocol.js';
+import { DatabaseError } from './error.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);
+    }
+    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, queryOptions) {
+        const request = {
+            baton: this.baton,
+            requests: [{
+                    type: "describe",
+                    sql: sql
+                }]
+        };
+        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;
+        }
+        // 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 || 'Describe execution failed', result.error?.code);
+            }
+            if (result.response?.type === "describe" && result.response.result) {
+                return result.response.result;
+            }
+        }
+        throw new DatabaseError('Unexpected describe response');
+    }
+    /**
+     * Execute a SQL statement and return all results.
+     *
+     * @param sql - The SQL statement to execute
+     * @param args - Optional array of parameter values or object with named parameters
+     * @param safeIntegers - Whether to return integers as BigInt
+     * @returns Promise resolving to the complete result set
+     */
+    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;
+    }
+    /**
+     * 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 or object with named parameters
+     * @returns Promise resolving to the raw response and cursor entries
+     */
+    async executeRaw(sql, args = [], queryOptions) {
+        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: positionalArgs,
+                            named_args: namedArgs,
+                            want_rows: true
+                        }
+                    }]
+            }
+        };
+        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;
+        }
+        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, safeIntegers = false) {
+        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(value => decodeValue(value, safeIntegers));
+                        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 DatabaseError(entry.error?.message || 'SQL execution failed', entry.error?.code);
+            }
+        }
+        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, queryOptions) {
+        const request = {
+            baton: this.baton,
+            batch: {
+                steps: statements.map(sql => ({
+                    stmt: {
+                        sql,
+                        args: [],
+                        named_args: [],
+                        want_rows: false
+                    }
+                }))
+            }
+        };
+        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;
+        }
+        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 DatabaseError(entry.error?.message || 'Batch execution failed', entry.error?.code);
+            }
+        }
+        return {
+            rowsAffected: totalRowsAffected,
+            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, queryOptions) {
+        const request = {
+            baton: this.baton,
+            requests: [{
+                    type: "sequence",
+                    sql: sql
+                }]
+        };
+        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;
+        }
+        // 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', result.error?.code);
+            }
+        }
+    }
+    /**
+     * 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, this.config.remoteEncryptionKey);
+            }
+            catch {
+                // Ignore errors during close — the connection might already be closed
+                // or the baton may be stale after a timeout.
+            }
+        }
+        // Reset local state
+        this.baton = null;
+        this.baseUrl = '';
+    }
+}

package/dist/statement.d.ts

@@ -0,0 +1,161 @@
+import { type Column, type QueryOptions } from './protocol.js';
+import { Session, type SessionConfig } from './session.js';
+import { type AsyncLock } from './async-lock.js';
+/**
+ * A prepared SQL statement that can be executed in multiple ways.
+ *
+ * Statements may either own a dedicated session or share a connection session to preserve transaction boundaries.
+ * 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;
+    private presentationMode;
+    private safeIntegerMode;
+    private columnMetadata;
+    private execLock?;
+    constructor(sessionConfig: SessionConfig, sql: string, columns?: Column[]);
+    /**
+     * Create a Statement that shares an existing session and serializes execution
+     * through the given lock. Used by Connection.prepare() so prepared statements
+     * participate in the connection's transaction scope.
+     */
+    static fromSession(session: Session, sql: string, columns: Column[] | undefined, execLock: AsyncLock): Statement;
+    /**
+     * Whether the prepared statement returns data.
+     *
+     * This is `true` for SELECT queries and statements with RETURNING clause,
+     * and `false` for INSERT, UPDATE, DELETE statements without RETURNING.
+     *
+     * @example
+     * ```typescript
+     * const stmt = await conn.prepare(sql);
+     * if (stmt.reader) {
+     *   return stmt.all(args);  // SELECT-like query
+     * } else {
+     *   return stmt.run(args);  // INSERT/UPDATE/DELETE
+     * }
+     * ```
+     */
+    get reader(): boolean;
+    /**
+     * Enable raw mode to return arrays instead of objects.
+     *
+     * @param raw Enable or disable raw mode. If you don't pass the parameter, raw mode is enabled.
+     * @returns This statement instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+     * const row = await stmt.raw().get([1]);
+     * console.log(row); // [1, "Alice", "alice@example.org"]
+     * ```
+     */
+    raw(raw?: boolean): Statement;
+    /**
+     * Enable pluck mode to return only the first column value from each row.
+     *
+     * @param pluck Enable or disable pluck mode. If you don't pass the parameter, pluck mode is enabled.
+     * @returns This statement instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const stmt = client.prepare("SELECT id FROM users");
+     * const ids = await stmt.pluck().all();
+     * console.log(ids); // [1, 2, 3, ...]
+     * ```
+     */
+    pluck(pluck?: boolean): Statement;
+    /**
+     * Sets safe integers mode for this statement.
+     *
+     * @param toggle Whether to use safe integers. If you don't pass the parameter, safe integers mode is enabled.
+     * @returns This statement instance for chaining
+     */
+    safeIntegers(toggle?: boolean): Statement;
+    /**
+     * Get column information for this statement.
+     *
+     * @returns Array of column metadata objects matching the native bindings format
+     *
+     * @example
+     * ```typescript
+     * const stmt = await client.prepare("SELECT id, name, email FROM users");
+     * const columns = stmt.columns();
+     * console.log(columns); // [{ name: 'id', type: 'INTEGER', column: null, database: null, table: null }, ...]
+     * ```
+     */
+    columns(): any[];
+    private withLock;
+    /**
+     * Executes the prepared statement.
+     *
+     * @param args - Optional array of parameter values or object with named parameters
+     * @returns Promise resolving to the result of the statement
+     *
+     * @example
+     * ```typescript
+     * const stmt = client.prepare("INSERT INTO users (name, email) VALUES (?, ?)");
+     * const result = await stmt.run(['John Doe', 'john.doe@example.com']);
+     * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
+     * ```
+     */
+    run(args?: any, queryOptions?: QueryOptions): Promise<any>;
+    /**
+     * Execute the statement and return the first row.
+     *
+     * @param args - Optional array of parameter values or object with named parameters
+     * @returns Promise resolving to the first row or undefined 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, queryOptions?: QueryOptions): Promise<any>;
+    /**
+     * Execute the statement and return all rows.
+     *
+     * @param args - Optional array of parameter values or object with named parameters
+     * @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, queryOptions?: QueryOptions): 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 or object with named parameters
+     * @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, queryOptions?: QueryOptions): AsyncGenerator<any>;
+    /**
+     * Normalize arguments to handle both single values and arrays.
+     * Matches the behavior of the native bindings.
+     */
+    private normalizeArgs;
+}