@electric-sql/client 1.1.4 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@electric-sql/client",
   "description": "Postgres everywhere - your data, in sync, wherever you need it.",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"

package/src/client.ts

@@ -9,6 +9,7 @@ import {
   SnapshotMetadata,
 } from './types'
 import { MessageParser, Parser, TransformFunction } from './parser'
+import { ColumnMapper, encodeWhereClause } from './column-mapper'
 import { getOffset, isUpToDateMessage, isChangeMessage } from './helpers'
 import {
   FetchError,
@@ -17,6 +18,7 @@ import {
   InvalidSignalError,
   MissingShapeHandleError,
   ReservedParamError,
+  MissingHeadersError,
 } from './error'
 import {
   BackoffDefaults,
@@ -58,6 +60,7 @@ import {
   fetchEventSource,
 } from '@microsoft/fetch-event-source'
 import { expiredShapesCache } from './expired-shapes-cache'
+import { upToDateTracker } from './up-to-date-tracker'
 import { SnapshotTracker } from './snapshot-tracker'
 
 const RESERVED_PARAMS: Set<ReservedParamKeys> = new Set([
@@ -292,8 +295,87 @@ export 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.
    *
@@ -368,16 +450,15 @@ export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
 
   forceDisconnectAndRefresh(): Promise<void>
 
-  requestSnapshot(params: {
-    where?: string
-    params?: Record<string, string>
-    limit: number
-    offset?: number
-    orderBy: string
-  }): Promise<{
+  requestSnapshot(params: SubsetParams): Promise<{
     metadata: SnapshotMetadata
     data: Array<Message<T>>
   }>
+
+  fetchSnapshot(opts: SubsetParams): Promise<{
+    metadata: SnapshotMetadata
+    data: Array<ChangeMessage<T>>
+  }>
 }
 
 /**
@@ -482,6 +563,8 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #activeSnapshotRequests = 0 // counter for concurrent snapshot requests
   #midStreamPromise?: Promise<void>
   #midStreamPromiseResolver?: () => void
+  #lastSeenCursor?: string // Last seen cursor from previous session (used to detect cached responses)
+  #currentFetchUrl?: URL // Current fetch URL for computing shape key
   #lastSseConnectionStartTime?: number
   #minSseConnectionDuration = 1000 // Minimum expected SSE connection duration (1 second)
   #consecutiveShortSseConnections = 0
@@ -491,16 +574,44 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #sseBackoffMaxDelay = 5000 // Maximum delay cap (ms)
   #unsubscribeFromVisibilityChanges?: () => void
 
+  // Derived state: we're in replay mode if we have a last seen cursor
+  get #replayMode(): boolean {
+    return this.#lastSeenCursor !== undefined
+  }
+
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
     validateOptions(this.options)
     this.#lastOffset = this.options.offset ?? `-1`
     this.#liveCacheBuster = ``
     this.#shapeHandle = this.options.handle
-    this.#messageParser = new MessageParser<T>(
-      options.parser,
-      options.transformer
-    )
+
+    // Build transformer chain: columnMapper.decode -> transformer
+    // columnMapper transforms column names, transformer transforms values
+    let transformer: TransformFunction<GetExtensions<T>> | undefined
+
+    if (options.columnMapper) {
+      const applyColumnMapper = (
+        row: Row<GetExtensions<T>>
+      ): Row<GetExtensions<T>> => {
+        const result: Record<string, unknown> = {}
+        for (const [dbKey, value] of Object.entries(row)) {
+          const appKey = options.columnMapper!.decode(dbKey)
+          result[appKey] = value
+        }
+        return result as Row<GetExtensions<T>>
+      }
+
+      transformer = options.transformer
+        ? (row: Row<GetExtensions<T>>) =>
+            options.transformer!(applyColumnMapper(row))
+        : applyColumnMapper
+    } else {
+      transformer = options.transformer
+    }
+
+    this.#messageParser = new MessageParser<T>(options.parser, transformer)
+
     this.#onError = this.options.onError
     this.#mode = this.options.log ?? `full`
 
@@ -737,7 +848,13 @@ export class ShapeStream<T extends Row<unknown> = Row>
     // Add PostgreSQL-specific parameters
     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,
+          this.options.columnMapper?.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)
@@ -758,23 +875,40 @@ export class ShapeStream<T extends Row<unknown> = Row>
     }
 
     if (subsetParams) {
-      if (subsetParams.where)
-        setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, subsetParams.where)
+      if (subsetParams.where && typeof subsetParams.where === `string`) {
+        const encodedWhere = encodeWhereClause(
+          subsetParams.where,
+          this.options.columnMapper?.encode
+        )
+        setQueryParam(fetchUrl, SUBSET_PARAM_WHERE, encodedWhere)
+      }
       if (subsetParams.params)
-        setQueryParam(fetchUrl, SUBSET_PARAM_WHERE_PARAMS, subsetParams.params)
+        // Serialize params as JSON to keep the parameter name constant for proxy configs
+        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,
+          this.options.columnMapper?.encode
+        )
+        setQueryParam(fetchUrl, SUBSET_PARAM_ORDER_BY, encodedOrderBy)
+      }
     }
 
     // Add Electric's internal parameters
     fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, this.#lastOffset)
     fetchUrl.searchParams.set(LOG_MODE_QUERY_PARAM, this.#mode)
 
-    if (this.#isUpToDate) {
+    // Snapshot requests (with subsetParams) should never use live polling
+    const isSnapshotRequest = subsetParams !== undefined
+
+    if (this.#isUpToDate && !isSnapshotRequest) {
       // If we are resuming from a paused state, we don't want to perform a live request
       // because it could be a long poll that holds for 20sec
       // and during all that time `isConnected` will be false
@@ -846,11 +980,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
       this.#liveCacheBuster = liveCacheBuster
     }
 
-    const getSchema = (): Schema => {
-      const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER)
-      return schemaHeader ? JSON.parse(schemaHeader) : {}
-    }
-    this.#schema = this.#schema ?? getSchema()
+    this.#schema = this.#schema ?? getSchemaFromHeaders(headers)
 
     // NOTE: 204s are deprecated, the Electric server should not
     // send these in latest versions but this is here for backwards
@@ -884,6 +1014,33 @@ export class ShapeStream<T extends Row<unknown> = Row>
         this.#isMidStream = false
         // Resolve the promise waiting for mid-stream to end
         this.#midStreamPromiseResolver?.()
+
+        // Check if we should suppress this up-to-date notification
+        // to prevent multiple renders from cached responses
+        if (this.#replayMode && !isSseMessage) {
+          // We're in replay mode (replaying cached responses during initial sync).
+          // Check if the cursor has changed - cursors are time-based and always
+          // increment, so a new cursor means fresh data from the server.
+          const currentCursor = this.#liveCacheBuster
+
+          if (currentCursor === this.#lastSeenCursor) {
+            // Same cursor = still replaying cached responses
+            // Suppress this up-to-date notification
+            return
+          }
+        }
+
+        // We're either:
+        // 1. Not in replay mode (normal operation), or
+        // 2. This is a live/SSE message (always fresh), or
+        // 3. Cursor has changed (exited replay mode with fresh data)
+        // In all cases, notify subscribers and record the up-to-date.
+        this.#lastSeenCursor = undefined // Exit replay mode
+
+        if (this.#currentFetchUrl) {
+          const shapeKey = canonicalShapeKey(this.#currentFetchUrl)
+          upToDateTracker.recordUpToDate(shapeKey, this.#liveCacheBuster)
+        }
       }
 
       // Filter messages using snapshot tracker
@@ -911,6 +1068,21 @@ export class ShapeStream<T extends Row<unknown> = Row>
     headers: Record<string, string>
     resumingFromPause?: boolean
   }): Promise<void> {
+    // Store current fetch URL for shape key computation
+    this.#currentFetchUrl = opts.fetchUrl
+
+    // Check if we should enter replay mode (replaying cached responses)
+    // This happens when we're starting fresh (offset=-1 or before first up-to-date)
+    // and there's a recent up-to-date in localStorage (< 60s)
+    if (!this.#isUpToDate && !this.#replayMode) {
+      const shapeKey = canonicalShapeKey(opts.fetchUrl)
+      const lastSeenCursor = upToDateTracker.shouldEnterReplayMode(shapeKey)
+      if (lastSeenCursor) {
+        // Enter replay mode and store the last seen cursor
+        this.#lastSeenCursor = lastSeenCursor
+      }
+    }
+
     const useSse = this.options.liveSse ?? this.options.experimentalLiveSse
     if (
       this.#isUpToDate &&
@@ -1237,7 +1409,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   }
 
   /**
-   * Request a snapshot for subset of data.
+   * Request a snapshot for subset of data and inject it into the subscribed data stream.
    *
    * Only available when mode is `changes_only`.
    * Returns the insertion point & the data, but more importantly injects the data
@@ -1275,16 +1447,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
         this.#pause()
       }
 
-      const { fetchUrl, requestHeaders } = await this.#constructUrl(
-        this.options.url,
-        true,
-        opts
-      )
-
-      const { metadata, data } = await this.#fetchSnapshot(
-        fetchUrl,
-        requestHeaders
-      )
+      const { metadata, data } = await this.fetchSnapshot(opts)
 
       const dataWithEndBoundary = (data as Array<Message<T>>).concat([
         { headers: { control: `snapshot-end`, ...metadata } },
@@ -1309,8 +1472,26 @@ export class ShapeStream<T extends Row<unknown> = Row>
     }
   }
 
-  async #fetchSnapshot(url: URL, headers: Record<string, string>) {
-    const response = await this.#fetchClient(url.toString(), { headers })
+  /**
+   * Fetch a snapshot for subset of data.
+   * Returns the metadata and the data, but does not inject it into the subscribed data stream.
+   *
+   * @param opts - The options for the snapshot request.
+   * @returns The metadata and the data for the snapshot.
+   */
+  async fetchSnapshot(opts: SubsetParams): Promise<{
+    metadata: SnapshotMetadata
+    data: Array<ChangeMessage<T>>
+  }> {
+    const { fetchUrl, requestHeaders } = await this.#constructUrl(
+      this.options.url,
+      true,
+      opts
+    )
+
+    const response = await this.#fetchClient(fetchUrl.toString(), {
+      headers: requestHeaders,
+    })
 
     if (!response.ok) {
       throw new FetchError(
@@ -1318,21 +1499,52 @@ export class ShapeStream<T extends Row<unknown> = Row>
         undefined,
         undefined,
         Object.fromEntries([...response.headers.entries()]),
-        url.toString()
+        fetchUrl.toString()
       )
     }
 
-    const { metadata, data } = await response.json()
-    const batch = this.#messageParser.parse<Array<ChangeMessage<T>>>(
-      JSON.stringify(data),
-      this.#schema!
+    // Use schema from stream if available, otherwise extract from response header
+    const schema: Schema =
+      this.#schema ??
+      getSchemaFromHeaders(response.headers, {
+        required: true,
+        url: fetchUrl.toString(),
+      })
+
+    const { metadata, data: rawData } = await response.json()
+    const data = this.#messageParser.parseSnapshotData<ChangeMessage<T>>(
+      rawData,
+      schema
     )
 
     return {
       metadata,
-      data: batch,
+      data,
+    }
+  }
+}
+
+/**
+ * Extracts the schema from response headers.
+ * @param headers - The response headers
+ * @param options - Options for schema extraction
+ * @param options.required - If true, throws MissingHeadersError when header is missing. Defaults to false.
+ * @param options.url - The URL to include in the error message if required is true
+ * @returns The parsed schema, or an empty object if not required and header is missing
+ * @throws {MissingHeadersError} if required is true and the header is missing
+ */
+function getSchemaFromHeaders(
+  headers: Headers,
+  options?: { required?: boolean; url?: string }
+): Schema {
+  const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER)
+  if (!schemaHeader) {
+    if (options?.required && options?.url) {
+      throw new MissingHeadersError(options.url, [SHAPE_SCHEMA_HEADER])
     }
+    return {}
   }
+  return JSON.parse(schemaHeader)
 }
 
 /**