@tursodatabase/serverless 0.1.1 → 0.1.3

package/dist/statement.d.ts

@@ -11,11 +11,26 @@ import { type SessionConfig } from './session.js';
 export declare class Statement {
     private session;
     private sql;
+    private presentationMode;
     constructor(sessionConfig: SessionConfig, sql: string);
+    /**
+     * 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;
     /**
      * Executes the prepared statement.
      *
-     * @param args - Optional array of parameter values for the SQL statement
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to the result of the statement
      *
      * @example
@@ -25,12 +40,12 @@ export declare class Statement {
      * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
      * ```
      */
-    run(args?: any[]): Promise<any>;
+    run(args?: any): Promise<any>;
     /**
      * 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
+     * @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
@@ -41,11 +56,11 @@ export declare class Statement {
      * }
      * ```
      */
-    get(args?: any[]): Promise<any>;
+    get(args?: any): Promise<any>;
     /**
      * Execute the statement and return all rows.
      *
-     * @param args - Optional array of parameter values for the SQL statement
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to an array of all result rows
      *
      * @example
@@ -55,14 +70,14 @@ export declare class Statement {
      * console.log(`Found ${activeUsers.length} active users`);
      * ```
      */
-    all(args?: any[]): Promise<any[]>;
+    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
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns AsyncGenerator that yields individual rows
      *
      * @example
@@ -74,5 +89,10 @@ export declare class Statement {
      * }
      * ```
      */
-    iterate(args?: any[]): AsyncGenerator<any>;
+    iterate(args?: any): AsyncGenerator<any>;
+    /**
+     * Normalize arguments to handle both single values and arrays.
+     * Matches the behavior of the native bindings.
+     */
+    private normalizeArgs;
 }

package/dist/statement.js

@@ -1,5 +1,6 @@
 import { decodeValue } from './protocol.js';
 import { Session } from './session.js';
+import { DatabaseError } from './error.js';
 /**
  * A prepared SQL statement that can be executed in multiple ways.
  *
@@ -11,13 +12,31 @@ import { Session } from './session.js';
  */
 export class Statement {
     constructor(sessionConfig, sql) {
+        this.presentationMode = 'expanded';
         this.session = new Session(sessionConfig);
         this.sql = sql;
     }
+    /**
+     * 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) {
+        this.presentationMode = raw === false ? 'expanded' : 'raw';
+        return this;
+    }
     /**
      * Executes the prepared statement.
      *
-     * @param args - Optional array of parameter values for the SQL statement
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to the result of the statement
      *
      * @example
@@ -27,15 +46,16 @@ export class Statement {
      * console.log(`Inserted user with ID ${result.lastInsertRowid}`);
      * ```
      */
-    async run(args = []) {
-        const result = await this.session.execute(this.sql, args);
+    async run(args) {
+        const normalizedArgs = this.normalizeArgs(args);
+        const result = await this.session.execute(this.sql, normalizedArgs);
         return { changes: result.rowsAffected, lastInsertRowid: result.lastInsertRowid };
     }
     /**
      * 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
+     * @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
@@ -46,14 +66,24 @@ export class Statement {
      * }
      * ```
      */
-    async get(args = []) {
-        const result = await this.session.execute(this.sql, args);
-        return result.rows[0] || null;
+    async get(args) {
+        const normalizedArgs = this.normalizeArgs(args);
+        const result = await this.session.execute(this.sql, normalizedArgs);
+        const row = result.rows[0];
+        if (!row) {
+            return undefined;
+        }
+        if (this.presentationMode === 'raw') {
+            // In raw mode, return the row as a plain array (it already is one)
+            // The row object is already an array with column properties added
+            return [...row];
+        }
+        return row;
     }
     /**
      * Execute the statement and return all rows.
      *
-     * @param args - Optional array of parameter values for the SQL statement
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns Promise resolving to an array of all result rows
      *
      * @example
@@ -63,9 +93,19 @@ export class Statement {
      * console.log(`Found ${activeUsers.length} active users`);
      * ```
      */
-    async all(args = []) {
-        const result = await this.session.execute(this.sql, args);
-        return result.rows;
+    async all(args) {
+        const normalizedArgs = this.normalizeArgs(args);
+        const result = await this.session.execute(this.sql, normalizedArgs);
+        if (this.presentationMode === 'raw') {
+            return result.rows.map((row) => [...row]);
+        }
+        return result.rows.map((row) => {
+            const obj = {};
+            result.columns.forEach((col, i) => {
+                obj[col] = row[i];
+            });
+            return obj;
+        });
     }
     /**
      * Execute the statement and return an async iterator for streaming results.
@@ -73,7 +113,7 @@ export class Statement {
      * 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
+     * @param args - Optional array of parameter values or object with named parameters
      * @returns AsyncGenerator that yields individual rows
      *
      * @example
@@ -85,8 +125,9 @@ export class Statement {
      * }
      * ```
      */
-    async *iterate(args = []) {
-        const { response, entries } = await this.session.executeRaw(this.sql, args);
+    async *iterate(args) {
+        const normalizedArgs = this.normalizeArgs(args);
+        const { response, entries } = await this.session.executeRaw(this.sql, normalizedArgs);
         let columns = [];
         for await (const entry of entries) {
             switch (entry.type) {
@@ -98,14 +139,40 @@ export class Statement {
                 case 'row':
                     if (entry.row) {
                         const decodedRow = entry.row.map(decodeValue);
-                        const rowObject = this.session.createRowObject(decodedRow, columns);
-                        yield rowObject;
+                        if (this.presentationMode === 'raw') {
+                            // In raw mode, yield arrays of values
+                            yield decodedRow;
+                        }
+                        else {
+                            const rowObject = this.session.createRowObject(decodedRow, columns);
+                            yield rowObject;
+                        }
                     }
                     break;
                 case 'step_error':
                 case 'error':
-                    throw new Error(entry.error?.message || 'SQL execution failed');
+                    throw new DatabaseError(entry.error?.message || 'SQL execution failed');
             }
         }
     }
+    /**
+     * Normalize arguments to handle both single values and arrays.
+     * Matches the behavior of the native bindings.
+     */
+    normalizeArgs(args) {
+        // No arguments provided
+        if (args === undefined) {
+            return [];
+        }
+        // If it's an array, return as-is
+        if (Array.isArray(args)) {
+            return args;
+        }
+        // Check if it's a plain object (for named parameters)
+        if (args !== null && typeof args === 'object' && args.constructor === Object) {
+            return args;
+        }
+        // Single value - wrap in array
+        return [args];
+    }
 }

package/dist/transaction.d.ts

@@ -0,0 +1,131 @@
+import { type SessionConfig } from "./session.js";
+/**
+ * Transaction mode for controlling transaction behavior.
+ */
+export type TransactionMode = "write" | "read" | "deferred";
+/**
+ * Transactions use a dedicated session to maintain state across multiple operations.
+ * All operations within a transaction are executed atomically - they either all
+ * succeed or all fail.
+ */
+export declare class Transaction {
+    private session;
+    private _closed;
+    private _committed;
+    private _rolledBack;
+    private constructor();
+    /**
+     * Create a new transaction instance.
+     *
+     * @param sessionConfig - Session configuration
+     * @param mode - Transaction mode
+     * @returns Promise resolving to a new Transaction instance
+     */
+    static create(sessionConfig: SessionConfig, mode?: TransactionMode): Promise<Transaction>;
+    private initializeTransaction;
+    /**
+     * Execute a SQL statement within the transaction.
+     *
+     * @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 tx = await client.transaction();
+     * const result = await tx.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+     * await tx.commit();
+     * ```
+     */
+    execute(sql: string, args?: any[]): Promise<any>;
+    /**
+     * Execute multiple SQL statements as a batch within the transaction.
+     *
+     * @param statements - Array of SQL statements to execute
+     * @returns Promise resolving to batch execution results
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.transaction();
+     * await tx.batch([
+     *   "INSERT INTO users (name) VALUES ('Alice')",
+     *   "INSERT INTO users (name) VALUES ('Bob')"
+     * ]);
+     * await tx.commit();
+     * ```
+     */
+    batch(statements: string[]): 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: any;
+        entries: AsyncGenerator<any>;
+    }>;
+    /**
+     * Commit the transaction, making all changes permanent.
+     *
+     * @returns Promise that resolves when the transaction is committed
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.transaction();
+     * await tx.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+     * await tx.commit(); // Changes are now permanent
+     * ```
+     */
+    commit(): Promise<void>;
+    /**
+     * Rollback the transaction, undoing all changes.
+     *
+     * @returns Promise that resolves when the transaction is rolled back
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.transaction();
+     * try {
+     *   await tx.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+     *   await tx.execute("INSERT INTO invalid_table VALUES (1)"); // This will fail
+     *   await tx.commit();
+     * } catch (error) {
+     *   await tx.rollback(); // Undo the first INSERT
+     * }
+     * ```
+     */
+    rollback(): Promise<void>;
+    /**
+     * Close the transaction without committing or rolling back.
+     *
+     * This will automatically rollback any uncommitted changes.
+     * It's safe to call this method multiple times.
+     */
+    close(): void;
+    /**
+     * Check if the transaction is closed.
+     *
+     * @returns True if the transaction has been committed, rolled back, or closed
+     */
+    get closed(): boolean;
+    /**
+     * Check if the transaction has been committed.
+     *
+     * @returns True if the transaction has been successfully committed
+     */
+    get committed(): boolean;
+    /**
+     * Check if the transaction has been rolled back.
+     *
+     * @returns True if the transaction has been rolled back
+     */
+    get rolledBack(): boolean;
+    /**
+     * Check transaction state and throw if it's not valid for operations.
+     *
+     * @throws Error if the transaction is closed
+     */
+    private checkState;
+}

package/dist/transaction.js

@@ -0,0 +1,207 @@
+import { Session } from "./session.js";
+import { DatabaseError } from "./error.js";
+/**
+ * Transactions use a dedicated session to maintain state across multiple operations.
+ * All operations within a transaction are executed atomically - they either all
+ * succeed or all fail.
+ */
+export class Transaction {
+    constructor(sessionConfig, mode = "deferred") {
+        this._closed = false;
+        this._committed = false;
+        this._rolledBack = false;
+        this.session = new Session(sessionConfig);
+    }
+    /**
+     * Create a new transaction instance.
+     *
+     * @param sessionConfig - Session configuration
+     * @param mode - Transaction mode
+     * @returns Promise resolving to a new Transaction instance
+     */
+    static async create(sessionConfig, mode = "deferred") {
+        const transaction = new Transaction(sessionConfig, mode);
+        await transaction.initializeTransaction(mode);
+        return transaction;
+    }
+    async initializeTransaction(mode) {
+        let beginStatement;
+        switch (mode) {
+            case "write":
+                beginStatement = "BEGIN IMMEDIATE";
+                break;
+            case "read":
+                beginStatement = "BEGIN";
+                break;
+            case "deferred":
+            default:
+                beginStatement = "BEGIN DEFERRED";
+                break;
+        }
+        await this.session.execute(beginStatement);
+    }
+    /**
+     * Execute a SQL statement within the transaction.
+     *
+     * @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 tx = await client.transaction();
+     * const result = await tx.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+     * await tx.commit();
+     * ```
+     */
+    async execute(sql, args = []) {
+        this.checkState();
+        return this.session.execute(sql, args);
+    }
+    /**
+     * Execute multiple SQL statements as a batch within the transaction.
+     *
+     * @param statements - Array of SQL statements to execute
+     * @returns Promise resolving to batch execution results
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.transaction();
+     * await tx.batch([
+     *   "INSERT INTO users (name) VALUES ('Alice')",
+     *   "INSERT INTO users (name) VALUES ('Bob')"
+     * ]);
+     * await tx.commit();
+     * ```
+     */
+    async batch(statements) {
+        this.checkState();
+        return this.session.batch(statements);
+    }
+    /**
+     * 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 = []) {
+        this.checkState();
+        return this.session.executeRaw(sql, args);
+    }
+    /**
+     * Commit the transaction, making all changes permanent.
+     *
+     * @returns Promise that resolves when the transaction is committed
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.transaction();
+     * await tx.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+     * await tx.commit(); // Changes are now permanent
+     * ```
+     */
+    async commit() {
+        this.checkState();
+        try {
+            await this.session.execute("COMMIT");
+            this._committed = true;
+            this._closed = true;
+        }
+        catch (error) {
+            // If commit fails, the transaction is still open
+            if (error instanceof Error) {
+                throw new DatabaseError(error.message);
+            }
+            throw new DatabaseError('Transaction commit failed');
+        }
+    }
+    /**
+     * Rollback the transaction, undoing all changes.
+     *
+     * @returns Promise that resolves when the transaction is rolled back
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.transaction();
+     * try {
+     *   await tx.execute("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+     *   await tx.execute("INSERT INTO invalid_table VALUES (1)"); // This will fail
+     *   await tx.commit();
+     * } catch (error) {
+     *   await tx.rollback(); // Undo the first INSERT
+     * }
+     * ```
+     */
+    async rollback() {
+        if (this._closed) {
+            return; // Already closed, nothing to rollback
+        }
+        try {
+            await this.session.execute("ROLLBACK");
+        }
+        catch (error) {
+            // Rollback errors are generally not critical - the transaction is abandoned anyway
+        }
+        finally {
+            this._rolledBack = true;
+            this._closed = true;
+        }
+    }
+    /**
+     * Close the transaction without committing or rolling back.
+     *
+     * This will automatically rollback any uncommitted changes.
+     * It's safe to call this method multiple times.
+     */
+    close() {
+        if (!this._closed) {
+            // Async rollback - don't wait for it to complete
+            this.rollback().catch(() => {
+                // Ignore rollback errors on close
+            });
+        }
+    }
+    /**
+     * Check if the transaction is closed.
+     *
+     * @returns True if the transaction has been committed, rolled back, or closed
+     */
+    get closed() {
+        return this._closed;
+    }
+    /**
+     * Check if the transaction has been committed.
+     *
+     * @returns True if the transaction has been successfully committed
+     */
+    get committed() {
+        return this._committed;
+    }
+    /**
+     * Check if the transaction has been rolled back.
+     *
+     * @returns True if the transaction has been rolled back
+     */
+    get rolledBack() {
+        return this._rolledBack;
+    }
+    /**
+     * Check transaction state and throw if it's not valid for operations.
+     *
+     * @throws Error if the transaction is closed
+     */
+    checkState() {
+        if (this._closed) {
+            if (this._committed) {
+                throw new DatabaseError("Transaction has already been committed");
+            }
+            else if (this._rolledBack) {
+                throw new DatabaseError("Transaction has already been rolled back");
+            }
+            else {
+                throw new DatabaseError("Transaction has been closed");
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tursodatabase/serverless",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/client.d.ts

@@ -1,31 +0,0 @@
-import { type CursorResponse, type CursorEntry } from './protocol.js';
-export interface Config {
-    url: string;
-    authToken: string;
-}
-export declare class Statement {
-    private connection;
-    private sql;
-    private args;
-    constructor(connection: Connection, sql: string, args?: any[]);
-    get(): Promise<any>;
-    all(): Promise<any[]>;
-    iterate(): AsyncGenerator<any>;
-    private execute;
-}
-export declare class Connection {
-    private config;
-    private baton;
-    private baseUrl;
-    constructor(config: Config);
-    prepare(sql: string, args?: any[]): Statement;
-    execute(sql: string, args?: any[]): Promise<any>;
-    executeRaw(sql: string, args?: any[]): Promise<{
-        response: CursorResponse;
-        entries: AsyncGenerator<CursorEntry>;
-    }>;
-    private processCursorEntries;
-    createRowObject(values: any[], columns: string[]): any;
-    batch(statements: string[], mode?: string): Promise<any>;
-}
-export declare function connect(config: Config): Connection;