docs: Clarify transformer is for value transforms, not legacy

- Remove "Legacy" label from transformer documentation
- Emphasize transformer is for VALUE transformations (e.g., decryption, computed fields)
- Clarify columnMapper is for COLUMN NAME transformations
- Run eslint --fix on column-mapper.ts

Author: claude

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

@@ -55,11 +55,11 @@ export interface ColumnMapper<Extensions = never> {
  */
 export function snakeToCamel(str: string): string {
   // Preserve leading underscores
-  const leadingUnderscores = str.match(/^_+/)?.[0] ?? ''
+  const leadingUnderscores = str.match(/^_+/)?.[0] ?? ``
   const withoutLeading = str.slice(leadingUnderscores.length)
 
   // Remove trailing underscores and convert to lowercase
-  const normalized = withoutLeading.replace(/_+$/, '').toLowerCase()
+  const normalized = withoutLeading.replace(/_+$/, ``).toLowerCase()
 
   // Convert snake_case to camelCase (handling multiple underscores)
   const camelCased = normalized.replace(/_+([a-z])/g, (_, letter) =>
@@ -88,10 +88,10 @@ export function camelToSnake(str: string): string {
     str
       // Insert underscore before uppercase letters that follow lowercase letters
       // e.g., userId -> user_Id
-      .replace(/([a-z])([A-Z])/g, '$1_$2')
+      .replace(/([a-z])([A-Z])/g, `$1_$2`)
       // Insert underscore before uppercase letters that are followed by lowercase letters
       // This handles acronyms: userID -> user_ID, but parseHTMLString -> parse_HTML_String
-      .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+      .replace(/([A-Z]+)([A-Z][a-z])/g, `$1_$2`)
       .toLowerCase()
   )
 }
@@ -175,7 +175,7 @@ export function encodeWhereClause(
   whereClause: string | undefined,
   encode?: (columnName: string) => string
 ): string {
-  if (!whereClause || !encode) return whereClause ?? ''
+  if (!whereClause || !encode) return whereClause ?? ``
 
   // SQL keywords that should not be transformed (common ones)
   const sqlKeywords = new Set([
@@ -301,6 +301,8 @@ export function encodeWhereClause(
  *   - 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
@@ -309,6 +311,7 @@ export function encodeWhereClause(
  * - 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

website/docs/api/clients/typescript.md

@@ -477,37 +477,77 @@ shape.subscribe((data) => {
 })
 ```
 
-**Transformer**
-
-While the parser operates on individual fields, the transformer allows you to modify the entire record after the parser has run.
+**Column Mapping**
 
-This can be used to convert field names to camelCase or rename fields.
+For transforming column names between database format (e.g., snake_case) and application format (e.g., camelCase), use the `columnMapper` option. This provides bidirectional transformation, automatically encoding column names in WHERE clauses and decoding them in query results.
 
 ```ts
+import { ShapeStream, snakeCamelMapper } from '@electric-sql/client'
+
 type CustomRow = {
   id: number
   postTitle: string // post_title in database
   createdAt: Date // created_at in database
 }
 
-// transformer example: camelCaseKeys
-const toCamelCase = (str: string) =>
-  str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase())
-
-const camelCaseKeys: TransformFunction = (row) =>
-  Object.fromEntries(Object.entries(row).map(([k, v]) => [toCamelCase(k), v]))
-
 const stream = new ShapeStream<CustomRow>({
   url: 'http://localhost:3000/v1/shape',
   params: {
     table: 'posts',
   },
-  transformer: camelCaseKeys,
+  parser: {
+    timestamptz: (date: string) => new Date(date), // Type conversion
+  },
+  columnMapper: snakeCamelMapper(), // Column name transformation
 })
 
-const shape = new Shape(stream)
-shape.subscribe((data) => {
-  console.log(Object.keys(data)) // [id, postTitle, createdAt]
+// Now you can use camelCase in WHERE clauses too:
+await stream.requestSnapshot({
+  where: "postTitle LIKE $1", // Automatically encoded to: post_title LIKE $1
+  params: { "1": "%electric%" },
+  orderBy: "createdAt DESC", // Automatically encoded to: created_at DESC
+  limit: 10,
+})
+```
+
+For custom mappings, use `createColumnMapper`:
+
+```ts
+import { createColumnMapper } from '@electric-sql/client'
+
+const mapper = createColumnMapper({
+  post_title: 'postTitle',
+  created_at: 'createdAt',
+})
+
+const stream = new ShapeStream<CustomRow>({
+  url: 'http://localhost:3000/v1/shape',
+  params: { table: 'posts' },
+  columnMapper: mapper,
+})
+```
+
+**Transformer**
+
+While the parser operates on individual fields and columnMapper renames columns, the transformer allows you to modify the entire record for value transformations like client-side decryption of end-to-end encrypted data, computing derived fields, or other data processing.
+
+**Note:** For column name transformations (snake_case ↔ camelCase), use `columnMapper` instead. The transformer is specifically for transforming values, not column names.
+
+```ts
+type CustomRow = {
+  id: number
+  title: string
+  encryptedData: string
+}
+
+const stream = new ShapeStream<CustomRow>({
+  url: 'http://localhost:3000/v1/shape',
+  params: { table: 'posts' },
+  columnMapper: snakeCamelMapper(), // Rename columns
+  transformer: (row) => ({
+    ...row,
+    encryptedData: decrypt(row.encryptedData), // Transform values
+  }),
 })
 ```