@electric-sql/client 1.3.1 → 1.4.1

package/dist/index.mjs

@@ -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,