@electric-sql/client 1.1.5 → 1.2.0

package/dist/index.d.ts

@@ -118,6 +118,140 @@ type Parser<Extensions = never> = {
 };
 type TransformFunction<Extensions = never> = (message: Row<Extensions>) => Row<Extensions>;
 
+type DbColumnName = string;
+type AppColumnName = string;
+/**
+ * A bidirectional column mapper that handles transforming column **names**
+ * between database format (e.g., snake_case) and application format (e.g., camelCase).
+ *
+ * **Important**: ColumnMapper only transforms column names, not column values or types.
+ * For type conversions (e.g., string → Date), use the `parser` option.
+ * For value transformations (e.g., encryption), use the `transformer` option.
+ *
+ * @example
+ * ```typescript
+ * const mapper = snakeCamelMapper()
+ * mapper.decode('user_id') // 'userId'
+ * mapper.encode('userId') // 'user_id'
+ * ```
+ */
+interface ColumnMapper {
+    /**
+     * Transform a column name from database format to application format.
+     * Applied to column names in query results.
+     */
+    decode: (dbColumnName: DbColumnName) => AppColumnName;
+    /**
+     * Transform a column name from application format to database format.
+     * Applied to column names in WHERE clauses and other query parameters.
+     */
+    encode: (appColumnName: AppColumnName) => DbColumnName;
+}
+/**
+ * Converts a snake_case string to camelCase.
+ *
+ * Handles edge cases:
+ * - Preserves leading underscores: `_user_id` → `_userId`
+ * - Preserves trailing underscores: `user_id_` → `userId_`
+ * - Collapses multiple underscores: `user__id` → `userId`
+ * - Normalizes to lowercase first: `user_Column` → `userColumn`
+ *
+ * @example
+ * snakeToCamel('user_id') // 'userId'
+ * snakeToCamel('project_id') // 'projectId'
+ * snakeToCamel('created_at') // 'createdAt'
+ * snakeToCamel('_private') // '_private'
+ * snakeToCamel('user__id') // 'userId'
+ * snakeToCamel('user_id_') // 'userId_'
+ */
+declare function snakeToCamel(str: string): string;
+/**
+ * Converts a camelCase string to snake_case.
+ *
+ * Handles consecutive capitals (acronyms) properly:
+ * - `userID` → `user_id`
+ * - `userHTTPSURL` → `user_https_url`
+ *
+ * @example
+ * camelToSnake('userId') // 'user_id'
+ * camelToSnake('projectId') // 'project_id'
+ * camelToSnake('createdAt') // 'created_at'
+ * camelToSnake('userID') // 'user_id'
+ * camelToSnake('parseHTMLString') // 'parse_html_string'
+ */
+declare function camelToSnake(str: string): string;
+/**
+ * Creates a column mapper from an explicit mapping of database columns to application columns.
+ *
+ * @param mapping - Object mapping database column names (keys) to application column names (values)
+ * @returns A ColumnMapper that can encode and decode column names bidirectionally
+ *
+ * @example
+ * const mapper = createColumnMapper({
+ *   user_id: 'userId',
+ *   project_id: 'projectId',
+ *   created_at: 'createdAt'
+ * })
+ *
+ * // Use with ShapeStream
+ * const stream = new ShapeStream({
+ *   url: 'http://localhost:3000/v1/shape',
+ *   params: { table: 'todos' },
+ *   columnMapper: mapper
+ * })
+ */
+declare function createColumnMapper(mapping: Record<string, string>): ColumnMapper;
+/**
+ * Creates a column mapper that automatically converts between snake_case and camelCase.
+ * This is the most common use case for column mapping.
+ *
+ * When a schema is provided, it will only map columns that exist in the schema.
+ * Otherwise, it will map any column name it encounters.
+ *
+ * **⚠️ Limitations and Edge Cases:**
+ * - **WHERE clause encoding**: Uses regex-based parsing which may not handle all complex
+ *   SQL expressions. Test thoroughly with your queries, especially those with:
+ *   - Complex nested expressions
+ *   - Custom operators or functions
+ *   - Column names that conflict with SQL keywords
+ *   - Quoted identifiers (e.g., `"$price"`, `"user-id"`) - not supported
+ *   - Column names with special characters (non-alphanumeric except underscore)
+ * - **Acronym ambiguity**: `userID` → `user_id` → `userId` (ID becomes Id after roundtrip)
+ *   Use `createColumnMapper()` with explicit mapping if you need exact control
+ * - **Type conversion**: This only renames columns, not values. Use `parser` for type conversion
+ *
+ * **When to use explicit mapping instead:**
+ * - You have column names that don't follow snake_case/camelCase patterns
+ * - You need exact control over mappings (e.g., `id` → `identifier`)
+ * - Your WHERE clauses are complex and automatic encoding fails
+ * - You have quoted identifiers or column names with special characters
+ *
+ * @param schema - Optional database schema to constrain mapping to known columns
+ * @returns A ColumnMapper for snake_case ↔ camelCase conversion
+ *
+ * @example
+ * // Basic usage
+ * const mapper = snakeCamelMapper()
+ *
+ * // With schema - only maps columns in schema (recommended)
+ * const mapper = snakeCamelMapper(schema)
+ *
+ * // Use with ShapeStream
+ * const stream = new ShapeStream({
+ *   url: 'http://localhost:3000/v1/shape',
+ *   params: { table: 'todos' },
+ *   columnMapper: snakeCamelMapper()
+ * })
+ *
+ * @example
+ * // If automatic encoding fails, fall back to manual column names in WHERE clauses:
+ * stream.requestSnapshot({
+ *   where: "user_id = $1", // Use database column names directly if needed
+ *   params: { "1": "123" }
+ * })
+ */
+declare function snakeCamelMapper(schema?: Schema): ColumnMapper;
+
 declare class FetchError extends Error {
     url: string;
     status: number;
@@ -301,7 +435,84 @@ interface ShapeStreamOptions<T = never> {
     fetchClient?: typeof fetch;
     backoffOptions?: BackoffOptions;
     parser?: Parser<T>;
+    /**
+     * Function to transform rows after parsing (e.g., for encryption, type coercion).
+     * Applied to data received from Electric.
+     *
+     * **Note**: If you're using `transformer` solely for column name transformation
+     * (e.g., snake_case → camelCase), consider using `columnMapper` instead, which
+     * provides bidirectional transformation and automatically encodes WHERE clauses.
+     *
+     * **Execution order** when both are provided:
+     * 1. `columnMapper.decode` runs first (renames columns)
+     * 2. `transformer` runs second (transforms values)
+     *
+     * @example
+     * ```typescript
+     * // For column renaming only - use columnMapper
+     * import { snakeCamelMapper } from '@electric-sql/client'
+     * const stream = new ShapeStream({ columnMapper: snakeCamelMapper() })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // For value transformation (encryption, etc.) - use transformer
+     * const stream = new ShapeStream({
+     *   transformer: (row) => ({
+     *     ...row,
+     *     encrypted_field: decrypt(row.encrypted_field)
+     *   })
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use both together
+     * const stream = new ShapeStream({
+     *   columnMapper: snakeCamelMapper(), // Runs first: renames columns
+     *   transformer: (row) => ({         // Runs second: transforms values
+     *     ...row,
+     *     encryptedData: decrypt(row.encryptedData)
+     *   })
+     * })
+     * ```
+     */
     transformer?: TransformFunction<T>;
+    /**
+     * Bidirectional column name mapper for transforming between database column names
+     * (e.g., snake_case) and application column names (e.g., camelCase).
+     *
+     * The mapper handles both:
+     * - **Decoding**: Database → Application (applied to query results)
+     * - **Encoding**: Application → Database (applied to WHERE clauses)
+     *
+     * @example
+     * ```typescript
+     * // Most common case: snake_case ↔ camelCase
+     * import { snakeCamelMapper } from '@electric-sql/client'
+     *
+     * const stream = new ShapeStream({
+     *   url: 'http://localhost:3000/v1/shape',
+     *   params: { table: 'todos' },
+     *   columnMapper: snakeCamelMapper()
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom mapping
+     * import { createColumnMapper } from '@electric-sql/client'
+     *
+     * const stream = new ShapeStream({
+     *   columnMapper: createColumnMapper({
+     *     user_id: 'userId',
+     *     project_id: 'projectId',
+     *     created_at: 'createdAt'
+     *   })
+     * })
+     * ```
+     */
+    columnMapper?: ColumnMapper;
     /**
      * A function for handling shapestream errors.
      *
@@ -597,4 +808,4 @@ 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 CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, 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, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue };
+export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type ColumnMapper, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, 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 };

package/dist/index.legacy-esm.js

@@ -269,6 +269,151 @@ function makeNullableParser(parser, columnInfo, columnName) {
   };
 }
 
+// src/column-mapper.ts
+function snakeToCamel(str) {
+  var _a, _b, _c, _d;
+  const leadingUnderscores = (_b = (_a = str.match(/^_+/)) == null ? void 0 : _a[0]) != null ? _b : ``;
+  const withoutLeading = str.slice(leadingUnderscores.length);
+  const trailingUnderscores = (_d = (_c = withoutLeading.match(/_+$/)) == null ? void 0 : _c[0]) != null ? _d : ``;
+  const core = trailingUnderscores ? withoutLeading.slice(
+    0,
+    withoutLeading.length - trailingUnderscores.length
+  ) : withoutLeading;
+  const normalized = core.toLowerCase();
+  const camelCased = normalized.replace(
+    /_+([a-z])/g,
+    (_, letter) => letter.toUpperCase()
+  );
+  return leadingUnderscores + camelCased + trailingUnderscores;
+}
+function camelToSnake(str) {
+  return str.replace(/([a-z])([A-Z])/g, `$1_$2`).replace(/([A-Z]+)([A-Z][a-z])/g, `$1_$2`).toLowerCase();
+}
+function createColumnMapper(mapping) {
+  const reverseMapping = {};
+  for (const [dbName, appName] of Object.entries(mapping)) {
+    reverseMapping[appName] = dbName;
+  }
+  return {
+    decode: (dbColumnName) => {
+      var _a;
+      return (_a = mapping[dbColumnName]) != null ? _a : dbColumnName;
+    },
+    encode: (appColumnName) => {
+      var _a;
+      return (_a = reverseMapping[appColumnName]) != null ? _a : appColumnName;
+    }
+  };
+}
+function encodeWhereClause(whereClause, encode) {
+  if (!whereClause || !encode) return whereClause != null ? whereClause : ``;
+  const sqlKeywords = /* @__PURE__ */ new Set([
+    `SELECT`,
+    `FROM`,
+    `WHERE`,
+    `AND`,
+    `OR`,
+    `NOT`,
+    `IN`,
+    `IS`,
+    `NULL`,
+    `NULLS`,
+    `FIRST`,
+    `LAST`,
+    `TRUE`,
+    `FALSE`,
+    `LIKE`,
+    `ILIKE`,
+    `BETWEEN`,
+    `ASC`,
+    `DESC`,
+    `LIMIT`,
+    `OFFSET`,
+    `ORDER`,
+    `BY`,
+    `GROUP`,
+    `HAVING`,
+    `DISTINCT`,
+    `AS`,
+    `ON`,
+    `JOIN`,
+    `LEFT`,
+    `RIGHT`,
+    `INNER`,
+    `OUTER`,
+    `CROSS`,
+    `CASE`,
+    `WHEN`,
+    `THEN`,
+    `ELSE`,
+    `END`,
+    `CAST`,
+    `LOWER`,
+    `UPPER`,
+    `COALESCE`,
+    `NULLIF`
+  ]);
+  const quotedRanges = [];
+  let pos = 0;
+  while (pos < whereClause.length) {
+    const ch = whereClause[pos];
+    if (ch === `'` || ch === `"`) {
+      const start = pos;
+      const quoteChar = ch;
+      pos++;
+      while (pos < whereClause.length) {
+        if (whereClause[pos] === quoteChar) {
+          if (whereClause[pos + 1] === quoteChar) {
+            pos += 2;
+          } else {
+            pos++;
+            break;
+          }
+        } else {
+          pos++;
+        }
+      }
+      quotedRanges.push({ start, end: pos });
+    } else {
+      pos++;
+    }
+  }
+  const isInQuotedString = (pos2) => {
+    return quotedRanges.some((range) => pos2 >= range.start && pos2 < range.end);
+  };
+  const identifierPattern = new RegExp("(?<![a-zA-Z0-9_])([a-zA-Z_][a-zA-Z0-9_]*)(?![a-zA-Z0-9_])", "g");
+  return whereClause.replace(identifierPattern, (match, _p1, offset) => {
+    if (isInQuotedString(offset)) {
+      return match;
+    }
+    if (sqlKeywords.has(match.toUpperCase())) {
+      return match;
+    }
+    if (match.startsWith(`$`)) {
+      return match;
+    }
+    const encoded = encode(match);
+    return encoded;
+  });
+}
+function snakeCamelMapper(schema) {
+  if (schema) {
+    const mapping = {};
+    for (const dbColumn of Object.keys(schema)) {
+      mapping[dbColumn] = snakeToCamel(dbColumn);
+    }
+    return createColumnMapper(mapping);
+  }
+  return {
+    decode: (dbColumnName) => {
+      return snakeToCamel(dbColumnName);
+    },
+    encode: (appColumnName) => {
+      return camelToSnake(appColumnName);
+    }
+  };
+}
+
 // src/helpers.ts
 function isChangeMessage(message) {
   return `key` in message;
@@ -664,6 +809,127 @@ var ExpiredShapesCache = class {
 };
 var expiredShapesCache = new ExpiredShapesCache();
 
+// src/up-to-date-tracker.ts
+var UpToDateTracker = class {
+  constructor() {
+    this.data = {};
+    this.storageKey = `electric_up_to_date_tracker`;
+    this.cacheTTL = 6e4;
+    // 60s to match typical CDN s-maxage cache duration
+    this.maxEntries = 250;
+    this.writeThrottleMs = 6e4;
+    // Throttle localStorage writes to once per 60s
+    this.lastWriteTime = 0;
+    this.load();
+    this.cleanup();
+  }
+  /**
+   * Records that a shape received an up-to-date message with a specific cursor.
+   * This timestamp and cursor are used to detect cache replay scenarios.
+   * Updates in-memory immediately, but throttles localStorage writes.
+   */
+  recordUpToDate(shapeKey, cursor) {
+    this.data[shapeKey] = {
+      timestamp: Date.now(),
+      cursor
+    };
+    const keys = Object.keys(this.data);
+    if (keys.length > this.maxEntries) {
+      const oldest = keys.reduce(
+        (min, k) => this.data[k].timestamp < this.data[min].timestamp ? k : min
+      );
+      delete this.data[oldest];
+    }
+    this.scheduleSave();
+  }
+  /**
+   * Schedules a throttled save to localStorage.
+   * Writes immediately if enough time has passed, otherwise schedules for later.
+   */
+  scheduleSave() {
+    const now = Date.now();
+    const timeSinceLastWrite = now - this.lastWriteTime;
+    if (timeSinceLastWrite >= this.writeThrottleMs) {
+      this.lastWriteTime = now;
+      this.save();
+    } else if (!this.pendingSaveTimer) {
+      const delay = this.writeThrottleMs - timeSinceLastWrite;
+      this.pendingSaveTimer = setTimeout(() => {
+        this.lastWriteTime = Date.now();
+        this.pendingSaveTimer = void 0;
+        this.save();
+      }, delay);
+    }
+  }
+  /**
+   * Checks if we should enter replay mode for this shape.
+   * Returns the last seen cursor if there's a recent up-to-date (< 60s),
+   * which means we'll likely be replaying cached responses.
+   * Returns null if no recent up-to-date exists.
+   */
+  shouldEnterReplayMode(shapeKey) {
+    const entry = this.data[shapeKey];
+    if (!entry) {
+      return null;
+    }
+    const age = Date.now() - entry.timestamp;
+    if (age >= this.cacheTTL) {
+      return null;
+    }
+    return entry.cursor;
+  }
+  /**
+   * Cleans up expired entries from the cache.
+   * Called on initialization and can be called periodically.
+   */
+  cleanup() {
+    const now = Date.now();
+    const keys = Object.keys(this.data);
+    let modified = false;
+    for (const key of keys) {
+      const age = now - this.data[key].timestamp;
+      if (age > this.cacheTTL) {
+        delete this.data[key];
+        modified = true;
+      }
+    }
+    if (modified) {
+      this.save();
+    }
+  }
+  save() {
+    if (typeof localStorage === `undefined`) return;
+    try {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.data));
+    } catch (e) {
+    }
+  }
+  load() {
+    if (typeof localStorage === `undefined`) return;
+    try {
+      const stored = localStorage.getItem(this.storageKey);
+      if (stored) {
+        this.data = JSON.parse(stored);
+      }
+    } catch (e) {
+      this.data = {};
+    }
+  }
+  /**
+   * Clears all tracked up-to-date timestamps.
+   * Useful for testing or manual cache invalidation.
+   */
+  clear() {
+    this.data = {};
+    if (this.pendingSaveTimer) {
+      clearTimeout(this.pendingSaveTimer);
+      this.pendingSaveTimer = void 0;
+    }
+    this.save();
+  }
+};
+var upToDateTracker = new UpToDateTracker();
+
 // src/snapshot-tracker.ts
 var SnapshotTracker = class {
   constructor() {
@@ -773,7 +1039,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, _lastSseConnectionStartTime, _minSseConnectionDuration, _consecutiveShortSseConnections, _maxShortSseConnections, _sseFallbackToLongPolling, _sseBackoffBaseDelay, _sseBackoffMaxDelay, _unsubscribeFromVisibilityChanges, _ShapeStream_instances, 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, _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);
@@ -808,6 +1074,10 @@ var ShapeStream = class {
     // counter for concurrent snapshot requests
     __privateAdd(this, _midStreamPromise);
     __privateAdd(this, _midStreamPromiseResolver);
+    __privateAdd(this, _lastSeenCursor);
+    // Last seen cursor from previous session (used to detect cached responses)
+    __privateAdd(this, _currentFetchUrl);
+    // Current fetch URL for computing shape key
     __privateAdd(this, _lastSseConnectionStartTime);
     __privateAdd(this, _minSseConnectionDuration, 1e3);
     // Minimum expected SSE connection duration (1 second)
@@ -826,10 +1096,21 @@ var ShapeStream = class {
     __privateSet(this, _lastOffset, (_a = this.options.offset) != null ? _a : `-1`);
     __privateSet(this, _liveCacheBuster, ``);
     __privateSet(this, _shapeHandle, this.options.handle);
-    __privateSet(this, _messageParser, new MessageParser(
-      options.parser,
-      options.transformer
-    ));
+    let transformer;
+    if (options.columnMapper) {
+      const applyColumnMapper = (row) => {
+        const result = {};
+        for (const [dbKey, value] of Object.entries(row)) {
+          const appKey = options.columnMapper.decode(dbKey);
+          result[appKey] = value;
+        }
+        return result;
+      };
+      transformer = options.transformer ? (row) => options.transformer(applyColumnMapper(row)) : applyColumnMapper;
+    } else {
+      transformer = options.transformer;
+    }
+    __privateSet(this, _messageParser, new MessageParser(options.parser, transformer));
     __privateSet(this, _onError, this.options.onError);
     __privateSet(this, _mode, (_b = this.options.log) != null ? _b : `full`);
     const baseFetchClient = (_c = options.fetchClient) != null ? _c : (...args) => fetch(...args);
@@ -1028,6 +1309,8 @@ _snapshotTracker = new WeakMap();
 _activeSnapshotRequests = new WeakMap();
 _midStreamPromise = new WeakMap();
 _midStreamPromiseResolver = new WeakMap();
+_lastSeenCursor = new WeakMap();
+_currentFetchUrl = new WeakMap();
 _lastSseConnectionStartTime = new WeakMap();
 _minSseConnectionDuration = new WeakMap();
 _consecutiveShortSseConnections = new WeakMap();
@@ -1037,6 +1320,9 @@ _sseBackoffBaseDelay = new WeakMap();
 _sseBackoffMaxDelay = new WeakMap();
 _unsubscribeFromVisibilityChanges = new WeakMap();
 _ShapeStream_instances = new WeakSet();
+replayMode_get = function() {
+  return __privateGet(this, _lastSeenCursor) !== void 0;
+};
 start_fn = async function() {
   var _a, _b, _c, _d, _e;
   __privateSet(this, _started, true);
@@ -1131,6 +1417,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;
   const [requestHeaders, params] = await Promise.all([
     resolveHeaders(this.options.headers),
     this.options.params ? toInternalParams(convertWhereParamsToObj(this.options.params)) : void 0
@@ -1139,7 +1426,13 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
   const fetchUrl = new URL(url);
   if (params) {
     if (params.table) setQueryParam(fetchUrl, TABLE_QUERY_PARAM, params.table);
-    if (params.where) setQueryParam(fetchUrl, WHERE_QUERY_PARAM, params.where);
+    if (params.where && typeof params.where === `string`) {
+      const encodedWhere = encodeWhereClause(
+        params.where,
+        (_a = this.options.columnMapper) == null ? void 0 : _a.encode
+      );
+      setQueryParam(fetchUrl, WHERE_QUERY_PARAM, encodedWhere);
+    }
     if (params.columns)
       setQueryParam(fetchUrl, COLUMNS_QUERY_PARAM, params.columns);
     if (params.replica) setQueryParam(fetchUrl, REPLICA_PARAM, params.replica);
@@ -1156,16 +1449,29 @@ constructUrl_fn = async function(url, resumingFromPause, subsetParams) {
     }
   }
   if (subsetParams) {
-    if (subsetParams.where)
-      setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, subsetParams.where);
+    if (subsetParams.where && typeof subsetParams.where === `string`) {
+      const encodedWhere = encodeWhereClause(
+        subsetParams.where,
+        (_b = this.options.columnMapper) == null ? void 0 : _b.encode
+      );
+      setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, encodedWhere);
+    }
     if (subsetParams.params)
-      setQueryParam(fetchUrl, SUBSET_PARAM_WHERE_PARAMS, subsetParams.params);
+      fetchUrl.searchParams.set(
+        SUBSET_PARAM_WHERE_PARAMS,
+        JSON.stringify(subsetParams.params)
+      );
     if (subsetParams.limit)
       setQueryParam(fetchUrl, SUBSET_PARAM_LIMIT, subsetParams.limit);
     if (subsetParams.offset)
       setQueryParam(fetchUrl, SUBSET_PARAM_OFFSET, subsetParams.offset);
-    if (subsetParams.orderBy)
-      setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, subsetParams.orderBy);
+    if (subsetParams.orderBy && typeof subsetParams.orderBy === `string`) {
+      const encodedOrderBy = encodeWhereClause(
+        subsetParams.orderBy,
+        (_c = this.options.columnMapper) == null ? void 0 : _c.encode
+      );
+      setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, encodedOrderBy);
+    }
   }
   fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, __privateGet(this, _lastOffset));
   fetchUrl.searchParams.set(LOG_MODE_QUERY_PARAM, __privateGet(this, _mode));
@@ -1244,6 +1550,17 @@ onMessages_fn = async function(batch, isSseMessage = false) {
       __privateSet(this, _isUpToDate, true);
       __privateSet(this, _isMidStream, false);
       (_a = __privateGet(this, _midStreamPromiseResolver)) == null ? void 0 : _a.call(this);
+      if (__privateGet(this, _ShapeStream_instances, replayMode_get) && !isSseMessage) {
+        const currentCursor = __privateGet(this, _liveCacheBuster);
+        if (currentCursor === __privateGet(this, _lastSeenCursor)) {
+          return;
+        }
+      }
+      __privateSet(this, _lastSeenCursor, void 0);
+      if (__privateGet(this, _currentFetchUrl)) {
+        const shapeKey = canonicalShapeKey(__privateGet(this, _currentFetchUrl));
+        upToDateTracker.recordUpToDate(shapeKey, __privateGet(this, _liveCacheBuster));
+      }
     }
     const messagesToProcess = batch.filter((message) => {
       if (isChangeMessage(message)) {
@@ -1256,6 +1573,14 @@ onMessages_fn = async function(batch, isSseMessage = false) {
 };
 fetchShape_fn = async function(opts) {
   var _a;
+  __privateSet(this, _currentFetchUrl, opts.fetchUrl);
+  if (!__privateGet(this, _isUpToDate) && !__privateGet(this, _ShapeStream_instances, replayMode_get)) {
+    const shapeKey = canonicalShapeKey(opts.fetchUrl);
+    const lastSeenCursor = upToDateTracker.shouldEnterReplayMode(shapeKey);
+    if (lastSeenCursor) {
+      __privateSet(this, _lastSeenCursor, lastSeenCursor);
+    }
+  }
   const useSse = (_a = this.options.liveSse) != null ? _a : this.options.experimentalLiveSse;
   if (__privateGet(this, _isUpToDate) && useSse && !__privateGet(this, _isRefreshing) && !opts.resumingFromPause && !__privateGet(this, _sseFallbackToLongPolling)) {
     opts.fetchUrl.searchParams.set(EXPERIMENTAL_LIVE_SSE_QUERY_PARAM, `true`);
@@ -1708,9 +2033,13 @@ export {
   FetchError,
   Shape,
   ShapeStream,
+  camelToSnake,
+  createColumnMapper,
   isChangeMessage,
   isControlMessage,
   isVisibleInSnapshot,
-  resolveValue
+  resolveValue,
+  snakeCamelMapper,
+  snakeToCamel
 };
 //# sourceMappingURL=index.legacy-esm.js.map