@tursodatabase/serverless 0.1.2 → 0.2.0

package/README.md

@@ -1,9 +1,22 @@
-# Turso serverless JavaScript driver
+<p align="center">
+  <h1 align="center">Turso Serverless Driver for JavaScript</h1>
+</p>
+
+<p align="center">
+  <a title="JavaScript" target="_blank" href="https://www.npmjs.com/package/@tursodatabase/serverless"><img alt="npm" src="https://img.shields.io/npm/v/@tursodatabase/serverless"></a>
+  <a title="MIT" target="_blank" href="https://github.com/tursodatabase/turso/blob/main/LICENSE.md"><img src="http://img.shields.io/badge/license-MIT-orange.svg?style=flat-square"></a>
+</p>
+<p align="center">
+  <a title="Users Discord" target="_blank" href="https://tur.so/discord"><img alt="Chat with other users of Turso on Discord" src="https://img.shields.io/discord/933071162680958986?label=Discord&logo=Discord&style=social"></a>
+</p>
+
+---
+
+## About
 
 A serverless database driver for Turso Cloud, using only `fetch()`. Connect to your database from serverless and edge functions, such as Cloudflare Workers and Vercel.
 
-> [!NOTE]
-> This driver is experimental and, therefore, subject to change at any time.
+> **⚠️ Warning:** This software is in BETA. It may still contain bugs and unexpected behavior. Use caution with production data and ensure you have backups.
 
 ## Installation
 
@@ -11,7 +24,9 @@ A serverless database driver for Turso Cloud, using only `fetch()`. Connect to y
 npm install @tursodatabase/serverless
 ```
 
-## Usage
+## Getting Started
+
+### Basic Usage
 
 ```javascript
 import { connect } from "@tursodatabase/serverless";
@@ -36,7 +51,11 @@ console.log(rows);
 for await (const row of stmt.iterate([123])) {
   console.log(row);
 }
+```
+
+### Batch Operations
 
+```javascript
 // Execute multiple statements in a batch
 await conn.batch([
   "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)",
@@ -45,9 +64,9 @@ await conn.batch([
 ]);
 ```
 
-### Compatibility layer for libSQL API
+### libSQL Compatibility Layer
 
-This driver supports the libSQL API as a compatibility layer.
+For existing libSQL applications, use the compatibility layer:
 
 ```javascript
 import { createClient } from "@tursodatabase/serverless/compat";
@@ -73,6 +92,21 @@ await client.batch([
 
 Check out the `examples/` directory for complete usage examples.
 
+## API Reference
+
+For complete API documentation, see [JavaScript API Reference](../../docs/javascript-api-reference.md).
+
+## Related Packages
+
+* The [@tursodatabase/database](https://www.npmjs.com/package/@tursodatabase/database) package provides the Turso in-memory database, compatible with SQLite.
+* The [@tursodatabase/sync](https://www.npmjs.com/package/@tursodatabase/sync) package provides bidirectional sync between a local Turso database and Turso Cloud. 
+
 ## License
 
-MIT
+This project is licensed under the [MIT license](../../LICENSE.md).
+
+## Support
+
+- [GitHub Issues](https://github.com/tursodatabase/turso/issues)
+- [Documentation](https://docs.turso.tech)
+- [Discord Community](https://tur.so/discord)

package/dist/compat.d.ts

@@ -2,16 +2,22 @@
  * Configuration options for creating a libSQL-compatible client.
  *
  * @remarks
- * This interface matches the libSQL client configuration but only `url` and `authToken`
- * are supported in the serverless compatibility layer. Other options will throw validation errors.
+ * This interface matches the libSQL client configuration. The `url`, `authToken`, and
+ * `remoteEncryptionKey` options are supported in the serverless compatibility layer.
+ * Other options will throw validation errors.
  */
 export interface Config {
     /** Database URL (required) */
     url: string;
     /** Authentication token for the database */
     authToken?: string;
-    /** @deprecated Database encryption key - not supported in serverless mode */
+    /** @deprecated Local database encryption key - not supported in serverless mode */
     encryptionKey?: string;
+    /**
+     * Encryption key for the remote database (base64 encoded)
+     * to enable access to encrypted Turso Cloud databases.
+     */
+    remoteEncryptionKey?: string;
     /** @deprecated Sync server URL - not supported in serverless mode */
     syncUrl?: string;
     /** @deprecated Sync frequency in seconds - not supported in serverless mode */

package/dist/compat.js

@@ -13,10 +13,12 @@ export class LibsqlError extends Error {
 class LibSQLClient {
     constructor(config) {
         this._closed = false;
+        this._defaultSafeIntegers = false;
         this.validateConfig(config);
         const sessionConfig = {
             url: config.url,
-            authToken: config.authToken || ''
+            authToken: config.authToken || '',
+            remoteEncryptionKey: config.remoteEncryptionKey
         };
         this.session = new Session(sessionConfig);
     }
@@ -52,7 +54,7 @@ class LibSQLClient {
         }
         if (unsupportedOptions.length > 0) {
             const optionsList = unsupportedOptions.map(opt => `'${opt.key}'`).join(', ');
-            throw new LibsqlError(`Unsupported configuration options: ${optionsList}. Only 'url' and 'authToken' are supported in the serverless compatibility layer.`, "UNSUPPORTED_CONFIG");
+            throw new LibsqlError(`Unsupported configuration options: ${optionsList}. Only 'url', 'authToken', and 'remoteEncryptionKey' are supported in the serverless compatibility layer.`, "UNSUPPORTED_CONFIG");
         }
         // Validate required options
         if (!config.url) {
@@ -108,15 +110,8 @@ class LibSQLClient {
             else {
                 normalizedStmt = this.normalizeStatement(stmtOrSql);
             }
-            await this.session.sequence(normalizedStmt.sql);
-            // Return empty result set for sequence execution
-            return this.convertResult({
-                columns: [],
-                columnTypes: [],
-                rows: [],
-                rowsAffected: 0,
-                lastInsertRowid: undefined
-            });
+            const result = await this.session.execute(normalizedStmt.sql, normalizedStmt.args, this._defaultSafeIntegers);
+            return this.convertResult(result);
         }
         catch (error) {
             throw new LibsqlError(error.message, "EXECUTE_ERROR");

package/dist/connection.d.ts

@@ -14,23 +14,45 @@ export interface Config extends SessionConfig {
 export declare class Connection {
     private config;
     private session;
+    private isOpen;
+    private defaultSafeIntegerMode;
+    private _inTransaction;
     constructor(config: Config);
+    /**
+     * Whether the database is currently in a transaction.
+     */
+    get inTransaction(): boolean;
     /**
      * Prepare a SQL statement for execution.
      *
      * Each prepared statement gets its own session to avoid conflicts during concurrent execution.
+     * This method fetches column metadata using the describe functionality.
      *
      * @param sql - The SQL statement to prepare
-     * @returns A Statement object that can be executed multiple ways
+     * @returns A Promise that resolves to a Statement object with column metadata
      *
      * @example
      * ```typescript
-     * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+     * const stmt = await client.prepare("SELECT * FROM users WHERE id = ?");
+     * const columns = stmt.columns();
      * const user = await stmt.get([123]);
-     * const allUsers = await stmt.all();
      * ```
      */
-    prepare(sql: string): Statement;
+    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[]): Promise<any>;
     /**
      * Execute a SQL statement and return all results.
      *
@@ -39,7 +61,7 @@ export declare class Connection {
      *
      * @example
      * ```typescript
-     * const result = await client.execute("SELECT * FROM users");
+     * const result = await client.exec("SELECT * FROM users");
      * console.log(result.rows);
      * ```
      */
@@ -68,12 +90,38 @@ export declare class Connection {
      * @returns Promise resolving to the result of the pragma
      */
     pragma(pragma: string): 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.

package/dist/connection.js

@@ -8,43 +8,91 @@ import { Statement } from './statement.js';
  */
 export class Connection {
     constructor(config) {
+        this.isOpen = true;
+        this.defaultSafeIntegerMode = false;
+        this._inTransaction = false;
         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.
      *
      * Each prepared statement gets its own session to avoid conflicts during concurrent execution.
+     * This method fetches column metadata using the describe functionality.
      *
      * @param sql - The SQL statement to prepare
-     * @returns A Statement object that can be executed multiple ways
+     * @returns A Promise that resolves to a Statement object with column metadata
      *
      * @example
      * ```typescript
-     * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+     * const stmt = await client.prepare("SELECT * FROM users WHERE id = ?");
+     * const columns = stmt.columns();
      * const user = await stmt.get([123]);
-     * const allUsers = await stmt.all();
      * ```
      */
-    prepare(sql) {
-        return new Statement(this.config, sql);
+    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 = new Statement(this.config, sql, description.cols);
+        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");
+     * const result = await client.execute("SELECT * FROM users WHERE id = ?", [123]);
+     * console.log(result.rows);
+     * ```
+     */
+    async execute(sql, args) {
+        if (!this.isOpen) {
+            throw new TypeError("The database connection is not open");
+        }
+        return this.session.execute(sql, args || [], this.defaultSafeIntegerMode);
+    }
+    /**
+     * 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) {
+        if (!this.isOpen) {
+            throw new TypeError("The database connection is not open");
+        }
         return this.session.sequence(sql);
     }
     /**
@@ -73,17 +121,93 @@ export class Connection {
      * @returns Promise resolving to the result of the pragma
      */
     async pragma(pragma) {
+        if (!this.isOpen) {
+            throw new TypeError("The database connection is not open");
+        }
         const sql = `PRAGMA ${pragma}`;
         return this.session.execute(sql);
     }
+    /**
+     * 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.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { Connection, connect, type Config } from './connection.js';
 export { Statement } from './statement.js';
 export { DatabaseError } from './error.js';
+export { type Column, ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/index.js

@@ -2,3 +2,4 @@
 export { Connection, connect } from './connection.js';
 export { Statement } from './statement.js';
 export { DatabaseError } from './error.js';
+export { ENCRYPTION_KEY_HEADER } from './protocol.js';

package/dist/protocol.d.ts

@@ -51,9 +51,21 @@ export interface SequenceRequest {
 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)[];
+    requests: (ExecuteRequest | BatchRequest | SequenceRequest | CloseRequest | DescribeRequest)[];
 }
 export interface PipelineResponse {
     baton: string | null;
@@ -61,8 +73,8 @@ export interface PipelineResponse {
     results: Array<{
         type: 'ok' | 'error';
         response?: {
-            type: 'execute' | 'batch' | 'sequence' | 'close';
-            result?: ExecuteResult;
+            type: 'execute' | 'batch' | 'sequence' | 'close' | 'describe';
+            result?: ExecuteResult | DescribeResult;
         };
         error?: {
             message: string;
@@ -71,7 +83,7 @@ export interface PipelineResponse {
     }>;
 }
 export declare function encodeValue(value: any): Value;
-export declare function decodeValue(value: Value): any;
+export declare function decodeValue(value: Value, safeIntegers?: boolean): any;
 export interface CursorRequest {
     baton: string | null;
     batch: {
@@ -94,8 +106,10 @@ export interface CursorEntry {
         code: string;
     };
 }
-export declare function executeCursor(url: string, authToken: string, request: CursorRequest): Promise<{
+/** HTTP header key for the encryption key */
+export declare const ENCRYPTION_KEY_HEADER = "x-turso-encryption-key";
+export declare function executeCursor(url: string, authToken: string | undefined, request: CursorRequest, remoteEncryptionKey?: string): Promise<{
     response: CursorResponse;
     entries: AsyncGenerator<CursorEntry>;
 }>;
-export declare function executePipeline(url: string, authToken: string, request: PipelineRequest): Promise<PipelineResponse>;
+export declare function executePipeline(url: string, authToken: string | undefined, request: PipelineRequest, remoteEncryptionKey?: string): Promise<PipelineResponse>;

package/dist/protocol.js

@@ -4,11 +4,17 @@ export function encodeValue(value) {
         return { type: 'null' };
     }
     if (typeof value === 'number') {
-        if (Number.isInteger(value)) {
-            return { type: 'integer', value: value.toString() };
+        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 };
     }
@@ -18,11 +24,14 @@ export function encodeValue(value) {
     }
     return { type: 'text', value: String(value) };
 }
-export function decodeValue(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;
@@ -35,20 +44,28 @@ export function decodeValue(value) {
                 for (let i = 0; i < binaryString.length; i++) {
                     bytes[i] = binaryString.charCodeAt(i);
                 }
-                return bytes;
+                return Buffer.from(bytes);
             }
             return null;
         default:
             return null;
     }
 }
-export async function executeCursor(url, authToken, request) {
+/** HTTP header key for the encryption key */
+export const ENCRYPTION_KEY_HEADER = 'x-turso-encryption-key';
+export async function executeCursor(url, authToken, request, remoteEncryptionKey) {
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (authToken) {
+        headers['Authorization'] = `Bearer ${authToken}`;
+    }
+    if (remoteEncryptionKey) {
+        headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
+    }
     const response = await fetch(`${url}/v3/cursor`, {
         method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${authToken}`,
-        },
+        headers,
         body: JSON.stringify(request),
     });
     if (!response.ok) {
@@ -127,13 +144,19 @@ export async function executeCursor(url, authToken, request) {
     }
     return { response: cursorResponse, entries: parseEntries() };
 }
-export async function executePipeline(url, authToken, request) {
+export async function executePipeline(url, authToken, request, remoteEncryptionKey) {
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (authToken) {
+        headers['Authorization'] = `Bearer ${authToken}`;
+    }
+    if (remoteEncryptionKey) {
+        headers[ENCRYPTION_KEY_HEADER] = remoteEncryptionKey;
+    }
     const response = await fetch(`${url}/v3/pipeline`, {
         method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${authToken}`,
-        },
+        headers,
         body: JSON.stringify(request),
     });
     if (!response.ok) {

package/dist/session.d.ts

@@ -1,12 +1,17 @@
-import { type CursorResponse, type CursorEntry } from './protocol.js';
+import { type CursorResponse, type CursorEntry, type DescribeResult } from './protocol.js';
 /**
  * Configuration options for a session.
  */
 export interface SessionConfig {
     /** Database URL */
     url: string;
-    /** Authentication token */
-    authToken: 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;
 }
 /**
  * A database session that manages the connection state and baton.
@@ -19,14 +24,22 @@ export declare class Session {
     private baton;
     private baseUrl;
     constructor(config: SessionConfig);
+    /**
+     * 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): 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>): Promise<any>;
+    execute(sql: string, args?: any[] | Record<string, any>, safeIntegers?: boolean): Promise<any>;
     /**
      * Execute a SQL statement and return the raw response and entries.
      *
@@ -44,7 +57,7 @@ export declare class Session {
      * @param entries - Async generator of cursor entries
      * @returns Promise resolving to the processed result
      */
-    processCursorEntries(entries: AsyncGenerator<CursorEntry>): Promise<any>;
+    processCursorEntries(entries: AsyncGenerator<CursorEntry>, safeIntegers?: boolean): Promise<any>;
     /**
      * Create a row object with both array and named property access.
      *

package/dist/session.js

@@ -18,16 +18,48 @@ export class Session {
         this.config = config;
         this.baseUrl = normalizeUrl(config.url);
     }
+    /**
+     * 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) {
+        const request = {
+            baton: this.baton,
+            requests: [{
+                    type: "describe",
+                    sql: sql
+                }]
+        };
+        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
+        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');
+            }
+            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 = []) {
+    async execute(sql, args = [], safeIntegers = false) {
         const { response, entries } = await this.executeRaw(sql, args);
-        const result = await this.processCursorEntries(entries);
+        const result = await this.processCursorEntries(entries, safeIntegers);
         return result;
     }
     /**
@@ -86,7 +118,7 @@ export class Session {
                     }]
             }
         };
-        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request);
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -99,7 +131,7 @@ export class Session {
      * @param entries - Async generator of cursor entries
      * @returns Promise resolving to the processed result
      */
-    async processCursorEntries(entries) {
+    async processCursorEntries(entries, safeIntegers = false) {
         let columns = [];
         let columnTypes = [];
         let rows = [];
@@ -115,7 +147,7 @@ export class Session {
                     break;
                 case 'row':
                     if (entry.row) {
-                        const decodedRow = entry.row.map(decodeValue);
+                        const decodedRow = entry.row.map(value => decodeValue(value, safeIntegers));
                         const rowObject = this.createRowObject(decodedRow, columns);
                         rows.push(rowObject);
                     }
@@ -184,7 +216,7 @@ export class Session {
                 }))
             }
         };
-        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request);
+        const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -225,7 +257,7 @@ export class Session {
                     sql: sql
                 }]
         };
-        const response = await executePipeline(this.baseUrl, this.config.authToken, request);
+        const response = await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
         this.baton = response.baton;
         if (response.base_url) {
             this.baseUrl = response.base_url;
@@ -254,7 +286,7 @@ export class Session {
                             type: "close"
                         }]
                 };
-                await executePipeline(this.baseUrl, this.config.authToken, request);
+                await executePipeline(this.baseUrl, this.config.authToken, request, this.config.remoteEncryptionKey);
             }
             catch (error) {
                 // Ignore errors during close, as the connection might already be closed

package/dist/statement.d.ts

@@ -1,3 +1,4 @@
+import { type Column } from './protocol.js';
 import { type SessionConfig } from './session.js';
 /**
  * A prepared SQL statement that can be executed in multiple ways.
@@ -12,7 +13,26 @@ export declare class Statement {
     private session;
     private sql;
     private presentationMode;
-    constructor(sessionConfig: SessionConfig, sql: string);
+    private safeIntegerMode;
+    private columnMetadata;
+    constructor(sessionConfig: SessionConfig, sql: string, columns?: Column[]);
+    /**
+     * 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.
      *
@@ -27,6 +47,40 @@ export declare class Statement {
      * ```
      */
     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[];
     /**
      * Executes the prepared statement.
      *

package/dist/statement.js

@@ -11,10 +11,31 @@ import { DatabaseError } from './error.js';
  * - `iterate(args?)`: Returns an async iterator for streaming results
  */
 export class Statement {
-    constructor(sessionConfig, sql) {
+    constructor(sessionConfig, sql, columns) {
         this.presentationMode = 'expanded';
+        this.safeIntegerMode = false;
         this.session = new Session(sessionConfig);
         this.sql = sql;
+        this.columnMetadata = columns || [];
+    }
+    /**
+     * 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() {
+        return this.columnMetadata.length > 0;
     }
     /**
      * Enable raw mode to return arrays instead of objects.
@@ -33,6 +54,51 @@ export class Statement {
         this.presentationMode = raw === false ? 'expanded' : 'raw';
         return this;
     }
+    /**
+     * 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) {
+        this.presentationMode = pluck === false ? 'expanded' : 'pluck';
+        return this;
+    }
+    /**
+     * 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) {
+        this.safeIntegerMode = toggle === false ? false : true;
+        return this;
+    }
+    /**
+     * 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() {
+        return this.columnMetadata.map(col => ({
+            name: col.name,
+            type: col.decltype
+        }));
+    }
     /**
      * Executes the prepared statement.
      *
@@ -48,7 +114,7 @@ export class Statement {
      */
     async run(args) {
         const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs);
+        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
         return { changes: result.rowsAffected, lastInsertRowid: result.lastInsertRowid };
     }
     /**
@@ -68,17 +134,26 @@ export class Statement {
      */
     async get(args) {
         const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs);
+        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
         const row = result.rows[0];
         if (!row) {
             return undefined;
         }
+        if (this.presentationMode === 'pluck') {
+            // In pluck mode, return only the first column value
+            return row[0];
+        }
         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;
+        // In expanded mode, convert to plain object with named properties  
+        const obj = {};
+        result.columns.forEach((col, i) => {
+            obj[col] = row[i];
+        });
+        return obj;
     }
     /**
      * Execute the statement and return all rows.
@@ -95,13 +170,22 @@ export class Statement {
      */
     async all(args) {
         const normalizedArgs = this.normalizeArgs(args);
-        const result = await this.session.execute(this.sql, normalizedArgs);
+        const result = await this.session.execute(this.sql, normalizedArgs, this.safeIntegerMode);
+        if (this.presentationMode === 'pluck') {
+            // In pluck mode, return only the first column value from each row
+            return result.rows.map((row) => row[0]);
+        }
         if (this.presentationMode === 'raw') {
-            // In raw mode, return arrays of values
-            // Each row is already an array with column properties added
             return result.rows.map((row) => [...row]);
         }
-        return result.rows;
+        // In expanded mode, convert rows to plain objects with named properties
+        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.
@@ -134,14 +218,22 @@ export class Statement {
                     break;
                 case 'row':
                     if (entry.row) {
-                        const decodedRow = entry.row.map(decodeValue);
-                        if (this.presentationMode === 'raw') {
+                        const decodedRow = entry.row.map(value => decodeValue(value, this.safeIntegerMode));
+                        if (this.presentationMode === 'pluck') {
+                            // In pluck mode, yield only the first column value
+                            yield decodedRow[0];
+                        }
+                        else if (this.presentationMode === 'raw') {
                             // In raw mode, yield arrays of values
                             yield decodedRow;
                         }
                         else {
-                            const rowObject = this.session.createRowObject(decodedRow, columns);
-                            yield rowObject;
+                            // In expanded mode, yield plain objects with named properties (consistent with all())
+                            const obj = {};
+                            columns.forEach((col, i) => {
+                                obj[col] = decodedRow[i];
+                            });
+                            yield obj;
                         }
                     }
                     break;

package/package.json

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

package/dist/transaction.d.ts

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

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