Merge 'Add @tursodatabase/serverless package' from Pekka Enberg

This package is for serverless access to the Turso Cloud using SQL over
HTTP protocol. The purpose of this package is to provide the same
interface as `@tursodatabase/turso`, but for serverless environments
that cannot host the database engine.
The package also provides a `@libsql/client` compatibility layer in the
`@tursodatabase/serverless/compat` module for drop-in replacement for
existing clients.

Closes #2209

packages/turso-serverless/AGENT.md

@@ -0,0 +1,192 @@
+# Agent Development Guide
+
+This document provides guidance for LLMs working on the `@tursodatabase/serverless` TypeScript driver.
+
+## Project Overview
+
+This is a **fetch() API-compatible serverless database driver** for Turso Cloud that implements the SQL over HTTP protocol (internally called "hrana"). It's designed for serverless and edge compute environments like Cloudflare Workers and Vercel Edge Functions.
+
+### Key Features
+- **HTTP-based SQL execution** using the v3 cursor endpoint for streaming
+- **Native streaming API** with Connection/Statement pattern
+- **LibSQL compatibility layer** for drop-in replacement
+- **TypeScript-first** with full type safety
+- **Edge-optimized** using only `fetch()` API
+
+## Architecture
+
+### Core Files Structure
+```
+src/
+├── connection.ts    # Connection class and connect() function
+├── statement.ts     # Statement class with get()/all()/iterate() methods
+├── protocol.ts      # Low-level SQL over HTTP protocol implementation
+├── compat.ts        # LibSQL API compatibility layer
+├── compat/index.ts  # Compatibility layer exports
+└── index.ts         # Main package exports
+```
+
+### Package Exports
+- **Main API**: `@tursodatabase/serverless` - Native streaming API
+- **Compatibility**: `@tursodatabase/serverless/compat` - LibSQL-compatible API
+
+## Native API Design
+
+### Connection/Statement Pattern
+```typescript
+import { connect } from "@tursodatabase/serverless";
+
+const client = connect({ url, authToken });
+const stmt = client.prepare("SELECT * FROM users WHERE id = ?", [123]);
+
+// Three execution modes:
+const row = await stmt.get();        // First row or null
+const rows = await stmt.all();       // All rows as array  
+for await (const row of stmt.iterate()) { ... } // Streaming iterator
+```
+
+### Key Classes
+
+#### Connection
+- **Purpose**: Database connection and session management
+- **Methods**: `prepare()`, `execute()`, `batch()`, `executeRaw()`
+- **Internal**: Manages baton tokens, base URL updates, cursor streaming
+
+#### Statement  
+- **Purpose**: Prepared statement execution with multiple access patterns
+- **Methods**: `get()`, `all()`, `iterate()`
+- **Streaming**: `iterate()` provides row-by-row streaming via AsyncGenerator
+
+#### Protocol Layer
+- **Purpose**: HTTP cursor endpoint communication
+- **Key Function**: `executeCursor()` returns streaming cursor entries
+- **Protocol**: Uses v3 cursor endpoint (`/v3/cursor`) with newline-delimited JSON
+
+## LibSQL Compatibility Layer
+
+### Purpose
+Provides drop-in compatibility with the standard libSQL client API for existing applications.
+
+### Key Differences
+- **Entry Point**: `createClient()` instead of `connect()`
+- **Import Path**: `@tursodatabase/serverless/compat`
+- **API Surface**: Matches libSQL client interface exactly
+- **Config Validation**: Only supports `url` and `authToken`, validates against unsupported options
+
+### Supported vs Unsupported
+```typescript
+// ✅ Supported
+const client = createClient({ url, authToken });
+await client.execute(sql, args);
+await client.batch(statements);
+
+// ❌ Unsupported (throws LibsqlError)
+createClient({ url, authToken, encryptionKey: "..." }); // Validation error
+await client.transaction(); // Not implemented
+await client.sync(); // Not supported for remote
+```
+
+## Protocol Implementation
+
+### SQL over HTTP (v3 Cursor)
+- **Endpoint**: `POST /v3/cursor`
+- **Request**: JSON with baton, batch steps
+- **Response**: Streaming newline-delimited JSON entries
+- **Entry Types**: `step_begin`, `row`, `step_end`, `step_error`, `error`
+
+### Session Management
+- **Baton Tokens**: Maintain session continuity across requests
+- **Base URL Updates**: Handle server-side redirects/load balancing
+- **URL Normalization**: Convert `libsql://` to `https://` automatically
+
+## Testing Strategy
+
+### Integration Tests
+```
+integration-tests/
+├── serverless.test.mjs  # Native API tests
+└── compat.test.mjs      # Compatibility layer tests
+```
+
+### Test Requirements
+- **Environment Variables**: `TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN`
+- **Serial Execution**: All tests use `test.serial()` to avoid conflicts
+- **Real Database**: Tests run against actual Turso instance
+
+### Running Tests
+```bash
+npm test  # Runs all integration tests
+npm run build  # TypeScript compilation
+```
+
+## Development Guidelines
+
+### Code Organization
+- **Single Responsibility**: Each file has a clear, focused purpose
+- **Type Safety**: Full TypeScript coverage with proper imports
+- **Error Handling**: Use proper error classes (`LibsqlError` for compat)
+- **Streaming First**: Leverage AsyncGenerator for memory efficiency
+
+### Key Patterns
+- **Protocol Abstraction**: Keep protocol details in `protocol.ts`
+- **Compatibility Isolation**: LibSQL compatibility in separate module
+- **Row Objects**: Arrays with column name properties (non-enumerable)
+- **Config Validation**: Explicit validation with helpful error messages
+
+### Performance Considerations
+- **Streaming**: Use `iterate()` for large result sets
+- **Memory**: Cursor endpoint provides constant memory usage
+- **Latency**: First results available immediately with streaming
+
+## Common Tasks
+
+### Adding New Features
+1. **Protocol**: Add to `protocol.ts` if it requires HTTP changes
+2. **Connection**: Add to `connection.ts` for connection-level features  
+3. **Statement**: Add to `statement.ts` for statement-level features
+4. **Compatibility**: Update `compat.ts` if LibSQL compatibility needed
+5. **Tests**: Add integration tests for new functionality
+
+### Debugging Issues
+1. **Check Protocol**: Use `executeRaw()` to inspect cursor entries
+2. **Validate Config**: Ensure URL/auth token are correct
+3. **Test Streaming**: Compare `all()` vs `iterate()` behavior
+4. **Review Errors**: Check for `LibsqlError` vs generic errors
+
+### Extending Compatibility
+1. **Research LibSQL**: Check `resources/libsql-client-ts` for API patterns
+2. **Validate Config**: Add validation for unsupported options
+3. **Map Interfaces**: Convert between LibSQL and native formats
+4. **Test Coverage**: Ensure compatibility tests cover new features
+
+## Important Notes
+
+### Security
+- **No Secret Logging**: Never log auth tokens or sensitive data
+- **Validation**: Always validate inputs, especially in compatibility layer
+- **Error Messages**: Don't expose internal implementation details
+
+### Compatibility
+- **Breaking Changes**: Avoid breaking the native API
+- **LibSQL Parity**: Match LibSQL behavior exactly in compatibility layer
+- **Version Support**: Document which libSQL features are supported
+
+### Edge Cases
+- **Large Results**: Test with large datasets to verify streaming
+- **Network Issues**: Handle connection failures gracefully
+- **Protocol Evolution**: Be prepared for protocol version updates
+
+## Future Considerations
+
+### Potential Enhancements
+- **Transaction Support**: Interactive transactions in compatibility layer
+- **Prepared Statement Caching**: Cache prepared statements
+- **Connection Pooling**: Multiple concurrent connections
+- **Protocol Negotiation**: Support multiple protocol versions
+
+### Monitoring
+- **Performance Metrics**: Track query latency and throughput
+- **Error Rates**: Monitor protocol and application errors
+- **Resource Usage**: Memory and CPU usage in serverless environments
+
+This guide should help future contributors understand the architecture and maintain consistency across the codebase.

packages/turso-serverless/README.md

@@ -0,0 +1,78 @@
+# Turso serverless JavaScript driver
+
+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.
+
+## Installation
+
+```bash
+npm install @tursodatabase/serverless
+```
+
+## Usage
+
+```javascript
+import { connect } from "@tursodatabase/serverless";
+
+const conn = connect({
+  url: process.env.TURSO_DATABASE_URL,
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+
+// Prepare a statement
+const stmt = conn.prepare("SELECT * FROM users WHERE id = ?");
+
+// Get first row
+const row = await stmt.get([123]);
+console.log(row);
+
+// Get all rows
+const rows = await stmt.all([123]);
+console.log(rows);
+
+// Iterate through rows (streaming)
+for await (const row of stmt.iterate([123])) {
+  console.log(row);
+}
+
+// Execute multiple statements in a batch
+await conn.batch([
+  "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)",
+  "INSERT INTO users (email) VALUES ('user@example.com')",
+  "INSERT INTO users (email) VALUES ('admin@example.com')",
+]);
+```
+
+### Compatibility layer for libSQL API
+
+This driver supports the libSQL API as a compatibility layer.
+
+```javascript
+import { createClient } from "@tursodatabase/serverless/compat";
+
+const client = createClient({
+  url: process.env.TURSO_DATABASE_URL,
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+
+// Execute a single SQL statement
+const result = await client.execute("SELECT * FROM users WHERE id = ?", [123]);
+console.log(result.rows);
+
+// Execute multiple statements in a batch
+await client.batch([
+  "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)",
+  "INSERT INTO users (email) VALUES ('user@example.com')",
+  "INSERT INTO users (email) VALUES ('admin@example.com')",
+]);
+```
+
+## Examples
+
+Check out the `examples/` directory for complete usage examples.
+
+## License
+
+MIT

packages/turso-serverless/examples/remote-compat/README.md

@@ -0,0 +1,19 @@
+# Remote
+
+This example demonstrates how to use Turso Cloud.
+
+## Install Dependencies
+
+```bash
+npm i
+```
+
+## Running
+
+Execute the example:
+
+```bash
+TURSO_DATABASE_URL="..." TURSO_AUTH_TOKEN="..." node index.mjs
+```
+
+This will connect to a remote SQLite database, insert some data, and then query the results.

packages/turso-serverless/examples/remote-compat/index.mjs

@@ -0,0 +1,20 @@
+import { createClient } from "@tursodatabase/serverless/compat";
+
+const client = createClient({
+    url: process.env.TURSO_DATABASE_URL,
+    authToken: process.env.TURSO_AUTH_TOKEN,
+});
+
+await client.batch(
+    [
+        "CREATE TABLE IF NOT EXISTS users (email TEXT)",
+        "INSERT INTO users VALUES ('first@example.com')",
+        "INSERT INTO users VALUES ('second@example.com')",
+        "INSERT INTO users VALUES ('third@example.com')",
+    ],
+    "write",
+);
+
+const result = await client.execute("SELECT * FROM users");
+
+console.log("Users:", result.rows);

packages/turso-serverless/examples/remote-compat/package-lock.json

@@ -0,0 +1,30 @@
+{
+  "name": "batch",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "batch",
+      "version": "1.0.0",
+      "license": "MIT",
+      "dependencies": {
+        "@tursodatabase/serverless": "../.."
+      }
+    },
+    "../..": {
+      "name": "@tursodatabase/serverless",
+      "version": "1.0.0",
+      "license": "MIT",
+      "devDependencies": {
+        "@types/node": "^24.0.13",
+        "ava": "^6.4.1",
+        "typescript": "^5.8.3"
+      }
+    },
+    "node_modules/@tursodatabase/serverless": {
+      "resolved": "../..",
+      "link": true
+    }
+  }
+}

packages/turso-serverless/examples/remote-compat/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "batch",
+  "version": "1.0.0",
+  "main": "index.mjs",
+  "author": "Giovanni Benussi",
+  "license": "MIT",
+  "dependencies": {
+    "@tursodatabase/serverless": "../.."
+  }
+}

packages/turso-serverless/examples/remote/README.md

@@ -0,0 +1,19 @@
+# Remote
+
+This example demonstrates how to use Turso Cloud.
+
+## Install Dependencies
+
+```bash
+npm i
+```
+
+## Running
+
+Execute the example:
+
+```bash
+TURSO_DATABASE_URL="..." TURSO_AUTH_TOKEN="..." node index.mjs
+```
+
+This will connect to a remote SQLite database, insert some data, and then query the results.

packages/turso-serverless/examples/remote/index.mjs

@@ -0,0 +1,36 @@
+import { connect } from "@tursodatabase/serverless";
+
+const client = connect({
+    url: process.env.TURSO_DATABASE_URL,
+    authToken: process.env.TURSO_AUTH_TOKEN,
+});
+
+await client.batch(
+    [
+        "CREATE TABLE IF NOT EXISTS users (email TEXT)",
+        "INSERT INTO users VALUES ('first@example.com')",
+        "INSERT INTO users VALUES ('second@example.com')",
+        "INSERT INTO users VALUES ('third@example.com')",
+    ],
+    "write",
+);
+
+// Using execute method
+const result = await client.execute("SELECT * FROM users");
+console.log("Users (execute):", result.rows);
+
+// Using prepare and get method
+const stmt = client.prepare("SELECT * FROM users LIMIT 1");
+const firstUser = await stmt.get();
+console.log("First user:", firstUser);
+
+// Using prepare and all method
+const allUsers = await stmt.all();
+console.log("All users (all):", allUsers);
+
+// Using prepare and iterate method
+console.log("Users (iterate):");
+const iterateStmt = client.prepare("SELECT * FROM users");
+for await (const user of iterateStmt.iterate()) {
+    console.log("  -", user[0]);
+}

packages/turso-serverless/examples/remote/package-lock.json

@@ -0,0 +1,29 @@
+{
+  "name": "remote",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "remote",
+      "version": "1.0.0",
+      "license": "MIT",
+      "dependencies": {
+        "@tursodatabase/serverless": "../.."
+      }
+    },
+    "../..": {
+      "name": "@tursodatabase/serverless",
+      "version": "1.0.0",
+      "license": "ISC",
+      "devDependencies": {
+        "@types/node": "^24.0.13",
+        "typescript": "^5.8.3"
+      }
+    },
+    "node_modules/@tursodatabase/serverless": {
+      "resolved": "../..",
+      "link": true
+    }
+  }
+}

packages/turso-serverless/examples/remote/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "remote",
+  "version": "1.0.0",
+  "main": "index.mjs",
+  "author": "Giovanni Benussi",
+  "license": "MIT",
+  "dependencies": {
+    "@tursodatabase/serverless": "../.."
+  }
+}

packages/turso-serverless/integration-tests/compat.test.mjs

@@ -0,0 +1,54 @@
+import test from 'ava';
+import { createClient, LibsqlError } from '../dist/compat/index.js';
+
+test.serial('createClient validates supported config options', async t => {
+  // Valid config should work
+  t.notThrows(() => {
+    const client = createClient({
+      url: process.env.TURSO_DATABASE_URL,
+      authToken: process.env.TURSO_AUTH_TOKEN,
+    });
+    client.close();
+  });
+});
+
+test.serial('createClient rejects unsupported config options', async t => {
+  const error = t.throws(() => {
+    createClient({
+      url: process.env.TURSO_DATABASE_URL,
+      authToken: process.env.TURSO_AUTH_TOKEN,
+      encryptionKey: 'some-key',
+      syncUrl: 'https://sync.example.com',
+    });
+  }, { instanceOf: LibsqlError });
+
+  t.is(error.code, 'UNSUPPORTED_CONFIG');
+  t.regex(error.message, /encryptionKey.*syncUrl/);
+  t.regex(error.message, /Only 'url' and 'authToken' are supported/);
+});
+
+test.serial('createClient requires url config option', async t => {
+  const error = t.throws(() => {
+    createClient({
+      authToken: process.env.TURSO_AUTH_TOKEN,
+    });
+  }, { instanceOf: LibsqlError });
+
+  t.is(error.code, 'MISSING_URL');
+  t.regex(error.message, /Missing required 'url'/);
+});
+
+test.serial('createClient works with basic libSQL API', async t => {
+  const client = createClient({
+    url: process.env.TURSO_DATABASE_URL,
+    authToken: process.env.TURSO_AUTH_TOKEN,
+  });
+
+  // Test basic functionality
+  const result = await client.execute('SELECT 42 as answer');
+  t.is(result.rows[0][0], 42);
+  t.is(result.columns[0], 'answer');
+  
+  client.close();
+  t.true(client.closed);
+});

packages/turso-serverless/integration-tests/serverless.test.mjs

@@ -0,0 +1,119 @@
+import test from 'ava';
+import { connect } from '../dist/index.js';
+
+const client = connect({
+  url: process.env.TURSO_DATABASE_URL,
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+
+test.serial('execute() method creates table and inserts data', async t => {
+  await client.execute('DROP TABLE IF EXISTS test_users');
+  
+  await client.execute('CREATE TABLE test_users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)');
+  
+  const insertResult = await client.execute(
+    'INSERT INTO test_users (name, email) VALUES (?, ?)',
+    ['John Doe', 'john@example.com']
+  );
+  
+  t.is(insertResult.rowsAffected, 1);
+  t.is(typeof insertResult.lastInsertRowid, 'number');
+});
+
+test.serial('execute() method queries data correctly', async t => {
+  const queryResult = await client.execute('SELECT * FROM test_users WHERE name = ?', ['John Doe']);
+  
+  t.is(queryResult.columns.length, 3);
+  t.true(queryResult.columns.includes('id'));
+  t.true(queryResult.columns.includes('name'));
+  t.true(queryResult.columns.includes('email'));
+  
+  t.is(queryResult.rows.length, 1);
+  t.is(queryResult.rows[0][1], 'John Doe');
+  t.is(queryResult.rows[0][2], 'john@example.com');
+});
+
+test.serial('prepare() method creates statement', async t => {
+  const stmt = client.prepare('SELECT * FROM test_users WHERE name = ?');
+  
+  const row = await stmt.get(['John Doe']);
+  t.is(row[1], 'John Doe');
+  t.is(row[2], 'john@example.com');
+  
+  const rows = await stmt.all(['John Doe']);
+  t.is(rows.length, 1);
+  t.is(rows[0][1], 'John Doe');
+});
+
+test.serial('statement iterate() method works', async t => {
+  // Ensure test data exists
+  await client.execute('CREATE TABLE IF NOT EXISTS test_users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)');
+  await client.execute('INSERT OR IGNORE INTO test_users (name, email) VALUES (?, ?)', ['John Doe', 'john@example.com']);
+  
+  const stmt = client.prepare('SELECT * FROM test_users');
+  
+  const rows = [];
+  for await (const row of stmt.iterate()) {
+    rows.push(row);
+  }
+  
+  t.true(rows.length >= 1);
+  t.is(rows[0][1], 'John Doe');
+});
+
+test.serial('batch() method executes multiple statements', async t => {
+  await client.execute('DROP TABLE IF EXISTS test_products');
+  
+  const batchResult = await client.batch([
+    'CREATE TABLE test_products (id INTEGER PRIMARY KEY, name TEXT, price REAL)',
+    'INSERT INTO test_products (name, price) VALUES ("Widget", 9.99)',
+    'INSERT INTO test_products (name, price) VALUES ("Gadget", 19.99)',
+    'INSERT INTO test_products (name, price) VALUES ("Tool", 29.99)'
+  ]);
+  
+  t.is(batchResult.rowsAffected, 3);
+  
+  const queryResult = await client.execute('SELECT COUNT(*) as count FROM test_products');
+  t.is(queryResult.rows[0][0], 3);
+});
+
+test.serial('execute() method queries a single value', async t => {
+  const rs = await client.execute('SELECT 42');
+  
+  t.is(rs.columns.length, 1);
+  t.is(rs.columnTypes.length, 1);
+  t.is(rs.rows.length, 1);
+  t.is(rs.rows[0].length, 1);
+  t.is(rs.rows[0][0], 42);
+});
+
+test.serial('execute() method queries a single row', async t => {
+  const rs = await client.execute(
+    "SELECT 1 AS one, 'two' AS two, 0.5 AS three"
+  );
+  
+  t.deepEqual(rs.columns, ["one", "two", "three"]);
+  t.deepEqual(rs.columnTypes, ["", "", ""]);
+  t.is(rs.rows.length, 1);
+
+  const r = rs.rows[0];
+  t.is(r.length, 3);
+  t.deepEqual(Array.from(r), [1, "two", 0.5]);
+  t.deepEqual(Object.entries(r), [
+    ["0", 1],
+    ["1", "two"],
+    ["2", 0.5],
+  ]);
+  
+  // Test column name access
+  t.is(r.one, 1);
+  t.is(r.two, "two");
+  t.is(r.three, 0.5);
+});
+
+test.serial('error handling works correctly', async t => {
+  const error = await t.throwsAsync(
+    () => client.execute('SELECT * FROM nonexistent_table')
+  );
+  t.regex(error.message, /SQLite error.*no such table|no such table|HTTP error/);
+});

packages/turso-serverless/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@tursodatabase/serverless",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./compat": {
+      "import": "./dist/compat/index.js",
+      "types": "./dist/compat/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "ava integration-tests/*.test.mjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^24.0.13",
+    "ava": "^6.4.1",
+    "typescript": "^5.8.3"
+  }
+}

packages/turso-serverless/src/compat.ts

@@ -0,0 +1,322 @@
+import { Connection, connect, type Config as TursoConfig } from './connection.js';
+
+/**
+ * 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.
+ */
+export interface Config {
+  /** Database URL (required) */
+  url: string;
+  /** Authentication token for the database */
+  authToken?: string;
+  /** @deprecated Database encryption key - not supported in serverless mode */
+  encryptionKey?: string;
+  /** @deprecated Sync server URL - not supported in serverless mode */
+  syncUrl?: string;
+  /** @deprecated Sync frequency in seconds - not supported in serverless mode */
+  syncInterval?: number;
+  /** @deprecated Consistency mode - not supported in serverless mode */
+  readYourWrites?: boolean;
+  /** @deprecated Offline mode support - not supported in serverless mode */
+  offline?: boolean;
+  /** @deprecated TLS settings - not supported in serverless mode */
+  tls?: boolean;
+  /** @deprecated Integer handling mode - not supported in serverless mode */
+  intMode?: "number" | "bigint" | "string";
+  /** @deprecated Custom fetch implementation - not supported in serverless mode */
+  fetch?: Function;
+  /** @deprecated Concurrent request limit - not supported in serverless mode */
+  concurrency?: number;
+}
+
+/** Input value types accepted by libSQL statements */
+export type InValue = null | string | number | bigint | ArrayBuffer | boolean | Uint8Array | Date;
+
+/** Input arguments - either positional array or named object */
+export type InArgs = Array<InValue> | Record<string, InValue>;
+
+/** Input statement - either SQL string or object with sql and args */
+export type InStatement = { sql: string; args?: InArgs } | string;
+
+/** Transaction execution modes */
+export type TransactionMode = "write" | "read" | "deferred";
+
+/**
+ * A result row that can be accessed both as an array and as an object.
+ * Supports both numeric indexing (row[0]) and column name access (row.column_name).
+ */
+export interface Row {
+  length: number;
+  [index: number]: InValue;
+  [name: string]: InValue;
+}
+
+/**
+ * Result set returned from SQL statement execution.
+ */
+export interface ResultSet {
+  /** Column names in the result set */
+  columns: Array<string>;
+  /** Column type information */
+  columnTypes: Array<string>;
+  /** Result rows */
+  rows: Array<Row>;
+  /** Number of rows affected by the statement */
+  rowsAffected: number;
+  /** ID of the last inserted row (for INSERT statements) */
+  lastInsertRowid: bigint | undefined;
+  /** Convert result set to JSON */
+  toJSON(): any;
+}
+
+/**
+ * libSQL-compatible error class with error codes.
+ */
+export class LibsqlError extends Error {
+  /** Machine-readable error code */
+  code: string;
+  /** Raw numeric error code (if available) */
+  rawCode?: number;
+
+  constructor(message: string, code: string, rawCode?: number) {
+    super(message);
+    this.name = 'LibsqlError';
+    this.code = code;
+    this.rawCode = rawCode;
+  }
+}
+
+/**
+ * Interactive transaction interface (not implemented in serverless mode).
+ * 
+ * @remarks
+ * Transactions are not supported in the serverless compatibility layer.
+ * Calling transaction() will throw a LibsqlError.
+ */
+export interface Transaction {
+  execute(stmt: InStatement): Promise<ResultSet>;
+  batch(stmts: Array<InStatement>): Promise<Array<ResultSet>>;
+  executeMultiple(sql: string): Promise<void>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  close(): void;
+  closed: boolean;
+}
+
+/**
+ * libSQL-compatible client interface.
+ * 
+ * This interface matches the standard libSQL client API for drop-in compatibility.
+ * Some methods are not implemented in the serverless compatibility layer.
+ */
+export interface Client {
+  execute(stmt: InStatement): Promise<ResultSet>;
+  execute(sql: string, args?: InArgs): Promise<ResultSet>;
+  batch(stmts: Array<InStatement>, mode?: TransactionMode): Promise<Array<ResultSet>>;
+  migrate(stmts: Array<InStatement>): Promise<Array<ResultSet>>;
+  transaction(mode?: TransactionMode): Promise<Transaction>;
+  executeMultiple(sql: string): Promise<void>;
+  sync(): Promise<any>;
+  close(): void;
+  closed: boolean;
+  protocol: string;
+}
+
+class LibSQLClient implements Client {
+  private connection: Connection;
+  private _closed = false;
+
+  constructor(config: Config) {
+    this.validateConfig(config);
+    
+    const tursoConfig: TursoConfig = {
+      url: config.url,
+      authToken: config.authToken || ''
+    };
+    this.connection = connect(tursoConfig);
+  }
+
+  private validateConfig(config: Config): void {
+    // Check for unsupported config options
+    const unsupportedOptions: Array<{ key: keyof Config; value: any }> = [];
+
+    if (config.encryptionKey !== undefined) {
+      unsupportedOptions.push({ key: 'encryptionKey', value: config.encryptionKey });
+    }
+    if (config.syncUrl !== undefined) {
+      unsupportedOptions.push({ key: 'syncUrl', value: config.syncUrl });
+    }
+    if (config.syncInterval !== undefined) {
+      unsupportedOptions.push({ key: 'syncInterval', value: config.syncInterval });
+    }
+    if (config.readYourWrites !== undefined) {
+      unsupportedOptions.push({ key: 'readYourWrites', value: config.readYourWrites });
+    }
+    if (config.offline !== undefined) {
+      unsupportedOptions.push({ key: 'offline', value: config.offline });
+    }
+    if (config.tls !== undefined) {
+      unsupportedOptions.push({ key: 'tls', value: config.tls });
+    }
+    if (config.intMode !== undefined) {
+      unsupportedOptions.push({ key: 'intMode', value: config.intMode });
+    }
+    if (config.fetch !== undefined) {
+      unsupportedOptions.push({ key: 'fetch', value: config.fetch });
+    }
+    if (config.concurrency !== undefined) {
+      unsupportedOptions.push({ key: 'concurrency', value: config.concurrency });
+    }
+
+    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"
+      );
+    }
+
+    // Validate required options
+    if (!config.url) {
+      throw new LibsqlError("Missing required 'url' configuration option", "MISSING_URL");
+    }
+  }
+
+  get closed(): boolean {
+    return this._closed;
+  }
+
+  get protocol(): string {
+    return "http";
+  }
+
+  private normalizeStatement(stmt: InStatement): { sql: string; args: any[] } {
+    if (typeof stmt === 'string') {
+      return { sql: stmt, args: [] };
+    }
+    
+    const args = stmt.args || [];
+    if (Array.isArray(args)) {
+      return { sql: stmt.sql, args };
+    }
+    
+    // Convert named args to positional args (simplified)
+    return { sql: stmt.sql, args: Object.values(args) };
+  }
+
+  private convertResult(result: any): ResultSet {
+    const resultSet: ResultSet = {
+      columns: result.columns || [],
+      columnTypes: result.columnTypes || [],
+      rows: result.rows || [],
+      rowsAffected: result.rowsAffected || 0,
+      lastInsertRowid: result.lastInsertRowid ? BigInt(result.lastInsertRowid) : undefined,
+      toJSON() {
+        return {
+          columns: this.columns,
+          columnTypes: this.columnTypes,
+          rows: this.rows,
+          rowsAffected: this.rowsAffected,
+          lastInsertRowid: this.lastInsertRowid?.toString()
+        };
+      }
+    };
+
+    return resultSet;
+  }
+
+  async execute(stmt: InStatement): Promise<ResultSet>;
+  async execute(sql: string, args?: InArgs): Promise<ResultSet>;
+  async execute(stmtOrSql: InStatement | string, args?: InArgs): Promise<ResultSet> {
+    try {
+      if (this._closed) {
+        throw new LibsqlError("Client is closed", "CLIENT_CLOSED");
+      }
+
+      let normalizedStmt: { sql: string; args: any[] };
+      
+      if (typeof stmtOrSql === 'string') {
+        const normalizedArgs = args ? (Array.isArray(args) ? args : Object.values(args)) : [];
+        normalizedStmt = { sql: stmtOrSql, args: normalizedArgs };
+      } else {
+        normalizedStmt = this.normalizeStatement(stmtOrSql);
+      }
+
+      const result = await this.connection.execute(normalizedStmt.sql, normalizedStmt.args);
+      return this.convertResult(result);
+    } catch (error: any) {
+      throw new LibsqlError(error.message, "EXECUTE_ERROR");
+    }
+  }
+
+  async batch(stmts: Array<InStatement>, mode?: TransactionMode): Promise<Array<ResultSet>> {
+    try {
+      if (this._closed) {
+        throw new LibsqlError("Client is closed", "CLIENT_CLOSED");
+      }
+
+      const sqlStatements = stmts.map(stmt => {
+        const normalized = this.normalizeStatement(stmt);
+        return normalized.sql; // For now, ignore args in batch
+      });
+
+      const result = await this.connection.batch(sqlStatements, mode);
+      
+      // Return array of result sets (simplified - actual implementation would be more complex)
+      return [this.convertResult(result)];
+    } catch (error: any) {
+      throw new LibsqlError(error.message, "BATCH_ERROR");
+    }
+  }
+
+  async migrate(stmts: Array<InStatement>): Promise<Array<ResultSet>> {
+    // For now, just call batch - in a real implementation this would disable foreign keys
+    return this.batch(stmts, "write");
+  }
+
+  async transaction(mode?: TransactionMode): Promise<Transaction> {
+    throw new LibsqlError("Transactions not implemented", "NOT_IMPLEMENTED");
+  }
+
+  async executeMultiple(sql: string): Promise<void> {
+    throw new LibsqlError("Execute multiple not implemented", "NOT_IMPLEMENTED");
+  }
+
+  async sync(): Promise<any> {
+    throw new LibsqlError("Sync not supported for remote databases", "NOT_SUPPORTED");
+  }
+
+  close(): void {
+    this._closed = true;
+  }
+}
+
+/**
+ * Create a libSQL-compatible client for Turso database access.
+ * 
+ * This function provides compatibility with the standard libSQL client API
+ * while using the Turso serverless driver under the hood.
+ * 
+ * @param config - Configuration object (only url and authToken are supported)
+ * @returns A Client instance compatible with libSQL API
+ * @throws LibsqlError if unsupported configuration options are provided
+ * 
+ * @example
+ * ```typescript
+ * import { createClient } from "@tursodatabase/serverless/compat";
+ * 
+ * const client = createClient({
+ *   url: process.env.TURSO_DATABASE_URL,
+ *   authToken: process.env.TURSO_AUTH_TOKEN
+ * });
+ * 
+ * const result = await client.execute("SELECT * FROM users");
+ * console.log(result.rows);
+ * ```
+ */
+export function createClient(config: Config): Client {
+  return new LibSQLClient(config);
+}

packages/turso-serverless/src/compat/index.ts

@@ -0,0 +1 @@
+export * from '../compat.js';

packages/turso-serverless/src/connection.ts

@@ -0,0 +1,100 @@
+import { Session, type SessionConfig } from './session.js';
+import { Statement } from './statement.js';
+
+/**
+ * Configuration options for connecting to a Turso database.
+ */
+export 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 for optimal performance.
+ */
+export class Connection {
+  private config: Config;
+  private session: Session;
+
+  constructor(config: Config) {
+    this.config = config;
+    this.session = new Session(config);
+  }
+
+  /**
+   * Prepare a SQL statement for execution.
+   * 
+   * Each prepared statement gets its own session to avoid conflicts during concurrent execution.
+   * 
+   * @param sql - The SQL statement to prepare
+   * @returns A Statement object that can be executed multiple ways
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+   * const user = await stmt.get([123]);
+   * const allUsers = await stmt.all();
+   * ```
+   */
+  prepare(sql: string): Statement {
+    return new Statement(this.config, sql);
+  }
+
+  /**
+   * 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");
+   * console.log(result.rows);
+   * ```
+   */
+  async execute(sql: string, args: any[] = []): Promise<any> {
+    return this.session.execute(sql, args);
+  }
+
+
+  /**
+   * Execute multiple SQL statements in a batch.
+   * 
+   * @param statements - Array of SQL statements to execute
+   * @param mode - Optional transaction mode (currently unused)
+   * @returns Promise resolving to batch execution results
+   * 
+   * @example
+   * ```typescript
+   * await client.batch([
+   *   "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+   *   "INSERT INTO users (name) VALUES ('Alice')",
+   *   "INSERT INTO users (name) VALUES ('Bob')"
+   * ]);
+   * ```
+   */
+  async batch(statements: string[], mode?: string): Promise<any> {
+    return this.session.batch(statements);
+  }
+}
+
+/**
+ * Create a new connection to a Turso database.
+ * 
+ * @param config - Configuration object with database URL and auth token
+ * @returns A new Connection instance
+ * 
+ * @example
+ * ```typescript
+ * import { connect } from "@tursodatabase/serverless";
+ * 
+ * const client = connect({
+ *   url: process.env.TURSO_DATABASE_URL,
+ *   authToken: process.env.TURSO_AUTH_TOKEN
+ * });
+ * ```
+ */
+export function connect(config: Config): Connection {
+  return new Connection(config);
+}

packages/turso-serverless/src/index.ts

@@ -0,0 +1,3 @@
+// Turso serverless driver entry point
+export { Connection, connect, type Config } from './connection.js';
+export { Statement } from './statement.js';

packages/turso-serverless/src/protocol.ts

@@ -0,0 +1,245 @@
+export interface Value {
+  type: 'null' | 'integer' | 'float' | 'text' | 'blob';
+  value?: string | number;
+  base64?: string;
+}
+
+export interface Column {
+  name: string;
+  decltype: string;
+}
+
+export interface ExecuteResult {
+  cols: Column[];
+  rows: Value[][];
+  affected_row_count: number;
+  last_insert_rowid?: string;
+}
+
+export interface ExecuteRequest {
+  type: 'execute';
+  stmt: {
+    sql: string;
+    args: Value[];
+    named_args: Value[];
+    want_rows: boolean;
+  };
+}
+
+export interface BatchStep {
+  stmt: {
+    sql: string;
+    args: Value[];
+    want_rows: boolean;
+  };
+  condition?: {
+    type: 'ok';
+    step: number;
+  };
+}
+
+export interface BatchRequest {
+  type: 'batch';
+  batch: {
+    steps: BatchStep[];
+  };
+}
+
+export interface PipelineRequest {
+  baton: string | null;
+  requests: (ExecuteRequest | BatchRequest)[];
+}
+
+export interface PipelineResponse {
+  baton: string | null;
+  base_url: string | null;
+  results: Array<{
+    type: 'ok' | 'error';
+    response?: {
+      type: 'execute' | 'batch';
+      result: ExecuteResult;
+    };
+    error?: {
+      message: string;
+      code: string;
+    };
+  }>;
+}
+
+export function encodeValue(value: any): Value {
+  if (value === null || value === undefined) {
+    return { type: 'null' };
+  }
+  
+  if (typeof value === 'number') {
+    if (Number.isInteger(value)) {
+      return { type: 'integer', value: value.toString() };
+    }
+    return { type: 'float', value };
+  }
+  
+  if (typeof value === 'string') {
+    return { type: 'text', value };
+  }
+  
+  if (value instanceof ArrayBuffer || value instanceof Uint8Array) {
+    const base64 = btoa(String.fromCharCode(...new Uint8Array(value)));
+    return { type: 'blob', base64 };
+  }
+  
+  return { type: 'text', value: String(value) };
+}
+
+export function decodeValue(value: Value): any {
+  switch (value.type) {
+    case 'null':
+      return null;
+    case 'integer':
+      return parseInt(value.value as string, 10);
+    case 'float':
+      return value.value as number;
+    case 'text':
+      return value.value as string;
+    case 'blob':
+      if (value.base64) {
+        const binaryString = atob(value.base64);
+        const bytes = new Uint8Array(binaryString.length);
+        for (let i = 0; i < binaryString.length; i++) {
+          bytes[i] = binaryString.charCodeAt(i);
+        }
+        return bytes;
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+
+export interface CursorRequest {
+  baton: string | null;
+  batch: {
+    steps: BatchStep[];
+  };
+}
+
+export interface CursorResponse {
+  baton: string | null;
+  base_url: string | null;
+}
+
+export interface CursorEntry {
+  type: 'step_begin' | 'step_end' | 'step_error' | 'row' | 'error';
+  step?: number;
+  cols?: Column[];
+  row?: Value[];
+  affected_row_count?: number;
+  last_insert_rowid?: string;
+  error?: {
+    message: string;
+    code: string;
+  };
+}
+
+export async function executeCursor(
+  url: string,
+  authToken: string,
+  request: CursorRequest
+): Promise<{ response: CursorResponse; entries: AsyncGenerator<CursorEntry> }> {
+  const response = await fetch(`${url}/v3/cursor`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${authToken}`,
+    },
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) {
+    let errorMessage = `HTTP error! status: ${response.status}`;
+    try {
+      const errorBody = await response.text();
+      const errorData = JSON.parse(errorBody);
+      if (errorData.message) {
+        errorMessage = errorData.message;
+      }
+    } catch {
+      // If we can't parse the error body, use the default HTTP error message
+    }
+    throw new Error(errorMessage);
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error('No response body');
+  }
+
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let isFirstLine = true;
+  let cursorResponse: CursorResponse;
+
+  async function* parseEntries(): AsyncGenerator<CursorEntry> {
+    try {
+      while (true) {
+        const { done, value } = await reader!.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        
+        let newlineIndex;
+        while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.slice(0, newlineIndex).trim();
+          buffer = buffer.slice(newlineIndex + 1);
+          
+          if (line) {
+            if (isFirstLine) {
+              cursorResponse = JSON.parse(line);
+              isFirstLine = false;
+            } else {
+              yield JSON.parse(line) as CursorEntry;
+            }
+          }
+        }
+      }
+    } finally {
+      reader!.releaseLock();
+    }
+  }
+
+  const entries = parseEntries();
+  
+  // Get the first entry to parse the cursor response
+  const firstEntry = await entries.next();
+  if (!firstEntry.done) {
+    // Put the first entry back
+    const generator = (async function* () {
+      yield firstEntry.value;
+      yield* entries;
+    })();
+    
+    return { response: cursorResponse!, entries: generator };
+  }
+  
+  return { response: cursorResponse!, entries };
+}
+
+export async function executePipeline(
+  url: string,
+  authToken: string,
+  request: PipelineRequest
+): Promise<PipelineResponse> {
+  const response = await fetch(`${url}/v3/pipeline`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${authToken}`,
+    },
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+
+  return response.json();
+}

packages/turso-serverless/src/session.ts

@@ -0,0 +1,216 @@
+import { 
+  executeCursor, 
+  encodeValue, 
+  decodeValue, 
+  type CursorRequest,
+  type CursorResponse,
+  type CursorEntry
+} from './protocol.js';
+
+/**
+ * Configuration options for a session.
+ */
+export interface SessionConfig {
+  /** Database URL */
+  url: string;
+  /** Authentication token */
+  authToken: string;
+}
+
+function normalizeUrl(url: string): string {
+  return url.replace(/^libsql:\/\//, 'https://');
+}
+
+function isValidIdentifier(str: string): boolean {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(str);
+}
+
+/**
+ * A database session that manages the connection state and baton.
+ * 
+ * Each session maintains its own connection state and can execute SQL statements
+ * independently without interfering with other sessions.
+ */
+export class Session {
+  private config: SessionConfig;
+  private baton: string | null = null;
+  private baseUrl: string;
+
+  constructor(config: SessionConfig) {
+    this.config = config;
+    this.baseUrl = normalizeUrl(config.url);
+  }
+
+  /**
+   * 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
+   */
+  async execute(sql: string, args: any[] = []): Promise<any> {
+    const { response, entries } = await this.executeRaw(sql, args);
+    const result = await this.processCursorEntries(entries);
+    return result;
+  }
+
+  /**
+   * 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: string, args: any[] = []): Promise<{ response: CursorResponse; entries: AsyncGenerator<CursorEntry> }> {
+    const request: CursorRequest = {
+      baton: this.baton,
+      batch: {
+        steps: [{
+          stmt: {
+            sql,
+            args: args.map(encodeValue),
+            want_rows: true
+          }
+        }]
+      }
+    };
+
+    const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request);
+    
+    this.baton = response.baton;
+    if (response.base_url) {
+      this.baseUrl = response.base_url;
+    }
+
+    return { response, entries };
+  }
+
+  /**
+   * Process cursor entries into a structured result.
+   * 
+   * @param entries - Async generator of cursor entries
+   * @returns Promise resolving to the processed result
+   */
+  async processCursorEntries(entries: AsyncGenerator<CursorEntry>): Promise<any> {
+    let columns: string[] = [];
+    let columnTypes: string[] = [];
+    let rows: any[] = [];
+    let rowsAffected = 0;
+    let lastInsertRowid: number | undefined;
+
+    for await (const entry of entries) {
+      switch (entry.type) {
+        case 'step_begin':
+          if (entry.cols) {
+            columns = entry.cols.map(col => col.name);
+            columnTypes = entry.cols.map(col => col.decltype || '');
+          }
+          break;
+        case 'row':
+          if (entry.row) {
+            const decodedRow = entry.row.map(decodeValue);
+            const rowObject = this.createRowObject(decodedRow, columns);
+            rows.push(rowObject);
+          }
+          break;
+        case 'step_end':
+          if (entry.affected_row_count !== undefined) {
+            rowsAffected = entry.affected_row_count;
+          }
+          if (entry.last_insert_rowid) {
+            lastInsertRowid = parseInt(entry.last_insert_rowid, 10);
+          }
+          break;
+        case 'step_error':
+        case 'error':
+          throw new Error(entry.error?.message || 'SQL execution failed');
+      }
+    }
+
+    return {
+      columns,
+      columnTypes,
+      rows,
+      rowsAffected,
+      lastInsertRowid
+    };
+  }
+
+  /**
+   * 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 {
+    const row = [...values];
+    
+    // Add column name properties to the array as non-enumerable
+    // Only add valid identifier names to avoid conflicts
+    columns.forEach((column, index) => {
+      if (column && isValidIdentifier(column)) {
+        Object.defineProperty(row, column, {
+          value: values[index],
+          enumerable: false,
+          writable: false,
+          configurable: true
+        });
+      }
+    });
+    
+    return row;
+  }
+
+  /**
+   * Execute multiple SQL statements in a batch.
+   * 
+   * @param statements - Array of SQL statements to execute
+   * @returns Promise resolving to batch execution results
+   */
+  async batch(statements: string[]): Promise<any> {
+    const request: CursorRequest = {
+      baton: this.baton,
+      batch: {
+        steps: statements.map(sql => ({
+          stmt: {
+            sql,
+            args: [],
+            want_rows: false
+          }
+        }))
+      }
+    };
+
+    const { response, entries } = await executeCursor(this.baseUrl, this.config.authToken, request);
+    
+    this.baton = response.baton;
+    if (response.base_url) {
+      this.baseUrl = response.base_url;
+    }
+
+    let totalRowsAffected = 0;
+    let lastInsertRowid: number | undefined;
+
+    for await (const entry of entries) {
+      switch (entry.type) {
+        case 'step_end':
+          if (entry.affected_row_count !== undefined) {
+            totalRowsAffected += entry.affected_row_count;
+          }
+          if (entry.last_insert_rowid) {
+            lastInsertRowid = parseInt(entry.last_insert_rowid, 10);
+          }
+          break;
+        case 'step_error':
+        case 'error':
+          throw new Error(entry.error?.message || 'Batch execution failed');
+      }
+    }
+
+    return {
+      rowsAffected: totalRowsAffected,
+      lastInsertRowid
+    };
+  }
+}

packages/turso-serverless/src/statement.ts

@@ -0,0 +1,107 @@
+import { 
+  decodeValue, 
+  type CursorEntry
+} from './protocol.js';
+import { Session, type SessionConfig } from './session.js';
+
+/**
+ * A prepared SQL statement that can be executed in multiple ways.
+ * 
+ * Each statement has its own session to avoid conflicts during concurrent execution.
+ * 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
+ */
+export class Statement {
+  private session: Session;
+  private sql: string;
+
+  constructor(sessionConfig: SessionConfig, sql: string) {
+    this.session = new Session(sessionConfig);
+    this.sql = sql;
+  }
+
+  /**
+   * 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
+   * 
+   * @example
+   * ```typescript
+   * const stmt = client.prepare("SELECT * FROM users WHERE id = ?");
+   * const user = await stmt.get([123]);
+   * if (user) {
+   *   console.log(user.name);
+   * }
+   * ```
+   */
+  async get(args: any[] = []): Promise<any> {
+    const result = await this.session.execute(this.sql, args);
+    return result.rows[0] || null;
+  }
+
+  /**
+   * Execute the statement and return all rows.
+   * 
+   * @param args - Optional array of parameter values for the SQL statement
+   * @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`);
+   * ```
+   */
+  async all(args: any[] = []): Promise<any[]> {
+    const result = await this.session.execute(this.sql, args);
+    return result.rows;
+  }
+
+  /**
+   * 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
+   * @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);
+   * }
+   * ```
+   */
+  async *iterate(args: any[] = []): AsyncGenerator<any> {
+    const { response, entries } = await this.session.executeRaw(this.sql, args);
+    
+    let columns: string[] = [];
+    
+    for await (const entry of entries) {
+      switch (entry.type) {
+        case 'step_begin':
+          if (entry.cols) {
+            columns = entry.cols.map(col => col.name);
+          }
+          break;
+        case 'row':
+          if (entry.row) {
+            const decodedRow = entry.row.map(decodeValue);
+            const rowObject = this.session.createRowObject(decodedRow, columns);
+            yield rowObject;
+          }
+          break;
+        case 'step_error':
+        case 'error':
+          throw new Error(entry.error?.message || 'SQL execution failed');
+      }
+    }
+  }
+
+}

packages/turso-serverless/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}