@tanstack/electric-db-collection 0.2.25 → 0.2.26

package/dist/esm/sql-compiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"sql-compiler.js","sources":["../../src/sql-compiler.ts"],"sourcesContent":["import { serialize } from './pg-serializer'\nimport type { SubsetParams } from '@electric-sql/client'\nimport type { IR, LoadSubsetOptions } from '@tanstack/db'\n\nexport type CompiledSqlRecord = Omit<SubsetParams, `params`> & {\n  params?: Array<unknown>\n}\n\nexport function compileSQL<T>(options: LoadSubsetOptions): SubsetParams {\n  const { where, orderBy, limit } = options\n\n  const params: Array<T> = []\n  const compiledSQL: CompiledSqlRecord = { params }\n\n  if (where) {\n    // TODO: this only works when the where expression's PropRefs directly reference a column of the collection\n    //       doesn't work if it goes through aliases because then we need to know the entire query to be able to follow the reference until the base collection (cf. followRef function)\n    compiledSQL.where = compileBasicExpression(where, params)\n  }\n\n  if (orderBy) {\n    compiledSQL.orderBy = compileOrderBy(orderBy, params)\n  }\n\n  if (limit) {\n    compiledSQL.limit = limit\n  }\n\n  // WORKAROUND for Electric bug: Empty subset requests don't load data\n  // Add dummy \"true = true\" predicate when there's no where clause\n  // This is always true so doesn't filter data, just tricks Electric into loading\n  if (!where) {\n    compiledSQL.where = `true = true`\n  }\n\n  // Serialize the values in the params array into PG formatted strings\n  // and transform the array into a Record<string, string>\n  const paramsRecord = params.reduce(\n    (acc, param, index) => {\n      const serialized = serialize(param)\n      // Empty strings are valid query values (e.g., WHERE column = '')\n      // Only omit null/undefined values from params\n      if (param != null) {\n        acc[`${index + 1}`] = serialized\n      }\n      return acc\n    },\n    {} as Record<string, string>,\n  )\n\n  return {\n    ...compiledSQL,\n    params: paramsRecord,\n  }\n}\n\n/**\n * Quote PostgreSQL identifiers to handle mixed case column names correctly.\n * Electric/Postgres requires quotes for case-sensitive identifiers.\n * @param name - The identifier to quote\n * @returns The quoted identifier\n */\nfunction quoteIdentifier(name: string): string {\n  return `\"${name}\"`\n}\n\n/**\n * Compiles the expression to a SQL string and mutates the params array with the values.\n * @param exp - The expression to compile\n * @param params - The params array\n * @returns The compiled SQL string\n */\nfunction compileBasicExpression(\n  exp: IR.BasicExpression<unknown>,\n  params: Array<unknown>,\n): string {\n  switch (exp.type) {\n    case `val`:\n      params.push(exp.value)\n      return `$${params.length}`\n    case `ref`:\n      // TODO: doesn't yet support JSON(B) values which could be accessed with nested props\n      if (exp.path.length !== 1) {\n        throw new Error(\n          `Compiler can't handle nested properties: ${exp.path.join(`.`)}`,\n        )\n      }\n      return quoteIdentifier(exp.path[0]!)\n    case `func`:\n      return compileFunction(exp, params)\n    default:\n      throw new Error(`Unknown expression type`)\n  }\n}\n\nfunction compileOrderBy(orderBy: IR.OrderBy, params: Array<unknown>): string {\n  const compiledOrderByClauses = orderBy.map((clause: IR.OrderByClause) =>\n    compileOrderByClause(clause, params),\n  )\n  return compiledOrderByClauses.join(`,`)\n}\n\nfunction compileOrderByClause(\n  clause: IR.OrderByClause,\n  params: Array<unknown>,\n): string {\n  // FIXME: We should handle stringSort and locale.\n  //        Correctly supporting them is tricky as it depends on Postgres' collation\n  const { expression, compareOptions } = clause\n  let sql = compileBasicExpression(expression, params)\n\n  if (compareOptions.direction === `desc`) {\n    sql = `${sql} DESC`\n  }\n\n  if (compareOptions.nulls === `first`) {\n    sql = `${sql} NULLS FIRST`\n  }\n\n  if (compareOptions.nulls === `last`) {\n    sql = `${sql} NULLS LAST`\n  }\n\n  return sql\n}\n\n/**\n * Check if a BasicExpression represents a null/undefined value\n */\nfunction isNullValue(exp: IR.BasicExpression<unknown>): boolean {\n  return exp.type === `val` && (exp.value === null || exp.value === undefined)\n}\n\nfunction compileFunction(\n  exp: IR.Func<unknown>,\n  params: Array<unknown> = [],\n): string {\n  const { name, args } = exp\n\n  const opName = getOpName(name)\n\n  // Handle comparison operators with null/undefined values\n  // These would create invalid queries with missing params (e.g., \"col = $1\" with empty params)\n  // In SQL, all comparisons with NULL return UNKNOWN, so these are almost always mistakes\n  if (isComparisonOp(name)) {\n    const nullArgIndex = args.findIndex((arg: IR.BasicExpression) =>\n      isNullValue(arg),\n    )\n\n    if (nullArgIndex !== -1) {\n      // All comparison operators (including eq) throw an error for null values\n      // Users should use isNull() or isUndefined() to check for null values\n      throw new Error(\n        `Cannot use null/undefined value with '${name}' operator. ` +\n          `Comparisons with null always evaluate to UNKNOWN in SQL. ` +\n          `Use isNull() or isUndefined() to check for null values, ` +\n          `or filter out null values before building the query.`,\n      )\n    }\n  }\n\n  const compiledArgs = args.map((arg: IR.BasicExpression) =>\n    compileBasicExpression(arg, params),\n  )\n\n  // Special case for IS NULL / IS NOT NULL - these are postfix operators\n  if (name === `isNull` || name === `isUndefined`) {\n    if (compiledArgs.length !== 1) {\n      throw new Error(`${name} expects 1 argument`)\n    }\n    return `${compiledArgs[0]} ${opName}`\n  }\n\n  // Special case for NOT - unary prefix operator\n  if (name === `not`) {\n    if (compiledArgs.length !== 1) {\n      throw new Error(`NOT expects 1 argument`)\n    }\n    // Check if the argument is IS NULL to generate IS NOT NULL\n    const arg = args[0]\n    if (arg && arg.type === `func`) {\n      const funcArg = arg\n      if (funcArg.name === `isNull` || funcArg.name === `isUndefined`) {\n        const innerArg = compileBasicExpression(funcArg.args[0]!, params)\n        return `${innerArg} IS NOT NULL`\n      }\n    }\n    return `${opName} (${compiledArgs[0]})`\n  }\n\n  if (isBinaryOp(name)) {\n    // Special handling for AND/OR which can be variadic\n    if ((name === `and` || name === `or`) && compiledArgs.length > 2) {\n      // Chain multiple arguments: (a AND b AND c) or (a OR b OR c)\n      return compiledArgs.map((arg) => `(${arg})`).join(` ${opName} `)\n    }\n\n    if (compiledArgs.length !== 2) {\n      throw new Error(`Binary operator ${name} expects 2 arguments`)\n    }\n    const [lhs, rhs] = compiledArgs\n\n    // Special case for comparison operators with boolean values\n    // PostgreSQL doesn't support < > <= >= on booleans\n    // Transform to equivalent equality checks or constant expressions\n    if (isBooleanComparisonOp(name)) {\n      const lhsArg = args[0]\n      const rhsArg = args[1]\n\n      // Check if RHS is a boolean literal value\n      if (\n        rhsArg &&\n        rhsArg.type === `val` &&\n        typeof rhsArg.value === `boolean`\n      ) {\n        const boolValue = rhsArg.value\n        // Remove the boolean param we just added since we'll transform the expression\n        params.pop()\n\n        // Transform based on operator and boolean value\n        // Boolean ordering: false < true\n        if (name === `lt`) {\n          if (boolValue === true) {\n            // lt(col, true) → col = false (only false is less than true)\n            params.push(false)\n            return `${lhs} = $${params.length}`\n          } else {\n            // lt(col, false) → nothing is less than false\n            return `false`\n          }\n        } else if (name === `gt`) {\n          if (boolValue === false) {\n            // gt(col, false) → col = true (only true is greater than false)\n            params.push(true)\n            return `${lhs} = $${params.length}`\n          } else {\n            // gt(col, true) → nothing is greater than true\n            return `false`\n          }\n        } else if (name === `lte`) {\n          if (boolValue === true) {\n            // lte(col, true) → everything is ≤ true\n            return `true`\n          } else {\n            // lte(col, false) → col = false\n            params.push(false)\n            return `${lhs} = $${params.length}`\n          }\n        } else if (name === `gte`) {\n          if (boolValue === false) {\n            // gte(col, false) → everything is ≥ false\n            return `true`\n          } else {\n            // gte(col, true) → col = true\n            params.push(true)\n            return `${lhs} = $${params.length}`\n          }\n        }\n      }\n\n      // Check if LHS is a boolean literal value (less common but handle it)\n      if (\n        lhsArg &&\n        lhsArg.type === `val` &&\n        typeof lhsArg.value === `boolean`\n      ) {\n        const boolValue = lhsArg.value\n        // Remove params for this expression and rebuild\n        params.pop() // remove RHS\n        params.pop() // remove LHS (boolean)\n\n        // Recompile RHS to get fresh param\n        const rhsCompiled = compileBasicExpression(rhsArg!, params)\n\n        // Transform: flip the comparison (val op col → col flipped_op val)\n        if (name === `lt`) {\n          // lt(true, col) → gt(col, true) → col > true → nothing is greater than true\n          if (boolValue === true) {\n            return `false`\n          } else {\n            // lt(false, col) → gt(col, false) → col = true\n            params.push(true)\n            return `${rhsCompiled} = $${params.length}`\n          }\n        } else if (name === `gt`) {\n          // gt(true, col) → lt(col, true) → col = false\n          if (boolValue === true) {\n            params.push(false)\n            return `${rhsCompiled} = $${params.length}`\n          } else {\n            // gt(false, col) → lt(col, false) → nothing is less than false\n            return `false`\n          }\n        } else if (name === `lte`) {\n          if (boolValue === false) {\n            // lte(false, col) → gte(col, false) → everything\n            return `true`\n          } else {\n            // lte(true, col) → gte(col, true) → col = true\n            params.push(true)\n            return `${rhsCompiled} = $${params.length}`\n          }\n        } else if (name === `gte`) {\n          if (boolValue === true) {\n            // gte(true, col) → lte(col, true) → everything\n            return `true`\n          } else {\n            // gte(false, col) → lte(col, false) → col = false\n            params.push(false)\n            return `${rhsCompiled} = $${params.length}`\n          }\n        }\n      }\n    }\n\n    // Special case for = ANY operator which needs parentheses around the array parameter\n    if (name === `in`) {\n      return `${lhs} ${opName}(${rhs})`\n    }\n    return `${lhs} ${opName} ${rhs}`\n  }\n\n  return `${opName}(${compiledArgs.join(`,`)})`\n}\n\nfunction isBinaryOp(name: string): boolean {\n  const binaryOps = [\n    `eq`,\n    `gt`,\n    `gte`,\n    `lt`,\n    `lte`,\n    `and`,\n    `or`,\n    `in`,\n    `like`,\n    `ilike`,\n  ]\n  return binaryOps.includes(name)\n}\n\n/**\n * Check if operator is a comparison operator that takes two values\n * These operators cannot accept null/undefined as values\n * (null comparisons in SQL always evaluate to UNKNOWN)\n */\nfunction isComparisonOp(name: string): boolean {\n  const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`]\n  return comparisonOps.includes(name)\n}\n\n/**\n * Checks if the operator is a comparison operator (excluding eq)\n * These operators don't work on booleans in PostgreSQL without casting\n */\nfunction isBooleanComparisonOp(name: string): boolean {\n  return [`gt`, `gte`, `lt`, `lte`].includes(name)\n}\n\nfunction getOpName(name: string): string {\n  const opNames = {\n    eq: `=`,\n    gt: `>`,\n    gte: `>=`,\n    lt: `<`,\n    lte: `<=`,\n    add: `+`,\n    and: `AND`,\n    or: `OR`,\n    not: `NOT`,\n    isUndefined: `IS NULL`,\n    isNull: `IS NULL`,\n    in: `= ANY`, // Use = ANY syntax for array parameters\n    like: `LIKE`,\n    ilike: `ILIKE`,\n    upper: `UPPER`,\n    lower: `LOWER`,\n    length: `LENGTH`,\n    concat: `CONCAT`,\n    coalesce: `COALESCE`,\n  }\n\n  const opName = opNames[name as keyof typeof opNames]\n\n  if (!opName) {\n    throw new Error(`Unknown operator/function: ${name}`)\n  }\n\n  return opName\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"sql-compiler.js","sources":["../../src/sql-compiler.ts"],"sourcesContent":["import { serialize } from './pg-serializer'\nimport type { SubsetParams } from '@electric-sql/client'\nimport type { IR, LoadSubsetOptions } from '@tanstack/db'\n\nexport type CompiledSqlRecord = Omit<SubsetParams, `params`> & {\n  params?: Array<unknown>\n}\n\n/**\n * Optional function to encode column names (e.g., camelCase to snake_case)\n * This is typically the `encode` function from a columnMapper\n */\nexport type ColumnEncoder = (columnName: string) => string\n\n/**\n * Options for SQL compilation\n */\nexport interface CompileSQLOptions {\n  /**\n   * Optional function to encode column names before quoting.\n   * Used to transform property names (e.g., camelCase) to database column names (e.g., snake_case).\n   * This should be the `encode` function from shapeOptions.columnMapper.\n   */\n  encodeColumnName?: ColumnEncoder\n}\n\nexport function compileSQL<T>(\n  options: LoadSubsetOptions,\n  compileOptions?: CompileSQLOptions,\n): SubsetParams {\n  const { where, orderBy, limit } = options\n  const encodeColumnName = compileOptions?.encodeColumnName\n\n  const params: Array<T> = []\n  const compiledSQL: CompiledSqlRecord = { params }\n\n  if (where) {\n    // TODO: this only works when the where expression's PropRefs directly reference a column of the collection\n    //       doesn't work if it goes through aliases because then we need to know the entire query to be able to follow the reference until the base collection (cf. followRef function)\n    compiledSQL.where = compileBasicExpression(where, params, encodeColumnName)\n  }\n\n  if (orderBy) {\n    compiledSQL.orderBy = compileOrderBy(orderBy, params, encodeColumnName)\n  }\n\n  if (limit) {\n    compiledSQL.limit = limit\n  }\n\n  // WORKAROUND for Electric bug: Empty subset requests don't load data\n  // Add dummy \"true = true\" predicate when there's no where clause\n  // This is always true so doesn't filter data, just tricks Electric into loading\n  if (!where) {\n    compiledSQL.where = `true = true`\n  }\n\n  // Serialize the values in the params array into PG formatted strings\n  // and transform the array into a Record<string, string>\n  const paramsRecord = params.reduce(\n    (acc, param, index) => {\n      const serialized = serialize(param)\n      // Empty strings are valid query values (e.g., WHERE column = '')\n      // Only omit null/undefined values from params\n      if (param != null) {\n        acc[`${index + 1}`] = serialized\n      }\n      return acc\n    },\n    {} as Record<string, string>,\n  )\n\n  return {\n    ...compiledSQL,\n    params: paramsRecord,\n  }\n}\n\n/**\n * Quote PostgreSQL identifiers to handle mixed case column names correctly.\n * Electric/Postgres requires quotes for case-sensitive identifiers.\n * @param name - The identifier to quote\n * @param encodeColumnName - Optional function to encode the column name before quoting (e.g., camelCase to snake_case)\n * @returns The quoted identifier\n */\nfunction quoteIdentifier(\n  name: string,\n  encodeColumnName?: ColumnEncoder,\n): string {\n  const columnName = encodeColumnName ? encodeColumnName(name) : name\n  return `\"${columnName}\"`\n}\n\n/**\n * Compiles the expression to a SQL string and mutates the params array with the values.\n * @param exp - The expression to compile\n * @param params - The params array\n * @param encodeColumnName - Optional function to encode column names (e.g., camelCase to snake_case)\n * @returns The compiled SQL string\n */\nfunction compileBasicExpression(\n  exp: IR.BasicExpression<unknown>,\n  params: Array<unknown>,\n  encodeColumnName?: ColumnEncoder,\n): string {\n  switch (exp.type) {\n    case `val`:\n      params.push(exp.value)\n      return `$${params.length}`\n    case `ref`:\n      // TODO: doesn't yet support JSON(B) values which could be accessed with nested props\n      if (exp.path.length !== 1) {\n        throw new Error(\n          `Compiler can't handle nested properties: ${exp.path.join(`.`)}`,\n        )\n      }\n      return quoteIdentifier(exp.path[0]!, encodeColumnName)\n    case `func`:\n      return compileFunction(exp, params, encodeColumnName)\n    default:\n      throw new Error(`Unknown expression type`)\n  }\n}\n\nfunction compileOrderBy(\n  orderBy: IR.OrderBy,\n  params: Array<unknown>,\n  encodeColumnName?: ColumnEncoder,\n): string {\n  const compiledOrderByClauses = orderBy.map((clause: IR.OrderByClause) =>\n    compileOrderByClause(clause, params, encodeColumnName),\n  )\n  return compiledOrderByClauses.join(`,`)\n}\n\nfunction compileOrderByClause(\n  clause: IR.OrderByClause,\n  params: Array<unknown>,\n  encodeColumnName?: ColumnEncoder,\n): string {\n  // FIXME: We should handle stringSort and locale.\n  //        Correctly supporting them is tricky as it depends on Postgres' collation\n  const { expression, compareOptions } = clause\n  let sql = compileBasicExpression(expression, params, encodeColumnName)\n\n  if (compareOptions.direction === `desc`) {\n    sql = `${sql} DESC`\n  }\n\n  if (compareOptions.nulls === `first`) {\n    sql = `${sql} NULLS FIRST`\n  }\n\n  if (compareOptions.nulls === `last`) {\n    sql = `${sql} NULLS LAST`\n  }\n\n  return sql\n}\n\n/**\n * Check if a BasicExpression represents a null/undefined value\n */\nfunction isNullValue(exp: IR.BasicExpression<unknown>): boolean {\n  return exp.type === `val` && (exp.value === null || exp.value === undefined)\n}\n\nfunction compileFunction(\n  exp: IR.Func<unknown>,\n  params: Array<unknown> = [],\n  encodeColumnName?: ColumnEncoder,\n): string {\n  const { name, args } = exp\n\n  const opName = getOpName(name)\n\n  // Handle comparison operators with null/undefined values\n  // These would create invalid queries with missing params (e.g., \"col = $1\" with empty params)\n  // In SQL, all comparisons with NULL return UNKNOWN, so these are almost always mistakes\n  if (isComparisonOp(name)) {\n    const nullArgIndex = args.findIndex((arg: IR.BasicExpression) =>\n      isNullValue(arg),\n    )\n\n    if (nullArgIndex !== -1) {\n      // All comparison operators (including eq) throw an error for null values\n      // Users should use isNull() or isUndefined() to check for null values\n      throw new Error(\n        `Cannot use null/undefined value with '${name}' operator. ` +\n          `Comparisons with null always evaluate to UNKNOWN in SQL. ` +\n          `Use isNull() or isUndefined() to check for null values, ` +\n          `or filter out null values before building the query.`,\n      )\n    }\n  }\n\n  const compiledArgs = args.map((arg: IR.BasicExpression) =>\n    compileBasicExpression(arg, params, encodeColumnName),\n  )\n\n  // Special case for IS NULL / IS NOT NULL - these are postfix operators\n  if (name === `isNull` || name === `isUndefined`) {\n    if (compiledArgs.length !== 1) {\n      throw new Error(`${name} expects 1 argument`)\n    }\n    return `${compiledArgs[0]} ${opName}`\n  }\n\n  // Special case for NOT - unary prefix operator\n  if (name === `not`) {\n    if (compiledArgs.length !== 1) {\n      throw new Error(`NOT expects 1 argument`)\n    }\n    // Check if the argument is IS NULL to generate IS NOT NULL\n    const arg = args[0]\n    if (arg && arg.type === `func`) {\n      const funcArg = arg\n      if (funcArg.name === `isNull` || funcArg.name === `isUndefined`) {\n        const innerArg = compileBasicExpression(\n          funcArg.args[0]!,\n          params,\n          encodeColumnName,\n        )\n        return `${innerArg} IS NOT NULL`\n      }\n    }\n    return `${opName} (${compiledArgs[0]})`\n  }\n\n  if (isBinaryOp(name)) {\n    // Special handling for AND/OR which can be variadic\n    if ((name === `and` || name === `or`) && compiledArgs.length > 2) {\n      // Chain multiple arguments: (a AND b AND c) or (a OR b OR c)\n      return compiledArgs.map((arg) => `(${arg})`).join(` ${opName} `)\n    }\n\n    if (compiledArgs.length !== 2) {\n      throw new Error(`Binary operator ${name} expects 2 arguments`)\n    }\n    const [lhs, rhs] = compiledArgs\n\n    // Special case for comparison operators with boolean values\n    // PostgreSQL doesn't support < > <= >= on booleans\n    // Transform to equivalent equality checks or constant expressions\n    if (isBooleanComparisonOp(name)) {\n      const lhsArg = args[0]\n      const rhsArg = args[1]\n\n      // Check if RHS is a boolean literal value\n      if (\n        rhsArg &&\n        rhsArg.type === `val` &&\n        typeof rhsArg.value === `boolean`\n      ) {\n        const boolValue = rhsArg.value\n        // Remove the boolean param we just added since we'll transform the expression\n        params.pop()\n\n        // Transform based on operator and boolean value\n        // Boolean ordering: false < true\n        if (name === `lt`) {\n          if (boolValue === true) {\n            // lt(col, true) → col = false (only false is less than true)\n            params.push(false)\n            return `${lhs} = $${params.length}`\n          } else {\n            // lt(col, false) → nothing is less than false\n            return `false`\n          }\n        } else if (name === `gt`) {\n          if (boolValue === false) {\n            // gt(col, false) → col = true (only true is greater than false)\n            params.push(true)\n            return `${lhs} = $${params.length}`\n          } else {\n            // gt(col, true) → nothing is greater than true\n            return `false`\n          }\n        } else if (name === `lte`) {\n          if (boolValue === true) {\n            // lte(col, true) → everything is ≤ true\n            return `true`\n          } else {\n            // lte(col, false) → col = false\n            params.push(false)\n            return `${lhs} = $${params.length}`\n          }\n        } else if (name === `gte`) {\n          if (boolValue === false) {\n            // gte(col, false) → everything is ≥ false\n            return `true`\n          } else {\n            // gte(col, true) → col = true\n            params.push(true)\n            return `${lhs} = $${params.length}`\n          }\n        }\n      }\n\n      // Check if LHS is a boolean literal value (less common but handle it)\n      if (\n        lhsArg &&\n        lhsArg.type === `val` &&\n        typeof lhsArg.value === `boolean`\n      ) {\n        const boolValue = lhsArg.value\n        // Remove params for this expression and rebuild\n        params.pop() // remove RHS\n        params.pop() // remove LHS (boolean)\n\n        // Recompile RHS to get fresh param\n        const rhsCompiled = compileBasicExpression(\n          rhsArg!,\n          params,\n          encodeColumnName,\n        )\n\n        // Transform: flip the comparison (val op col → col flipped_op val)\n        if (name === `lt`) {\n          // lt(true, col) → gt(col, true) → col > true → nothing is greater than true\n          if (boolValue === true) {\n            return `false`\n          } else {\n            // lt(false, col) → gt(col, false) → col = true\n            params.push(true)\n            return `${rhsCompiled} = $${params.length}`\n          }\n        } else if (name === `gt`) {\n          // gt(true, col) → lt(col, true) → col = false\n          if (boolValue === true) {\n            params.push(false)\n            return `${rhsCompiled} = $${params.length}`\n          } else {\n            // gt(false, col) → lt(col, false) → nothing is less than false\n            return `false`\n          }\n        } else if (name === `lte`) {\n          if (boolValue === false) {\n            // lte(false, col) → gte(col, false) → everything\n            return `true`\n          } else {\n            // lte(true, col) → gte(col, true) → col = true\n            params.push(true)\n            return `${rhsCompiled} = $${params.length}`\n          }\n        } else if (name === `gte`) {\n          if (boolValue === true) {\n            // gte(true, col) → lte(col, true) → everything\n            return `true`\n          } else {\n            // gte(false, col) → lte(col, false) → col = false\n            params.push(false)\n            return `${rhsCompiled} = $${params.length}`\n          }\n        }\n      }\n    }\n\n    // Special case for = ANY operator which needs parentheses around the array parameter\n    if (name === `in`) {\n      return `${lhs} ${opName}(${rhs})`\n    }\n    return `${lhs} ${opName} ${rhs}`\n  }\n\n  return `${opName}(${compiledArgs.join(`,`)})`\n}\n\nfunction isBinaryOp(name: string): boolean {\n  const binaryOps = [\n    `eq`,\n    `gt`,\n    `gte`,\n    `lt`,\n    `lte`,\n    `and`,\n    `or`,\n    `in`,\n    `like`,\n    `ilike`,\n  ]\n  return binaryOps.includes(name)\n}\n\n/**\n * Check if operator is a comparison operator that takes two values\n * These operators cannot accept null/undefined as values\n * (null comparisons in SQL always evaluate to UNKNOWN)\n */\nfunction isComparisonOp(name: string): boolean {\n  const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`]\n  return comparisonOps.includes(name)\n}\n\n/**\n * Checks if the operator is a comparison operator (excluding eq)\n * These operators don't work on booleans in PostgreSQL without casting\n */\nfunction isBooleanComparisonOp(name: string): boolean {\n  return [`gt`, `gte`, `lt`, `lte`].includes(name)\n}\n\nfunction getOpName(name: string): string {\n  const opNames = {\n    eq: `=`,\n    gt: `>`,\n    gte: `>=`,\n    lt: `<`,\n    lte: `<=`,\n    add: `+`,\n    and: `AND`,\n    or: `OR`,\n    not: `NOT`,\n    isUndefined: `IS NULL`,\n    isNull: `IS NULL`,\n    in: `= ANY`, // Use = ANY syntax for array parameters\n    like: `LIKE`,\n    ilike: `ILIKE`,\n    upper: `UPPER`,\n    lower: `LOWER`,\n    length: `LENGTH`,\n    concat: `CONCAT`,\n    coalesce: `COALESCE`,\n  }\n\n  const opName = opNames[name as keyof typeof opNames]\n\n  if (!opName) {\n    throw new Error(`Unknown operator/function: ${name}`)\n  }\n\n  return opName\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/electric-db-collection",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "ElectricSQL collection for TanStack DB",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/store": "^0.8.0",
     "debug": "^4.4.3",
-    "@tanstack/db": "0.5.20"
+    "@tanstack/db": "0.5.21"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",

package/src/electric.ts

@@ -22,6 +22,7 @@ import {
   removeTagFromIndex,
   tagMatchesPattern,
 } from './tag-index'
+import type { ColumnEncoder } from './sql-compiler'
 import type {
   MoveOutPattern,
   MoveTag,
@@ -347,6 +348,7 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
   write,
   commit,
   collectionId,
+  encodeColumnName,
 }: {
   stream: ShapeStream<T>
   syncMode: ElectricSyncMode
@@ -359,17 +361,24 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
   }) => void
   commit: () => void
   collectionId?: string
+  /**
+   * Optional function to encode column names (e.g., camelCase to snake_case).
+   * This is typically the `encode` function from shapeOptions.columnMapper.
+   */
+  encodeColumnName?: ColumnEncoder
 }): DeduplicatedLoadSubset | null {
   // Eager mode doesn't need subset loading
   if (syncMode === `eager`) {
     return null
   }
 
+  const compileOptions = encodeColumnName ? { encodeColumnName } : undefined
+
   const loadSubset = async (opts: LoadSubsetOptions) => {
     // In progressive mode, use fetchSnapshot during snapshot phase
     if (isBufferingInitialSync()) {
       // Progressive mode snapshot phase: fetch and apply immediately
-      const snapshotParams = compileSQL<T>(opts)
+      const snapshotParams = compileSQL<T>(opts, compileOptions)
       try {
         const { data: rows } = await stream.fetchSnapshot(snapshotParams)
 
@@ -428,7 +437,10 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
           orderBy,
           // No limit - get all ties
         }
-        const whereCurrentParams = compileSQL<T>(whereCurrentOpts)
+        const whereCurrentParams = compileSQL<T>(
+          whereCurrentOpts,
+          compileOptions,
+        )
         promises.push(stream.requestSnapshot(whereCurrentParams))
 
         debug(
@@ -442,7 +454,7 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
           orderBy,
           limit,
         }
-        const whereFromParams = compileSQL<T>(whereFromOpts)
+        const whereFromParams = compileSQL<T>(whereFromOpts, compileOptions)
         promises.push(stream.requestSnapshot(whereFromParams))
 
         debug(
@@ -453,7 +465,7 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
         await Promise.all(promises)
       } else {
         // No cursor - standard single request
-        const snapshotParams = compileSQL<T>(opts)
+        const snapshotParams = compileSQL<T>(opts, compileOptions)
         await stream.requestSnapshot(snapshotParams)
       }
     }
@@ -1296,6 +1308,9 @@ function createElectricSync<T extends Row<unknown>>(
         write,
         commit,
         collectionId,
+        // Pass the columnMapper's encode function to transform column names
+        // (e.g., camelCase to snake_case) when compiling SQL for subset queries
+        encodeColumnName: shapeOptions.columnMapper?.encode,
       })
 
       unsubscribeStream = stream.subscribe((messages: Array<Message<T>>) => {

package/src/sql-compiler.ts

@@ -6,8 +6,30 @@ export type CompiledSqlRecord = Omit<SubsetParams, `params`> & {
   params?: Array<unknown>
 }
 
-export function compileSQL<T>(options: LoadSubsetOptions): SubsetParams {
+/**
+ * Optional function to encode column names (e.g., camelCase to snake_case)
+ * This is typically the `encode` function from a columnMapper
+ */
+export type ColumnEncoder = (columnName: string) => string
+
+/**
+ * Options for SQL compilation
+ */
+export interface CompileSQLOptions {
+  /**
+   * Optional function to encode column names before quoting.
+   * Used to transform property names (e.g., camelCase) to database column names (e.g., snake_case).
+   * This should be the `encode` function from shapeOptions.columnMapper.
+   */
+  encodeColumnName?: ColumnEncoder
+}
+
+export function compileSQL<T>(
+  options: LoadSubsetOptions,
+  compileOptions?: CompileSQLOptions,
+): SubsetParams {
   const { where, orderBy, limit } = options
+  const encodeColumnName = compileOptions?.encodeColumnName
 
   const params: Array<T> = []
   const compiledSQL: CompiledSqlRecord = { params }
@@ -15,11 +37,11 @@ export function compileSQL<T>(options: LoadSubsetOptions): SubsetParams {
   if (where) {
     // TODO: this only works when the where expression's PropRefs directly reference a column of the collection
     //       doesn't work if it goes through aliases because then we need to know the entire query to be able to follow the reference until the base collection (cf. followRef function)
-    compiledSQL.where = compileBasicExpression(where, params)
+    compiledSQL.where = compileBasicExpression(where, params, encodeColumnName)
   }
 
   if (orderBy) {
-    compiledSQL.orderBy = compileOrderBy(orderBy, params)
+    compiledSQL.orderBy = compileOrderBy(orderBy, params, encodeColumnName)
   }
 
   if (limit) {
@@ -58,21 +80,28 @@ export function compileSQL<T>(options: LoadSubsetOptions): SubsetParams {
  * Quote PostgreSQL identifiers to handle mixed case column names correctly.
  * Electric/Postgres requires quotes for case-sensitive identifiers.
  * @param name - The identifier to quote
+ * @param encodeColumnName - Optional function to encode the column name before quoting (e.g., camelCase to snake_case)
  * @returns The quoted identifier
  */
-function quoteIdentifier(name: string): string {
-  return `"${name}"`
+function quoteIdentifier(
+  name: string,
+  encodeColumnName?: ColumnEncoder,
+): string {
+  const columnName = encodeColumnName ? encodeColumnName(name) : name
+  return `"${columnName}"`
 }
 
 /**
  * Compiles the expression to a SQL string and mutates the params array with the values.
  * @param exp - The expression to compile
  * @param params - The params array
+ * @param encodeColumnName - Optional function to encode column names (e.g., camelCase to snake_case)
  * @returns The compiled SQL string
  */
 function compileBasicExpression(
   exp: IR.BasicExpression<unknown>,
   params: Array<unknown>,
+  encodeColumnName?: ColumnEncoder,
 ): string {
   switch (exp.type) {
     case `val`:
@@ -85,17 +114,21 @@ function compileBasicExpression(
           `Compiler can't handle nested properties: ${exp.path.join(`.`)}`,
         )
       }
-      return quoteIdentifier(exp.path[0]!)
+      return quoteIdentifier(exp.path[0]!, encodeColumnName)
     case `func`:
-      return compileFunction(exp, params)
+      return compileFunction(exp, params, encodeColumnName)
     default:
       throw new Error(`Unknown expression type`)
   }
 }
 
-function compileOrderBy(orderBy: IR.OrderBy, params: Array<unknown>): string {
+function compileOrderBy(
+  orderBy: IR.OrderBy,
+  params: Array<unknown>,
+  encodeColumnName?: ColumnEncoder,
+): string {
   const compiledOrderByClauses = orderBy.map((clause: IR.OrderByClause) =>
-    compileOrderByClause(clause, params),
+    compileOrderByClause(clause, params, encodeColumnName),
   )
   return compiledOrderByClauses.join(`,`)
 }
@@ -103,11 +136,12 @@ function compileOrderBy(orderBy: IR.OrderBy, params: Array<unknown>): string {
 function compileOrderByClause(
   clause: IR.OrderByClause,
   params: Array<unknown>,
+  encodeColumnName?: ColumnEncoder,
 ): string {
   // FIXME: We should handle stringSort and locale.
   //        Correctly supporting them is tricky as it depends on Postgres' collation
   const { expression, compareOptions } = clause
-  let sql = compileBasicExpression(expression, params)
+  let sql = compileBasicExpression(expression, params, encodeColumnName)
 
   if (compareOptions.direction === `desc`) {
     sql = `${sql} DESC`
@@ -134,6 +168,7 @@ function isNullValue(exp: IR.BasicExpression<unknown>): boolean {
 function compileFunction(
   exp: IR.Func<unknown>,
   params: Array<unknown> = [],
+  encodeColumnName?: ColumnEncoder,
 ): string {
   const { name, args } = exp
 
@@ -160,7 +195,7 @@ function compileFunction(
   }
 
   const compiledArgs = args.map((arg: IR.BasicExpression) =>
-    compileBasicExpression(arg, params),
+    compileBasicExpression(arg, params, encodeColumnName),
   )
 
   // Special case for IS NULL / IS NOT NULL - these are postfix operators
@@ -181,7 +216,11 @@ function compileFunction(
     if (arg && arg.type === `func`) {
       const funcArg = arg
       if (funcArg.name === `isNull` || funcArg.name === `isUndefined`) {
-        const innerArg = compileBasicExpression(funcArg.args[0]!, params)
+        const innerArg = compileBasicExpression(
+          funcArg.args[0]!,
+          params,
+          encodeColumnName,
+        )
         return `${innerArg} IS NOT NULL`
       }
     }
@@ -270,7 +309,11 @@ function compileFunction(
         params.pop() // remove LHS (boolean)
 
         // Recompile RHS to get fresh param
-        const rhsCompiled = compileBasicExpression(rhsArg!, params)
+        const rhsCompiled = compileBasicExpression(
+          rhsArg!,
+          params,
+          encodeColumnName,
+        )
 
         // Transform: flip the comparison (val op col → col flipped_op val)
         if (name === `lt`) {