@tursodatabase/serverless 1.2.0-pre.1 → 1.2.0

package/dist/protocol.d.ts

@@ -0,0 +1,120 @@
+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

@@ -0,0 +1,199 @@
+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();
+}

package/dist/session.d.ts

@@ -0,0 +1,93 @@
+import { type CursorResponse, type CursorEntry, type DescribeResult, type QueryOptions } from './protocol.js';
+/**
+ * Configuration options for a session.
+ */
+export interface SessionConfig {
+    /** Database URL */
+    url: string;
+    /** Authentication token (optional for local development with turso dev) */
+    authToken?: string;
+    /**
+     * Encryption key for the remote database (base64 encoded)
+     * 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.
+ *
+ * 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);
+    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, queryOptions?: QueryOptions): Promise<DescribeResult>;
+    /**
+     * 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
+     */
+    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.
+     *
+     * @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
+     */
+    executeRaw(sql: string, args?: any[] | Record<string, any>, queryOptions?: QueryOptions): 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>, safeIntegers?: boolean): 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[], 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, queryOptions?: QueryOptions): 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>;
+}