@electric-sql/client 1.2.0 → 1.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@electric-sql/client",
   "description": "Postgres everywhere - your data, in sync, wherever you need it.",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"
@@ -14,7 +14,7 @@
     "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^7.14.1",
     "@typescript-eslint/parser": "^7.14.1",
-    "@vitest/coverage-istanbul": "2.1.4",
+    "@vitest/coverage-istanbul": "4.0.15",
     "cache-control-parser": "^2.0.6",
     "concurrently": "^8.2.2",
     "eslint": "^8.57.0",
@@ -28,7 +28,7 @@
     "tsup": "^8.0.1",
     "typescript": "^5.5.2",
     "uuid": "^10.0.0",
-    "vitest": "^3.0.0",
+    "vitest": "^4.0.15",
     "vitest-localstorage-mock": "^0.1.2"
   },
   "type": "module",

package/src/client.ts

@@ -9,7 +9,11 @@ import {
   SnapshotMetadata,
 } from './types'
 import { MessageParser, Parser, TransformFunction } from './parser'
-import { ColumnMapper, encodeWhereClause } from './column-mapper'
+import {
+  ColumnMapper,
+  encodeWhereClause,
+  quoteIdentifier,
+} from './column-mapper'
 import { getOffset, isUpToDateMessage, isChangeMessage } from './helpers'
 import {
   FetchError,
@@ -855,8 +859,27 @@ export class ShapeStream<T extends Row<unknown> = Row>
         )
         setQueryParam(fetchUrl, WHERE_QUERY_PARAM, encodedWhere)
       }
-      if (params.columns)
-        setQueryParam(fetchUrl, COLUMNS_QUERY_PARAM, params.columns)
+      if (params.columns) {
+        // Get original columns array from options (before toInternalParams converted to string)
+        const originalColumns = await resolveValue(this.options.params?.columns)
+        if (Array.isArray(originalColumns)) {
+          // Apply columnMapper encoding if present
+          let encodedColumns = originalColumns.map(String)
+          if (this.options.columnMapper) {
+            encodedColumns = encodedColumns.map(
+              this.options.columnMapper.encode
+            )
+          }
+          // Quote each column name to handle special characters (commas, etc.)
+          const serializedColumns = encodedColumns
+            .map(quoteIdentifier)
+            .join(`,`)
+          setQueryParam(fetchUrl, COLUMNS_QUERY_PARAM, serializedColumns)
+        } else {
+          // Fallback: columns was already a string
+          setQueryParam(fetchUrl, COLUMNS_QUERY_PARAM, params.columns)
+        }
+      }
       if (params.replica) setQueryParam(fetchUrl, REPLICA_PARAM, params.replica)
       if (params.params)
         setQueryParam(fetchUrl, WHERE_PARAMS_PARAM, params.params)
@@ -1132,10 +1155,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
     // Track when the SSE connection starts
     this.#lastSseConnectionStartTime = Date.now()
 
+    // Add Accept header for SSE requests
+    const sseHeaders = {
+      ...headers,
+      Accept: `text/event-stream`,
+    }
+
     try {
       let buffer: Array<Message<T>> = []
       await fetchEventSource(fetchUrl.toString(), {
-        headers,
+        headers: sseHeaders,
         fetch,
         onopen: async (response: Response) => {
           this.#connected = true

package/src/column-mapper.ts

@@ -3,6 +3,31 @@ import { Schema } from './types'
 type DbColumnName = string
 type AppColumnName = string
 
+/**
+ * Quote a PostgreSQL identifier for safe use in query parameters.
+ *
+ * Wraps the identifier in double quotes and escapes any internal
+ * double quotes by doubling them. This ensures identifiers with
+ * special characters (commas, spaces, etc.) are handled correctly.
+ *
+ * @param identifier - The identifier to quote
+ * @returns The quoted identifier
+ *
+ * @example
+ * ```typescript
+ * quoteIdentifier('user_id')        // '"user_id"'
+ * quoteIdentifier('foo,bar')        // '"foo,bar"'
+ * quoteIdentifier('has"quote')      // '"has""quote"'
+ * ```
+ *
+ * @internal
+ */
+export function quoteIdentifier(identifier: string): string {
+  // Escape internal double quotes by doubling them
+  const escaped = identifier.replace(/"/g, `""`)
+  return `"${escaped}"`
+}
+
 /**
  * A bidirectional column mapper that handles transforming column **names**
  * between database format (e.g., snake_case) and application format (e.g., camelCase).

package/src/types.ts

@@ -43,10 +43,30 @@ export type NormalizedPgSnapshot = {
 }
 
 interface Header {
-  [key: Exclude<string, `operation` | `control`>]: Value
+  [key: Exclude<string, `operation` | `control` | `event`>]: Value
 }
 
 export type Operation = `insert` | `update` | `delete`
+/**
+ * A tag is a string identifying a reason for this row to be part of the shape.
+ *
+ * Tags can be composite, but they are always sent as a single string. Compound tags
+ * are separated by `|`. It's up to the client to split the tag into its components
+ * in order to react to move-outs correctly. Tag parts are guaranteed to not contain an
+ * unescaped `|` character (escaped as `\\|`) or be a literal `*`.
+ *
+ * Composite tag width is guaranteed to be fixed for a given shape.
+ */
+export type MoveTag = string
+
+/**
+ * A move-out pattern is a position and a value. The position is the index of the column
+ * that is being moved out. The value is the value of the column that is being moved out.
+ *
+ * Tag width and value order is fixed for a given shape, so the client can determine
+ * which tags match this pattern.
+ */
+export type MoveOutPattern = { pos: number; value: string }
 
 export type ControlMessage = {
   headers:
@@ -57,16 +77,27 @@ export type ControlMessage = {
     | (Header & { control: `snapshot-end` } & PostgresSnapshot)
 }
 
+export type EventMessage = {
+  headers: Header & { event: `move-out`; patterns: MoveOutPattern[] }
+}
+
 export type ChangeMessage<T extends Row<unknown> = Row> = {
   key: string
   value: T
   old_value?: Partial<T> // Only provided for updates if `replica` is `full`
-  headers: Header & { operation: Operation; txids?: number[] }
+  headers: Header & {
+    operation: Operation
+    txids?: number[]
+    /** Tags will always be present for changes if the shape has a subquery in its where clause, and are omitted otherwise.*/
+    tags?: MoveTag[]
+    removed_tags?: MoveTag[]
+  }
 }
 
 // Define the type for a record
 export type Message<T extends Row<unknown> = Row> =
   | ControlMessage
+  | EventMessage
   | ChangeMessage<T>
 
 /**