@electric-sql/client 1.3.0 → 1.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@electric-sql/client",
   "description": "Postgres everywhere - your data, in sync, wherever you need it.",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"

package/src/client.ts

@@ -59,7 +59,10 @@ import {
   SUBSET_PARAM_LIMIT,
   SUBSET_PARAM_OFFSET,
   SUBSET_PARAM_ORDER_BY,
+  SUBSET_PARAM_WHERE_EXPR,
+  SUBSET_PARAM_ORDER_BY_EXPR,
 } from './constants'
+import { compileExpression, compileOrderBy } from './expression-compiler'
 import {
   EventSourceMessage,
   fetchEventSource,
@@ -890,13 +893,29 @@ export class ShapeStream<T extends Row<unknown> = Row>
     }
 
     if (subsetParams) {
-      if (subsetParams.where && typeof subsetParams.where === `string`) {
+      // Prefer structured expressions when available (allows proper columnMapper application)
+      // Fall back to legacy string format for backwards compatibility
+      if (subsetParams.whereExpr) {
+        // Compile structured expression with columnMapper applied
+        const compiledWhere = compileExpression(
+          subsetParams.whereExpr,
+          this.options.columnMapper?.encode
+        )
+        setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, compiledWhere)
+        // Also send the structured expression for servers that support it
+        fetchUrl.searchParams.set(
+          SUBSET_PARAM_WHERE_EXPR,
+          JSON.stringify(subsetParams.whereExpr)
+        )
+      } else if (subsetParams.where && typeof subsetParams.where === `string`) {
+        // Legacy string format (no columnMapper applied to already-compiled SQL)
         const encodedWhere = encodeWhereClause(
           subsetParams.where,
           this.options.columnMapper?.encode
         )
         setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, encodedWhere)
       }
+
       if (subsetParams.params)
         // Serialize params as JSON to keep the parameter name constant for proxy configs
         fetchUrl.searchParams.set(
@@ -907,7 +926,25 @@ export class ShapeStream<T extends Row<unknown> = Row>
         setQueryParam(fetchUrl, SUBSET_PARAM_LIMIT, subsetParams.limit)
       if (subsetParams.offset)
         setQueryParam(fetchUrl, SUBSET_PARAM_OFFSET, subsetParams.offset)
-      if (subsetParams.orderBy && typeof subsetParams.orderBy === `string`) {
+
+      // Prefer structured ORDER BY expressions when available
+      if (subsetParams.orderByExpr) {
+        // Compile structured ORDER BY with columnMapper applied
+        const compiledOrderBy = compileOrderBy(
+          subsetParams.orderByExpr,
+          this.options.columnMapper?.encode
+        )
+        setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, compiledOrderBy)
+        // Also send the structured expression for servers that support it
+        fetchUrl.searchParams.set(
+          SUBSET_PARAM_ORDER_BY_EXPR,
+          JSON.stringify(subsetParams.orderByExpr)
+        )
+      } else if (
+        subsetParams.orderBy &&
+        typeof subsetParams.orderBy === `string`
+      ) {
+        // Legacy string format
         const encodedOrderBy = encodeWhereClause(
           subsetParams.orderBy,
           this.options.columnMapper?.encode
@@ -982,7 +1019,26 @@ export class ShapeStream<T extends Row<unknown> = Row>
     const { headers, status } = response
     const shapeHandle = headers.get(SHAPE_HANDLE_HEADER)
     if (shapeHandle) {
-      this.#shapeHandle = shapeHandle
+      // Don't accept a handle we know is expired - this can happen if a
+      // proxy serves a stale cached response despite the expired_handle
+      // cache buster parameter
+      const shapeKey = this.#currentFetchUrl
+        ? canonicalShapeKey(this.#currentFetchUrl)
+        : null
+      const expiredHandle = shapeKey
+        ? expiredShapesCache.getExpiredHandle(shapeKey)
+        : null
+      if (shapeHandle !== expiredHandle) {
+        this.#shapeHandle = shapeHandle
+      } else {
+        console.warn(
+          `[Electric] Received stale cached response with expired shape handle. ` +
+            `This should not happen and indicates a proxy/CDN caching misconfiguration. ` +
+            `The response contained handle "${shapeHandle}" which was previously marked as expired. ` +
+            `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. ` +
+            `Ignoring the stale handle and continuing with handle "${this.#shapeHandle}".`
+        )
+      }
     }
 
     const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER)

package/src/constants.ts

@@ -26,6 +26,8 @@ export const SUBSET_PARAM_LIMIT = `subset__limit`
 export const SUBSET_PARAM_OFFSET = `subset__offset`
 export const SUBSET_PARAM_ORDER_BY = `subset__order_by`
 export const SUBSET_PARAM_WHERE_PARAMS = `subset__params`
+export const SUBSET_PARAM_WHERE_EXPR = `subset__where_expr`
+export const SUBSET_PARAM_ORDER_BY_EXPR = `subset__order_by_expr`
 
 // Query parameters that should be passed through when proxying Electric requests
 export const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string> = [
@@ -41,4 +43,6 @@ export const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string> = [
   SUBSET_PARAM_OFFSET,
   SUBSET_PARAM_ORDER_BY,
   SUBSET_PARAM_WHERE_PARAMS,
+  SUBSET_PARAM_WHERE_EXPR,
+  SUBSET_PARAM_ORDER_BY_EXPR,
 ]

package/src/expression-compiler.ts

@@ -0,0 +1,132 @@
+import { SerializedExpression, SerializedOrderByClause } from './types'
+import { quoteIdentifier } from './column-mapper'
+
+/**
+ * Compiles a serialized expression into a SQL string.
+ * Applies columnMapper transformations to column references.
+ *
+ * @param expr - The serialized expression to compile
+ * @param columnMapper - Optional function to transform column names (e.g., camelCase to snake_case)
+ * @returns The compiled SQL string
+ *
+ * @example
+ * ```typescript
+ * const expr = { type: 'ref', column: 'userId' }
+ * compileExpression(expr, camelToSnake) // '"user_id"'
+ * ```
+ */
+export function compileExpression(
+  expr: SerializedExpression,
+  columnMapper?: (col: string) => string
+): string {
+  switch (expr.type) {
+    case `ref`: {
+      // Apply columnMapper, then quote
+      const mappedColumn = columnMapper
+        ? columnMapper(expr.column)
+        : expr.column
+      return quoteIdentifier(mappedColumn)
+    }
+    case `val`:
+      return `$${expr.paramIndex}`
+    case `func`:
+      return compileFunction(expr, columnMapper)
+    default: {
+      // TypeScript exhaustiveness check
+      const _exhaustive: never = expr
+      throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustive)}`)
+    }
+  }
+}
+
+/**
+ * Compiles a function expression into SQL.
+ */
+function compileFunction(
+  expr: { type: `func`; name: string; args: SerializedExpression[] },
+  columnMapper?: (col: string) => string
+): string {
+  const args = expr.args.map((arg) => compileExpression(arg, columnMapper))
+
+  switch (expr.name) {
+    // Binary comparison operators
+    case `eq`:
+      return `${args[0]} = ${args[1]}`
+    case `gt`:
+      return `${args[0]} > ${args[1]}`
+    case `gte`:
+      return `${args[0]} >= ${args[1]}`
+    case `lt`:
+      return `${args[0]} < ${args[1]}`
+    case `lte`:
+      return `${args[0]} <= ${args[1]}`
+
+    // Logical operators
+    case `and`:
+      return args.map((a) => `(${a})`).join(` AND `)
+    case `or`:
+      return args.map((a) => `(${a})`).join(` OR `)
+    case `not`:
+      return `NOT (${args[0]})`
+
+    // Special operators
+    case `in`:
+      return `${args[0]} = ANY(${args[1]})`
+    case `like`:
+      return `${args[0]} LIKE ${args[1]}`
+    case `ilike`:
+      return `${args[0]} ILIKE ${args[1]}`
+    case `isNull`:
+    case `isUndefined`:
+      return `${args[0]} IS NULL`
+
+    // String functions
+    case `upper`:
+      return `UPPER(${args[0]})`
+    case `lower`:
+      return `LOWER(${args[0]})`
+    case `length`:
+      return `LENGTH(${args[0]})`
+    case `concat`:
+      return `CONCAT(${args.join(`, `)})`
+
+    // Other functions
+    case `coalesce`:
+      return `COALESCE(${args.join(`, `)})`
+
+    default:
+      throw new Error(`Unknown function: ${expr.name}`)
+  }
+}
+
+/**
+ * Compiles serialized ORDER BY clauses into a SQL string.
+ * Applies columnMapper transformations to column references.
+ *
+ * @param clauses - The serialized ORDER BY clauses to compile
+ * @param columnMapper - Optional function to transform column names
+ * @returns The compiled SQL ORDER BY string
+ *
+ * @example
+ * ```typescript
+ * const clauses = [{ column: 'createdAt', direction: 'desc', nulls: 'first' }]
+ * compileOrderBy(clauses, camelToSnake) // '"created_at" DESC NULLS FIRST'
+ * ```
+ */
+export function compileOrderBy(
+  clauses: SerializedOrderByClause[],
+  columnMapper?: (col: string) => string
+): string {
+  return clauses
+    .map((clause) => {
+      const mappedColumn = columnMapper
+        ? columnMapper(clause.column)
+        : clause.column
+      let sql = quoteIdentifier(mappedColumn)
+      if (clause.direction === `desc`) sql += ` DESC`
+      if (clause.nulls === `first`) sql += ` NULLS FIRST`
+      if (clause.nulls === `last`) sql += ` NULLS LAST`
+      return sql
+    })
+    .join(`, `)
+}

package/src/fetch.ts

@@ -1,6 +1,7 @@
 import {
   CHUNK_LAST_OFFSET_HEADER,
   CHUNK_UP_TO_DATE_HEADER,
+  EXPIRED_HANDLE_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   SHAPE_HANDLE_HEADER,
@@ -436,6 +437,21 @@ function getNextChunkUrl(url: string, res: Response): string | void {
   // potentially miss more recent data
   if (nextUrl.searchParams.has(LIVE_QUERY_PARAM)) return
 
+  // don't prefetch if the response handle is the expired handle from the request
+  // this can happen when a proxy serves a stale cached response despite the
+  // expired_handle cache buster parameter
+  const expiredHandle = nextUrl.searchParams.get(EXPIRED_HANDLE_QUERY_PARAM)
+  if (expiredHandle && shapeHandle === expiredHandle) {
+    console.warn(
+      `[Electric] Received stale cached response with expired shape handle. ` +
+        `This should not happen and indicates a proxy/CDN caching misconfiguration. ` +
+        `The response contained handle "${shapeHandle}" which was previously marked as expired. ` +
+        `Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. ` +
+        `Skipping prefetch to prevent infinite 409 loop.`
+    )
+    return
+  }
+
   nextUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, shapeHandle)
   nextUrl.searchParams.set(OFFSET_QUERY_PARAM, lastOffset)
   nextUrl.searchParams.sort()

package/src/index.ts

@@ -16,3 +16,4 @@ export {
   snakeToCamel,
   camelToSnake,
 } from './column-mapper'
+export { compileExpression, compileOrderBy } from './expression-compiler'

package/src/types.ts

@@ -68,12 +68,40 @@ export type MoveTag = string
  */
 export type MoveOutPattern = { pos: number; value: string }
 
+/**
+ * Serialized expression types for structured subset queries.
+ * These allow Electric to properly apply columnMapper transformations
+ * before generating the final SQL.
+ */
+export type SerializedExpression =
+  | { type: `ref`; column: string } // Column reference
+  | { type: `val`; paramIndex: number } // Parameter placeholder ($1, $2, etc.)
+  | { type: `func`; name: string; args: SerializedExpression[] } // Operator/function
+
+/**
+ * Serialized ORDER BY clause for structured subset queries.
+ */
+export type SerializedOrderByClause = {
+  column: string
+  direction?: `asc` | `desc` // omitted means 'asc'
+  nulls?: `first` | `last`
+}
+
 export type SubsetParams = {
+  /** Legacy string format WHERE clause */
   where?: string
+  /** Positional parameter values for WHERE clause */
   params?: Record<string, string>
+  /** Maximum number of rows to return */
   limit?: number
+  /** Number of rows to skip */
   offset?: number
+  /** Legacy string format ORDER BY clause */
   orderBy?: string
+  /** Structured WHERE expression (preferred when available) */
+  whereExpr?: SerializedExpression
+  /** Structured ORDER BY clauses (preferred when available) */
+  orderByExpr?: SerializedOrderByClause[]
 }
 
 export type ControlMessage = {