Move non-protocol options like table & where to the params sub-key (#…

…2081)

Fix #2079

Electric's TypeScript client is currently tightly coupled to
PostgreSQL-specific options in its `ShapeStreamOptions` interface. As
Electric plans to support multiple data sources in the future, we need
to separate protocol-level options from source-specific options.

## Changes

1. Created a new `PostgresParams` type to define PostgreSQL-specific
parameters:
   - `table`: The root table for the shape
   - `where`: Where clauses for the shape
   - `columns`: Columns to include in the shape
   - `replica`: Whether to send full or partial row updates
2. Moved PostgreSQL-specific options from the top-level
`ShapeStreamOptions` interface to the `params` sub-key
3. Updated `ParamsRecord` type to include PostgreSQL parameters
4. Updated the `ShapeStream` class to handle parameters from the
`params` object
5. Updated documentation to reflect the changes

## Migration Example

Before:
```typescript
const stream = new ShapeStream({
  url: 'http://localhost:3000/v1/shape',
  table: 'users',
  where: 'id > 100',
  columns: ['id', 'name'],
  replica: 'full'
})
```

After:
```typescript
const stream = new ShapeStream({
  url: 'http://localhost:3000/v1/shape',
  params: {
    table: 'users',
    where: 'id > 100',
    columns: ['id', 'name'],
    replica: 'full'
  }
})
```

.changeset/tiny-socks-drive.md

@@ -0,0 +1,49 @@
+---
+"@electric-sql/client": minor
+"@electric-sql/react": minor
+---
+
+[BREAKING]: Move non-protocol options like table & where to the params sub-key
+
+## Context
+
+Electric's TypeScript client is currently tightly coupled to PostgreSQL-specific options in its `ShapeStreamOptions` interface. As Electric plans to support multiple data sources in the future, we need to separate protocol-level options from source-specific options.
+
+## Changes
+
+1. Created a new `PostgresParams` type to define PostgreSQL-specific parameters:
+   - `table`: The root table for the shape
+   - `where`: Where clauses for the shape
+   - `columns`: Columns to include in the shape
+   - `replica`: Whether to send full or partial row updates
+
+2. Moved PostgreSQL-specific options from the top-level `ShapeStreamOptions` interface to the `params` sub-key
+3. Updated `ParamsRecord` type to include PostgreSQL parameters
+4. Updated the `ShapeStream` class to handle parameters from the `params` object
+5. Updated documentation to reflect the changes
+
+## Migration Example
+
+Before:
+```typescript
+const stream = new ShapeStream({
+  url: 'http://localhost:3000/v1/shape',
+  table: 'users',
+  where: 'id > 100',
+  columns: ['id', 'name'],
+  replica: 'full'
+})
+```
+
+After:
+```typescript
+const stream = new ShapeStream({
+  url: 'http://localhost:3000/v1/shape',
+  params: {
+    table: 'users',
+    where: 'id > 100',
+    columns: ['id', 'name'],
+    replica: 'full'
+  }
+})
+```

examples/basic-example/src/Example.tsx

@@ -8,7 +8,9 @@ const baseUrl = import.meta.env.ELECTRIC_URL ?? `http://localhost:3000`
 export const Example = () => {
   const { data: items } = useShape<Item>({
     url: `${baseUrl}/v1/shape`,
-    table: `items`,
+    params: {
+      table: `items`,
+    },
   })
 
   return (

examples/linearlite/src/pages/Issue/Comments.tsx

@@ -18,10 +18,10 @@ function Comments(commentProps: CommentsProps) {
   const [newCommentBody, setNewCommentBody] = useState<string>(``)
   const allComments = useShape({
     url: `${baseUrl}/v1/shape`,
-    table: `comment`,
-    databaseId,
     params: {
       token,
+      database_id: databaseId,
+      table: `comment`,
     },
   })! as Comment[]
 

examples/linearlite/src/shapes.ts

@@ -3,8 +3,8 @@ import { baseUrl, databaseId, token } from './electric'
 
 export const issueShape: ShapeStreamOptions = {
   url: `${baseUrl}/v1/shape/`,
-  table: `issue`,
   params: {
+    table: `issue`,
     token,
     database_id: databaseId,
   },

examples/nextjs-example/app/page.tsx

@@ -5,17 +5,22 @@ import { useOptimistic } from "react"
 import { useShape, getShapeStream } from "@electric-sql/react"
 import "./Example.css"
 import { matchStream } from "./match-stream"
+import { ShapeStreamOptions } from "@electric-sql/client/*"
 
-const itemShape = () => {
+const itemShape = (): ShapeStreamOptions => {
   if (typeof window !== `undefined`) {
     return {
       url: new URL(`/shape-proxy`, window?.location.origin).href,
-      table: `items`,
+      params: {
+        table: `items`,
+      },
     }
   } else {
     return {
       url: new URL(`https://not-sure-how-this-works.com/shape-proxy`).href,
-      table: `items`,
+      params: {
+        table: `items`,
+      },
     }
   }
 }

examples/proxy-auth/app/page.tsx

@@ -22,15 +22,19 @@ const usersShape = (): ShapeStreamOptions => {
     return {
       url: new URL(`/shape-proxy?org_id=${org_id}`, window.location.origin)
         .href,
-      table: `users`,
+      params: {
+        table: `users`,
+      },
       headers: {
         Authorization: org_id || ``,
       },
     }
   } else {
     return {
       url: new URL(`https://not-sure-how-this-works.com/shape-proxy`).href,
-      table: `items`,
+      params: {
+        table: `items`,
+      },
     }
   }
 }

examples/redis-sync/src/index.ts

@@ -34,7 +34,9 @@ client.connect().then(async () => {
 
   const itemsStream = new ShapeStream({
     url: `http://localhost:3000/v1/shape`,
-    table: `items`,
+    params: {
+      table: `items`,
+    },
   })
   itemsStream.subscribe(async (messages: Message[]) => {
     // Begin a Redis transaction

examples/todo-app/src/routes/index.tsx

@@ -20,7 +20,9 @@ type ToDo = {
 export default function Index() {
   const { data: todos } = useShape<ToDo>({
     url: `http://localhost:3000/v1/shape`,
-    table: `todos`,
+    params: {
+      table: `todos`,
+    }
   })
   todos.sort((a, b) => a.created_at - b.created_at)
   console.log({ todos })

packages/react-hooks/README.md

@@ -22,7 +22,9 @@ import { useShape } from "@electric-sql/react"
 export default function MyComponent () {
   const { isLoading, data } = useShape({
     url: "http://my-api.com/shape",
-    table: `foo`,
+    params: {
+      table: `foo`
+    }
   })
 
   if (isLoading) {

packages/react-hooks/src/react-hooks.tsx

@@ -23,8 +23,27 @@ export async function preloadShape<T extends Row<unknown> = Row>(
   return shape
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function sortObjectKeys(obj: any): any {
+  if (typeof obj !== `object` || obj === null) return obj
+
+  if (Array.isArray(obj)) {
+    return obj.map(sortObjectKeys)
+  }
+
+  return (
+    Object.keys(obj)
+      .sort()
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .reduce<Record<string, any>>((sorted, key) => {
+        sorted[key] = sortObjectKeys(obj[key])
+        return sorted
+      }, {})
+  )
+}
+
 export function sortedOptionsHash<T>(options: ShapeStreamOptions<T>): string {
-  return JSON.stringify(options, Object.keys(options).sort())
+  return JSON.stringify(sortObjectKeys(options))
 }
 
 export function getShapeStream<T extends Row<unknown>>(

packages/react-hooks/test/react-hooks.test-d.ts

@@ -5,7 +5,9 @@ import { Row } from 'packages/typescript-client/dist'
 describe(`useShape`, () => {
   it(`should infer correct return type when no selector is provided`, () => {
     const shape = useShape({
-      table: ``,
+      params: {
+        table: ``,
+      },
       url: ``,
     })
 
@@ -21,7 +23,9 @@ describe(`useShape`, () => {
 
   it(`should infer correct return type when a selector is provided`, () => {
     const shape = useShape({
-      table: ``,
+      params: {
+        table: ``,
+      },
       url: ``,
       selector: (_value: UseShapeResult) => {
         return {
@@ -38,7 +42,9 @@ describe(`useShape`, () => {
 
   it(`should raise a type error if type argument does not equal inferred return type`, () => {
     const shape = useShape<Row, number>({
-      table: ``,
+      params: {
+        table: ``,
+      },
       url: ``,
       // @ts-expect-error - should have type mismatch, because doesn't match the declared `Number` type
       selector: (_value: UseShapeResult) => {