@electric-sql/client 1.3.1 → 1.4.1

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 & {
@@ -333,6 +366,7 @@ declare const LIVE_CACHE_BUSTER_QUERY_PARAM = "cursor";
 declare const SHAPE_HANDLE_QUERY_PARAM = "handle";
 declare const LIVE_QUERY_PARAM = "live";
 declare const OFFSET_QUERY_PARAM = "offset";
+declare const CACHE_BUSTER_QUERY_PARAM = "cache-buster";
 declare const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 type Replica = `full` | `default`;
@@ -386,7 +420,7 @@ type ExternalParamsRecord<T extends Row<unknown> = Row> = {
 } & Partial<PostgresParams<T>> & {
     [K in ReservedParamKeys]?: never;
 };
-type ReservedParamKeys = typeof LIVE_CACHE_BUSTER_QUERY_PARAM | typeof SHAPE_HANDLE_QUERY_PARAM | typeof LIVE_QUERY_PARAM | typeof OFFSET_QUERY_PARAM | `subset__${string}`;
+type ReservedParamKeys = typeof LIVE_CACHE_BUSTER_QUERY_PARAM | typeof SHAPE_HANDLE_QUERY_PARAM | typeof LIVE_QUERY_PARAM | typeof OFFSET_QUERY_PARAM | typeof CACHE_BUSTER_QUERY_PARAM | `subset__${string}`;
 /**
  * External headers type - what users provide.
  * Allows string or function values for any header.
@@ -841,4 +875,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

@@ -130,6 +130,12 @@ For more information visit the troubleshooting guide: /docs/guides/troubleshooti
     super(msg);
   }
 };
+var StaleCacheError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = `StaleCacheError`;
+  }
+};
 
 // src/parser.ts
 var parseNumber = (value) => Number(value);
@@ -467,6 +473,9 @@ 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 CACHE_BUSTER_QUERY_PARAM = `cache-buster`;
 var ELECTRIC_PROTOCOL_QUERY_PARAMS = [
   LIVE_QUERY_PARAM,
   LIVE_SSE_QUERY_PARAM,
@@ -479,7 +488,10 @@ 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,
+  CACHE_BUSTER_QUERY_PARAM
 ];
 
 // src/fetch.ts
@@ -766,6 +778,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
@@ -1012,7 +1099,8 @@ var RESERVED_PARAMS = /* @__PURE__ */ new Set([
   LIVE_CACHE_BUSTER_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   LIVE_QUERY_PARAM,
-  OFFSET_QUERY_PARAM
+  OFFSET_QUERY_PARAM,
+  CACHE_BUSTER_QUERY_PARAM
 ]);
 async function resolveValue(value) {
   if (typeof value === `function`) {
@@ -1054,7 +1142,7 @@ function canonicalShapeKey(url) {
   cleanUrl.searchParams.sort();
   return cleanUrl.toString();
 }
-var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSeenCursor, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _ShapeStream_instances, replayMode_get, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn;
+var _error, _fetchClient2, _sseFetchClient, _messageParser, _subscribers, _started, _state, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _isMidStream, _connected, _shapeHandle, _mode, _schema, _onError, _requestAbortController, _isRefreshing, _tickPromise, _tickPromiseResolver, _tickPromiseRejecter, _messageChain, _snapshotTracker, _activeSnapshotRequests, _midStreamPromise, _midStreamPromiseResolver, _lastSeenCursor, _currentFetchUrl, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _staleCacheBuster, _staleCacheRetryCount, _maxStaleCacheRetries, _ShapeStream_instances, replayMode_get, start_fn, requestShape_fn, constructUrl_fn, createAbortListener_fn, onInitialResponse_fn, onMessages_fn, fetchShape_fn, requestShapeLongPoll_fn, requestShapeSSE_fn, pause_fn, resume_fn, nextTick_fn, waitForStreamEnd_fn, publish_fn, sendErrorToSubscribers_fn, subscribeToVisibilityChanges_fn, reset_fn;
 var ShapeStream = class {
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
@@ -1105,6 +1193,10 @@ var ShapeStream = class {
     __privateAdd(this, _sseBackoffMaxDelay, 5e3);
     // Maximum delay cap (ms)
     __privateAdd(this, _unsubscribeFromVisibilityChanges);
+    __privateAdd(this, _staleCacheBuster);
+    // Cache buster set when stale CDN response detected, used on retry requests to bypass cache
+    __privateAdd(this, _staleCacheRetryCount, 0);
+    __privateAdd(this, _maxStaleCacheRetries, 3);
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
@@ -1335,6 +1427,9 @@ _sseFallbackToLongPolling = new WeakMap();
 _sseBackoffBaseDelay = new WeakMap();
 _sseBackoffMaxDelay = new WeakMap();
 _unsubscribeFromVisibilityChanges = new WeakMap();
+_staleCacheBuster = new WeakMap();
+_staleCacheRetryCount = new WeakMap();
+_maxStaleCacheRetries = new WeakMap();
 _ShapeStream_instances = new WeakSet();
 replayMode_get = function() {
   return __privateGet(this, _lastSeenCursor) !== void 0;
@@ -1348,7 +1443,8 @@ start_fn = async function() {
     __privateSet(this, _error, err);
     if (__privateGet(this, _onError)) {
       const retryOpts = await __privateGet(this, _onError).call(this, err);
-      if (retryOpts && typeof retryOpts === `object`) {
+      const isRetryable = !(err instanceof MissingHeadersError);
+      if (retryOpts && typeof retryOpts === `object` && isRetryable) {
         if (retryOpts.params) {
           this.options.params = __spreadValues(__spreadValues({}, (_a = this.options.params) != null ? _a : {}), retryOpts.params);
         }
@@ -1410,6 +1506,9 @@ requestShape_fn = async function() {
       }
       return;
     }
+    if (e instanceof StaleCacheError) {
+      return __privateMethod(this, _ShapeStream_instances, requestShape_fn).call(this);
+    }
     if (!(e instanceof FetchError)) throw e;
     if (e.status == 409) {
       if (__privateGet(this, _shapeHandle)) {
@@ -1433,7 +1532,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
@@ -1478,10 +1577,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);
     }
@@ -1494,10 +1603,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);
     }
@@ -1522,6 +1641,12 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
   if (expiredHandle) {
     fetchUrl.searchParams.set(EXPIRED_HANDLE_QUERY_PARAM, expiredHandle);
   }
+  if (__privateGet(this, _staleCacheBuster)) {
+    fetchUrl.searchParams.set(
+      CACHE_BUSTER_QUERY_PARAM,
+      __privateGet(this, _staleCacheBuster)
+    );
+  }
   fetchUrl.searchParams.sort();
   return {
     fetchUrl,
@@ -1544,7 +1669,7 @@ createAbortListener_fn = async function(signal) {
   }
 };
 onInitialResponse_fn = async function(response) {
-  var _a;
+  var _a, _b, _c, _d;
   const { headers, status } = response;
   const shapeHandle = headers.get(SHAPE_HANDLE_HEADER);
   if (shapeHandle) {
@@ -1552,6 +1677,30 @@ onInitialResponse_fn = async function(response) {
     const expiredHandle = shapeKey ? expiredShapesCache.getExpiredHandle(shapeKey) : null;
     if (shapeHandle !== expiredHandle) {
       __privateSet(this, _shapeHandle, shapeHandle);
+      if (__privateGet(this, _staleCacheBuster)) {
+        __privateSet(this, _staleCacheBuster, void 0);
+        __privateSet(this, _staleCacheRetryCount, 0);
+      }
+    } else if (__privateGet(this, _shapeHandle) === void 0) {
+      __privateWrapper(this, _staleCacheRetryCount)._++;
+      await ((_a = response.body) == null ? void 0 : _a.cancel());
+      if (__privateGet(this, _staleCacheRetryCount) > __privateGet(this, _maxStaleCacheRetries)) {
+        throw new FetchError(
+          502,
+          void 0,
+          void 0,
+          {},
+          (_c = (_b = __privateGet(this, _currentFetchUrl)) == null ? void 0 : _b.toString()) != null ? _c : ``,
+          `CDN continues serving stale cached responses after ${__privateGet(this, _maxStaleCacheRetries)} retry attempts. This indicates a severe proxy/CDN misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key. For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting`
+        );
+      }
+      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. For more information visit the troubleshooting guide: https://electric-sql.com/docs/guides/troubleshooting Retrying with a random cache buster to bypass the stale cache (attempt ${__privateGet(this, _staleCacheRetryCount)}/${__privateGet(this, _maxStaleCacheRetries)}).`
+      );
+      __privateSet(this, _staleCacheBuster, `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`);
+      throw new StaleCacheError(
+        `Received stale cached response with expired handle "${shapeHandle}". This indicates a proxy/CDN caching misconfiguration. Check that your proxy includes all query parameters (especially 'handle' and 'offset') in its cache key.`
+      );
     } 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)}".`
@@ -1566,7 +1715,7 @@ onInitialResponse_fn = async function(response) {
   if (liveCacheBuster) {
     __privateSet(this, _liveCacheBuster, liveCacheBuster);
   }
-  __privateSet(this, _schema, (_a = __privateGet(this, _schema)) != null ? _a : getSchemaFromHeaders(headers));
+  __privateSet(this, _schema, (_d = __privateGet(this, _schema)) != null ? _d : getSchemaFromHeaders(headers));
   if (status === 204) {
     __privateSet(this, _lastSyncedAt, Date.now());
   }
@@ -1804,6 +1953,8 @@ reset_fn = function(handle) {
   __privateSet(this, _activeSnapshotRequests, 0);
   __privateSet(this, _consecutiveShortSseConnections, 0);
   __privateSet(this, _sseFallbackToLongPolling, false);
+  __privateSet(this, _staleCacheBuster, void 0);
+  __privateSet(this, _staleCacheRetryCount, 0);
 };
 ShapeStream.Replica = {
   FULL: `full`,
@@ -2078,6 +2229,8 @@ export {
   Shape,
   ShapeStream,
   camelToSnake,
+  compileExpression,
+  compileOrderBy,
   createColumnMapper,
   isChangeMessage,
   isControlMessage,