@pineliner/odb-client 1.0.7 → 1.0.9

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())

package/src/database/adapters/odblite.ts

@@ -6,6 +6,7 @@ import type {
   QueryResult,
   PreparedStatement,
   ODBLiteConfig,
+  QueryOptions,
 } from '../types'
 import {
   convertTemplateToQuery,
@@ -18,6 +19,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
+}
+
 /**
  * ODB-Lite adapter for DatabaseManager
  * Wraps ServiceClient and ODBLiteClient with Connection interface
@@ -162,15 +205,19 @@ class ODBLiteConnection 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 {
+      let rows: any[]
+      let rowsAffected: number
+      let lastInsertRowid: any
+
       // Handle object format { sql, args }
       if (typeof sql === 'object') {
         // Debug logging for SQL errors
@@ -178,25 +225,41 @@ class ODBLiteConnection implements Connection {
           console.log('[ODBLite] Executing SQL:', sql.sql)
           console.log('[ODBLite] With args:', sql.args)
         }
-        const result = await this.client.sql.execute(sql.sql, sql.args || [])
-        return {
-          rows: result.rows,
-          rowsAffected: result.rowsAffected || 0,
-          lastInsertRowid: (result as any).lastInsertRowid,
+        let args = sql.args || []
+        // Stringify JSON parameters if specified
+        if (options?.stringifyParams) {
+          args = stringifyJsonParams(args, options.stringifyParams)
+        }
+        const result = await this.client.sql.execute(sql.sql, args)
+        rows = result.rows
+        rowsAffected = result.rowsAffected || 0
+        lastInsertRowid = (result as any).lastInsertRowid
+      } else {
+        // Handle string format
+        if (process.env.DEBUG_SQL) {
+          console.log('[ODBLite] Executing SQL:', sql)
+          console.log('[ODBLite] With params:', params)
+        }
+        let args = params
+        // Stringify JSON parameters if specified
+        if (options?.stringifyParams) {
+          args = stringifyJsonParams(args, options.stringifyParams)
         }
+        const result = await this.client.sql.execute(sql, args)
+        rows = result.rows
+        rowsAffected = result.rowsAffected || 0
+        lastInsertRowid = (result as any).lastInsertRowid
       }
 
-      // Handle string format
-      if (process.env.DEBUG_SQL) {
-        console.log('[ODBLite] Executing SQL:', sql)
-        console.log('[ODBLite] With params:', params)
+      // Parse JSON columns if specified
+      if (options?.jsonColumns) {
+        rows = parseJsonColumns(rows, options.jsonColumns)
       }
-      const result = await this.client.sql.execute(sql, params)
 
       return {
-        rows: result.rows,
-        rowsAffected: result.rowsAffected || 0,
-        lastInsertRowid: (result as any).lastInsertRowid,
+        rows,
+        rowsAffected,
+        lastInsertRowid,
       }
     } catch (error: any) {
       // Re-throw the original error to let the application handle it

package/src/database/types.ts

@@ -25,6 +25,32 @@ export interface QueryResult<T = any> {
   lastInsertRowid?: number | bigint
 }
 
+/**
+ * Query options for fine-grained control
+ */
+export interface QueryOptions {
+  /**
+   * List of column names that should be auto-parsed as JSON when reading
+   * Only applies to columns that contain stringified JSON in SELECT queries
+   *
+   * @example
+   * await conn.query('SELECT * FROM suppliers', [], { jsonColumns: ['connections', 'config'] })
+   */
+  jsonColumns?: string[]
+
+  /**
+   * Automatically stringify parameters for JSON columns in UPDATE/INSERT queries
+   * Maps column names to parameter indices (0-based)
+   *
+   * @example
+   * // UPDATE suppliers SET connections = ?, updated_at = ? WHERE id = ?
+   * await conn.execute(query, [connections, now, id], {
+   *   stringifyParams: { connections: 0 }  // Auto-stringify first parameter
+   * })
+   */
+  stringifyParams?: Record<string, number>
+}
+
 /**
  * Unified database connection interface
  * All backends implement this through adapters
@@ -43,8 +69,8 @@ export interface Connection {
   sql(value: any, ...keys: string[]): any
 
   // Standard query methods (return QueryResult)
-  query<T = any>(sql: string, params?: any[]): Promise<QueryResult<T>>
-  execute(sql: string | { sql: string; args?: any[] }, params?: any[]): Promise<QueryResult>
+  query<T = any>(sql: string, params?: any[], options?: QueryOptions): Promise<QueryResult<T>>
+  execute(sql: string | { sql: string; args?: any[] }, params?: any[], options?: QueryOptions): Promise<QueryResult>
   prepare(sql: string): PreparedStatement
 
   // Transaction support

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 // ORM exports (Drizzle-like query builder)
 export {
   ORM,
+  Transaction as ORMTransaction,
   createORM,
   eq,
   ne,

package/src/orm/index.ts

@@ -461,6 +461,129 @@ class TableQueryBuilder {
   }
 }
 
+// ============================================================
+// MANUAL TRANSACTION CLASS
+// ============================================================
+
+/**
+ * Manual Transaction Control
+ * Allows explicit commit/rollback control
+ */
+export class Transaction {
+  private orm: ORM
+  private isCommitted: boolean = false
+  private isRolledBack: boolean = false
+  private db: Connection
+  private savepointName?: string
+
+  constructor(db: Connection, transactionDepth: number = 0, savepointName?: string) {
+    this.db = db
+    this.orm = new ORM(db, transactionDepth)
+    this.savepointName = savepointName
+  }
+
+  /**
+   * Access ORM methods (select, insert, update, delete)
+   */
+  select(fields?: Record<string, any>) {
+    this.checkNotFinalized()
+    return this.orm.select(fields)
+  }
+
+  insert(tableName: string) {
+    this.checkNotFinalized()
+    return this.orm.insert(tableName)
+  }
+
+  update(tableName: string) {
+    this.checkNotFinalized()
+    return this.orm.update(tableName)
+  }
+
+  delete(tableName: string) {
+    this.checkNotFinalized()
+    return this.orm.delete(tableName)
+  }
+
+  execute(sql: string, params?: any[]) {
+    this.checkNotFinalized()
+    return this.orm.execute(sql, params)
+  }
+
+  /**
+   * Create nested transaction (savepoint)
+   */
+  async transaction(): Promise<Transaction>
+  async transaction<T>(fn: (tx: ORM) => Promise<T>): Promise<T>
+  async transaction<T>(fn?: (tx: ORM) => Promise<T>): Promise<T | Transaction> {
+    this.checkNotFinalized()
+
+    if (fn) {
+      // Callback-style nested transaction
+      return await this.orm.transaction(fn)
+    } else {
+      // Manual-style nested transaction
+      return await this.orm.transaction()
+    }
+  }
+
+  /**
+   * Commit the transaction
+   */
+  async commit(): Promise<void> {
+    if (this.isCommitted) {
+      throw new Error('Transaction already committed')
+    }
+    if (this.isRolledBack) {
+      throw new Error('Transaction already rolled back')
+    }
+
+    if (this.savepointName) {
+      // Release savepoint for nested transaction
+      await this.db.execute(`RELEASE SAVEPOINT ${this.savepointName}`, [])
+    } else {
+      // Commit top-level transaction
+      await this.db.execute('COMMIT', [])
+    }
+
+    this.isCommitted = true
+  }
+
+  /**
+   * Rollback the transaction
+   */
+  async rollback(): Promise<void> {
+    if (this.isCommitted) {
+      throw new Error('Transaction already committed')
+    }
+    if (this.isRolledBack) {
+      throw new Error('Transaction already rolled back')
+    }
+
+    if (this.savepointName) {
+      // Rollback to savepoint for nested transaction
+      await this.db.execute(`ROLLBACK TO SAVEPOINT ${this.savepointName}`, [])
+    } else {
+      // Rollback top-level transaction
+      await this.db.execute('ROLLBACK', [])
+    }
+
+    this.isRolledBack = true
+  }
+
+  /**
+   * Check if transaction is finalized
+   */
+  private checkNotFinalized() {
+    if (this.isCommitted) {
+      throw new Error('Cannot perform operations on committed transaction')
+    }
+    if (this.isRolledBack) {
+      throw new Error('Cannot perform operations on rolled back transaction')
+    }
+  }
+}
+
 // ============================================================
 // ORM CONNECTION WRAPPER
 // ============================================================
@@ -471,9 +594,11 @@ class TableQueryBuilder {
  */
 export class ORM {
   private db: Connection
+  private transactionDepth: number = 0
 
-  constructor(db: Connection) {
+  constructor(db: Connection, transactionDepth: number = 0) {
     this.db = db
+    this.transactionDepth = transactionDepth
   }
 
   /**
@@ -525,6 +650,96 @@ export class ORM {
   execute(sql: string, params?: any[]) {
     return this.db.execute(sql, params)
   }
+
+  /**
+   * Execute a transaction with support for nested transactions (savepoints)
+   * @example
+   * // Callback-style transaction
+   * const result = await orm.transaction(async (tx) => {
+   *   const user = await tx.insert('users').values({ name: 'Alice' }).returning()
+   *   const profile = await tx.insert('profiles').values({
+   *     userId: user[0].id,
+   *     bio: 'Hello world',
+   *   }).returning()
+   *   return { user, profile }
+   * })
+   *
+   * @example
+   * // Manual transaction control
+   * const tx = await orm.transaction()
+   * try {
+   *   await tx.insert('users').values({ name: 'Bob' }).execute()
+   *   await tx.insert('profiles').values({ userId: 1, bio: 'Something' }).execute()
+   *   await tx.commit()
+   * } catch (err) {
+   *   await tx.rollback()
+   *   throw err
+   * }
+   *
+   * @example
+   * // Nested transaction (savepoint)
+   * await orm.transaction(async (outer) => {
+   *   await outer.insert('users').values({ name: 'Outer' })
+   *
+   *   await outer.transaction(async (inner) => {
+   *     await inner.insert('users').values({ name: 'Inner' })
+   *     // If this inner block throws, only the inner part rolls back
+   *   })
+   * })
+   */
+  async transaction(): Promise<Transaction>
+  async transaction<T>(fn: (tx: ORM) => Promise<T>): Promise<T>
+  async transaction<T>(fn?: (tx: ORM) => Promise<T>): Promise<T | Transaction> {
+    // Manual transaction control (no callback provided)
+    if (!fn) {
+      if (this.transactionDepth > 0) {
+        // Nested manual transaction - create savepoint
+        const savepointName = `sp_${this.transactionDepth}_${Date.now()}`
+        await this.db.execute(`SAVEPOINT ${savepointName}`, [])
+        return new Transaction(this.db, this.transactionDepth + 1, savepointName)
+      } else {
+        // Top-level manual transaction
+        await this.db.execute('BEGIN TRANSACTION', [])
+        return new Transaction(this.db, 1)
+      }
+    }
+
+    // Callback-style transaction
+    // Check if we're already in a transaction (nested transaction)
+    if (this.transactionDepth > 0) {
+      // Nested transaction - use savepoint
+      const savepointName = `sp_${this.transactionDepth}_${Date.now()}`
+
+      try {
+        // Create savepoint
+        await this.db.execute(`SAVEPOINT ${savepointName}`, [])
+
+        // Create a new ORM instance with incremented depth
+        const nestedOrm = new ORM(this.db, this.transactionDepth + 1)
+
+        // Execute the user's transaction function
+        const result = await fn(nestedOrm)
+
+        // Release savepoint on success
+        await this.db.execute(`RELEASE SAVEPOINT ${savepointName}`, [])
+
+        return result
+      } catch (error) {
+        // Rollback to savepoint on error
+        await this.db.execute(`ROLLBACK TO SAVEPOINT ${savepointName}`, [])
+        throw error
+      }
+    } else {
+      // Top-level transaction - use the connection's transaction method
+      return await this.db.transaction(async (txConnection) => {
+        // Create a new ORM instance wrapping the transaction connection
+        // Start at depth 1 since we're now inside a transaction
+        const txOrm = new ORM(txConnection, 1)
+        // Execute the user's transaction function with the transaction ORM
+        return await fn(txOrm)
+      })
+    }
+  }
 }
 
 /**