@electric-sql/client 1.3.0 → 1.4.0

package/dist/cjs/index.cjs

@@ -71,6 +71,8 @@ __export(src_exports, {
   Shape: () => Shape,
   ShapeStream: () => ShapeStream,
   camelToSnake: () => camelToSnake,
+  compileExpression: () => compileExpression,
+  compileOrderBy: () => compileOrderBy,
   createColumnMapper: () => createColumnMapper,
   isChangeMessage: () => isChangeMessage,
   isControlMessage: () => isControlMessage,
@@ -502,6 +504,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,
@@ -514,7 +518,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
@@ -768,6 +774,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();
@@ -794,6 +807,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
 var import_fetch_event_source = require("@microsoft/fetch-event-source");
 
@@ -1459,7 +1547,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
@@ -1504,10 +1592,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);
     }
@@ -1520,10 +1618,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);
     }
@@ -1574,7 +1682,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) {
@@ -2097,6 +2213,8 @@ notify_fn = function() {
   Shape,
   ShapeStream,
   camelToSnake,
+  compileExpression,
+  compileOrderBy,
   createColumnMapper,
   isChangeMessage,
   isControlMessage,