@electric-sql/client 1.1.5 → 1.2.0

package/dist/cjs/index.cjs

@@ -90,10 +90,14 @@ __export(src_exports, {
   FetchError: () => FetchError,
   Shape: () => Shape,
   ShapeStream: () => ShapeStream,
+  camelToSnake: () => camelToSnake,
+  createColumnMapper: () => createColumnMapper,
   isChangeMessage: () => isChangeMessage,
   isControlMessage: () => isControlMessage,
   isVisibleInSnapshot: () => isVisibleInSnapshot,
-  resolveValue: () => resolveValue
+  resolveValue: () => resolveValue,
+  snakeCamelMapper: () => snakeCamelMapper,
+  snakeToCamel: () => snakeToCamel
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -322,6 +326,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;
@@ -715,6 +864,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() {
@@ -832,7 +1102,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);
@@ -867,6 +1137,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)
@@ -885,10 +1159,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);
@@ -1093,6 +1378,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();
@@ -1102,6 +1389,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 = function() {
   return __async(this, null, function* () {
     var _a, _b, _c, _d, _e;
@@ -1201,6 +1491,7 @@ requestShape_fn = function() {
 };
 constructUrl_fn = function(url, resumingFromPause, subsetParams) {
   return __async(this, null, function* () {
+    var _a, _b, _c;
     const [requestHeaders, params] = yield Promise.all([
       resolveHeaders(this.options.headers),
       this.options.params ? toInternalParams(convertWhereParamsToObj(this.options.params)) : void 0
@@ -1209,7 +1500,13 @@ constructUrl_fn = 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);
@@ -1226,16 +1523,29 @@ constructUrl_fn = 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));
@@ -1320,6 +1630,17 @@ onMessages_fn = 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)) {
@@ -1334,6 +1655,14 @@ onMessages_fn = function(batch, isSseMessage = false) {
 fetchShape_fn = function(opts) {
   return __async(this, null, function* () {
     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`);
@@ -1804,9 +2133,13 @@ notify_fn = function() {
   FetchError,
   Shape,
   ShapeStream,
+  camelToSnake,
+  createColumnMapper,
   isChangeMessage,
   isControlMessage,
   isVisibleInSnapshot,
-  resolveValue
+  resolveValue,
+  snakeCamelMapper,
+  snakeToCamel
 });
 //# sourceMappingURL=index.cjs.map