@pineliner/odb-client 1.0.8 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pineliner/odb-client",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Isomorphic client for ODB-Lite with postgres.js-like template string SQL support",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/core/client.ts

@@ -1,9 +1,16 @@
 import type { ODBLiteConfig, ODBLiteConnection, QueryResult, Transaction, TransactionCallback, TransactionMode, SQLFragment } from '../types.ts';
 import { HTTPClient } from './http-client.ts';
 import { SQLParser } from './sql-parser.ts';
-import { createSimpleTransaction, SimpleTransaction } from './transaction.ts';
+import { createBatchTransaction, createSimpleTransaction, SimpleTransaction } from './transaction.ts';
 import { ConnectionError } from '../types.ts';
 
+// Batch result type
+interface BatchResult<T = any> {
+  results: QueryResult<T>[];
+  executionTime: number;
+  statementsExecuted: number;
+}
+
 // Define the callable SQL function type
 interface SQLFunction {
   // Primary call signatures - context-aware like postgres.js
@@ -20,6 +27,9 @@ interface SQLFunction {
   // libsql-compatible execute method (for backward compatibility)
   execute<T = any>(sql: string | { sql: string; args?: any[] }, args?: any[]): Promise<QueryResult<T>>;
 
+  // Batch execution - runs multiple statements on same connection (for transactions)
+  batch<T = any>(statements: Array<{ sql: string; params?: any[] }>): Promise<BatchResult<T>>;
+
   // Transaction support - multiple overloads like postgres.js
   begin(): Promise<Transaction>;
   begin<T>(callback: TransactionCallback<T>): Promise<T>;
@@ -36,7 +46,7 @@ interface SQLFunction {
  * Main ODBLite client that provides postgres.js-like interface
  */
 export class ODBLiteClient implements ODBLiteConnection {
-  private httpClient: HTTPClient;
+  public httpClient: HTTPClient;
   public config: ODBLiteConfig;
   public sql: SQLFunction;
 
@@ -78,21 +88,27 @@ export class ODBLiteClient implements ODBLiteConnection {
       }
     };
 
+    // Batch execution - runs multiple statements on same connection (for transactions)
+    sqlFunction.batch = async <T = any>(statements: Array<{ sql: string; params?: any[] }>): Promise<BatchResult<T>> => {
+      return await this.httpClient.batch<T>(statements);
+    };
+
     // Enhanced begin method with callback support
+    // Uses batch-based transactions for true ACID guarantees
     sqlFunction.begin = async <T = any>(
       modeOrCallback?: TransactionMode | TransactionCallback<T>,
       callback?: TransactionCallback<T>
     ): Promise<Transaction | T> => {
       // Determine if this is callback-style or traditional
       if (typeof modeOrCallback === 'function') {
-        // begin(callback)
+        // begin(callback) - execute with batch transaction
         return this.executeTransactionWithCallback(modeOrCallback);
       } else if (typeof modeOrCallback === 'string' && callback) {
-        // begin(mode, callback)
+        // begin(mode, callback) - execute with batch transaction
         return this.executeTransactionWithCallback(callback, modeOrCallback);
       } else {
-        // begin() - traditional style
-        return createSimpleTransaction(this.httpClient);
+        // begin() - traditional style, returns batch transaction
+        return createBatchTransaction(this.httpClient);
       }
     };
     sqlFunction.ping = async (): Promise<boolean> => {
@@ -119,23 +135,24 @@ export class ODBLiteClient implements ODBLiteConnection {
 
   /**
    * Execute a transaction with callback (postgres.js style)
+   * Uses batch-based transaction for true ACID guarantees
    */
   private async executeTransactionWithCallback<T>(
     callback: TransactionCallback<T>,
     mode?: TransactionMode
   ): Promise<T> {
-    const tx = createSimpleTransaction(this.httpClient);
+    const tx = createBatchTransaction(this.httpClient);
 
     try {
       // Execute the callback with the transaction
       const result = await callback(tx);
 
-      // Commit the transaction
+      // Commit the transaction - sends all queued statements as batch
       await tx.commit();
 
       return result as T;
     } catch (error) {
-      // Rollback on any error
+      // Rollback on any error - for batch transactions, this just clears the queue
       await tx.rollback();
       throw error;
     }
@@ -152,10 +169,10 @@ export class ODBLiteClient implements ODBLiteConnection {
 
   /**
    * Begin a transaction
-   * Note: Uses simple transaction model suitable for HTTP-based access
+   * Uses batch-based transaction for true ACID guarantees
    */
   async begin(): Promise<Transaction> {
-    return createSimpleTransaction(this.httpClient);
+    return createBatchTransaction(this.httpClient);
   }
 
   /**

package/src/core/http-client.ts

@@ -76,6 +76,58 @@ export class HTTPClient {
     }
   }
 
+  /**
+   * Execute multiple statements on the same connection (for transactions)
+   * All statements are sent in a single HTTP request and executed atomically on the server
+   */
+  async batch<T = any>(statements: Array<{ sql: string; params?: any[] }>): Promise<{
+    results: QueryResult<T>[];
+    executionTime: number;
+    statementsExecuted: number;
+  }> {
+    if (!this.config.databaseId) {
+      throw new ConnectionError('No database ID configured. Use setDatabase() first.')
+    }
+
+    const url = `${this.config.baseUrl}/batch/${this.config.databaseId}`
+    const body = { statements }
+
+    try {
+      const response = await this.makeRequest(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify(body)
+      })
+
+      const data = await response.json()
+
+      if (!data.success) {
+        throw new QueryError(data.error || 'Batch failed')
+      }
+
+      const batchData = data.data || data
+      return {
+        results: batchData.results || [],
+        executionTime: batchData.executionTime || 0,
+        statementsExecuted: batchData.statementsExecuted || statements.length
+      }
+    } catch (error) {
+      if (error instanceof QueryError || error instanceof ConnectionError) {
+        throw error
+      }
+
+      throw new QueryError(
+        error instanceof Error ? error.message : 'Unknown error occurred',
+        undefined,
+        undefined,
+        error instanceof Error ? error : undefined
+      )
+    }
+  }
+
   /**
    * Check database health
    */
@@ -198,4 +250,93 @@ export class HTTPClient {
   getConfig(): Readonly<ODBLiteConfig> {
     return { ...this.config }
   }
+
+  /**
+   * Ensure namespaces exist for the database
+   * Creates the namespace .db files if they don't exist
+   */
+  async ensureNamespaces(namespaces: string[]): Promise<{
+    success: boolean;
+    databaseName: string;
+    namespaces: string[];
+  }> {
+    if (!this.config.databaseId) {
+      throw new ConnectionError('No database ID configured. Use setDatabase() first.')
+    }
+
+    const url = `${this.config.baseUrl}/namespaces/${this.config.databaseId}`
+    const body = { namespaces }
+
+    try {
+      const response = await this.makeRequest(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify(body)
+      })
+
+      const data = await response.json()
+
+      if (!data.success) {
+        throw new ConnectionError(data.error || 'Failed to ensure namespaces')
+      }
+
+      return data
+    } catch (error) {
+      if (error instanceof ConnectionError) {
+        throw error
+      }
+
+      throw new ConnectionError(
+        error instanceof Error ? error.message : 'Unknown error occurred',
+        error instanceof Error ? error : undefined
+      )
+    }
+  }
+
+  /**
+   * Get namespace information for the database
+   */
+  async getNamespaces(): Promise<{
+    success: boolean;
+    databaseName: string;
+    exists: boolean;
+    namespaces: string[];
+    registered: boolean;
+    registeredNamespaces: string[];
+  }> {
+    if (!this.config.databaseId) {
+      throw new ConnectionError('No database ID configured. Use setDatabase() first.')
+    }
+
+    const url = `${this.config.baseUrl}/namespaces/${this.config.databaseId}`
+
+    try {
+      const response = await this.makeRequest(url, {
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`
+        }
+      })
+
+      const data = await response.json()
+
+      if (!data.success) {
+        throw new ConnectionError(data.error || 'Failed to get namespaces')
+      }
+
+      return data
+    } catch (error) {
+      if (error instanceof ConnectionError) {
+        throw error
+      }
+
+      throw new ConnectionError(
+        error instanceof Error ? error.message : 'Unknown error occurred',
+        error instanceof Error ? error : undefined
+      )
+    }
+  }
 }

package/src/core/transaction.ts

@@ -3,6 +3,209 @@ import type { HTTPClient } from './http-client.ts';
 import { SQLParser } from './sql-parser.ts';
 import { QueryError } from '../types.ts';
 
+/**
+ * Create a batch-based transaction that executes all statements atomically
+ * using the /batch endpoint. This ensures true ACID transactions by:
+ * 1. Collecting all write statements during callback execution
+ * 2. Sending BEGIN + statements + COMMIT as a single batch request
+ * 3. If callback throws, nothing is executed (implicit rollback)
+ */
+export function createBatchTransaction(httpClient: HTTPClient): Transaction {
+  let isCommitted = false;
+  let isRolledBack = false;
+  const queuedStatements: Array<{ sql: string; params: any[] }> = [];
+
+  const checkTransactionState = (): void => {
+    if (isCommitted) {
+      throw new QueryError('Transaction has already been committed');
+    }
+    if (isRolledBack) {
+      throw new QueryError('Transaction has been rolled back');
+    }
+  };
+
+  const isReadQuery = (sql: string): boolean => {
+    const trimmed = sql.trim().toUpperCase();
+    return trimmed.startsWith('SELECT') ||
+           trimmed.startsWith('WITH') ||
+           trimmed.startsWith('EXPLAIN') ||
+           trimmed.startsWith('PRAGMA');
+  };
+
+  // Create the callable transaction function
+  const txFunction = <T = any>(sql: TemplateStringsArray | any, ...values: any[]): Promise<QueryResult<T>> | SQLFragment => {
+    checkTransactionState();
+
+    // Handle template string queries
+    if (Array.isArray(sql) && (('raw' in sql) || (typeof sql[0] === 'string' && values.length >= 0))) {
+      const parsed = SQLParser.parse(sql, values);
+
+      // For read queries, execute immediately (outside transaction for now)
+      // TODO: Consider queueing reads too for strict isolation
+      if (isReadQuery(parsed.sql)) {
+        return httpClient.query<T>(parsed.sql, parsed.params);
+      }
+
+      // For write queries, queue them for batch execution
+      queuedStatements.push(parsed);
+
+      // Return a placeholder result
+      return Promise.resolve({
+        rows: [],
+        rowsAffected: 0,
+        executionTime: 0
+      });
+    }
+
+    // Handle direct object/array inputs
+    const parsed = SQLParser.parse(sql, values);
+    return {
+      text: parsed.sql,
+      values: parsed.params
+    };
+  };
+
+  // Attach utility methods
+  txFunction.raw = (text: string): string => SQLParser.raw(text);
+  txFunction.identifier = (name: string): string => SQLParser.identifier(name);
+
+  // Add execute method for compatibility
+  txFunction.execute = async <T = any>(sql: string | { sql: string; args?: any[] }, args?: any[]): Promise<QueryResult<T>> => {
+    checkTransactionState();
+
+    const sqlStr = typeof sql === 'string' ? sql : sql.sql;
+    const params = typeof sql === 'string' ? (args || []) : (sql.args || []);
+
+    // For read queries, execute immediately
+    if (isReadQuery(sqlStr)) {
+      return await httpClient.query<T>(sqlStr, params);
+    }
+
+    // For write queries, queue them
+    queuedStatements.push({ sql: sqlStr, params });
+
+    return {
+      rows: [],
+      rowsAffected: 0,
+      executionTime: 0
+    };
+  };
+
+  // Add query method for compatibility
+  txFunction.query = async <T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> => {
+    checkTransactionState();
+
+    if (isReadQuery(sql)) {
+      return await httpClient.query<T>(sql, params);
+    }
+
+    queuedStatements.push({ sql, params });
+    return {
+      rows: [],
+      rowsAffected: 0,
+      executionTime: 0
+    };
+  };
+
+  txFunction.commit = async (): Promise<void> => {
+    checkTransactionState();
+
+    if (queuedStatements.length === 0) {
+      isCommitted = true;
+      return;
+    }
+
+    try {
+      // Build batch: BEGIN + statements + COMMIT
+      const batchStatements = [
+        { sql: 'BEGIN', params: [] },
+        ...queuedStatements,
+        { sql: 'COMMIT', params: [] }
+      ];
+
+      // Execute all statements atomically via batch endpoint
+      await httpClient.batch(batchStatements);
+
+      isCommitted = true;
+    } catch (error) {
+      isRolledBack = true;
+      throw new QueryError(
+        `Transaction failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        undefined,
+        undefined,
+        error instanceof Error ? error : undefined
+      );
+    }
+  };
+
+  txFunction.rollback = async (): Promise<void> => {
+    checkTransactionState();
+    // For batch transactions, rollback is implicit - we just don't commit
+    // Clear the queue and mark as rolled back
+    queuedStatements.length = 0;
+    isRolledBack = true;
+  };
+
+  txFunction.savepoint = async <T = any>(callback: (sql: Transaction) => Promise<T>): Promise<T> => {
+    checkTransactionState();
+
+    // Create a nested transaction that collects its own statements
+    const savepointStatements: Array<{ sql: string; params: any[] }> = [];
+
+    const savepointTx = <U = any>(sql: TemplateStringsArray | any, ...values: any[]): Promise<QueryResult<U>> | SQLFragment => {
+      if (isCommitted || isRolledBack) {
+        throw new QueryError('Transaction is no longer active');
+      }
+
+      if (Array.isArray(sql) && (('raw' in sql) || (typeof sql[0] === 'string' && values.length >= 0))) {
+        const parsed = SQLParser.parse(sql, values);
+
+        if (isReadQuery(parsed.sql)) {
+          return httpClient.query<U>(parsed.sql, parsed.params);
+        }
+
+        savepointStatements.push(parsed);
+        return Promise.resolve({
+          rows: [],
+          rowsAffected: 0,
+          executionTime: 0
+        });
+      }
+
+      const parsed = SQLParser.parse(sql, values);
+      return { text: parsed.sql, values: parsed.params };
+    };
+
+    (savepointTx as any).raw = (text: string): string => SQLParser.raw(text);
+    (savepointTx as any).identifier = (name: string): string => SQLParser.identifier(name);
+    (savepointTx as any).execute = async <U = any>(sql: string | { sql: string; args?: any[] }, args?: any[]): Promise<QueryResult<U>> => {
+      const sqlStr = typeof sql === 'string' ? sql : sql.sql;
+      const params = typeof sql === 'string' ? (args || []) : (sql.args || []);
+      if (isReadQuery(sqlStr)) {
+        return await httpClient.query<U>(sqlStr, params);
+      }
+      savepointStatements.push({ sql: sqlStr, params });
+      return { rows: [], rowsAffected: 0, executionTime: 0 };
+    };
+    (savepointTx as any).commit = async (): Promise<void> => {};
+    (savepointTx as any).rollback = async (): Promise<void> => {
+      savepointStatements.length = 0;
+    };
+
+    try {
+      const result = await callback(savepointTx as Transaction);
+      // On success, add savepoint statements to main transaction
+      queuedStatements.push(...savepointStatements);
+      return result;
+    } catch (error) {
+      // On error, savepoint statements are discarded (not added to main)
+      throw error;
+    }
+  };
+
+  return txFunction as Transaction;
+}
+
 /**
  * Create a transaction function similar to the main sql function
  */

package/src/database/adapters/bun-sqlite.ts

@@ -5,6 +5,7 @@ import type {
   QueryResult,
   PreparedStatement,
   BunSQLiteConfig,
+  QueryOptions,
 } from '../types'
 import {
   convertTemplateToQuery,
@@ -17,6 +18,48 @@ import {
   where
 } from '../sql-template'
 
+/**
+ * Parse JSON columns in query results
+ * Only parses if the value is a string (to avoid double-parsing)
+ */
+function parseJsonColumns<T = any>(rows: any[], jsonColumns?: string[]): T[] {
+  if (!jsonColumns || jsonColumns.length === 0) {
+    return rows
+  }
+
+  return rows.map(row => {
+    const parsed = { ...row }
+    for (const col of jsonColumns) {
+      if (col in parsed && typeof parsed[col] === 'string') {
+        try {
+          parsed[col] = JSON.parse(parsed[col])
+        } catch {
+          // Keep original value if parsing fails
+        }
+      }
+    }
+    return parsed
+  })
+}
+
+/**
+ * Stringify JSON parameters for INSERT/UPDATE queries
+ * Only stringifies if the value is an object/array (not already a string)
+ */
+function stringifyJsonParams(params: any[], stringifyParams?: Record<string, number>): any[] {
+  if (!stringifyParams || Object.keys(stringifyParams).length === 0) {
+    return params
+  }
+
+  const result = [...params]
+  for (const [_columnName, index] of Object.entries(stringifyParams)) {
+    if (index < result.length && result[index] != null && typeof result[index] === 'object') {
+      result[index] = JSON.stringify(result[index])
+    }
+  }
+  return result
+}
+
 /**
  * Bun SQLite adapter for DatabaseManager
  * Wraps bun:sqlite with Connection interface
@@ -117,14 +160,14 @@ class BunSQLiteConnection implements Connection {
   /**
    * Query with SQL string and parameters (alias for execute)
    */
-  async query<T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> {
-    return this.execute(sql, params) as Promise<QueryResult<T>>
+  async query<T = any>(sql: string, params: any[] = [], options?: QueryOptions): Promise<QueryResult<T>> {
+    return this.execute(sql, params, options) as Promise<QueryResult<T>>
   }
 
   /**
    * Execute SQL with parameters
    */
-  async execute(sql: string | { sql: string; args?: any[] }, params: any[] = []): Promise<QueryResult> {
+  async execute(sql: string | { sql: string; args?: any[] }, params: any[] = [], options?: QueryOptions): Promise<QueryResult> {
     try {
       // Handle object format { sql, args }
       let sqlStr: string
@@ -147,14 +190,25 @@ class BunSQLiteConnection implements Connection {
         sqlParams = params
       }
 
+      // Stringify JSON parameters if specified
+      if (options?.stringifyParams) {
+        sqlParams = stringifyJsonParams(sqlParams, options.stringifyParams)
+      }
+
       const stmt = this.db.query(sqlStr)
       const isSelect = sqlStr.trim().toUpperCase().startsWith('SELECT') ||
                        sqlStr.trim().toUpperCase().includes('RETURNING')
 
       if (isSelect) {
-        const rows = stmt.all(...sqlParams)
+        let rows = stmt.all(...sqlParams) as any[]
+
+        // Parse JSON columns if specified
+        if (options?.jsonColumns) {
+          rows = parseJsonColumns(rows, options.jsonColumns)
+        }
+
         return {
-          rows: rows as any[],
+          rows,
           rowsAffected: 0,
         }
       } else {

package/src/database/adapters/libsql.ts

@@ -5,6 +5,7 @@ import type {
   QueryResult,
   PreparedStatement,
   LibSQLConfig,
+  QueryOptions,
 } from '../types'
 import {
   convertTemplateToQuery,
@@ -17,6 +18,48 @@ import {
   where
 } from '../sql-template'
 
+/**
+ * Parse JSON columns in query results
+ * Only parses if the value is a string (to avoid double-parsing)
+ */
+function parseJsonColumns<T = any>(rows: any[], jsonColumns?: string[]): T[] {
+  if (!jsonColumns || jsonColumns.length === 0) {
+    return rows
+  }
+
+  return rows.map(row => {
+    const parsed = { ...row }
+    for (const col of jsonColumns) {
+      if (col in parsed && typeof parsed[col] === 'string') {
+        try {
+          parsed[col] = JSON.parse(parsed[col])
+        } catch {
+          // Keep original value if parsing fails
+        }
+      }
+    }
+    return parsed
+  })
+}
+
+/**
+ * Stringify JSON parameters for INSERT/UPDATE queries
+ * Only stringifies if the value is an object/array (not already a string)
+ */
+function stringifyJsonParams(params: any[], stringifyParams?: Record<string, number>): any[] {
+  if (!stringifyParams || Object.keys(stringifyParams).length === 0) {
+    return params
+  }
+
+  const result = [...params]
+  for (const [_columnName, index] of Object.entries(stringifyParams)) {
+    if (index < result.length && result[index] != null && typeof result[index] === 'object') {
+      result[index] = JSON.stringify(result[index])
+    }
+  }
+  return result
+}
+
 /**
  * LibSQL adapter for DatabaseManager
  * Wraps @libsql/client with Connection interface
@@ -117,15 +160,15 @@ class LibSQLConnection implements Connection {
   /**
    * Query with SQL string and parameters (alias for execute)
    */
-  async query<T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> {
-    return this.execute(sql, params) as Promise<QueryResult<T>>
+  async query<T = any>(sql: string, params: any[] = [], options?: QueryOptions): Promise<QueryResult<T>> {
+    return this.execute(sql, params, options) as Promise<QueryResult<T>>
   }
 
   /**
    * Execute SQL with parameters
    * Supports both formats: execute(sql, params) and execute({sql, args})
    */
-  async execute(sql: string | { sql: string; args?: any[] }, params: any[] = []): Promise<QueryResult> {
+  async execute(sql: string | { sql: string; args?: any[] }, params: any[] = [], options?: QueryOptions): Promise<QueryResult> {
     try {
       const target = this.txClient || this.client
 
@@ -137,19 +180,36 @@ class LibSQLConnection implements Connection {
           console.log('[LibSQL] Executing SQL:', sql)
           console.log('[LibSQL] With params:', params)
         }
-        query = { sql, args: params }
+        let args = params
+        // Stringify JSON parameters if specified
+        if (options?.stringifyParams) {
+          args = stringifyJsonParams(args, options.stringifyParams)
+        }
+        query = { sql, args }
       } else {
         if (process.env.DEBUG_SQL) {
           console.log('[LibSQL] Executing SQL:', sql.sql)
           console.log('[LibSQL] With args:', sql.args)
         }
-        query = { sql: sql.sql, args: sql.args || [] }
+        let args = sql.args || []
+        // Stringify JSON parameters if specified
+        if (options?.stringifyParams) {
+          args = stringifyJsonParams(args, options.stringifyParams)
+        }
+        query = { sql: sql.sql, args }
       }
 
       const result = await target.execute(query)
 
+      let rows = result.rows as any[]
+
+      // Parse JSON columns if specified
+      if (options?.jsonColumns) {
+        rows = parseJsonColumns(rows, options.jsonColumns)
+      }
+
       return {
-        rows: result.rows as any[],
+        rows,
         rowsAffected: Number(result.rowsAffected),
         lastInsertRowid: result.lastInsertRowid
           ? BigInt(result.lastInsertRowid.toString())