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

sqlite-compiler.ts

362 lines9.8 KB

1import type { IR, LoadSubsetOptions } from '@tanstack/db'
2​
3/**
4 * Result of compiling LoadSubsetOptions to SQLite
5 */
6export interface SQLiteCompiledQuery {
7 /** The WHERE clause (without "WHERE" keyword), e.g., "price > ?" */
8 where?: string
9 /** The ORDER BY clause (without "ORDER BY" keyword), e.g., "price DESC" */
10 orderBy?: string
11 /** The LIMIT value */
12 limit?: number
13 /** Parameter values in order, to be passed to SQLite query */
14 params: Array<unknown>
16​
17/**
18 * Options for controlling how SQL is compiled.
19 */
20export interface CompileSQLiteOptions {
21 /**
22 * When set, column references emit `json_extract(<jsonColumn>, '$.<columnName>')`
23 * instead of `"<columnName>"`. The `id` column is excluded since it's stored
24 * as a direct column in the tracked table.
25 */
26 jsonColumn?: string
28​
29/**
30 * Compiles TanStack DB LoadSubsetOptions to SQLite query components.
31 *
32 * @example
33 * ```typescript
34 * const compiled = compileSQLite({
35 * where: { type: 'func', name: 'gt', args: [
36 * { type: 'ref', path: ['price'] },
37 * { type: 'val', value: 100 }
38 * ]},
39 * orderBy: [{ expression: { type: 'ref', path: ['price'] }, compareOptions: { direction: 'desc', nulls: 'last' } }],
40 * limit: 50
41 * })
42 * // Result: { where: '"price" > ?', orderBy: '"price" DESC', limit: 50, params: [100] }
43 * ```
44 */
45export function compileSQLite(
46 options: LoadSubsetOptions,
47 compileOptions?: CompileSQLiteOptions,
48): SQLiteCompiledQuery {
49 const { where, orderBy, limit } = options
50​
51 const params: Array<unknown> = []
52 const result: SQLiteCompiledQuery = { params }
53​
54 if (where) {
55 result.where = compileExpression(where, params, compileOptions)
56 }
57​
58 if (orderBy) {
59 result.orderBy = compileOrderBy(orderBy, params, compileOptions)
60 }
61​
62 if (limit !== undefined) {
63 result.limit = limit
64 }
65​
66 return result
68​
69/**
70 * Quote SQLite identifiers to handle column names correctly.
71 * SQLite uses double quotes for identifiers.
72 */
73function quoteIdentifier(name: string): string {
74 // Escape any double quotes in the name by doubling them
75 const escaped = name.replace(/"/g, `""`)
76 return `"${escaped}"`
78​
79/**
80 * Compiles a BasicExpression to a SQL string, mutating the params array.
81 */
82function compileExpression(
83 exp: IR.BasicExpression<unknown>,
84 params: Array<unknown>,
85 compileOptions?: CompileSQLiteOptions,
86): string {
87 switch (exp.type) {
88 case `val`:
89 params.push(exp.value)
90 return `?`
91 case `ref`: {
92 if (exp.path.length !== 1) {
93 throw new Error(
94 `SQLite compiler doesn't support nested properties: ${exp.path.join(`.`)}`,
95 )
96 }
97 const columnName = exp.path[0]!
98​
99 // PowerSync stores `id` as a top-level row column rather than inside the
100 // JSON `data` object, so we skip json_extract. However, when compiling for
101 // trigger WHEN clauses we still need the OLD./NEW. prefix. Extract it from
102 // the jsonColumn option.
103 if (compileOptions?.jsonColumn && columnName === `id`) {
104 const prefix = compileOptions.jsonColumn.split('.')[0]!
105 return `${prefix}.${quoteIdentifier(columnName)}`
106 } else if (compileOptions?.jsonColumn) {
107 return `json_extract(${compileOptions.jsonColumn}, '$.${columnName}')`
108 }
109 return quoteIdentifier(columnName)
110 }
111 case `func`:
112 return compileFunction(exp, params, compileOptions)
113 default:
114 throw new Error(`Unknown expression type: ${(exp as any).type}`)
115 }
117​
118/**
119 * Compiles an OrderBy array to a SQL ORDER BY clause.
120 */
121function compileOrderBy(
122 orderBy: IR.OrderBy,
123 params: Array<unknown>,
124 compileOptions?: CompileSQLiteOptions,
125): string {
126 const clauses = orderBy.map((clause: IR.OrderByClause) =>
127 compileOrderByClause(clause, params, compileOptions),
128 )
129 return clauses.join(`, `)
131​
132/**
133 * Compiles a single OrderByClause to SQL.
134 */
135function compileOrderByClause(
136 clause: IR.OrderByClause,
137 params: Array<unknown>,
138 compileOptions?: CompileSQLiteOptions,
139): string {
140 const { expression, compareOptions } = clause
141 let sql = compileExpression(expression, params, compileOptions)
142​
143 if (compareOptions.direction === `desc`) {
144 sql = `${sql} DESC`
145 }
146​
147 // SQLite supports NULLS FIRST/LAST (since 3.30.0)
148 if (compareOptions.nulls === `first`) {
149 sql = `${sql} NULLS FIRST`
150 } else {
151 // Default to NULLS LAST (nulls === 'last')
152 sql = `${sql} NULLS LAST`
153 }
154​
155 return sql
157​
158/**
159 * Check if a BasicExpression represents a null/undefined value
160 */
161function isNullValue(exp: IR.BasicExpression<unknown>): boolean {
162 return exp.type === `val` && (exp.value === null || exp.value === undefined)
164​
165/**
166 * Compiles a function expression (operator) to SQL.
167 */
168function compileFunction(
169 exp: IR.Func<unknown>,
170 params: Array<unknown>,
171 compileOptions?: CompileSQLiteOptions,
172): string {
173 const { name, args } = exp
174​
175 // Check for null values in comparison operators
176 if (isComparisonOp(name)) {
177 const hasNullArg = args.some((arg: IR.BasicExpression) => isNullValue(arg))
178 if (hasNullArg) {
179 throw new Error(
180 `Cannot use null/undefined with '${name}' operator. ` +
181 `Use isNull() to check for null values.`,
182 )
183 }
184 }
185​
186 // Compile arguments
187 const compiledArgs = args.map((arg: IR.BasicExpression) =>
188 compileExpression(arg, params, compileOptions),
189 )
190​
191 // Handle different operator types
192 switch (name) {
193 // Binary comparison operators
194 case `eq`:
195 case `gt`:
196 case `gte`:
197 case `lt`:
198 case `lte`: {
199 if (compiledArgs.length !== 2) {
200 throw new Error(`${name} expects 2 arguments`)
201 }
202 const opSymbol = getComparisonOp(name)
203 return `${compiledArgs[0]} ${opSymbol} ${compiledArgs[1]}`
204 }
205​
206 // Logical operators
207 case `and`:
208 case `or`: {
209 if (compiledArgs.length < 2) {
210 throw new Error(`${name} expects at least 2 arguments`)
211 }
212 const opKeyword = name === `and` ? `AND` : `OR`
213 return compiledArgs
214 .map((arg: string) => `(${arg})`)
215 .join(` ${opKeyword} `)
216 }
217​
218 case `not`: {
219 if (compiledArgs.length !== 1) {
220 throw new Error(`not expects 1 argument`)
221 }
222 // Check if argument is isNull/isUndefined for IS NOT NULL
223 const arg = args[0]
224 if (arg && arg.type === `func`) {
225 if (arg.name === `isNull` || arg.name === `isUndefined`) {
226 const innerArg = compileExpression(
227 arg.args[0]!,
228 params,
229 compileOptions,
230 )
231 return `${innerArg} IS NOT NULL`
232 }
233 }
234 return `NOT (${compiledArgs[0]})`
235 }
236​
237 // Null checking
238 case `isNull`:
239 case `isUndefined`: {
240 if (compiledArgs.length !== 1) {
241 throw new Error(`${name} expects 1 argument`)
242 }
243 return `${compiledArgs[0]} IS NULL`
244 }
245​
246 // IN operator
247 case `in`: {
248 if (compiledArgs.length !== 2) {
249 throw new Error(`in expects 2 arguments (column and array)`)
250 }
251 // The second argument should be an array value
252 // We need to handle this specially - expand the array into multiple placeholders
253 const lastParamIndex = params.length - 1
254 const arrayValue = params[lastParamIndex]
255​
256 if (!Array.isArray(arrayValue)) {
257 throw new Error(`in operator requires an array value`)
258 }
259​
260 // Remove the array param and add individual values
261 params.pop()
262 const placeholders = arrayValue.map(() => {
263 params.push(arrayValue[params.length - lastParamIndex])
264 return `?`
265 })
266​
267 // Re-add individual values properly
268 params.length = lastParamIndex // Reset to before array
269 for (const val of arrayValue) {
270 params.push(val)
271 }
272​
273 return `${compiledArgs[0]} IN (${placeholders.join(`, `)})`
274 }
275​
276 // String operators
277 case `like`: {
278 if (compiledArgs.length !== 2) {
279 throw new Error(`like expects 2 arguments`)
280 }
281 return `${compiledArgs[0]} LIKE ${compiledArgs[1]}`
282 }
283​
284 case `ilike`: {
285 if (compiledArgs.length !== 2) {
286 throw new Error(`ilike expects 2 arguments`)
287 }
288 return `${compiledArgs[0]} LIKE ${compiledArgs[1]} COLLATE NOCASE`
289 }
290​
291 // String case functions
292 case `upper`: {
293 if (compiledArgs.length !== 1) {
294 throw new Error(`upper expects 1 argument`)
295 }
296 return `UPPER(${compiledArgs[0]})`
297 }
298​
299 case `lower`: {
300 if (compiledArgs.length !== 1) {
301 throw new Error(`lower expects 1 argument`)
302 }
303 return `LOWER(${compiledArgs[0]})`
304 }
305​
306 case `length`: {
307 if (compiledArgs.length !== 1) {
308 throw new Error(`length expects 1 argument`)
309 }
310 return `LENGTH(${compiledArgs[0]})`
311 }
312​
313 case `concat`: {
314 if (compiledArgs.length < 1) {
315 throw new Error(`concat expects at least 1 argument`)
316 }
317 return `CONCAT(${compiledArgs.join(`, `)})`
318 }
319​
320 case `add`: {
321 if (compiledArgs.length !== 2) {
322 throw new Error(`add expects 2 arguments`)
323 }
324 return `${compiledArgs[0]} + ${compiledArgs[1]}`
325 }
326​
327 // Null fallback
328 case `coalesce`: {
329 if (compiledArgs.length < 1) {
330 throw new Error(`coalesce expects at least 1 argument`)
331 }
332 return `COALESCE(${compiledArgs.join(`, `)})`
333 }
334​
335 default:
336 throw new Error(
337 `Operator '${name}' is not supported in PowerSync on-demand sync. ` +
338 `Supported operators: eq, gt, gte, lt, lte, and, or, not, isNull, in, like, ilike, upper, lower, length, concat, add, coalesce`,
339 )
340 }
342​
343/**
344 * Check if operator is a comparison operator
345 */
346function isComparisonOp(name: string): boolean {
347 return [`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`].includes(name)
349​
350/**
351 * Get the SQL symbol for a comparison operator
352 */
353function getComparisonOp(name: string): string {
354 const ops: Record<string, string> = {
355 eq: `=`,
356 gt: `>`,
357 gte: `>=`,
358 lt: `<`,
359 lte: `<=`,
360 }
361 return ops[name]!