feat: Add transformer to ShapeStreamOption. (#3105)

stereosteve · web-flow · commit 9be77512a686 · 2025-09-08T16:08:18.000-06:00
`messageParser` will call `transformer` with the complete `message.value`. Can be used to convert object keys to camelCase. Possible solution to: #2904. This is an alternative to #3104 that would make it an option on the ShapeStreamOptions, so it can be exposed to the `useShape` hook without extra work.
diff --git a/.changeset/bright-fishes-attack.md b/.changeset/bright-fishes-attack.md
@@ -0,0 +1,6 @@
+---
+"@electric-sql/client": patch
+"@electric-sql/react": patch
+---
+
+Add `transformer` function to `ShapeStreamOptions` to support transforms like camelCase keys.
diff --git a/packages/react-hooks/src/react-hooks.tsx b/packages/react-hooks/src/react-hooks.tsx
@@ -25,6 +25,7 @@ export async function preloadShape<T extends Row<unknown> = Row>(
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function sortObjectKeys(obj: any): any {
+  if (typeof obj === `function`) return Function.prototype.toString.call(obj)
   if (typeof obj !== `object` || obj === null) return obj
 
   if (Array.isArray(obj)) {
diff --git a/packages/react-hooks/test/react-hooks.test.tsx b/packages/react-hooks/test/react-hooks.test.tsx
@@ -48,6 +48,47 @@ describe(`sortedOptionsHash`, () => {
       expect(hash1).not.toEqual(hash2)
     }
   )
+  bareIt(`should create same hash with identical transformer function`, () => {
+    const hash1 = sortedOptionsHash({
+      url: `http://whatever`,
+      params: {
+        table: `foo`,
+      },
+      offset: `-1`,
+      transformer: (r) => ({ ...r, test: 1 }),
+    })
+    const hash2 = sortedOptionsHash({
+      offset: `-1`,
+      params: {
+        table: `foo`,
+      },
+      transformer: (r) => ({ ...r, test: 1 }),
+      url: `http://whatever`,
+    })
+    expect(hash1).toEqual(hash2)
+  })
+  bareIt(
+    `should create different hash with different transformer functions`,
+    () => {
+      const hash1 = sortedOptionsHash({
+        url: `http://whatever`,
+        params: {
+          table: `foo`,
+        },
+        offset: `-1`,
+        transformer: (r) => ({ ...r, test: 1 }),
+      })
+      const hash2 = sortedOptionsHash({
+        offset: `-1`,
+        params: {
+          table: `foo`,
+        },
+        transformer: (r) => ({ ...r, test: 2 }),
+        url: `http://whatever`,
+      })
+      expect(hash1).not.toEqual(hash2)
+    }
+  )
 })
 
 describe(`useShape`, () => {
diff --git a/packages/typescript-client/src/client.ts b/packages/typescript-client/src/client.ts
@@ -6,7 +6,7 @@ import {
   MaybePromise,
   GetExtensions,
 } from './types'
-import { MessageParser, Parser } from './parser'
+import { MessageParser, Parser, TransformFunction } from './parser'
 import { getOffset, isUpToDateMessage } from './helpers'
 import {
   FetchError,
@@ -259,6 +259,7 @@ export interface ShapeStreamOptions<T = never> {
   fetchClient?: typeof fetch
   backoffOptions?: BackoffOptions
   parser?: Parser<T>
+  transformer?: TransformFunction<T>
 
   /**
    * A function for handling shapestream errors.
@@ -379,7 +380,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
     this.#lastOffset = this.options.offset ?? `-1`
     this.#liveCacheBuster = ``
     this.#shapeHandle = this.options.handle
-    this.#messageParser = new MessageParser<T>(options.parser)
+    this.#messageParser = new MessageParser<T>(
+      options.parser,
+      options.transformer
+    )
     this.#onError = this.options.onError
 
     const baseFetchClient =
diff --git a/packages/typescript-client/src/parser.ts b/packages/typescript-client/src/parser.ts
@@ -19,6 +19,10 @@ export type Parser<Extensions = never> = {
   [key: string]: ParseFunction<Extensions>
 }
 
+export type TransformFunction<Extensions = never> = (
+  message: Row<Extensions>
+) => Row<Extensions>
+
 const parseNumber = (value: string) => Number(value)
 const parseBool = (value: string) => value === `true` || value === `t`
 const parseBigInt = (value: string) => BigInt(value)
@@ -94,11 +98,16 @@ export function pgArrayParser<Extensions>(
 
 export class MessageParser<T extends Row<unknown>> {
   private parser: Parser<GetExtensions<T>>
-  constructor(parser?: Parser<GetExtensions<T>>) {
+  private transformer?: TransformFunction<GetExtensions<T>>
+  constructor(
+    parser?: Parser<GetExtensions<T>>,
+    transformer?: TransformFunction<GetExtensions<T>>
+  ) {
     // Merge the provided parser with the default parser
     // to use the provided parser whenever defined
     // and otherwise fall back to the default parser
     this.parser = { ...defaultParser, ...parser }
+    this.transformer = transformer
   }
 
   parse<Result>(messages: string, schema: Schema): Result {
@@ -118,6 +127,8 @@ export class MessageParser<T extends Row<unknown>> {
         Object.keys(row).forEach((key) => {
           row[key] = this.parseRow(key, row[key] as NullableToken, schema)
         })
+
+        if (this.transformer) value = this.transformer(value)
       }
       return value
     }) as Result
diff --git a/packages/typescript-client/test/client.test.ts b/packages/typescript-client/test/client.test.ts
@@ -12,6 +12,7 @@ import {
 import { Message, Row, ChangeMessage } from '../src/types'
 import { MissingHeadersError } from '../src/error'
 import { resolveValue } from '../src'
+import { TransformFunction } from '../src/parser'
 
 const BASE_URL = inject(`baseUrl`)
 
@@ -119,6 +120,38 @@ describe.for(fetchAndSse)(
       expect(shape.lastSynced()).toBeLessThanOrEqual(Date.now() - start)
     })
 
+    it(`should transform record with transformer function`, async ({
+      issuesTableUrl,
+      insertIssues,
+      aborter,
+    }) => {
+      const [id] = await insertIssues({ title: `test title` })
+
+      // transformer example: uppercase keys
+      const uppercaseKeys: TransformFunction = (row) =>
+        Object.fromEntries(
+          Object.entries(row).map(([k, v]) => [k.toUpperCase(), v])
+        )
+
+      const shapeStream = new ShapeStream({
+        url: `${BASE_URL}/v1/shape`,
+        params: {
+          table: issuesTableUrl,
+        },
+        signal: aborter.signal,
+        experimentalLiveSse,
+        transformer: uppercaseKeys,
+      })
+
+      const shape = new Shape(shapeStream)
+
+      const rows = await new Promise((resolve) => {
+        shape.subscribe(({ rows }) => resolve(rows))
+      })
+
+      expect(rows).toEqual([{ ID: id, TITLE: `test title`, PRIORITY: 10 }])
+    })
+
     it(`should continually sync a shape/table`, async ({
       issuesTableUrl,
       insertIssues,
diff --git a/website/docs/api/clients/typescript.md b/website/docs/api/clients/typescript.md
@@ -238,6 +238,12 @@ export interface ShapeStreamOptions<T = never> {
    */
   parser?: Parser<T>
 
+  /**
+   * A function to transform the Message value before emitting to subscribers.
+   * This can be used to camelCase keys or rename fields.
+   */
+  transformer?: TransformFunction<T>
+
   /**
    * A function for handling errors.
    * This is optional, when it is not provided any shapestream errors will be thrown.
@@ -386,6 +392,40 @@ 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.
+
+This can be used to convert field names to camelCase or rename fields.
+
+```ts
+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,
+})
+
+const shape = new Shape(stream)
+shape.subscribe((data) => {
+  console.log(Object.keys(data)) // [id, postTitle, createdAt]
+})
+```
+
 #### Replica full
 
 By default Electric sends the modified columns in an update message, not the complete row. To be specific:
