@electric-sql/client 1.3.0 → 1.4.0

package/dist/index.d.ts

@@ -45,12 +45,45 @@ 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.
+ */
+type SerializedExpression = {
+    type: `ref`;
+    column: string;
+} | {
+    type: `val`;
+    paramIndex: number;
+} | {
+    type: `func`;
+    name: string;
+    args: SerializedExpression[];
+};
+/**
+ * Serialized ORDER BY clause for structured subset queries.
+ */
+type SerializedOrderByClause = {
+    column: string;
+    direction?: `asc` | `desc`;
+    nulls?: `first` | `last`;
+};
 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[];
 };
 type ControlMessage = {
     headers: (Header & {
@@ -841,4 +874,35 @@ declare function isControlMessage<T extends Row<unknown> = Row>(message: Message
  */
 declare function isVisibleInSnapshot(txid: number | bigint | `${bigint}`, snapshot: PostgresSnapshot | NormalizedPgSnapshot): boolean;
 
-export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type ColumnMapper, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type EventMessage, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, type MoveOutPattern, type MoveTag, type NormalizedPgSnapshot, type NumericColumn, type Offset, type Operation, type PostgresParams, type PostgresSnapshot, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type SnapshotMetadata, type SubsetParams, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, camelToSnake, createColumnMapper, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue, snakeCamelMapper, snakeToCamel };
+/**
+ * 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"'
+ * ```
+ */
+declare function compileExpression(expr: SerializedExpression, columnMapper?: (col: string) => string): string;
+/**
+ * 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'
+ * ```
+ */
+declare function compileOrderBy(clauses: SerializedOrderByClause[], columnMapper?: (col: string) => string): string;
+
+export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type ColumnMapper, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type EventMessage, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, type MoveOutPattern, type MoveTag, type NormalizedPgSnapshot, type NumericColumn, type Offset, type Operation, type PostgresParams, type PostgresSnapshot, type RegularColumn, type Row, type Schema, type SerializedExpression, type SerializedOrderByClause, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type SnapshotMetadata, type SubsetParams, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, camelToSnake, compileExpression, compileOrderBy, createColumnMapper, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue, snakeCamelMapper, snakeToCamel };

package/dist/index.legacy-esm.js

@@ -467,6 +467,8 @@ var SUBSET_PARAM_LIMIT = `subset__limit`;
 var SUBSET_PARAM_OFFSET = `subset__offset`;
 var SUBSET_PARAM_ORDER_BY = `subset__order_by`;
 var SUBSET_PARAM_WHERE_PARAMS = `subset__params`;
+var SUBSET_PARAM_WHERE_EXPR = `subset__where_expr`;
+var SUBSET_PARAM_ORDER_BY_EXPR = `subset__order_by_expr`;
 var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
   LIVE_QUERY_PARAM,
   LIVE_SSE_QUERY_PARAM,
@@ -479,7 +481,9 @@ var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
   SUBSET_PARAM_LIMIT,
   SUBSET_PARAM_OFFSET,
   SUBSET_PARAM_ORDER_BY,
-  SUBSET_PARAM_WHERE_PARAMS
+  SUBSET_PARAM_WHERE_PARAMS,
+  SUBSET_PARAM_WHERE_EXPR,
+  SUBSET_PARAM_ORDER_BY_EXPR
 ];
 
 // src/fetch.ts
@@ -733,6 +737,13 @@ function getNextChunkUrl(url, res) {
   if (!shapeHandle || !lastOffset || isUpToDate) return;
   const nextUrl = new URL(url);
   if (nextUrl.searchParams.has(LIVE_QUERY_PARAM)) return;
+  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();
@@ -759,6 +770,81 @@ function chainAborter(aborter, sourceSignal) {
 function noop() {
 }
 
+// src/expression-compiler.ts
+function compileExpression(expr, columnMapper) {
+  switch (expr.type) {
+    case `ref`: {
+      const mappedColumn = columnMapper ? columnMapper(expr.column) : expr.column;
+      return quoteIdentifier(mappedColumn);
+    }
+    case `val`:
+      return `$${expr.paramIndex}`;
+    case `func`:
+      return compileFunction(expr, columnMapper);
+    default: {
+      const _exhaustive = expr;
+      throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+function compileFunction(expr, columnMapper) {
+  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}`);
+  }
+}
+function compileOrderBy(clauses, columnMapper) {
+  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(`, `);
+}
+
 // src/client.ts
 import {
   fetchEventSource
@@ -1426,7 +1512,7 @@ requestShape_fn = async function() {
   return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
 };
 constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
-  var _a, _b, _c, _d;
+  var _a, _b, _c, _d, _e, _f;
   const [requestHeaders, params] = await Promise.all([
     resolveHeaders(this.options.headers),
     this.options.params ? toInternalParams(convertWhereParamsToObj(this.options.params)) : void 0
@@ -1471,10 +1557,20 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
     }
   }
   if (subsetParams) {
-    if (subsetParams.where && typeof subsetParams.where === `string`) {
+    if (subsetParams.whereExpr) {
+      const compiledWhere = compileExpression(
+        subsetParams.whereExpr,
+        (_c = this.options.columnMapper) == null ? void 0 : _c.encode
+      );
+      setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, compiledWhere);
+      fetchUrl.searchParams.set(
+        SUBSET_PARAM_WHERE_EXPR,
+        JSON.stringify(subsetParams.whereExpr)
+      );
+    } else if (subsetParams.where && typeof subsetParams.where === `string`) {
       const encodedWhere = encodeWhereClause(
         subsetParams.where,
-        (_c = this.options.columnMapper) == null ? void 0 : _c.encode
+        (_d = this.options.columnMapper) == null ? void 0 : _d.encode
       );
       setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, encodedWhere);
     }
@@ -1487,10 +1583,20 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
       setQueryParam(fetchUrl, SUBSET_PARAM_LIMIT, subsetParams.limit);
     if (subsetParams.offset)
       setQueryParam(fetchUrl, SUBSET_PARAM_OFFSET, subsetParams.offset);
-    if (subsetParams.orderBy && typeof subsetParams.orderBy === `string`) {
+    if (subsetParams.orderByExpr) {
+      const compiledOrderBy = compileOrderBy(
+        subsetParams.orderByExpr,
+        (_e = this.options.columnMapper) == null ? void 0 : _e.encode
+      );
+      setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, compiledOrderBy);
+      fetchUrl.searchParams.set(
+        SUBSET_PARAM_ORDER_BY_EXPR,
+        JSON.stringify(subsetParams.orderByExpr)
+      );
+    } else if (subsetParams.orderBy && typeof subsetParams.orderBy === `string`) {
       const encodedOrderBy = encodeWhereClause(
         subsetParams.orderBy,
-        (_d = this.options.columnMapper) == null ? void 0 : _d.encode
+        (_f = this.options.columnMapper) == null ? void 0 : _f.encode
       );
       setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, encodedOrderBy);
     }
@@ -1541,7 +1647,15 @@ onInitialResponse_fn = async function(response) {
   const { headers, status } = response;
   const shapeHandle = headers.get(SHAPE_HANDLE_HEADER);
   if (shapeHandle) {
-    __privateSet(this, _shapeHandle, shapeHandle);
+    const shapeKey = __privateGet(this, _currentFetchUrl) ? canonicalShapeKey(__privateGet(this, _currentFetchUrl)) : null;
+    const expiredHandle = shapeKey ? expiredShapesCache.getExpiredHandle(shapeKey) : null;
+    if (shapeHandle !== expiredHandle) {
+      __privateSet(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 "${__privateGet(this, _shapeHandle)}".`
+      );
+    }
   }
   const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER);
   if (lastOffset) {
@@ -2063,6 +2177,8 @@ export {
   Shape,
   ShapeStream,
   camelToSnake,
+  compileExpression,
+  compileOrderBy,
   createColumnMapper,
   isChangeMessage,
   isControlMessage,