@tanstack/electric-db-collection 0.2.12 → 0.2.14

package/src/sql-compiler.ts

@@ -1,6 +1,6 @@
-import { serialize } from "./pg-serializer"
-import type { SubsetParams } from "@electric-sql/client"
-import type { IR, LoadSubsetOptions } from "@tanstack/db"
+import { serialize } from './pg-serializer'
+import type { SubsetParams } from '@electric-sql/client'
+import type { IR, LoadSubsetOptions } from '@tanstack/db'
 
 export type CompiledSqlRecord = Omit<SubsetParams, `params`> & {
   params?: Array<unknown>
@@ -45,7 +45,7 @@ export function compileSQL<T>(options: LoadSubsetOptions): SubsetParams {
       }
       return acc
     },
-    {} as Record<string, string>
+    {} as Record<string, string>,
   )
 
   return {
@@ -72,7 +72,7 @@ function quoteIdentifier(name: string): string {
  */
 function compileBasicExpression(
   exp: IR.BasicExpression<unknown>,
-  params: Array<unknown>
+  params: Array<unknown>,
 ): string {
   switch (exp.type) {
     case `val`:
@@ -82,7 +82,7 @@ function compileBasicExpression(
       // TODO: doesn't yet support JSON(B) values which could be accessed with nested props
       if (exp.path.length !== 1) {
         throw new Error(
-          `Compiler can't handle nested properties: ${exp.path.join(`.`)}`
+          `Compiler can't handle nested properties: ${exp.path.join(`.`)}`,
         )
       }
       return quoteIdentifier(exp.path[0]!)
@@ -95,14 +95,14 @@ function compileBasicExpression(
 
 function compileOrderBy(orderBy: IR.OrderBy, params: Array<unknown>): string {
   const compiledOrderByClauses = orderBy.map((clause: IR.OrderByClause) =>
-    compileOrderByClause(clause, params)
+    compileOrderByClause(clause, params),
   )
   return compiledOrderByClauses.join(`,`)
 }
 
 function compileOrderByClause(
   clause: IR.OrderByClause,
-  params: Array<unknown>
+  params: Array<unknown>,
 ): string {
   // FIXME: We should handle stringSort and locale.
   //        Correctly supporting them is tricky as it depends on Postgres' collation
@@ -124,16 +124,43 @@ function compileOrderByClause(
   return sql
 }
 
+/**
+ * Check if a BasicExpression represents a null/undefined value
+ */
+function isNullValue(exp: IR.BasicExpression<unknown>): boolean {
+  return exp.type === `val` && (exp.value === null || exp.value === undefined)
+}
+
 function compileFunction(
   exp: IR.Func<unknown>,
-  params: Array<unknown> = []
+  params: Array<unknown> = [],
 ): string {
   const { name, args } = exp
 
   const opName = getOpName(name)
 
+  // Handle comparison operators with null/undefined values
+  // These would create invalid queries with missing params (e.g., "col = $1" with empty params)
+  // In SQL, all comparisons with NULL return UNKNOWN, so these are almost always mistakes
+  if (isComparisonOp(name)) {
+    const nullArgIndex = args.findIndex((arg: IR.BasicExpression) =>
+      isNullValue(arg),
+    )
+
+    if (nullArgIndex !== -1) {
+      // All comparison operators (including eq) throw an error for null values
+      // Users should use isNull() or isUndefined() to check for null values
+      throw new Error(
+        `Cannot use null/undefined value with '${name}' operator. ` +
+          `Comparisons with null always evaluate to UNKNOWN in SQL. ` +
+          `Use isNull() or isUndefined() to check for null values, ` +
+          `or filter out null values before building the query.`,
+      )
+    }
+  }
+
   const compiledArgs = args.map((arg: IR.BasicExpression) =>
-    compileBasicExpression(arg, params)
+    compileBasicExpression(arg, params),
   )
 
   // Special case for IS NULL / IS NOT NULL - these are postfix operators
@@ -172,6 +199,120 @@ function compileFunction(
       throw new Error(`Binary operator ${name} expects 2 arguments`)
     }
     const [lhs, rhs] = compiledArgs
+
+    // Special case for comparison operators with boolean values
+    // PostgreSQL doesn't support < > <= >= on booleans
+    // Transform to equivalent equality checks or constant expressions
+    if (isBooleanComparisonOp(name)) {
+      const lhsArg = args[0]
+      const rhsArg = args[1]
+
+      // Check if RHS is a boolean literal value
+      if (
+        rhsArg &&
+        rhsArg.type === `val` &&
+        typeof rhsArg.value === `boolean`
+      ) {
+        const boolValue = rhsArg.value
+        // Remove the boolean param we just added since we'll transform the expression
+        params.pop()
+
+        // Transform based on operator and boolean value
+        // Boolean ordering: false < true
+        if (name === `lt`) {
+          if (boolValue === true) {
+            // lt(col, true) → col = false (only false is less than true)
+            params.push(false)
+            return `${lhs} = $${params.length}`
+          } else {
+            // lt(col, false) → nothing is less than false
+            return `false`
+          }
+        } else if (name === `gt`) {
+          if (boolValue === false) {
+            // gt(col, false) → col = true (only true is greater than false)
+            params.push(true)
+            return `${lhs} = $${params.length}`
+          } else {
+            // gt(col, true) → nothing is greater than true
+            return `false`
+          }
+        } else if (name === `lte`) {
+          if (boolValue === true) {
+            // lte(col, true) → everything is ≤ true
+            return `true`
+          } else {
+            // lte(col, false) → col = false
+            params.push(false)
+            return `${lhs} = $${params.length}`
+          }
+        } else if (name === `gte`) {
+          if (boolValue === false) {
+            // gte(col, false) → everything is ≥ false
+            return `true`
+          } else {
+            // gte(col, true) → col = true
+            params.push(true)
+            return `${lhs} = $${params.length}`
+          }
+        }
+      }
+
+      // Check if LHS is a boolean literal value (less common but handle it)
+      if (
+        lhsArg &&
+        lhsArg.type === `val` &&
+        typeof lhsArg.value === `boolean`
+      ) {
+        const boolValue = lhsArg.value
+        // Remove params for this expression and rebuild
+        params.pop() // remove RHS
+        params.pop() // remove LHS (boolean)
+
+        // Recompile RHS to get fresh param
+        const rhsCompiled = compileBasicExpression(rhsArg!, params)
+
+        // Transform: flip the comparison (val op col → col flipped_op val)
+        if (name === `lt`) {
+          // lt(true, col) → gt(col, true) → col > true → nothing is greater than true
+          if (boolValue === true) {
+            return `false`
+          } else {
+            // lt(false, col) → gt(col, false) → col = true
+            params.push(true)
+            return `${rhsCompiled} = $${params.length}`
+          }
+        } else if (name === `gt`) {
+          // gt(true, col) → lt(col, true) → col = false
+          if (boolValue === true) {
+            params.push(false)
+            return `${rhsCompiled} = $${params.length}`
+          } else {
+            // gt(false, col) → lt(col, false) → nothing is less than false
+            return `false`
+          }
+        } else if (name === `lte`) {
+          if (boolValue === false) {
+            // lte(false, col) → gte(col, false) → everything
+            return `true`
+          } else {
+            // lte(true, col) → gte(col, true) → col = true
+            params.push(true)
+            return `${rhsCompiled} = $${params.length}`
+          }
+        } else if (name === `gte`) {
+          if (boolValue === true) {
+            // gte(true, col) → lte(col, true) → everything
+            return `true`
+          } else {
+            // gte(false, col) → lte(col, false) → col = false
+            params.push(false)
+            return `${rhsCompiled} = $${params.length}`
+          }
+        }
+      }
+    }
+
     // Special case for = ANY operator which needs parentheses around the array parameter
     if (name === `in`) {
       return `${lhs} ${opName}(${rhs})`
@@ -198,6 +339,24 @@ function isBinaryOp(name: string): boolean {
   return binaryOps.includes(name)
 }
 
+/**
+ * Check if operator is a comparison operator that takes two values
+ * These operators cannot accept null/undefined as values
+ * (null comparisons in SQL always evaluate to UNKNOWN)
+ */
+function isComparisonOp(name: string): boolean {
+  const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`]
+  return comparisonOps.includes(name)
+}
+
+/**
+ * Checks if the operator is a comparison operator (excluding eq)
+ * These operators don't work on booleans in PostgreSQL without casting
+ */
+function isBooleanComparisonOp(name: string): boolean {
+  return [`gt`, `gte`, `lt`, `lte`].includes(name)
+}
+
 function getOpName(name: string): string {
   const opNames = {
     eq: `=`,