@tursodatabase/serverless 0.1.0

package/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

package/dist/client.d.ts

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

package/dist/client.js

@@ -0,0 +1,184 @@
+import { executeCursor, encodeValue, decodeValue } from './protocol.js';
+function normalizeUrl(url) {
+    return url.replace(/^libsql:\/\//, 'https://');
+}
+function isValidIdentifier(str) {
+    return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(str);
+}
+export class Statement {
+    constructor(connection, sql, args = []) {
+        this.connection = connection;
+        this.sql = sql;
+        this.args = args;
+    }
+    async get() {
+        const result = await this.execute();
+        return result.rows[0] || null;
+    }
+    async all() {
+        const result = await this.execute();
+        return result.rows;
+    }
+    async *iterate() {
+        const { response, entries } = await this.connection.executeRaw(this.sql, this.args);
+        let columns = [];
+        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.connection.createRowObject(decodedRow, columns);
+                        yield rowObject;
+                    }
+                    break;
+                case 'step_error':
+                case 'error':
+                    throw new Error(entry.error?.message || 'SQL execution failed');
+            }
+        }
+    }
+    async execute() {
+        return this.connection.execute(this.sql, this.args);
+    }
+}
+export class Connection {
+    constructor(config) {
+        this.baton = null;
+        this.config = config;
+        this.baseUrl = normalizeUrl(config.url);
+    }
+    prepare(sql, args = []) {
+        return new Statement(this, sql, args);
+    }
+    async execute(sql, args = []) {
+        const { response, entries } = await this.executeRaw(sql, args);
+        const result = await this.processCursorEntries(entries);
+        return result;
+    }
+    async executeRaw(sql, args = []) {
+        const request = {
+            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 };
+    }
+    async processCursorEntries(entries) {
+        let columns = [];
+        let columnTypes = [];
+        let rows = [];
+        let rowsAffected = 0;
+        let lastInsertRowid;
+        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
+        };
+    }
+    createRowObject(values, columns) {
+        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;
+    }
+    async batch(statements, mode) {
+        const request = {
+            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;
+        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
+        };
+    }
+}
+export function connect(config) {
+    return new Connection(config);
+}

package/dist/compat/index.d.ts

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

package/dist/compat/index.js

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

package/dist/compat.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 declare 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);
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare function createClient(config: Config): Client;

package/dist/compat.js

@@ -0,0 +1,177 @@
+import { connect } from './connection.js';
+/**
+ * libSQL-compatible error class with error codes.
+ */
+export class LibsqlError extends Error {
+    constructor(message, code, rawCode) {
+        super(message);
+        this.name = 'LibsqlError';
+        this.code = code;
+        this.rawCode = rawCode;
+    }
+}
+class LibSQLClient {
+    constructor(config) {
+        this._closed = false;
+        this.validateConfig(config);
+        const tursoConfig = {
+            url: config.url,
+            authToken: config.authToken || ''
+        };
+        this.connection = connect(tursoConfig);
+    }
+    validateConfig(config) {
+        // Check for unsupported config options
+        const unsupportedOptions = [];
+        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() {
+        return this._closed;
+    }
+    get protocol() {
+        return "http";
+    }
+    normalizeStatement(stmt) {
+        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) };
+    }
+    convertResult(result) {
+        const 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(stmtOrSql, args) {
+        try {
+            if (this._closed) {
+                throw new LibsqlError("Client is closed", "CLIENT_CLOSED");
+            }
+            let normalizedStmt;
+            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) {
+            throw new LibsqlError(error.message, "EXECUTE_ERROR");
+        }
+    }
+    async batch(stmts, mode) {
+        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) {
+            throw new LibsqlError(error.message, "BATCH_ERROR");
+        }
+    }
+    async migrate(stmts) {
+        // For now, just call batch - in a real implementation this would disable foreign keys
+        return this.batch(stmts, "write");
+    }
+    async transaction(mode) {
+        throw new LibsqlError("Transactions not implemented", "NOT_IMPLEMENTED");
+    }
+    async executeMultiple(sql) {
+        throw new LibsqlError("Execute multiple not implemented", "NOT_IMPLEMENTED");
+    }
+    async sync() {
+        throw new LibsqlError("Sync not supported for remote databases", "NOT_SUPPORTED");
+    }
+    close() {
+        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) {
+    return new LibSQLClient(config);
+}

package/dist/connection.d.ts

@@ -0,0 +1,82 @@
+import { 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 declare class Connection {
+    private config;
+    private session;
+    constructor(config: 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;
+    /**
+     * 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);
+     * ```
+     */
+    execute(sql: string, args?: any[]): Promise<any>;
+    /**
+     * Execute multiple SQL statements in a batch.
+     *
+     * @param statements - Array of SQL statements to execute
+     * @param mode - Optional transaction mode (currently unused)
+     * @returns Promise resolving to batch execution results
+     *
+     * @example
+     * ```typescript
+     * await client.batch([
+     *   "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
+     *   "INSERT INTO users (name) VALUES ('Alice')",
+     *   "INSERT INTO users (name) VALUES ('Bob')"
+     * ]);
+     * ```
+     */
+    batch(statements: string[], mode?: string): Promise<any>;
+}
+/**
+ * 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 declare function connect(config: Config): Connection;