Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

sql-compiler.ts

433 lines13.3 KB

1import { serialize } from './pg-serializer'
2import type { SubsetParams } from '@electric-sql/client'
3import type { IR, LoadSubsetOptions } from '@tanstack/db'
4​
5export type CompiledSqlRecord = Omit<SubsetParams, `params`> & {
6 params?: Array<unknown>
7}
8​
9/**
10 * Optional function to encode column names (e.g., camelCase to snake_case)
11 * This is typically the `encode` function from a columnMapper
12 */
13export type ColumnEncoder = (columnName: string) => string
14​
15/**
16 * Options for SQL compilation
17 */
18export interface CompileSQLOptions {
19 /**
20 * Optional function to encode column names before quoting.
21 * Used to transform property names (e.g., camelCase) to database column names (e.g., snake_case).
22 * This should be the `encode` function from shapeOptions.columnMapper.
23 */
24 encodeColumnName?: ColumnEncoder
26​
27export function compileSQL<T>(
28 options: LoadSubsetOptions,
29 compileOptions?: CompileSQLOptions,
30): SubsetParams {
31 const { where, orderBy, limit } = options
32 const encodeColumnName = compileOptions?.encodeColumnName
33​
34 const params: Array<T> = []
35 const compiledSQL: CompiledSqlRecord = { params }
36​
37 if (where) {
38 // TODO: this only works when the where expression's PropRefs directly reference a column of the collection
39 // 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)
40 compiledSQL.where = compileBasicExpression(where, params, encodeColumnName)
41 }
42​
43 if (orderBy) {
44 compiledSQL.orderBy = compileOrderBy(orderBy, params, encodeColumnName)
45 }
46​
47 if (limit) {
48 compiledSQL.limit = limit
49 }
50​
51 // WORKAROUND for Electric bug: Empty subset requests don't load data
52 // Add dummy "true = true" predicate when there's no where clause
53 // This is always true so doesn't filter data, just tricks Electric into loading
54 if (!where) {
55 compiledSQL.where = `true = true`
56 }
57​
58 // Serialize the values in the params array into PG formatted strings
59 // and transform the array into a Record<string, string>
60 const paramsRecord = params.reduce(
61 (acc, param, index) => {
62 const serialized = serialize(param)
63 // Empty strings are valid query values (e.g., WHERE column = '')
64 // Only omit null/undefined values from params
65 if (param != null) {
66 acc[`${index + 1}`] = serialized
67 }
68 return acc
69 },
70 {} as Record<string, string>,
71 )
72​
73 return {
74 ...compiledSQL,
75 params: paramsRecord,
76 }
78​
79/**
80 * Quote PostgreSQL identifiers to handle mixed case column names correctly.
81 * Electric/Postgres requires quotes for case-sensitive identifiers.
82 * @param name - The identifier to quote
83 * @param encodeColumnName - Optional function to encode the column name before quoting (e.g., camelCase to snake_case)
84 * @returns The quoted identifier
85 */
86function quoteIdentifier(
87 name: string,
88 encodeColumnName?: ColumnEncoder,
89): string {
90 const columnName = encodeColumnName ? encodeColumnName(name) : name
91 return `"${columnName}"`
93​
94/**
95 * Compiles the expression to a SQL string and mutates the params array with the values.
96 * @param exp - The expression to compile
97 * @param params - The params array
98 * @param encodeColumnName - Optional function to encode column names (e.g., camelCase to snake_case)
99 * @returns The compiled SQL string
100 */
101function compileBasicExpression(
102 exp: IR.BasicExpression<unknown>,
103 params: Array<unknown>,
104 encodeColumnName?: ColumnEncoder,
105): string {
106 switch (exp.type) {
107 case `val`:
108 params.push(exp.value)
109 return `$${params.length}`
110 case `ref`:
111 // TODO: doesn't yet support JSON(B) values which could be accessed with nested props
112 if (exp.path.length !== 1) {
113 throw new Error(
114 `Compiler can't handle nested properties: ${exp.path.join(`.`)}`,
115 )
116 }
117 return quoteIdentifier(exp.path[0]!, encodeColumnName)
118 case `func`:
119 return compileFunction(exp, params, encodeColumnName)
120 default:
121 throw new Error(`Unknown expression type`)
122 }
124​
125function compileOrderBy(
126 orderBy: IR.OrderBy,
127 params: Array<unknown>,
128 encodeColumnName?: ColumnEncoder,
129): string {
130 const compiledOrderByClauses = orderBy.map((clause: IR.OrderByClause) =>
131 compileOrderByClause(clause, params, encodeColumnName),
132 )
133 return compiledOrderByClauses.join(`,`)
135​
136function compileOrderByClause(
137 clause: IR.OrderByClause,
138 params: Array<unknown>,
139 encodeColumnName?: ColumnEncoder,
140): string {
141 // FIXME: We should handle stringSort and locale.
142 // Correctly supporting them is tricky as it depends on Postgres' collation
143 const { expression, compareOptions } = clause
144 let sql = compileBasicExpression(expression, params, encodeColumnName)
145​
146 if (compareOptions.direction === `desc`) {
147 sql = `${sql} DESC`
148 }
149​
150 if (compareOptions.nulls === `first`) {
151 sql = `${sql} NULLS FIRST`
152 }
153​
154 if (compareOptions.nulls === `last`) {
155 sql = `${sql} NULLS LAST`
156 }
157​
158 return sql
160​
161/**
162 * Check if a BasicExpression represents a null/undefined value
163 */
164function isNullValue(exp: IR.BasicExpression<unknown>): boolean {
165 return exp.type === `val` && (exp.value === null || exp.value === undefined)
167​
168function compileFunction(
169 exp: IR.Func<unknown>,
170 params: Array<unknown> = [],
171 encodeColumnName?: ColumnEncoder,
172): string {
173 const { name, args } = exp
174​
175 const opName = getOpName(name)
176​
177 // Handle comparison operators with null/undefined values
178 // These would create invalid queries with missing params (e.g., "col = $1" with empty params)
179 // In SQL, all comparisons with NULL return UNKNOWN, so these are almost always mistakes
180 if (isComparisonOp(name)) {
181 const nullArgIndex = args.findIndex((arg: IR.BasicExpression) =>
182 isNullValue(arg),
183 )
184​
185 if (nullArgIndex !== -1) {
186 // All comparison operators (including eq) throw an error for null values
187 // Users should use isNull() or isUndefined() to check for null values
188 throw new Error(
189 `Cannot use null/undefined value with '${name}' operator. ` +
190 `Comparisons with null always evaluate to UNKNOWN in SQL. ` +
191 `Use isNull() or isUndefined() to check for null values, ` +
192 `or filter out null values before building the query.`,
193 )
194 }
195 }
196​
197 const compiledArgs = args.map((arg: IR.BasicExpression) =>
198 compileBasicExpression(arg, params, encodeColumnName),
199 )
200​
201 // Special case for IS NULL / IS NOT NULL - these are postfix operators
202 if (name === `isNull` || name === `isUndefined`) {
203 if (compiledArgs.length !== 1) {
204 throw new Error(`${name} expects 1 argument`)
205 }
206 return `${compiledArgs[0]} ${opName}`
207 }
208​
209 // Special case for NOT - unary prefix operator
210 if (name === `not`) {
211 if (compiledArgs.length !== 1) {
212 throw new Error(`NOT expects 1 argument`)
213 }
214 // Check if the argument is IS NULL to generate IS NOT NULL
215 const arg = args[0]
216 if (arg && arg.type === `func`) {
217 const funcArg = arg
218 if (funcArg.name === `isNull` || funcArg.name === `isUndefined`) {
219 const innerArg = compileBasicExpression(
220 funcArg.args[0]!,
221 params,
222 encodeColumnName,
223 )
224 return `${innerArg} IS NOT NULL`
225 }
226 }
227 return `${opName} (${compiledArgs[0]})`
228 }
229​
230 if (isBinaryOp(name)) {
231 // Special handling for AND/OR which can be variadic
232 if ((name === `and` || name === `or`) && compiledArgs.length > 2) {
233 // Chain multiple arguments: (a AND b AND c) or (a OR b OR c)
234 return compiledArgs.map((arg) => `(${arg})`).join(` ${opName} `)
235 }
236​
237 if (compiledArgs.length !== 2) {
238 throw new Error(`Binary operator ${name} expects 2 arguments`)
239 }
240 const [lhs, rhs] = compiledArgs
241​
242 // Special case for comparison operators with boolean values
243 // PostgreSQL doesn't support < > <= >= on booleans
244 // Transform to equivalent equality checks or constant expressions
245 if (isBooleanComparisonOp(name)) {
246 const lhsArg = args[0]
247 const rhsArg = args[1]
248​
249 // Check if RHS is a boolean literal value
250 if (
251 rhsArg &&
252 rhsArg.type === `val` &&
253 typeof rhsArg.value === `boolean`
254 ) {
255 const boolValue = rhsArg.value
256 // Remove the boolean param we just added since we'll transform the expression
257 params.pop()
258​
259 // Transform based on operator and boolean value
260 // Boolean ordering: false < true
261 if (name === `lt`) {
262 if (boolValue === true) {
263 // lt(col, true) → col = false (only false is less than true)
264 params.push(false)
265 return `${lhs} = $${params.length}`
266 } else {
267 // lt(col, false) → nothing is less than false
268 return `false`
269 }
270 } else if (name === `gt`) {
271 if (boolValue === false) {
272 // gt(col, false) → col = true (only true is greater than false)
273 params.push(true)
274 return `${lhs} = $${params.length}`
275 } else {
276 // gt(col, true) → nothing is greater than true
277 return `false`
278 }
279 } else if (name === `lte`) {
280 if (boolValue === true) {
281 // lte(col, true) → everything is ≤ true
282 return `true`
283 } else {
284 // lte(col, false) → col = false
285 params.push(false)
286 return `${lhs} = $${params.length}`
287 }
288 } else if (name === `gte`) {
289 if (boolValue === false) {
290 // gte(col, false) → everything is ≥ false
291 return `true`
292 } else {
293 // gte(col, true) → col = true
294 params.push(true)
295 return `${lhs} = $${params.length}`
296 }
297 }
298 }
299​
300 // Check if LHS is a boolean literal value (less common but handle it)
301 if (
302 lhsArg &&
303 lhsArg.type === `val` &&
304 typeof lhsArg.value === `boolean`
305 ) {
306 const boolValue = lhsArg.value
307 // Remove params for this expression and rebuild
308 params.pop() // remove RHS
309 params.pop() // remove LHS (boolean)
310​
311 // Recompile RHS to get fresh param
312 const rhsCompiled = compileBasicExpression(
313 rhsArg!,
314 params,
315 encodeColumnName,
316 )
317​
318 // Transform: flip the comparison (val op col → col flipped_op val)
319 if (name === `lt`) {
320 // lt(true, col) → gt(col, true) → col > true → nothing is greater than true
321 if (boolValue === true) {
322 return `false`
323 } else {
324 // lt(false, col) → gt(col, false) → col = true
325 params.push(true)
326 return `${rhsCompiled} = $${params.length}`
327 }
328 } else if (name === `gt`) {
329 // gt(true, col) → lt(col, true) → col = false
330 if (boolValue === true) {
331 params.push(false)
332 return `${rhsCompiled} = $${params.length}`
333 } else {
334 // gt(false, col) → lt(col, false) → nothing is less than false
335 return `false`
336 }
337 } else if (name === `lte`) {
338 if (boolValue === false) {
339 // lte(false, col) → gte(col, false) → everything
340 return `true`
341 } else {
342 // lte(true, col) → gte(col, true) → col = true
343 params.push(true)
344 return `${rhsCompiled} = $${params.length}`
345 }
346 } else if (name === `gte`) {
347 if (boolValue === true) {
348 // gte(true, col) → lte(col, true) → everything
349 return `true`
350 } else {
351 // gte(false, col) → lte(col, false) → col = false
352 params.push(false)
353 return `${rhsCompiled} = $${params.length}`
354 }
355 }
356 }
357 }
358​
359 // Special case for = ANY operator which needs parentheses around the array parameter
360 if (name === `in`) {
361 return `${lhs} ${opName}(${rhs})`
362 }
363 return `${lhs} ${opName} ${rhs}`
364 }
365​
366 return `${opName}(${compiledArgs.join(`,`)})`
368​
369function isBinaryOp(name: string): boolean {
370 const binaryOps = [
371 `eq`,
372 `gt`,
373 `gte`,
374 `lt`,
375 `lte`,
376 `and`,
377 `or`,
378 `in`,
379 `like`,
380 `ilike`,
381 ]
382 return binaryOps.includes(name)
384​
385/**
386 * Check if operator is a comparison operator that takes two values
387 * These operators cannot accept null/undefined as values
388 * (null comparisons in SQL always evaluate to UNKNOWN)
389 */
390function isComparisonOp(name: string): boolean {
391 const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`]
392 return comparisonOps.includes(name)
394​
395/**
396 * Checks if the operator is a comparison operator (excluding eq)
397 * These operators don't work on booleans in PostgreSQL without casting
398 */
399function isBooleanComparisonOp(name: string): boolean {
400 return [`gt`, `gte`, `lt`, `lte`].includes(name)
402​
403function getOpName(name: string): string {
404 const opNames = {
405 eq: `=`,
406 gt: `>`,
407 gte: `>=`,
408 lt: `<`,
409 lte: `<=`,
410 add: `+`,
411 and: `AND`,
412 or: `OR`,
413 not: `NOT`,
414 isUndefined: `IS NULL`,
415 isNull: `IS NULL`,
416 in: `= ANY`, // Use = ANY syntax for array parameters
417 like: `LIKE`,
418 ilike: `ILIKE`,
419 upper: `UPPER`,
420 lower: `LOWER`,
421 length: `LENGTH`,
422 concat: `CONCAT`,
423 coalesce: `COALESCE`,
424 }
425​
426 const opName = opNames[name as keyof typeof opNames]
427​
428 if (!opName) {
429 throw new Error(`Unknown operator/function: ${name}`)
430 }
431​
432 return opName