@tursodatabase/serverless 1.1.0 → 1.1.2-pre.1

package/dist/connection.js

@@ -1,312 +0,0 @@
-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.
- *
- * ## 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");
-        }
-        this.config = config;
-        this.session = new Session(config);
-        // Define inTransaction property
-        Object.defineProperty(this, 'inTransaction', {
-            get: () => this._inTransaction,
-            enumerable: true
-        });
-    }
-    /**
-     * Whether the database is currently in a transaction.
-     */
-    get inTransaction() {
-        return this._inTransaction;
-    }
-    /**
-     * Prepare a SQL statement for execution.
-     *
-     * Prepared statements created from a Connection use the same underlying session so transaction boundaries are preserved.
-     * This method fetches column metadata using the describe functionality.
-     *
-     * @param sql - The SQL statement to prepare
-     * @returns A Promise that resolves to a Statement object with column metadata
-     *
-     * @example
-     * ```typescript
-     * const stmt = await client.prepare("SELECT * FROM users WHERE id = ?");
-     * const columns = stmt.columns();
-     * const user = await stmt.get([123]);
-     * ```
-     */
-    async prepare(sql) {
-        if (!this.isOpen) {
-            throw new TypeError("The database connection is not open");
-        }
-        // Create a session to get column metadata via describe
-        const session = new Session(this.config);
-        const description = await session.describe(sql);
-        await session.close();
-        const stmt = Statement.fromSession(this.session, sql, description.cols, this.execLock);
-        if (this.defaultSafeIntegerMode) {
-            stmt.safeIntegers(true);
-        }
-        return stmt;
-    }
-    /**
-     * 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 WHERE id = ?", [123]);
-     * console.log(result.rows);
-     * ```
-     */
-    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, queryOptions);
-        }
-        finally {
-            this.execLock.release();
-        }
-    }
-    /**
-     * Execute a SQL statement and return all results.
-     *
-     * @param sql - The SQL statement to execute
-     * @returns Promise resolving to the complete result set
-     *
-     * @example
-     * ```typescript
-     * const result = await client.exec("SELECT * FROM users");
-     * console.log(result.rows);
-     * ```
-     */
-    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, queryOptions);
-        }
-        finally {
-            this.execLock.release();
-        }
-    }
-    /**
-     * 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, queryOptions) {
-        if (!this.isOpen) {
-            throw new TypeError("The database connection is not open");
-        }
-        await this.execLock.acquire();
-        try {
-            return await this.session.batch(statements, queryOptions);
-        }
-        finally {
-            this.execLock.release();
-        }
-    }
-    /**
-     * Execute a pragma.
-     *
-     * @param pragma - The pragma to execute
-     * @returns Promise resolving to the result of the 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, [], false, queryOptions);
-        }
-        finally {
-            this.execLock.release();
-        }
-    }
-    /**
-     * Sets the default safe integers mode for all statements from this connection.
-     *
-     * @param toggle - Whether to use safe integers by default.
-     */
-    defaultSafeIntegers(toggle) {
-        this.defaultSafeIntegerMode = toggle === false ? false : true;
-    }
-    /**
-     * Returns a function that executes the given function in a transaction.
-     *
-     * @param fn - The function to wrap in a transaction
-     * @returns A function that will execute fn within a transaction
-     *
-     * @example
-     * ```typescript
-     * const insert = await client.prepare("INSERT INTO users (name) VALUES (?)");
-     * const insertMany = client.transaction((users) => {
-     *   for (const user of users) {
-     *     insert.run([user]);
-     *   }
-     * });
-     *
-     * await insertMany(['Alice', 'Bob', 'Charlie']);
-     * ```
-     */
-    transaction(fn) {
-        if (typeof fn !== "function") {
-            throw new TypeError("Expected first argument to be a function");
-        }
-        const db = this;
-        const wrapTxn = (mode) => {
-            return async (...bindParameters) => {
-                await db.exec("BEGIN " + mode);
-                db._inTransaction = true;
-                try {
-                    const result = await fn(...bindParameters);
-                    await db.exec("COMMIT");
-                    db._inTransaction = false;
-                    return result;
-                }
-                catch (err) {
-                    await db.exec("ROLLBACK");
-                    db._inTransaction = false;
-                    throw err;
-                }
-            };
-        };
-        const properties = {
-            default: { value: wrapTxn("") },
-            deferred: { value: wrapTxn("DEFERRED") },
-            immediate: { value: wrapTxn("IMMEDIATE") },
-            exclusive: { value: wrapTxn("EXCLUSIVE") },
-            database: { value: this, enumerable: true },
-        };
-        Object.defineProperties(properties.default.value, properties);
-        Object.defineProperties(properties.deferred.value, properties);
-        Object.defineProperties(properties.immediate.value, properties);
-        Object.defineProperties(properties.exclusive.value, properties);
-        return properties.default.value;
-    }
-    /**
-     * 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();
-    }
-    async reconnect() {
-        try {
-            if (this.isOpen) {
-                await this.close();
-            }
-        }
-        finally {
-            this.session = new Session(this.config);
-            this.isOpen = true;
-        }
-    }
-}
-/**
- * Create a new connection to a Turso database.
- *
- * 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:
- *
- * ```typescript
- * import { connect } from "@tursodatabase/serverless";
- *
- * 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/dist/error.d.ts

@@ -1,19 +0,0 @@
-export declare class DatabaseError extends Error {
-    /** Machine-readable error code (e.g., "SQLITE_CONSTRAINT") */
-    code?: string;
-    /** Raw numeric error code */
-    rawCode?: number;
-    /** Original error that caused this 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

@@ -1,24 +0,0 @@
-export class DatabaseError extends Error {
-    constructor(message, code, rawCode, cause) {
-        super(message);
-        this.name = 'DatabaseError';
-        this.code = code;
-        this.rawCode = rawCode;
-        this.cause = cause;
-        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/protocol.d.ts

@@ -1,120 +0,0 @@
-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 NamedArg {
-    name: string;
-    value: Value;
-}
-export interface ExecuteRequest {
-    type: 'execute';
-    stmt: {
-        sql: string;
-        args: Value[];
-        named_args: NamedArg[];
-        want_rows: boolean;
-    };
-}
-export interface BatchStep {
-    stmt: {
-        sql: string;
-        args: Value[];
-        named_args?: NamedArg[];
-        want_rows: boolean;
-    };
-    condition?: {
-        type: 'ok';
-        step: number;
-    };
-}
-export interface BatchRequest {
-    type: 'batch';
-    batch: {
-        steps: BatchStep[];
-    };
-}
-export interface SequenceRequest {
-    type: 'sequence';
-    sql: string;
-}
-export interface CloseRequest {
-    type: 'close';
-}
-export interface DescribeRequest {
-    type: 'describe';
-    sql: string;
-}
-export interface DescribeResult {
-    params: Array<{
-        name?: string;
-    }>;
-    cols: Column[];
-    is_explain: boolean;
-    is_readonly: boolean;
-}
-export interface PipelineRequest {
-    baton: string | null;
-    requests: (ExecuteRequest | BatchRequest | SequenceRequest | CloseRequest | DescribeRequest)[];
-}
-export interface PipelineResponse {
-    baton: string | null;
-    base_url: string | null;
-    results: Array<{
-        type: 'ok' | 'error';
-        response?: {
-            type: 'execute' | 'batch' | 'sequence' | 'close' | 'describe';
-            result?: ExecuteResult | DescribeResult;
-        };
-        error?: {
-            message: string;
-            code: string;
-        };
-    }>;
-}
-export declare function encodeValue(value: any): Value;
-export declare function decodeValue(value: Value, safeIntegers?: boolean): 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;
-    };
-}
-/** HTTP header key for the encryption key */
-export declare const ENCRYPTION_KEY_HEADER = "x-turso-encryption-key";
-/** 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, signal?: AbortSignal): Promise<PipelineResponse>;

package/dist/protocol.js

@@ -1,199 +0,0 @@
-import { DatabaseError, TimeoutError } from './error.js';
-export function encodeValue(value) {
-    if (value === null || value === undefined) {
-        return { type: 'null' };
-    }
-    if (typeof value === 'number') {
-        if (!Number.isFinite(value)) {
-            throw new Error("Only finite numbers (not Infinity or NaN) can be passed as arguments");
-        }
-        return { type: 'float', value };
-    }
-    if (typeof value === 'bigint') {
-        return { type: 'integer', value: value.toString() };
-    }
-    if (typeof value === 'boolean') {
-        return { type: 'integer', value: value ? '1' : '0' };
-    }
-    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, safeIntegers = false) {
-    switch (value.type) {
-        case 'null':
-            return null;
-        case 'integer':
-            if (safeIntegers) {
-                return BigInt(value.value);
-            }
-            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 Buffer.from(bytes);
-            }
-            return null;
-        default:
-            return null;
-    }
-}
-/** HTTP header key for the encryption key */
-export const ENCRYPTION_KEY_HEADER = 'x-turso-encryption-key';
-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',
-    };
-    if (authToken) {
-        headers['Authorization'] = `Bearer ${authToken}`;
-    }
-    if (remoteEncryptionKey) {
-        headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
-    }
-    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 {
-            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 DatabaseError(errorMessage);
-    }
-    const reader = response.body?.getReader();
-    if (!reader) {
-        throw new DatabaseError('No response body');
-    }
-    const decoder = new TextDecoder();
-    let buffer = '';
-    let cursorResponse;
-    // First, read until we get the cursor response (first 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() {
-        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) {
-                let readResult;
-                try {
-                    readResult = await reader.read();
-                }
-                catch (error) {
-                    wrapAbortError(error);
-                }
-                if (readResult.done)
-                    break;
-                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);
-                    if (line) {
-                        yield JSON.parse(line);
-                    }
-                }
-            }
-            // Process any remaining data in the buffer
-            if (buffer.trim()) {
-                yield JSON.parse(buffer.trim());
-            }
-        }
-        finally {
-            reader.releaseLock();
-        }
-    }
-    return { response: cursorResponse, entries: parseEntries() };
-}
-export async function executePipeline(url, authToken, request, remoteEncryptionKey, signal) {
-    const headers = {
-        'Content-Type': 'application/json',
-    };
-    if (authToken) {
-        headers['Authorization'] = `Bearer ${authToken}`;
-    }
-    if (remoteEncryptionKey) {
-        headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
-    }
-    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}`);
-    }
-    return response.json();
-}