@pineliner/odb-client 1.0.6 → 1.0.7

package/src/database/adapters/odblite.ts

@@ -7,6 +7,16 @@ import type {
   PreparedStatement,
   ODBLiteConfig,
 } from '../types'
+import {
+  convertTemplateToQuery,
+  sql as sqlHelper,
+  empty,
+  raw,
+  fragment,
+  join,
+  set,
+  where
+} from '../sql-template'
 
 /**
  * ODB-Lite adapter for DatabaseManager
@@ -15,7 +25,7 @@ import type {
 export class ODBLiteAdapter implements DatabaseAdapter {
   readonly type = 'odblite' as const
   private config: ODBLiteConfig
-  private serviceClient: ServiceClient
+  public serviceClient: ServiceClient
 
   constructor(config: ODBLiteConfig) {
     this.config = config
@@ -27,19 +37,24 @@ export class ODBLiteAdapter implements DatabaseAdapter {
 
   async connect(config: any): Promise<Connection> {
     const databaseName = config.databaseName || 'default'
+    const databaseHash = config.databaseHash // Optional: connect directly by hash
 
-    // Ensure database exists
-    const dbInfo = await this.serviceClient.getDatabaseByName(databaseName)
-
-    if (!dbInfo) {
-      // Create database - pass nodeId from config if provided, otherwise server selects
-      await this.serviceClient.createDatabase(databaseName, this.config.nodeId)
+    // If hash is provided, skip database lookup and connect directly
+    if (databaseHash) {
+      const client = new ODBLiteClient({
+        baseUrl: this.config.serviceUrl,
+        apiKey: this.config.apiKey,
+        databaseId: databaseHash,
+      })
+      return new ODBLiteConnection(client, this.serviceClient, databaseName, databaseHash)
     }
 
-    // Get fresh database info
+    // Otherwise, query by name
+    // Check if database exists
     const db = await this.serviceClient.getDatabaseByName(databaseName)
+
     if (!db) {
-      throw new Error(`Database ${databaseName} not found after creation`)
+      throw new Error(`Database ${databaseName} not found. Please create it first using the admin API.`)
     }
 
     // Create ODBLiteClient for this database
@@ -87,6 +102,9 @@ class ODBLiteConnection implements Connection {
   public databaseName: string
   public databaseHash: string
 
+  // Dual-purpose sql method (postgres.js-compatible)
+  public sql: any
+
   constructor(
     client: ODBLiteClient,
     serviceClient: ServiceClient,
@@ -97,22 +115,48 @@ class ODBLiteConnection implements Connection {
     this.serviceClient = serviceClient
     this.databaseName = databaseName
     this.databaseHash = databaseHash
-  }
 
-  /**
-   * Template tag query (postgres.js-like)
-   */
-  async sql<T = any>(
-    strings: TemplateStringsArray,
-    ...values: any[]
-  ): Promise<QueryResult<T>> {
-    // ODBLiteClient.sql is a function that returns a Promise
-    const result = await this.client.sql(strings, ...values)
+    // Create dual-purpose sql method (postgres.js lazy evaluation pattern)
+    // Handles both template tag calls AND helper function calls
+    const self = this
+    this.sql = function(stringsOrValue: any, ...values: any[]): any {
+      // Check if called as template tag (has 'raw' property)
+      if (stringsOrValue && typeof stringsOrValue === 'object' && 'raw' in stringsOrValue) {
+        // Template literal call: sql`SELECT...`
+        // Return a thenable SqlFragment (lazy evaluation):
+        // - Can be embedded in other queries as SqlFragment
+        // - Can be awaited to execute and return rows
+        const query = convertTemplateToQuery(stringsOrValue, values)
 
-    return {
-      rows: result.rows as T[],
-      rowsAffected: result.rowsAffected || 0,
+        // Create thenable fragment
+        const thenableFragment: any = {
+          _isSqlFragment: true,
+          sql: query.sql,
+          args: query.args
+        }
+
+        // Make it awaitable by adding then method (using bracket notation to avoid linter error)
+        thenableFragment['then'] = function(onFulfilled: any, onRejected: any) {
+          return self.execute(query)
+            .then(result => result.rows)
+            .then(onFulfilled, onRejected)
+        }
+
+        return thenableFragment
+      } else {
+        // Regular function call: sql(['col1', 'col2']) or sql(obj, 'key')
+        // Return SqlFragment for use in template literals
+        return sqlHelper(stringsOrValue, ...values)
+      }
     }
+
+    // Attach helper methods as properties (postgres.js style)
+    this.sql.empty = empty
+    this.sql.raw = raw
+    this.sql.fragment = fragment
+    this.sql.join = join
+    this.sql.set = set
+    this.sql.where = where
   }
 
   /**
@@ -129,22 +173,34 @@ class ODBLiteConnection implements Connection {
     try {
       // Handle object format { sql, args }
       if (typeof sql === 'object') {
+        // Debug logging for SQL errors
+        if (process.env.DEBUG_SQL) {
+          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,
         }
       }
 
       // Handle string format
+      if (process.env.DEBUG_SQL) {
+        console.log('[ODBLite] Executing SQL:', sql)
+        console.log('[ODBLite] With params:', params)
+      }
       const result = await this.client.sql.execute(sql, params)
 
       return {
         rows: result.rows,
         rowsAffected: result.rowsAffected || 0,
+        lastInsertRowid: (result as any).lastInsertRowid,
       }
     } catch (error: any) {
-      throw new Error(`SQL execution failed: ${error.message}`)
+      // Re-throw the original error to let the application handle it
+      throw error
     }
   }
 
@@ -207,4 +263,12 @@ class ODBLiteConnection implements Connection {
     // ODBLiteClient connections are stateless HTTP requests
     // No explicit close needed
   }
+
+  /**
+   * Create ORM instance for this connection
+   */
+  createORM(): any {
+    const { createORM } = require('../../orm/index.ts')
+    return createORM(this)
+  }
 }

package/src/database/index.ts

@@ -5,6 +5,10 @@ export { DatabaseManager } from './manager'
 export { parseSQL, splitSQLStatements } from './sql-parser'
 export type { ParsedStatements, SQLParserOptions } from './sql-parser'
 
+// SQL Template helpers (postgres.js-compatible)
+export { sql, raw, empty, fragment, join, set, where, convertTemplateToQuery } from './sql-template'
+export type { SqlQuery, SqlFragment } from './sql-template'
+
 // Backend adapters
 export { BunSQLiteAdapter } from './adapters/bun-sqlite'
 export { LibSQLAdapter } from './adapters/libsql'

package/src/database/sql-template.examples.ts

@@ -0,0 +1,363 @@
+/**
+ * SQL Template Examples - postgres.js Compatible Usage
+ *
+ * This file demonstrates all supported postgres.js patterns with our sql-template implementation.
+ * These examples show the exact usage from postgres.js documentation.
+ *
+ * NOTE: This file is for documentation only - not included in build
+ * @file sql-template.examples.ts
+ */
+
+// @ts-nocheck - This file is for documentation purposes only
+
+import { sql, set, fragment, empty, raw, join, where } from './sql-template'
+import type { Connection } from './types'
+
+// Mock connection for type checking
+declare const db: any
+
+/**
+ * Example 1: Query Parameters (Basic)
+ */
+async function example1_queryParameters() {
+  const name = 'John'
+  const age = 30
+
+  // Simple parameterized query
+  await db`SELECT * FROM users WHERE name = ${name} AND age > ${age}`
+  // → SELECT * FROM users WHERE name = ? AND age = ?
+  // → args: ["John", 30]
+}
+
+/**
+ * Example 2: Dynamic Column Selection
+ */
+async function example2_dynamicColumns() {
+  const columns = ['name', 'age']
+
+  await db`
+    SELECT ${sql(columns)}
+    FROM users
+  `
+  // → SELECT name, age FROM users
+}
+
+/**
+ * Example 3: Dynamic Insert (Single Object)
+ */
+async function example3_dynamicInsert() {
+  const user = {
+    name: 'Murray',
+    age: 68
+  }
+
+  // With explicit columns
+  await db`INSERT INTO users ${sql(user, 'name', 'age')}`
+  // → INSERT INTO users (name, age) VALUES (?, ?)
+  // → args: ["Murray", 68]
+
+  // With columns array
+  const columns = ['name', 'age']
+  await db`INSERT INTO users ${sql(user, columns)}`
+  // → INSERT INTO users (name, age) VALUES (?, ?)
+}
+
+/**
+ * Example 4: Bulk Insert (Array of Objects)
+ */
+async function example4_bulkInsert() {
+  const users = [
+    { name: 'Murray', age: 68, garbage: 'ignore' },
+    { name: 'Walter', age: 80 }
+  ]
+
+  // With specific columns
+  await db`INSERT INTO users ${sql(users, 'name', 'age')}`
+  // → INSERT INTO users (name, age) VALUES (?, ?), (?, ?)
+  // → args: ["Murray", 68, "Walter", 80]
+
+  // Using all keys from first object
+  await db`INSERT INTO users ${sql(users)}`
+  // → INSERT INTO users (name, age, garbage) VALUES (?, ?, ?), (?, ?, ?)
+  // → args: ["Murray", 68, "ignore", "Walter", 80, undefined]
+}
+
+/**
+ * Example 5: Dynamic Column Updates
+ */
+async function example5_dynamicUpdate() {
+  const user = {
+    id: 1,
+    name: 'Murray',
+    age: 68
+  }
+
+  // Using set() helper with specific columns
+  await db`
+    UPDATE users
+    SET ${set(user, 'name', 'age')}
+    WHERE user_id = ${user.id}
+  `
+  // → UPDATE users SET name = ?, age = ? WHERE user_id = ?
+  // → args: ["Murray", 68, 1]
+
+  // Using set() with object (all keys)
+  const updates = { name: user.name, age: user.age }
+  await db`
+    UPDATE users
+    SET ${set(updates)}
+    WHERE user_id = ${user.id}
+  `
+  // → UPDATE users SET name = ?, age = ? WHERE user_id = ?
+
+  // Columns can also be given with an array
+  const columns = ['name', 'age']
+  await db`
+    UPDATE users
+    SET ${set(user, ...columns)}
+    WHERE user_id = ${user.id}
+  `
+}
+
+/**
+ * Example 6: Multiple Updates in One Query
+ */
+async function example6_multipleUpdates() {
+  const users = [
+    [1, 'John', 34],
+    [2, 'Jane', 27],
+  ]
+
+  await db`
+    UPDATE users
+    SET name = update_data.name, age = (update_data.age)::int
+    FROM (VALUES ${sql(users)}) AS update_data (id, name, age)
+    WHERE users.id = (update_data.id)::int
+    RETURNING users.id, users.name, users.age
+  `
+  // → UPDATE users SET name = update_data.name, age = (update_data.age)::int
+  //   FROM (VALUES (?, ?, ?), (?, ?, ?)) AS update_data (id, name, age)
+  //   WHERE users.id = (update_data.id)::int
+  //   RETURNING users.id, users.name, users.age
+  // → args: [1, "John", 34, 2, "Jane", 27]
+}
+
+/**
+ * Example 7: Dynamic WHERE IN Clause
+ */
+async function example7_whereIn() {
+  // Using sql() wrapper
+  const users1 = await db`
+    SELECT *
+    FROM users
+    WHERE age IN ${sql([68, 75, 23])}
+  `
+  // → SELECT * FROM users WHERE age IN (?, ?, ?)
+  // → args: [68, 75, 23]
+
+  // Using array directly (auto-converted)
+  const users2 = await db`
+    SELECT *
+    FROM users
+    WHERE age IN ${[68, 75, 23]}
+  `
+  // → SELECT * FROM users WHERE age IN (?, ?, ?)
+  // → args: [68, 75, 23]
+}
+
+/**
+ * Example 8: Dynamic Values in SELECT
+ */
+async function example8_dynamicValues() {
+  const [{ a, b, c }] = await db`
+    SELECT *
+    FROM (VALUES ${sql(['a', 'b', 'c'])}) AS x(a, b, c)
+  `
+  // Note: sql(['a', 'b', 'c']) produces "a, b, c" (column list)
+  // For VALUES with actual data, use 2D array or direct template
+}
+
+/**
+ * Example 9: Conditional Fragments
+ */
+async function example9_conditionalFragments() {
+  const isAdmin = true
+  const minAge = 25
+
+  await db`
+    SELECT * FROM users
+    WHERE is_active = 1
+    ${isAdmin ? fragment`AND role = 'admin'` : empty()}
+    ${minAge ? fragment`AND age >= ${minAge}` : empty()}
+  `
+  // → SELECT * FROM users WHERE is_active = 1 AND role = 'admin' AND age >= ?
+  // → args: [25]
+}
+
+/**
+ * Example 10: Transactions
+ */
+async function example10_transactions() {
+  const user = { name: 'John', email: 'john@example.com' }
+  const userId = 1
+  const amount = 100
+
+  await db.begin(async tx => {
+    await tx`INSERT INTO users ${sql(user, 'name', 'email')}`
+    await tx`UPDATE accounts SET balance = balance - ${amount} WHERE user_id = ${userId}`
+  })
+  // Automatically commits on success, rolls back on error
+}
+
+/**
+ * Example 11: Raw SQL (Dangerous!)
+ */
+async function example11_rawSql() {
+  const tableName = 'users'  // From config, not user input!
+  const userId = 1
+
+  await db`SELECT * FROM ${raw(tableName)} WHERE id = ${userId}`
+  // → SELECT * FROM users WHERE id = ?
+  // → args: [1]
+
+  // ❌ NEVER DO THIS with user input:
+  // const userTable = req.query.table  // Dangerous!
+  // await db`SELECT * FROM ${raw(userTable)}`  // SQL injection!
+}
+
+/**
+ * Example 12: Reusable Fragments
+ */
+async function example12_reusableFragments() {
+  // Static fragment
+  const activeUsers = fragment`is_active = 1 AND is_deleted = 0`
+
+  // Parameterized fragment function
+  const olderThan = (age: number) => fragment`age > ${age}`
+  const youngerThan = (age: number) => fragment`age < ${age}`
+
+  await db`
+    SELECT * FROM users
+    WHERE ${activeUsers}
+    AND ${olderThan(25)}
+  `
+  // → SELECT * FROM users WHERE is_active = 1 AND is_deleted = 0 AND age > ?
+  // → args: [25]
+
+  // Complex reusable conditions
+  const validUser = fragment`
+    is_active = 1
+    AND is_deleted = 0
+    AND is_verified = 1
+    AND banned_at IS NULL
+  `
+
+  const adminUser = fragment`${validUser} AND role = 'admin'`
+
+  await db`SELECT * FROM users WHERE ${adminUser}`
+}
+
+/**
+ * Example 13: Combining Fragments with join()
+ */
+async function example13_joiningFragments() {
+  const conditions = [
+    fragment`age > ${25}`,
+    fragment`country = ${'US'}`,
+    fragment`is_active = 1`
+  ]
+
+  await db`
+    SELECT * FROM users
+    WHERE ${join(conditions, ' AND ')}
+  `
+  // → SELECT * FROM users WHERE age > ? AND country = ? AND is_active = 1
+  // → args: [25, "US"]
+}
+
+/**
+ * Example 14: WHERE Helper
+ */
+async function example14_whereHelper() {
+  const filters = { is_active: 1, role: 'admin', age: 30 }
+
+  await db`
+    SELECT * FROM users
+    WHERE ${where(filters)}
+  `
+  // → SELECT * FROM users WHERE is_active = ? AND role = ? AND age = ?
+  // → args: [1, "admin", 30]
+}
+
+/**
+ * Example 15: Complex Real-World Example
+ */
+async function example15_complexRealWorld() {
+  const searchTerm = 'john'
+  const filters = {
+    is_active: 1,
+    is_deleted: 0
+  }
+  const minAge = 25
+  const maxAge = 65
+  const roles = ['admin', 'moderator']
+  const sortBy = 'created_at'
+
+  await db`
+    SELECT ${sql(['id', 'name', 'email', 'role', 'created_at'])}
+    FROM users
+    WHERE ${where(filters)}
+      ${searchTerm ? fragment`AND (name LIKE ${'%' + searchTerm + '%'} OR email LIKE ${'%' + searchTerm + '%'})` : empty()}
+      ${minAge ? fragment`AND age >= ${minAge}` : empty()}
+      ${maxAge ? fragment`AND age <= ${maxAge}` : empty()}
+      ${roles.length > 0 ? fragment`AND role IN ${roles}` : empty()}
+    ORDER BY ${raw(sortBy)} DESC
+    LIMIT 100
+  `
+  // → SELECT id, name, email, role, created_at FROM users
+  //   WHERE is_active = ? AND is_deleted = ?
+  //   AND (name LIKE ? OR email LIKE ?)
+  //   AND age >= ?
+  //   AND age <= ?
+  //   AND role IN (?, ?)
+  //   ORDER BY created_at DESC
+  //   LIMIT 100
+  // → args: [1, 0, "%john%", "%john%", 25, 65, "admin", "moderator"]
+}
+
+/**
+ * Example 16: Batch Operations
+ */
+async function example16_batchOperations() {
+  // Batch insert with 2D array
+  const userData = [
+    [1, 'John', 30],
+    [2, 'Jane', 25],
+    [3, 'Bob', 35]
+  ]
+
+  await db`
+    INSERT INTO users (id, name, age)
+    VALUES ${sql(userData)}
+  `
+  // → INSERT INTO users (id, name, age) VALUES (?, ?, ?), (?, ?, ?), (?, ?, ?)
+  // → args: [1, "John", 30, 2, "Jane", 25, 3, "Bob", 35]
+}
+
+/**
+ * All examples demonstrate postgres.js-compatible patterns:
+ *
+ * ✅ Template literals with automatic parameterization
+ * ✅ sql(columns[]) for dynamic column selection
+ * ✅ sql(object, ...keys) for INSERT statements
+ * ✅ sql(objects[], ...keys) for bulk INSERT
+ * ✅ sql(array[][]) for VALUES clause
+ * ✅ Array values for IN clauses
+ * ✅ set(object, ...keys) for UPDATE SET clauses
+ * ✅ where(object) for WHERE conditions
+ * ✅ fragment`` for reusable query parts
+ * ✅ empty() for conditional fragments
+ * ✅ raw() for unescaped SQL (use carefully!)
+ * ✅ join(fragments[], separator) for combining fragments
+ * ✅ Transactions with begin()
+ */