@tursodatabase/serverless 1.1.1 → 1.1.2-pre.1

package/dist/index.d.ts

@@ -1,5 +1,516 @@
-export { Connection, connect, type Config } from './connection.js';
-export { Statement } from './statement.js';
-export { Session, type SessionConfig } from './session.js';
-export { DatabaseError, TimeoutError } from './error.js';
-export { type Column, type QueryOptions, ENCRYPTION_KEY_HEADER } from './protocol.js';
+interface Value {
+    type: 'null' | 'integer' | 'float' | 'text' | 'blob';
+    value?: string | number;
+    base64?: string;
+}
+interface Column {
+    name: string;
+    decltype: string;
+}
+interface DescribeResult {
+    params: Array<{
+        name?: string;
+    }>;
+    cols: Column[];
+    is_explain: boolean;
+    is_readonly: boolean;
+}
+interface CursorResponse {
+    baton: string | null;
+    base_url: string | null;
+}
+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 | number;
+    error?: {
+        message: string;
+        code: string;
+    };
+}
+/** HTTP header key for the encryption key */
+declare const ENCRYPTION_KEY_HEADER = "x-turso-encryption-key";
+/** Per-query timeout options. Overrides defaultQueryTimeout for this call. */
+interface QueryOptions {
+    /** Per-query timeout in milliseconds. Overrides defaultQueryTimeout for this call. */
+    queryTimeout?: number;
+}
+
+/**
+ * Configuration options for a session.
+ */
+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.
+ */
+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>;
+}
+
+declare class AsyncLock {
+    private locked;
+    private queue;
+    acquire(): Promise<void>;
+    release(): void;
+}
+
+/**
+ * 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
+ */
+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;
+}
+
+/**
+ * Configuration options for connecting to a Turso database.
+ */
+interface Config extends SessionConfig {
+}
+/**
+ * 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))
+ * );
+ * ```
+ */
+declare class Connection {
+    private config;
+    private session;
+    private isOpen;
+    private defaultSafeIntegerMode;
+    private _inTransaction;
+    private execLock;
+    constructor(config: Config);
+    /**
+     * Whether the database is currently in a transaction.
+     */
+    get inTransaction(): boolean;
+    /**
+     * 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]);
+     * ```
+     */
+    prepare(sql: string): Promise<Statement>;
+    /**
+     * 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);
+     * ```
+     */
+    execute(sql: string, args?: any[], queryOptions?: QueryOptions): Promise<any>;
+    /**
+     * 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);
+     * ```
+     */
+    exec(sql: string, queryOptions?: QueryOptions): Promise<any>;
+    /**
+     * 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')"
+     * ]);
+     * ```
+     */
+    batch(statements: string[], mode?: string, queryOptions?: QueryOptions): Promise<any>;
+    /**
+     * Execute a pragma.
+     *
+     * @param pragma - The pragma to execute
+     * @returns Promise resolving to the result of the pragma
+     */
+    pragma(pragma: string, queryOptions?: QueryOptions): Promise<any>;
+    /**
+     * Sets the default safe integers mode for all statements from this connection.
+     *
+     * @param toggle - Whether to use safe integers by default.
+     */
+    defaultSafeIntegers(toggle?: boolean): void;
+    /**
+     * 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: (...args: any[]) => any): any;
+    /**
+     * Close the connection.
+     *
+     * This sends a close request to the server to properly clean up the stream.
+     */
+    close(): Promise<void>;
+    reconnect(): Promise<void>;
+}
+/**
+ * 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
+ */
+declare function connect(config: Config): Connection;
+
+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.
+ */
+declare class TimeoutError extends DatabaseError {
+    constructor(message?: string, cause?: Error);
+}
+
+export { type Column, type Config, Connection, DatabaseError, ENCRYPTION_KEY_HEADER, type QueryOptions, Session, type SessionConfig, Statement, TimeoutError, connect };