@pineliner/odb-client 1.0.6 → 1.0.7

package/src/database/sql-template.ts

@@ -0,0 +1,660 @@
+/**
+ * SQL Template Tag Converter - postgres.js Compatible
+ *
+ * Provides postgres.js-style SQL template literals and helper methods
+ * for safe, composable SQL query building.
+ *
+ * ## Basic Usage
+ *
+ * ```typescript
+ * import { getConnection, sql } from '@pineliner/odb-client'
+ *
+ * const db = await getConnection('tenant-id')
+ *
+ * // Simple query with parameters
+ * const users = await db`SELECT * FROM users WHERE id = ${userId}`
+ *
+ * // Use sql() helper for dynamic parts
+ * const columns = ['name', 'email', 'age']
+ * const result = await db`SELECT ${sql(columns)} FROM users`
+ * ```
+ *
+ * ## Supported Patterns (postgres.js Compatible)
+ *
+ * ### 1. Query Parameters (Basic Template Literals)
+ * ```typescript
+ * // Parameters are automatically escaped
+ * await db`SELECT * FROM users WHERE name = ${name} AND age > ${age}`
+ * // → SELECT * FROM users WHERE name = ? AND age = ?  [name, age]
+ * ```
+ *
+ * ### 2. Dynamic Column Selection
+ * ```typescript
+ * const columns = ['name', 'age']
+ *
+ * await db`
+ *   SELECT ${sql(columns)}
+ *   FROM users
+ * `
+ * // → SELECT name, age FROM users
+ * ```
+ *
+ * ### 3. Dynamic Inserts (Single Object)
+ * ```typescript
+ * const user = {
+ *   name: 'Murray',
+ *   age: 68
+ * }
+ *
+ * await db`INSERT INTO users ${sql(user, 'name', 'age')}`
+ * // → INSERT INTO users (name, age) VALUES (?, ?)
+ * //   ["Murray", 68]
+ *
+ * // Columns can also be given with an array
+ * const columns = ['name', 'age']
+ * await db`INSERT INTO users ${sql(user, columns)}`
+ * ```
+ *
+ * ### 4. Bulk Inserts (Array of Objects)
+ * ```typescript
+ * const users = [
+ *   { name: 'Murray', age: 68, garbage: 'ignore' },
+ *   { name: 'Walter', age: 80 }
+ * ]
+ *
+ * await db`INSERT INTO users ${sql(users, 'name', 'age')}`
+ * // → INSERT INTO users (name, age) VALUES (?, ?), (?, ?)
+ * //   ["Murray", 68, "Walter", 80]
+ *
+ * // Omit column names to use all object keys
+ * await db`INSERT INTO users ${sql(users)}`
+ * // → INSERT INTO users (name, age, garbage) VALUES (?, ?, ?), (?, ?, ?)
+ * ```
+ *
+ * ### 5. Dynamic Column Updates
+ * ```typescript
+ * const user = {
+ *   id: 1,
+ *   name: 'Murray',
+ *   age: 68
+ * }
+ *
+ * await db`
+ *   UPDATE users
+ *   SET ${set(user, 'name', 'age')}
+ *   WHERE user_id = ${user.id}
+ * `
+ * // → UPDATE users SET name = ?, age = ? WHERE user_id = ?
+ * //   ["Murray", 68, 1]
+ *
+ * // Or using set() helper
+ * await db`
+ *   UPDATE users
+ *   SET ${set({ name: user.name, age: user.age })}
+ *   WHERE user_id = ${user.id}
+ * `
+ * ```
+ *
+ * ### 6. Multiple Updates in One Query
+ * ```typescript
+ * 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 ... FROM (VALUES (?, ?, ?), (?, ?, ?)) AS update_data ...
+ * //   [1, "John", 34, 2, "Jane", 27]
+ * ```
+ *
+ * ### 7. Dynamic WHERE IN Clause
+ * ```typescript
+ * const users = await db`
+ *   SELECT *
+ *   FROM users
+ *   WHERE age IN ${sql([68, 75, 23])}
+ * `
+ * // → SELECT * FROM users WHERE age IN (?, ?, ?)
+ * //   [68, 75, 23]
+ *
+ * // Or use array directly in template
+ * await db`SELECT * FROM users WHERE age IN ${[68, 75, 23]}`
+ * ```
+ *
+ * ### 8. Dynamic Values in SELECT
+ * ```typescript
+ * const [{ a, b, c }] = await db`
+ *   SELECT *
+ *   FROM (VALUES ${sql(['a', 'b', 'c'])}) AS x(a, b, c)
+ * `
+ * // Note: For VALUES with string literals, use the array directly or wrap in sql()
+ * ```
+ *
+ * ### 9. Conditional Fragments
+ * ```typescript
+ * 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 >= ?
+ * //   [25]
+ * ```
+ *
+ * ### 10. Transactions
+ * ```typescript
+ * 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
+ * ```
+ *
+ * ### 11. Raw SQL (use with caution)
+ * ```typescript
+ * const tableName = 'users'  // From trusted source only!
+ * await db`SELECT * FROM ${raw(tableName)} WHERE id = ${userId}`
+ * // → SELECT * FROM users WHERE id = ?
+ * //   [userId]
+ * ```
+ *
+ * ### 12. Reusable Fragments
+ * ```typescript
+ * const activeUsers = fragment`is_active = 1 AND is_deleted = 0`
+ * const olderThan = (age: number) => fragment`age > ${age}`
+ *
+ * await db`
+ *   SELECT * FROM users
+ *   WHERE ${activeUsers}
+ *   AND ${olderThan(25)}
+ * `
+ * ```
+ *
+ * ## API Reference
+ *
+ * - `sql(columns: string[])` - Dynamic column list for SELECT
+ * - `sql(object, ...keys)` - INSERT format from single object
+ * - `sql(objects[], ...keys)` - Bulk INSERT from array of objects
+ * - `sql(array[][])` - Bulk insert values (2D array)
+ * - `fragment` `` ` - Template tag for reusable query fragments
+ * - `raw(string)` - Unescaped SQL fragment (dangerous!)
+ * - `empty()` - Empty SQL fragment for conditionals
+ * - `set(object)` - Generate SET clause for UPDATE
+ * - `where(object)` - Generate WHERE clause with AND conditions
+ * - `join(fragments[], separator)` - Combine multiple fragments
+ */
+
+export interface SqlQuery {
+  sql: string
+  args: any[]
+}
+
+export interface SqlFragment {
+  _isSqlFragment: true
+  sql: string
+  args: any[]
+}
+
+/**
+ * Convert template literal to parameterized query
+ *
+ * @param strings - Template literal strings
+ * @param values - Template literal values
+ * @returns Object with sql string and args array
+ *
+ * @example
+ * ```typescript
+ * const query = convertTemplateToQuery(
+ *   ['SELECT * FROM users WHERE id = ', ' AND name = ', ''],
+ *   [userId, userName]
+ * )
+ * // → { sql: "SELECT * FROM users WHERE id = ? AND name = ?", args: [userId, userName] }
+ * ```
+ */
+export function convertTemplateToQuery(
+  strings: TemplateStringsArray,
+  values: any[]
+): SqlQuery {
+  let sql = ''
+  const args: any[] = []
+
+  for (let i = 0; i < strings.length; i++) {
+    sql += strings[i]
+
+    if (i < values.length) {
+      const value = values[i]
+
+      // Handle SQL fragments (from sql`...` or sql())
+      if (isSqlFragment(value)) {
+        sql += value.sql
+        args.push(...value.args)
+      }
+      // Handle arrays for IN clauses or bulk inserts
+      else if (Array.isArray(value)) {
+        // Check if it's a 2D array (bulk insert)
+        if (value.length > 0 && Array.isArray(value[0])) {
+          // Bulk insert: [[1, 'John'], [2, 'Jane']]
+          const rowPlaceholders = value.map(row =>
+            `(${row.map(() => '?').join(', ')})`
+          ).join(', ')
+          sql += rowPlaceholders
+          args.push(...value.flat())
+        } else {
+          // Simple array for IN clause: [1, 2, 3]
+          const placeholders = value.map(() => '?').join(', ')
+          sql += `(${placeholders})`
+          args.push(...value)
+        }
+      }
+      // Regular parameterized value
+      else {
+        sql += '?'
+        args.push(value)
+      }
+    }
+  }
+
+  return { sql, args }
+}
+
+/**
+ * Check if value is a SQL fragment
+ */
+function isSqlFragment(value: any): value is SqlFragment {
+  return value && typeof value === 'object' && value._isSqlFragment === true
+}
+
+/**
+ * sql() helper - postgres.js compatible
+ *
+ * Multi-purpose SQL helper that adapts based on arguments.
+ *
+ * @param value - Array, object, array of objects, or 2D array
+ * @param keys - Optional keys (string[] or ...string)
+ * @returns SQL fragment
+ *
+ * @example Dynamic column selection
+ * ```typescript
+ * sql(['name', 'email', 'age'])
+ * // → "name, email, age"
+ * ```
+ *
+ * @example Single object INSERT
+ * ```typescript
+ * sql({ name: 'John', age: 30 }, 'name', 'age')
+ * // → "(name, age) VALUES (?, ?)" with args ["John", 30]
+ * ```
+ *
+ * @example Single object UPDATE
+ * ```typescript
+ * sql({ name: 'John', age: 30 }, 'name', 'age')
+ * // Context determines if INSERT or UPDATE format
+ * // For UPDATE: "name" = ?, "age" = ? with args ["John", 30]
+ * // For INSERT: (name, age) VALUES (?, ?) with args ["John", 30]
+ * ```
+ *
+ * @example Array of objects (bulk insert)
+ * ```typescript
+ * sql([{ name: 'John', age: 30 }, { name: 'Jane', age: 25 }], 'name', 'age')
+ * // → "(name, age) VALUES (?, ?), (?, ?)" with args ["John", 30, "Jane", 25]
+ * ```
+ *
+ * @example 2D array (bulk insert values)
+ * ```typescript
+ * sql([[1, 'John'], [2, 'Jane']])
+ * // → "(?, ?), (?, ?)" with args [1, "John", 2, "Jane"]
+ * ```
+ *
+ * @example VALUES clause
+ * ```typescript
+ * sql(['a', 'b', 'c'])
+ * // In SELECT context: "a, b, c"
+ * // In VALUES context: You'd use the array directly in template
+ * ```
+ */
+export function sql(
+  value: any,
+  ...keys: (string | string[])[]
+): SqlFragment {
+  // Normalize keys - accept both sql(obj, 'a', 'b') and sql(obj, ['a', 'b'])
+  let columnKeys: string[] = []
+  if (keys.length > 0) {
+    if (Array.isArray(keys[0])) {
+      columnKeys = keys[0]
+    } else {
+      columnKeys = keys as string[]
+    }
+  }
+
+  // Pattern 0: Single string → raw identifier (column/table name)
+  if (typeof value === 'string' && columnKeys.length === 0) {
+    return {
+      _isSqlFragment: true,
+      sql: value,
+      args: []
+    }
+  }
+
+  // Pattern 1: Array of strings → column list for SELECT
+  if (Array.isArray(value) && value.length > 0 && typeof value[0] === 'string') {
+    return {
+      _isSqlFragment: true,
+      sql: value.join(', '),
+      args: []
+    }
+  }
+
+  // Pattern 2: Array of objects with keys → bulk insert
+  if (Array.isArray(value) && value.length > 0 && typeof value[0] === 'object' && !Array.isArray(value[0])) {
+    if (columnKeys.length === 0) {
+      // Use keys from first object
+      columnKeys = Object.keys(value[0])
+    }
+
+    // Extract values in column order for each object
+    const allValues: any[] = []
+    const rowPlaceholders: string[] = []
+
+    for (const obj of value) {
+      const rowValues = columnKeys.map(key => obj[key])
+      allValues.push(...rowValues)
+      rowPlaceholders.push(`(${columnKeys.map(() => '?').join(', ')})`)
+    }
+
+    return {
+      _isSqlFragment: true,
+      sql: `(${columnKeys.join(', ')}) VALUES ${rowPlaceholders.join(', ')}`,
+      args: allValues
+    }
+  }
+
+  // Pattern 3: Single object → INSERT or UPDATE format
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    // If no keys specified, use all keys from the object
+    if (columnKeys.length === 0) {
+      columnKeys = Object.keys(value)
+    }
+
+    const values = columnKeys.map(key => value[key])
+    const placeholders = columnKeys.map(() => '?').join(', ')
+
+    // Return INSERT format - context will determine usage
+    // For UPDATE, use set() helper instead
+    return {
+      _isSqlFragment: true,
+      sql: `(${columnKeys.join(', ')}) VALUES (${placeholders})`,
+      args: values
+    }
+  }
+
+  // Pattern 4: 2D Array → bulk insert values (raw)
+  if (Array.isArray(value) && value.length > 0 && Array.isArray(value[0])) {
+    const rowPlaceholders = value.map(row =>
+      `(${row.map(() => '?').join(', ')})`
+    ).join(', ')
+
+    return {
+      _isSqlFragment: true,
+      sql: rowPlaceholders,
+      args: value.flat()
+    }
+  }
+
+  // Pattern 5: Empty fragment (no arguments or empty array)
+  return {
+    _isSqlFragment: true,
+    sql: '',
+    args: []
+  }
+}
+
+/**
+ * Create an empty SQL fragment
+ *
+ * Useful for conditional queries where you want to add nothing.
+ *
+ * @returns Empty SQL fragment
+ *
+ * @example
+ * ```typescript
+ * const isFiltered = false
+ * await db`
+ *   SELECT * FROM users
+ *   WHERE is_active = 1
+ *   ${isFiltered ? sql`AND age > 25` : empty()}
+ * `
+ * ```
+ */
+export function empty(): SqlFragment {
+  return {
+    _isSqlFragment: true,
+    sql: '',
+    args: []
+  }
+}
+
+/**
+ * Create a raw SQL fragment (use with extreme caution!)
+ *
+ * This bypasses parameterization and inserts the string directly into SQL.
+ * **WARNING**: Can lead to SQL injection if used with untrusted input!
+ *
+ * Only use for:
+ * - Table/column names from trusted sources
+ * - SQL keywords or operators
+ * - Pre-validated identifiers
+ *
+ * @param value - Raw SQL string (must be from trusted source)
+ * @returns SQL fragment with no parameters
+ *
+ * @example Safe usage (trusted table name)
+ * ```typescript
+ * const tableName = 'users'  // From config, not user input!
+ * await db`SELECT * FROM ${raw(tableName)} WHERE id = ${userId}`
+ * ```
+ *
+ * @example UNSAFE - Never do this!
+ * ```typescript
+ * // ❌ DANGEROUS - SQL injection vulnerability!
+ * const userInput = req.query.table  // From user!
+ * await db`SELECT * FROM ${raw(userInput)}`  // Don't do this!
+ * ```
+ */
+export function raw(value: string): SqlFragment {
+  return {
+    _isSqlFragment: true,
+    sql: value,
+    args: []
+  }
+}
+
+/**
+ * Create a reusable SQL fragment from template literal
+ *
+ * Useful for building composable query parts that can be reused.
+ *
+ * @param strings - Template literal strings
+ * @param values - Template literal values
+ * @returns SQL fragment that can be embedded in other queries
+ *
+ * @example Basic fragment
+ * ```typescript
+ * const activeUsers = fragment`is_active = 1 AND is_deleted = 0`
+ *
+ * await db`SELECT * FROM users WHERE ${activeUsers}`
+ * await db`SELECT COUNT(*) FROM users WHERE ${activeUsers}`
+ * ```
+ *
+ * @example Parameterized fragment
+ * ```typescript
+ * const olderThan = (age: number) => fragment`age > ${age}`
+ * const youngerThan = (age: number) => fragment`age < ${age}`
+ *
+ * await db`
+ *   SELECT * FROM users
+ *   WHERE ${olderThan(25)} AND ${youngerThan(65)}
+ * `
+ * ```
+ *
+ * @example Complex reusable conditions
+ * ```typescript
+ * 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}`
+ * ```
+ */
+export function fragment(
+  strings: TemplateStringsArray,
+  ...values: any[]
+): SqlFragment {
+  const query = convertTemplateToQuery(strings, values)
+  return {
+    _isSqlFragment: true,
+    ...query
+  }
+}
+
+/**
+ * Combine multiple SQL fragments
+ *
+ * @param fragments - Array of SQL fragments
+ * @param separator - Optional separator (default: ', ')
+ * @returns Combined SQL fragment
+ *
+ * @example
+ * ```typescript
+ * const conditions = [
+ *   sql`age > ${25}`,
+ *   sql`country = ${'US'}`,
+ *   sql`is_active = 1`
+ * ]
+ *
+ * await db`
+ *   SELECT * FROM users
+ *   WHERE ${join(conditions, ' AND ')}
+ * `
+ * ```
+ */
+export function join(fragments: SqlFragment[], separator: string = ', '): SqlFragment {
+  if (fragments.length === 0) {
+    return empty()
+  }
+
+  const sql = fragments.map(f => f.sql).join(separator)
+  const args = fragments.flatMap(f => f.args)
+
+  return {
+    _isSqlFragment: true,
+    sql,
+    args
+  }
+}
+
+/**
+ * Create SET clause for UPDATE queries
+ *
+ * @param data - Object with column: value pairs
+ * @param keys - Optional array of keys to include (filters the object)
+ * @returns SQL fragment for SET clause
+ *
+ * @example All keys
+ * ```typescript
+ * const updates = { name: 'John Doe', age: 31, updated_at: new Date() }
+ *
+ * await db`
+ *   UPDATE users
+ *   SET ${set(updates)}
+ *   WHERE id = ${userId}
+ * `
+ * // → UPDATE users SET name = ?, age = ?, updated_at = ? WHERE id = ?
+ * ```
+ *
+ * @example Specific keys only
+ * ```typescript
+ * const user = { id: 1, name: 'Murray', age: 68 }
+ *
+ * await db`
+ *   UPDATE users
+ *   SET ${set(user, 'name', 'age')}
+ *   WHERE user_id = ${user.id}
+ * `
+ * // → UPDATE users SET name = ?, age = ? WHERE user_id = ?
+ * ```
+ */
+export function set(
+  data: Record<string, any>,
+  ...keys: string[]
+): SqlFragment {
+  let columns: string[]
+
+  if (keys.length > 0) {
+    // Use only specified keys
+    columns = keys
+  } else {
+    // Use all keys from object
+    columns = Object.keys(data)
+  }
+
+  if (columns.length === 0) {
+    return empty()
+  }
+
+  const setClauses = columns.map(key => `${key} = ?`)
+  const values = columns.map(key => data[key])
+
+  return {
+    _isSqlFragment: true,
+    sql: setClauses.join(', '),
+    args: values
+  }
+}
+
+/**
+ * Create WHERE clause from object (AND conditions)
+ *
+ * @param conditions - Object with column: value pairs
+ * @returns SQL fragment for WHERE clause
+ *
+ * @example
+ * ```typescript
+ * 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 = ?
+ * ```
+ */
+export function where(conditions: Record<string, any>): SqlFragment {
+  const entries = Object.entries(conditions)
+  if (entries.length === 0) {
+    return empty()
+  }
+
+  const whereClauses = entries.map(([key]) => `${key} = ?`)
+  const values = entries.map(([, value]) => value)
+
+  return {
+    _isSqlFragment: true,
+    sql: whereClauses.join(' AND '),
+    args: values
+  }
+}

package/src/database/types.ts

@@ -28,12 +28,21 @@ export interface QueryResult<T = any> {
 /**
  * Unified database connection interface
  * All backends implement this through adapters
+ *
+ * postgres.js-compatible API:
+ * - sql`...` returns rows array directly (not QueryResult)
+ * - sql() can be called as helper function for fragments
+ * - sql.empty(), sql.raw(), etc. are available as helper methods
  */
 export interface Connection {
-  // Template tag queries (postgres.js-like)
-  sql<T = any>(strings: TemplateStringsArray, ...values: any[]): Promise<QueryResult<T>>
+  // Template tag queries (postgres.js-compatible)
+  // Returns rows array directly, not { rows: [...] }
+  sql<T = any>(strings: TemplateStringsArray, ...values: any[]): Promise<T[]>
 
-  // Standard query methods (same as execute)
+  // Helper function overload (for fragments like sql(['col1', 'col2']))
+  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>
   prepare(sql: string): PreparedStatement
@@ -45,6 +54,9 @@ export interface Connection {
   // Connection management
   close(): Promise<void>
 
+  // ORM support (optional)
+  createORM?(): any
+
   // Metadata (optional, ODB-Lite specific)
   databaseHash?: string
   databaseName?: string