@electric-sql/client 0.7.3 → 0.9.0

package/README.md

@@ -51,17 +51,19 @@ import { ShapeStream } from '@electric-sql/client'
 // Passes subscribers rows as they're inserted, updated, or deleted
 const stream = new ShapeStream({
   url: `${BASE_URL}/v1/shape`,
-  table: `foo`,
+  params: {
+    table: `foo`
+  }
 })
 
 // You can also add custom headers and URL parameters
 const streamWithParams = new ShapeStream({
   url: `${BASE_URL}/v1/shape`,
-  table: `foo`,
   headers: {
     'Authorization': 'Bearer token'
   },
   params: {
+    table: `foo`,
     'custom-param': 'value'
   }
 })
@@ -80,7 +82,9 @@ import { ShapeStream, Shape } from '@electric-sql/client'
 
 const stream = new ShapeStream({
   url: `${BASE_URL}/v1/shape`,
-  table: `foo`,
+  params: {
+    table: `foo`
+  }
 })
 const shape = new Shape(stream)
 
@@ -93,4 +97,81 @@ shape.subscribe(({ rows }) => {
 }
 ```
 
-See the [Docs](https://electric-sql.com) and [Examples](https://electric-sql.com/examples/basic) for more information.
+### Error Handling
+
+The ShapeStream provides two ways to handle errors:
+
+1. Using the `onError` handler:
+```typescript
+const stream = new ShapeStream({
+  url: `${BASE_URL}/v1/shape`,
+  params: {
+    table: `foo`
+  },
+  onError: (error) => {
+    // Handle all stream errors here
+    console.error('Stream error:', error)
+  }
+})
+```
+
+If no `onError` handler is provided, the ShapeStream will throw errors that occur during streaming.
+
+2. Individual subscribers can optionally handle errors specific to their subscription:
+```typescript
+stream.subscribe(
+  (messages) => {
+    // Handle messages
+  },
+  (error) => {
+    // Handle errors for this specific subscription
+    console.error('Subscription error:', error)
+  }
+)
+```
+
+Common error types include:
+- `MissingShapeUrlError`: Missing required URL parameter
+- `InvalidSignalError`: Invalid AbortSignal instance
+- `ReservedParamError`: Using reserved parameter names
+
+Runtime errors:
+- `FetchError`: HTTP errors during shape fetching
+- `FetchBackoffAbortError`: Fetch aborted using AbortSignal
+- `MissingShapeHandleError`: Missing required shape handle
+- `ParserNullValueError`: Parser encountered NULL value in a column that doesn't allow NULL values
+
+See the [typescript client docs on the website](https://electric-sql.com/docs/api/clients/typescript#error-handling) for more details on error handling.
+
+And in general, see the [docs website](https://electric-sql.com) and [examples folder](https://electric-sql.com/examples/basic) for more information.
+
+## Develop
+
+Install the pnpm workspace at the repo root:
+
+```shell
+pnpm install
+```
+
+Build the package:
+
+```shell
+cd packages/typescript-client
+pnpm build
+```
+
+## Test
+
+In one terminal, start the backend running:
+
+```shell
+cd ../sync-service
+mix deps.get
+mix stop_dev && mix compile && mix start_dev && ies -S mix
+```
+
+Then in this folder:
+
+```shell
+pnpm test
+```