fix: always throw errors & always use named Error classes

.changeset/fair-pants-pretend.md

@@ -0,0 +1,15 @@
+---
+"@electric-sql/client": patch
+---
+
+refactor: improve error handling with new error classes & stream control
+
+- Add `onError` handler to ShapeStream for centralized error handling
+- Add new error classes:
+  - MissingShapeUrlError
+  - InvalidSignalError
+  - MissingShapeHandleError
+  - ReservedParamError
+  - ParserNullValueError
+  - ShapeStreamAlreadyRunningError
+- Improve error propagation through ShapeStream lifecycle

.changeset/grumpy-cougars-cheat.md

@@ -0,0 +1,5 @@
+---
+"@electric-sql/client": minor
+---
+
+[BREAKING] Remove subscribeOnceToUpToDate method from ShapeStream. Instead, you should subscribe to the stream and check for the up-to-date control message.

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

@@ -35,7 +35,7 @@ export function getShapeStream<T extends Row<unknown>>(
   // If the stream is already cached, return it if valid
   if (streamCache.has(shapeHash)) {
     const stream = streamCache.get(shapeHash)! as ShapeStream<T>
-    if (stream.error === undefined && !stream.options.signal?.aborted) {
+    if (!stream.error && !stream.options.signal?.aborted) {
       return stream
     }
 
@@ -57,10 +57,7 @@ export function getShape<T extends Row<unknown>>(
 ): Shape<T> {
   // If the stream is already cached, return it if valid
   if (shapeCache.has(shapeStream)) {
-    if (
-      shapeStream.error === undefined &&
-      !shapeStream.options.signal?.aborted
-    ) {
+    if (!shapeStream.error && !shapeStream.options.signal?.aborted) {
       return shapeCache.get(shapeStream)! as Shape<T>
     }
 

packages/react-hooks/test/support/global-setup.ts

@@ -65,7 +65,7 @@ export default async function ({ provide }: GlobalSetupContext) {
   provide(`proxyCachePath`, proxyCachePath)
 
   return async () => {
-    await client.query(`DROP SCHEMA electric_test`)
+    await client.query(`DROP SCHEMA electric_test CASCADE`)
     await client.end()
   }
 }

packages/react-hooks/test/support/test-context.ts

@@ -37,12 +37,14 @@ export const testWithDbClient = test.extend<{
   clearShape: async ({}, use) => {
     use(async (table: string, handle?: string) => {
       const baseUrl = inject(`baseUrl`)
-      const resp = await fetch(
-        `${baseUrl}/v1/shape?table=${table}${handle ? `&handle=${handle}` : ``}`,
-        {
-          method: `DELETE`,
-        }
-      )
+      const url = new URL(`${baseUrl}/v1/shape`)
+      url.searchParams.set(`table`, table)
+      if (handle) {
+        url.searchParams.set(`handle`, handle)
+      }
+      const resp = await fetch(url.toString(), {
+        method: `DELETE`,
+      })
       if (!resp.ok) {
         console.error(
           await FetchError.fromResponse(

packages/typescript-client/README.md

@@ -93,7 +93,51 @@ 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`,
+  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