@tanstack/electric-db-collection 0.4.8 → 0.5.1

package/dist/cjs/electric.d.cts

@@ -1,4 +1,4 @@
-import { BaseCollectionConfig, CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncMode, UpdateMutationFnParams, UtilsRecord } from '@tanstack/db';
+import { BaseCollectionConfig, CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncMode, UpdateMutationFnParams } from '@tanstack/db';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { GetExtensions, Message, Row, ShapeStreamOptions } from '@electric-sql/client';
 export { isChangeMessage, isControlMessage } from '@electric-sql/client';
@@ -28,11 +28,11 @@ export type MatchFunction<T extends Row<unknown>> = (message: Message<T>) => boo
 /**
  * Matching strategies for Electric synchronization
  * Handlers can return:
- * - Txid strategy: { txid: number | number[], timeout?: number } (recommended)
+ * - Txid strategy: { txid: number | number[], timeout?: number } (deprecated compatibility behavior)
  * - Void (no return value) - mutation completes without waiting
  *
  * The optional timeout property specifies how long to wait for the txid(s) in milliseconds.
- * If not specified, defaults to 5000ms.
+ * If not specified, defaults to 15000ms.
  */
 export type MatchingStrategy = {
     txid: Txid | Array<Txid>;
@@ -61,7 +61,7 @@ export type ElectricSyncMode = SyncMode | `progressive`;
  * @template T - The type of items in the collection
  * @template TSchema - The schema type for validation
  */
-export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends Omit<BaseCollectionConfig<T, string | number, TSchema, ElectricCollectionUtils<T>, any>, `onInsert` | `onUpdate` | `onDelete` | `syncMode`> {
+export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends Omit<BaseCollectionConfig<T, string | number, TSchema, ElectricCollectionUtils<T>>, `onInsert` | `onUpdate` | `onDelete` | `syncMode`> {
     /**
      * Configuration options for the ElectricSQL ShapeStream
      */
@@ -74,43 +74,82 @@ export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>,
     [ELECTRIC_TEST_HOOKS]?: ElectricTestHooks;
     /**
      * Optional asynchronous handler function called before an insert operation
+     *
+     * **IMPORTANT - Electric Synchronization:**
+     * This handler **must not resolve** until synchronization is confirmed.
+     * Await one of these synchronization utilities before the handler completes:
+     * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+     * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+     *
+     * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+     *
      * @param params Object containing transaction and collection information
-     * @returns Promise resolving to { txid, timeout? } or void
+     * @returns Promise that should resolve after synchronization is complete
+     *
+     * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+     * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+     *
      * @example
-     * // Basic Electric insert handler with txid (recommended)
-     * onInsert: async ({ transaction }) => {
+     * // Recommended: Wait for txid to sync
+     * onInsert: async ({ transaction, collection }) => {
      *   const newItem = transaction.mutations[0].modified
      *   const result = await api.todos.create({
      *     data: newItem
      *   })
-     *   return { txid: result.txid }
+     *   // Wait for txid to sync before handler completes
+     *   await collection.utils.awaitTxId(result.txid)
      * }
      *
      * @example
      * // Insert handler with custom timeout
-     * onInsert: async ({ transaction }) => {
+     * onInsert: async ({ transaction, collection }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   const result = await api.todos.create({
+     *     data: newItem
+     *   })
+     *   // Wait up to 10 seconds for txid
+     *   await collection.utils.awaitTxId(result.txid, 10000)
+     * }
+     *
+     * @example
+     * // Insert handler with timeout error handling
+     * onInsert: async ({ transaction, collection }) => {
      *   const newItem = transaction.mutations[0].modified
      *   const result = await api.todos.create({
      *     data: newItem
      *   })
-     *   return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
+     *
+     *   try {
+     *     await collection.utils.awaitTxId(result.txid, 5000)
+     *   } catch (error) {
+     *     // Decide sync timeout policy:
+     *     // - Throw to rollback optimistic state
+     *     // - Catch to keep optimistic state (eventual consistency)
+     *     // - Schedule background retry
+     *     console.warn('Sync timeout, keeping optimistic state:', error)
+     *     // Don't throw - allow optimistic state to persist
+     *   }
      * }
      *
      * @example
-     * // Insert handler with multiple items - return array of txids
-     * onInsert: async ({ transaction }) => {
+     * // Insert handler with multiple items
+     * onInsert: async ({ transaction, collection }) => {
      *   const items = transaction.mutations.map(m => m.modified)
      *   const results = await Promise.all(
      *     items.map(item => api.todos.create({ data: item }))
      *   )
-     *   return { txid: results.map(r => r.txid) }
+     *   // Wait for all txids to sync
+     *   await Promise.all(
+     *     results.map(r => collection.utils.awaitTxId(r.txid))
+     *   )
      * }
      *
      * @example
-     * // Use awaitMatch utility for custom matching
+     * // Alternative: Use awaitMatch utility for custom matching logic
      * onInsert: async ({ transaction, collection }) => {
      *   const newItem = transaction.mutations[0].modified
      *   await api.todos.create({ data: newItem })
+     *   // Wait for specific change to appear in sync stream
      *   await collection.utils.awaitMatch(
      *     (message) => isChangeMessage(message) &&
      *                  message.headers.operation === 'insert' &&
@@ -121,24 +160,39 @@ export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>,
     onInsert?: (params: InsertMutationFnParams<T, string | number, ElectricCollectionUtils<T>>) => Promise<MatchingStrategy>;
     /**
      * Optional asynchronous handler function called before an update operation
+     *
+     * **IMPORTANT - Electric Synchronization:**
+     * This handler **must not resolve** until synchronization is confirmed.
+     * Await one of these synchronization utilities before the handler completes:
+     * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+     * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+     *
+     * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+     *
      * @param params Object containing transaction and collection information
-     * @returns Promise resolving to { txid, timeout? } or void
+     * @returns Promise that should resolve after synchronization is complete
+     *
+     * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+     * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+     *
      * @example
-     * // Basic Electric update handler with txid (recommended)
-     * onUpdate: async ({ transaction }) => {
+     * // Recommended: Wait for txid to sync
+     * onUpdate: async ({ transaction, collection }) => {
      *   const { original, changes } = transaction.mutations[0]
      *   const result = await api.todos.update({
      *     where: { id: original.id },
      *     data: changes
      *   })
-     *   return { txid: result.txid }
+     *   // Wait for txid to sync before handler completes
+     *   await collection.utils.awaitTxId(result.txid)
      * }
      *
      * @example
-     * // Use awaitMatch utility for custom matching
+     * // Alternative: Use awaitMatch utility for custom matching logic
      * onUpdate: async ({ transaction, collection }) => {
      *   const { original, changes } = transaction.mutations[0]
      *   await api.todos.update({ where: { id: original.id }, data: changes })
+     *   // Wait for specific change to appear in sync stream
      *   await collection.utils.awaitMatch(
      *     (message) => isChangeMessage(message) &&
      *                  message.headers.operation === 'update' &&
@@ -149,23 +203,38 @@ export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>,
     onUpdate?: (params: UpdateMutationFnParams<T, string | number, ElectricCollectionUtils<T>>) => Promise<MatchingStrategy>;
     /**
      * Optional asynchronous handler function called before a delete operation
+     *
+     * **IMPORTANT - Electric Synchronization:**
+     * This handler **must not resolve** until synchronization is confirmed.
+     * Await one of these synchronization utilities before the handler completes:
+     * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+     * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+     *
+     * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+     *
      * @param params Object containing transaction and collection information
-     * @returns Promise resolving to { txid, timeout? } or void
+     * @returns Promise that should resolve after synchronization is complete
+     *
+     * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+     * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+     *
      * @example
-     * // Basic Electric delete handler with txid (recommended)
-     * onDelete: async ({ transaction }) => {
+     * // Recommended: Wait for txid to sync
+     * onDelete: async ({ transaction, collection }) => {
      *   const mutation = transaction.mutations[0]
      *   const result = await api.todos.delete({
      *     id: mutation.original.id
      *   })
-     *   return { txid: result.txid }
+     *   // Wait for txid to sync before handler completes
+     *   await collection.utils.awaitTxId(result.txid)
      * }
      *
      * @example
-     * // Use awaitMatch utility for custom matching
+     * // Alternative: Use awaitMatch utility for custom matching logic
      * onDelete: async ({ transaction, collection }) => {
      *   const mutation = transaction.mutations[0]
      *   await api.todos.delete({ id: mutation.original.id })
+     *   // Wait for specific change to appear in sync stream
      *   await collection.utils.awaitMatch(
      *     (message) => isChangeMessage(message) &&
      *                  message.headers.operation === 'delete' &&
@@ -186,7 +255,7 @@ export type AwaitMatchFn<T extends Row<unknown>> = (matchFn: MatchFunction<T>, t
 /**
  * Electric collection utilities type
  */
-export interface ElectricCollectionUtils<T extends Row<unknown> = Row<unknown>> extends UtilsRecord {
+export interface ElectricCollectionUtils<T extends Row<unknown> = Row<unknown>> {
     awaitTxId: AwaitTxIdFn;
     awaitMatch: AwaitMatchFn<T>;
 }

package/dist/cjs/sql-compiler.cjs

@@ -35,7 +35,7 @@ function compileSQL(options, compileOptions) {
 }
 function quoteIdentifier(name, encodeColumnName) {
   const columnName = encodeColumnName ? encodeColumnName(name) : name;
-  return `"${columnName}"`;
+  return `"${columnName.replace(/"/g, `""`)}"`;
 }
 function compileBasicExpression(exp, params, encodeColumnName) {
   switch (exp.type) {
@@ -91,9 +91,44 @@ function compileFunction(exp, params = [], encodeColumnName) {
       );
     }
   }
-  const compiledArgs = args.map(
-    (arg) => compileBasicExpression(arg, params, encodeColumnName)
+  if (name === `not`) {
+    if (args.length !== 1) throw new Error(`NOT expects 1 argument`);
+    const arg = args[0];
+    if (arg?.type === `func` && (arg.name === `isNull` || arg.name === `isUndefined`)) {
+      if (arg.args.length !== 1) {
+        throw new Error(`${arg.name} expects 1 argument`);
+      }
+      const innerArg = arg.args[0];
+      const compiled = compileBasicExpression(
+        innerArg,
+        params,
+        encodeColumnName
+      );
+      return `${innerArg.type === `func` ? `(${compiled})` : compiled} IS NOT NULL`;
+    }
+  }
+  const booleanLiteralIndex = args.findIndex(
+    (arg) => arg.type === `val` && typeof arg.value === `boolean`
   );
+  if (args.length === 2 && isBooleanComparisonOp(name) && booleanLiteralIndex !== -1) {
+    const literalValue = args[booleanLiteralIndex].value;
+    const valueArg = args[booleanLiteralIndex === 0 ? 1 : 0];
+    const compiled = compileBasicExpression(valueArg, params, encodeColumnName);
+    const value = `(${compiled})`;
+    const lessThan = (name === `lt` || name === `lte`) === (booleanLiteralIndex === 1);
+    const inclusive = name === `lte` || name === `gte`;
+    if (inclusive && literalValue === lessThan) {
+      return `${value} = ${value}`;
+    }
+    if (!inclusive && literalValue !== lessThan) {
+      return `${value} <> ${value}`;
+    }
+    return `${value} = ${lessThan ? `FALSE` : `TRUE`}`;
+  }
+  const compiledArgs = args.map((arg) => {
+    const compiled = compileBasicExpression(arg, params, encodeColumnName);
+    return arg.type === `func` && (arg.name === `and` || arg.name === `or` || name !== `and` && name !== `or` && name !== `not` && (isBinaryOp(arg.name) || arg.name === `not` || arg.name === `isNull` || arg.name === `isUndefined`)) ? `(${compiled})` : compiled;
+  });
   if (name === `isNull` || name === `isUndefined`) {
     if (compiledArgs.length !== 1) {
       throw new Error(`${name} expects 1 argument`);
@@ -101,108 +136,25 @@ function compileFunction(exp, params = [], encodeColumnName) {
     return `${compiledArgs[0]} ${opName}`;
   }
   if (name === `not`) {
-    if (compiledArgs.length !== 1) {
-      throw new Error(`NOT expects 1 argument`);
-    }
-    const arg = args[0];
-    if (arg && arg.type === `func`) {
-      const funcArg = arg;
-      if (funcArg.name === `isNull` || funcArg.name === `isUndefined`) {
-        const innerArg = compileBasicExpression(
-          funcArg.args[0],
-          params,
-          encodeColumnName
-        );
-        return `${innerArg} IS NOT NULL`;
-      }
-    }
     return `${opName} (${compiledArgs[0]})`;
   }
   if (isBinaryOp(name)) {
     if ((name === `and` || name === `or`) && compiledArgs.length > 2) {
-      return compiledArgs.map((arg) => `(${arg})`).join(` ${opName} `);
+      return compiledArgs.join(` ${opName} `);
     }
     if (compiledArgs.length !== 2) {
       throw new Error(`Binary operator ${name} expects 2 arguments`);
     }
     const [lhs, rhs] = compiledArgs;
-    if (isBooleanComparisonOp(name)) {
-      const lhsArg = args[0];
-      const rhsArg = args[1];
-      if (rhsArg && rhsArg.type === `val` && typeof rhsArg.value === `boolean`) {
-        const boolValue = rhsArg.value;
-        params.pop();
-        if (name === `lt`) {
-          if (boolValue === true) {
-            params.push(false);
-            return `${lhs} = $${params.length}`;
-          } else {
-            return `false`;
-          }
-        } else if (name === `gt`) {
-          if (boolValue === false) {
-            params.push(true);
-            return `${lhs} = $${params.length}`;
-          } else {
-            return `false`;
-          }
-        } else if (name === `lte`) {
-          if (boolValue === true) {
-            return `true`;
-          } else {
-            params.push(false);
-            return `${lhs} = $${params.length}`;
-          }
-        } else if (name === `gte`) {
-          if (boolValue === false) {
-            return `true`;
-          } else {
-            params.push(true);
-            return `${lhs} = $${params.length}`;
-          }
-        }
+    if (name === `in`) {
+      const valueArg = args[0];
+      const arrayArg = args[1];
+      if (valueArg.type === `val` && Array.isArray(valueArg.value)) {
+        throw new Error(`Array-valued 'in' left operand; expected a scalar`);
       }
-      if (lhsArg && lhsArg.type === `val` && typeof lhsArg.value === `boolean`) {
-        const boolValue = lhsArg.value;
-        params.pop();
-        params.pop();
-        const rhsCompiled = compileBasicExpression(
-          rhsArg,
-          params,
-          encodeColumnName
-        );
-        if (name === `lt`) {
-          if (boolValue === true) {
-            return `false`;
-          } else {
-            params.push(true);
-            return `${rhsCompiled} = $${params.length}`;
-          }
-        } else if (name === `gt`) {
-          if (boolValue === true) {
-            params.push(false);
-            return `${rhsCompiled} = $${params.length}`;
-          } else {
-            return `false`;
-          }
-        } else if (name === `lte`) {
-          if (boolValue === false) {
-            return `true`;
-          } else {
-            params.push(true);
-            return `${rhsCompiled} = $${params.length}`;
-          }
-        } else if (name === `gte`) {
-          if (boolValue === true) {
-            return `true`;
-          } else {
-            params.push(false);
-            return `${rhsCompiled} = $${params.length}`;
-          }
-        }
+      if (arrayArg.type === `ref` && valueArg.type === `val`) {
+        return `${lhs} = ANY(${rhs}) AND ${rhs} @> ARRAY[${lhs}] AND ${rhs} IS NOT NULL`;
       }
-    }
-    if (name === `in`) {
       return `${lhs} ${opName}(${rhs})`;
     }
     return `${lhs} ${opName} ${rhs}`;
@@ -225,7 +177,7 @@ function isBinaryOp(name) {
   return binaryOps.includes(name);
 }
 function isComparisonOp(name) {
-  const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`];
+  const comparisonOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`];
   return comparisonOps.includes(name);
 }
 function isBooleanComparisonOp(name) {

package/dist/cjs/sql-compiler.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"sql-compiler.cjs","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":["serialize"],"mappings":"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"}
+{"version":3,"file":"sql-compiler.cjs","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.replace(/\"/g, `\"\"`)}\"`\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      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  if (name === `not`) {\n    if (args.length !== 1) throw new Error(`NOT expects 1 argument`)\n    const arg = args[0]\n    if (\n      arg?.type === `func` &&\n      (arg.name === `isNull` || arg.name === `isUndefined`)\n    ) {\n      if (arg.args.length !== 1) {\n        throw new Error(`${arg.name} expects 1 argument`)\n      }\n      const innerArg = arg.args[0]!\n      const compiled = compileBasicExpression(\n        innerArg,\n        params,\n        encodeColumnName,\n      )\n      return `${innerArg.type === `func` ? `(${compiled})` : compiled} IS NOT NULL`\n    }\n  }\n\n  const booleanLiteralIndex = args.findIndex(\n    (arg) => arg.type === `val` && typeof arg.value === `boolean`,\n  )\n  if (\n    args.length === 2 &&\n    isBooleanComparisonOp(name) &&\n    booleanLiteralIndex !== -1\n  ) {\n    const literalValue = (args[booleanLiteralIndex] as IR.Value<boolean>).value\n    const valueArg = args[booleanLiteralIndex === 0 ? 1 : 0]!\n    const compiled = compileBasicExpression(valueArg, params, encodeColumnName)\n    const value = `(${compiled})`\n    const lessThan =\n      (name === `lt` || name === `lte`) === (booleanLiteralIndex === 1)\n    const inclusive = name === `lte` || name === `gte`\n\n    if (inclusive && literalValue === lessThan) {\n      return `${value} = ${value}`\n    }\n    if (!inclusive && literalValue !== lessThan) {\n      return `${value} <> ${value}`\n    }\n    return `${value} = ${lessThan ? `FALSE` : `TRUE`}`\n  }\n\n  const compiledArgs = args.map((arg: IR.BasicExpression) => {\n    const compiled = compileBasicExpression(arg, params, encodeColumnName)\n    // AND/OR group their children by precedence; NOT already wraps its operand.\n    // In value positions, preserve any nested operator as a single expression.\n    return arg.type === `func` &&\n      (arg.name === `and` ||\n        arg.name === `or` ||\n        (name !== `and` &&\n          name !== `or` &&\n          name !== `not` &&\n          (isBinaryOp(arg.name) ||\n            arg.name === `not` ||\n            arg.name === `isNull` ||\n            arg.name === `isUndefined`)))\n      ? `(${compiled})`\n      : compiled\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    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.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    if (name === `in`) {\n      const valueArg = args[0]!\n      const arrayArg = args[1]!\n\n      if (valueArg.type === `val` && Array.isArray(valueArg.value)) {\n        throw new Error(`Array-valued 'in' left operand; expected a scalar`)\n      }\n\n      if (arrayArg.type === `ref` && valueArg.type === `val`) {\n        // Resolve literal parameters from the array element type before containment.\n        return `${lhs} = ANY(${rhs}) AND ${rhs} @> ARRAY[${lhs}] AND ${rhs} IS NOT NULL`\n      }\n\n      // Literal value lists and ref/ref membership retain the original = ANY form.\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`, `in`]\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":["serialize"],"mappings":"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"}