Fix columnMapper to support loading subsets (#3564)

When using columnMapper with ShapeStream, the columns parameter was not
being encoded from app column names to database column names. This fix
ensures that when a user specifies columns using app format (e.g.,
camelCase like `userId`), they are properly converted to the database
format (e.g., snake_case like `user_id`) before being sent to the
server.

This makes columnMapper work correctly with column subsets.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: KyleAMathews

packages/typescript-client/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)

packages/typescript-client/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).

packages/typescript-client/test/column-mapper.test.ts

@@ -5,9 +5,34 @@ import {
   createColumnMapper,
   snakeCamelMapper,
   encodeWhereClause,
+  quoteIdentifier,
 } from '../src/column-mapper'
 import type { Schema } from '../src/types'
 
+describe(`quoteIdentifier`, () => {
+  it(`should wrap identifier in double quotes`, () => {
+    expect(quoteIdentifier(`user_id`)).toBe(`"user_id"`)
+    expect(quoteIdentifier(`simple`)).toBe(`"simple"`)
+  })
+
+  it(`should escape internal double quotes by doubling`, () => {
+    expect(quoteIdentifier(`has"quote`)).toBe(`"has""quote"`)
+    expect(quoteIdentifier(`two"quotes"here`)).toBe(`"two""quotes""here"`)
+  })
+
+  it(`should handle identifiers with commas`, () => {
+    expect(quoteIdentifier(`foo,bar`)).toBe(`"foo,bar"`)
+  })
+
+  it(`should handle identifiers with spaces`, () => {
+    expect(quoteIdentifier(`has space`)).toBe(`"has space"`)
+  })
+
+  it(`should handle empty string`, () => {
+    expect(quoteIdentifier(``)).toBe(`""`)
+  })
+})
+
 describe(`snakeToCamel`, () => {
   it(`should convert snake_case to camelCase`, () => {
     expect(snakeToCamel(`user_id`)).toBe(`userId`)

packages/typescript-client/test/integration.test.ts

@@ -13,6 +13,7 @@ import {
   IssueRow,
   testWithIssuesTable as it,
   testWithMultitypeTable as mit,
+  testWithSpecialColumnsTable as scit,
 } from './support/test-context'
 import * as h from './support/test-helpers'
 
@@ -817,6 +818,48 @@ describe(`HTTP Sync`, () => {
     }
   )
 
+  scit(
+    `should handle columns with special characters (commas, quotes, spaces)`,
+    async ({ dbClient, aborter, tableSql, tableUrl }) => {
+      // Insert data with special column names
+      await dbClient.query(
+        `INSERT INTO ${tableSql} (id, "normal", "has,comma", "has""quote", "has space") VALUES ($1, $2, $3, $4, $5)`,
+        [1, `normal_value`, `comma_value`, `quote_value`, `space_value`]
+      )
+
+      // Get initial data, selecting only some columns including ones with special chars
+      const shapeData = new Map()
+      const stream = new ShapeStream({
+        url: `${BASE_URL}/v1/shape`,
+        params: {
+          table: tableUrl,
+          columns: [`id`, `normal`, `has,comma`, `has"quote`],
+        },
+        signal: aborter.signal,
+      })
+
+      await h.forEachMessage(stream, aborter, async (res, msg, nth) => {
+        if (!isChangeMessage(msg)) return
+        shapeData.set(msg.key, msg.value)
+
+        if (nth === 0) {
+          // Verify we got the correct columns, including those with special chars
+          expect(msg.value).toStrictEqual({
+            id: 1,
+            normal: `normal_value`,
+            'has,comma': `comma_value`,
+            'has"quote': `quote_value`,
+          })
+          // Verify the column with space was NOT included
+          expect(msg.value).not.toHaveProperty(`has space`)
+          res()
+        }
+      })
+
+      expect([...shapeData.values()]).toHaveLength(1)
+    }
+  )
+
   it(`should chunk a large log with reasonably sized chunks`, async ({
     insertIssues,
     waitForIssues,