@electric-sql/client 0.7.3 → 0.8.0

package/README.md

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

package/dist/cjs/index.cjs

@@ -85,6 +85,91 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/error.ts
+var FetchError = class _FetchError extends Error {
+  constructor(status, text, json, headers, url, message) {
+    super(
+      message || `HTTP Error ${status} at ${url}: ${text != null ? text : JSON.stringify(json)}`
+    );
+    this.url = url;
+    this.name = `FetchError`;
+    this.status = status;
+    this.text = text;
+    this.json = json;
+    this.headers = headers;
+  }
+  static fromResponse(response, url) {
+    return __async(this, null, function* () {
+      const status = response.status;
+      const headers = Object.fromEntries([...response.headers.entries()]);
+      let text = void 0;
+      let json = void 0;
+      const contentType = response.headers.get(`content-type`);
+      if (contentType && contentType.includes(`application/json`)) {
+        json = yield response.json();
+      } else {
+        text = yield response.text();
+      }
+      return new _FetchError(status, text, json, headers, url);
+    });
+  }
+};
+var FetchBackoffAbortError = class extends Error {
+  constructor() {
+    super(`Fetch with backoff aborted`);
+    this.name = `FetchBackoffAbortError`;
+  }
+};
+var MissingShapeUrlError = class extends Error {
+  constructor() {
+    super(`Invalid shape options: missing required url parameter`);
+    this.name = `MissingShapeUrlError`;
+  }
+};
+var InvalidSignalError = class extends Error {
+  constructor() {
+    super(`Invalid signal option. It must be an instance of AbortSignal.`);
+    this.name = `InvalidSignalError`;
+  }
+};
+var MissingShapeHandleError = class extends Error {
+  constructor() {
+    super(
+      `shapeHandle is required if this isn't an initial fetch (i.e. offset > -1)`
+    );
+    this.name = `MissingShapeHandleError`;
+  }
+};
+var ReservedParamError = class extends Error {
+  constructor(reservedParams) {
+    super(
+      `Cannot use reserved Electric parameter names in custom params: ${reservedParams.join(`, `)}`
+    );
+    this.name = `ReservedParamError`;
+  }
+};
+var ParserNullValueError = class extends Error {
+  constructor(columnName) {
+    super(`Column "${columnName != null ? columnName : `unknown`}" does not allow NULL values`);
+    this.name = `ParserNullValueError`;
+  }
+};
+var MissingHeadersError = class extends Error {
+  constructor(url, missingHeaders) {
+    let msg = `The response for the shape request to ${url} didn't include the following required headers:
+`;
+    missingHeaders.forEach((h) => {
+      msg += `- ${h}
+`;
+    });
+    msg += `
+This is often due to a proxy not setting CORS correctly so that all Electric headers can be read by the client.`;
+    msg += `
+For more information visit the troubleshooting guide: /docs/guides/troubleshooting/missing-headers`;
+    super(msg);
+  }
+};
+
 // src/parser.ts
 var parseNumber = (value) => Number(value);
 var parseBool = (value) => value === `true` || value === `t`;
@@ -186,7 +271,7 @@ function makeNullableParser(parser, columnInfo, columnName) {
   return (value) => {
     if (isPgNull(value)) {
       if (!isNullable) {
-        throw new Error(`Column ${columnName != null ? columnName : `unknown`} is not nullable`);
+        throw new ParserNullValueError(columnName != null ? columnName : `unknown`);
       }
       return null;
     }
@@ -208,54 +293,6 @@ function isUpToDateMessage(message) {
   return isControlMessage(message) && message.headers.control === `up-to-date`;
 }
 
-// src/error.ts
-var FetchError = class _FetchError extends Error {
-  constructor(status, text, json, headers, url, message) {
-    super(
-      message || `HTTP Error ${status} at ${url}: ${text != null ? text : JSON.stringify(json)}`
-    );
-    this.url = url;
-    this.name = `FetchError`;
-    this.status = status;
-    this.text = text;
-    this.json = json;
-    this.headers = headers;
-  }
-  static fromResponse(response, url) {
-    return __async(this, null, function* () {
-      const status = response.status;
-      const headers = Object.fromEntries([...response.headers.entries()]);
-      let text = void 0;
-      let json = void 0;
-      const contentType = response.headers.get(`content-type`);
-      if (contentType && contentType.includes(`application/json`)) {
-        json = yield response.json();
-      } else {
-        text = yield response.text();
-      }
-      return new _FetchError(status, text, json, headers, url);
-    });
-  }
-};
-var FetchBackoffAbortError = class extends Error {
-  constructor() {
-    super(`Fetch with backoff aborted`);
-  }
-};
-var MissingHeadersError = class extends Error {
-  constructor(url, missingHeaders) {
-    let msg = `The response for the shape request to ${url} didn't include the following required headers:
-`;
-    missingHeaders.forEach((h) => {
-      msg += `- ${h}
-`;
-    });
-    msg += `
-This is often due to a proxy not setting CORS correctly so that all Electric headers can be read by the client.`;
-    super(msg);
-  }
-};
-
 // src/constants.ts
 var LIVE_CACHE_BUSTER_HEADER = `electric-cursor`;
 var SHAPE_HANDLE_HEADER = `electric-handle`;
@@ -355,7 +392,7 @@ function createFetchWithResponseHeadersCheck(fetchClient) {
     if (response.ok) {
       const headers = response.headers;
       const missingHeaders = [];
-      const addMissingHeaders = (requiredHeaders) => requiredHeaders.filter((h) => !headers.has(h));
+      const addMissingHeaders = (requiredHeaders) => missingHeaders.push(...requiredHeaders.filter((h) => !headers.has(h)));
       addMissingHeaders(requiredElectricResponseHeaders);
       const input = args[0];
       const urlString = input.toString();
@@ -472,14 +509,14 @@ var RESERVED_PARAMS = /* @__PURE__ */ new Set([
   WHERE_QUERY_PARAM,
   REPLICA_PARAM
 ]);
-var _fetchClient2, _messageParser, _subscribers, _upToDateSubscribers, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _connected, _shapeHandle, _databaseId, _schema, _error, _replica, _ShapeStream_instances, publish_fn, sendErrorToSubscribers_fn, notifyUpToDateSubscribers_fn, sendErrorToUpToDateSubscribers_fn, reset_fn;
+var _error, _fetchClient2, _messageParser, _subscribers, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _connected, _shapeHandle, _databaseId, _schema, _onError, _replica, _ShapeStream_instances, start_fn, publish_fn, sendErrorToSubscribers_fn, reset_fn;
 var _ShapeStream = class _ShapeStream {
   constructor(options) {
     __privateAdd(this, _ShapeStream_instances);
+    __privateAdd(this, _error, null);
     __privateAdd(this, _fetchClient2);
     __privateAdd(this, _messageParser);
     __privateAdd(this, _subscribers, /* @__PURE__ */ new Map());
-    __privateAdd(this, _upToDateSubscribers, /* @__PURE__ */ new Map());
     __privateAdd(this, _lastOffset);
     __privateAdd(this, _liveCacheBuster);
     // Seconds since our Electric Epoch 😎
@@ -490,17 +527,18 @@ var _ShapeStream = class _ShapeStream {
     __privateAdd(this, _shapeHandle);
     __privateAdd(this, _databaseId);
     __privateAdd(this, _schema);
-    __privateAdd(this, _error);
+    __privateAdd(this, _onError);
     __privateAdd(this, _replica);
     var _a, _b, _c;
-    validateOptions(options);
     this.options = __spreadValues({ subscribe: true }, options);
+    validateOptions(this.options);
     __privateSet(this, _lastOffset, (_a = this.options.offset) != null ? _a : `-1`);
     __privateSet(this, _liveCacheBuster, ``);
-    __privateSet(this, _shapeHandle, this.options.shapeHandle);
+    __privateSet(this, _shapeHandle, this.options.handle);
     __privateSet(this, _databaseId, this.options.databaseId);
     __privateSet(this, _messageParser, new MessageParser(options.parser));
     __privateSet(this, _replica, this.options.replica);
+    __privateSet(this, _onError, this.options.onError);
     const baseFetchClient = (_b = options.fetchClient) != null ? _b : (...args) => fetch(...args);
     const fetchWithBackoffClient = createFetchWithBackoff(baseFetchClient, __spreadProps(__spreadValues({}, (_c = options.backoffOptions) != null ? _c : BackoffDefaults), {
       onFailedAttempt: () => {
@@ -512,131 +550,22 @@ var _ShapeStream = class _ShapeStream {
     __privateSet(this, _fetchClient2, createFetchWithResponseHeadersCheck(
       createFetchWithChunkBuffer(fetchWithBackoffClient)
     ));
-    this.start();
+    __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
   }
   get shapeHandle() {
     return __privateGet(this, _shapeHandle);
   }
+  get error() {
+    return __privateGet(this, _error);
+  }
   get isUpToDate() {
     return __privateGet(this, _isUpToDate);
   }
   get lastOffset() {
     return __privateGet(this, _lastOffset);
   }
-  get error() {
-    return __privateGet(this, _error);
-  }
-  start() {
-    return __async(this, null, function* () {
-      var _a, _b;
-      __privateSet(this, _isUpToDate, false);
-      const { url, table, where, columns, signal } = this.options;
-      try {
-        while (!(signal == null ? void 0 : signal.aborted) && !__privateGet(this, _isUpToDate) || this.options.subscribe) {
-          const fetchUrl = new URL(url);
-          if (this.options.params) {
-            const reservedParams = Object.keys(this.options.params).filter(
-              (key) => RESERVED_PARAMS.has(key)
-            );
-            if (reservedParams.length > 0) {
-              throw new Error(
-                `Cannot use reserved Electric parameter names in custom params: ${reservedParams.join(`, `)}`
-              );
-            }
-            for (const [key, value] of Object.entries(this.options.params)) {
-              fetchUrl.searchParams.set(key, value);
-            }
-          }
-          if (table) fetchUrl.searchParams.set(TABLE_QUERY_PARAM, table);
-          if (where) fetchUrl.searchParams.set(WHERE_QUERY_PARAM, where);
-          if (columns && columns.length > 0)
-            fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, columns.join(`,`));
-          fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, __privateGet(this, _lastOffset));
-          if (__privateGet(this, _isUpToDate)) {
-            fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`);
-            fetchUrl.searchParams.set(
-              LIVE_CACHE_BUSTER_QUERY_PARAM,
-              __privateGet(this, _liveCacheBuster)
-            );
-          }
-          if (__privateGet(this, _shapeHandle)) {
-            fetchUrl.searchParams.set(
-              SHAPE_HANDLE_QUERY_PARAM,
-              __privateGet(this, _shapeHandle)
-            );
-          }
-          if (__privateGet(this, _databaseId)) {
-            fetchUrl.searchParams.set(DATABASE_ID_QUERY_PARAM, __privateGet(this, _databaseId));
-          }
-          if (((_a = __privateGet(this, _replica)) != null ? _a : _ShapeStream.Replica.DEFAULT) != _ShapeStream.Replica.DEFAULT) {
-            fetchUrl.searchParams.set(REPLICA_PARAM, __privateGet(this, _replica));
-          }
-          let response;
-          try {
-            response = yield __privateGet(this, _fetchClient2).call(this, fetchUrl.toString(), {
-              signal,
-              headers: this.options.headers
-            });
-            __privateSet(this, _connected, true);
-          } catch (e) {
-            if (e instanceof FetchBackoffAbortError) break;
-            if (e instanceof MissingHeadersError) throw e;
-            if (!(e instanceof FetchError)) throw e;
-            if (e.status == 409) {
-              const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER];
-              __privateMethod(this, _ShapeStream_instances, reset_fn).call(this, newShapeHandle);
-              yield __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, e.json);
-              continue;
-            } else if (e.status >= 400 && e.status < 500) {
-              __privateMethod(this, _ShapeStream_instances, sendErrorToUpToDateSubscribers_fn).call(this, e);
-              __privateMethod(this, _ShapeStream_instances, sendErrorToSubscribers_fn).call(this, e);
-              throw e;
-            }
-          }
-          const { headers, status } = response;
-          const shapeHandle = headers.get(SHAPE_HANDLE_HEADER);
-          if (shapeHandle) {
-            __privateSet(this, _shapeHandle, shapeHandle);
-          }
-          const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER);
-          if (lastOffset) {
-            __privateSet(this, _lastOffset, lastOffset);
-          }
-          const liveCacheBuster = headers.get(LIVE_CACHE_BUSTER_HEADER);
-          if (liveCacheBuster) {
-            __privateSet(this, _liveCacheBuster, liveCacheBuster);
-          }
-          const getSchema = () => {
-            const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER);
-            return schemaHeader ? JSON.parse(schemaHeader) : {};
-          };
-          __privateSet(this, _schema, (_b = __privateGet(this, _schema)) != null ? _b : getSchema());
-          const messages = status === 204 ? `[]` : yield response.text();
-          if (status === 204) {
-            __privateSet(this, _lastSyncedAt, Date.now());
-          }
-          const batch = __privateGet(this, _messageParser).parse(messages, __privateGet(this, _schema));
-          if (batch.length > 0) {
-            const prevUpToDate = __privateGet(this, _isUpToDate);
-            const lastMessage = batch[batch.length - 1];
-            if (isUpToDateMessage(lastMessage)) {
-              __privateSet(this, _lastSyncedAt, Date.now());
-              __privateSet(this, _isUpToDate, true);
-            }
-            yield __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, batch);
-            if (!prevUpToDate && __privateGet(this, _isUpToDate)) {
-              __privateMethod(this, _ShapeStream_instances, notifyUpToDateSubscribers_fn).call(this);
-            }
-          }
-        }
-      } catch (err) {
-        __privateSet(this, _error, err);
-      } finally {
-        __privateSet(this, _connected, false);
-      }
-    });
-  }
-  subscribe(callback, onError) {
+  subscribe(callback, onError = () => {
+  }) {
     const subscriptionId = Math.random();
     __privateGet(this, _subscribers).set(subscriptionId, [callback, onError]);
     return () => {
@@ -646,16 +575,6 @@ var _ShapeStream = class _ShapeStream {
   unsubscribeAll() {
     __privateGet(this, _subscribers).clear();
   }
-  subscribeOnceToUpToDate(callback, error) {
-    const subscriptionId = Math.random();
-    __privateGet(this, _upToDateSubscribers).set(subscriptionId, [callback, error]);
-    return () => {
-      __privateGet(this, _upToDateSubscribers).delete(subscriptionId);
-    };
-  }
-  unsubscribeAllUpToDateSubscribers() {
-    __privateGet(this, _upToDateSubscribers).clear();
-  }
   /** Unix time at which we last synced. Undefined when `isLoading` is true. */
   lastSyncedAt() {
     return __privateGet(this, _lastSyncedAt);
@@ -671,13 +590,13 @@ var _ShapeStream = class _ShapeStream {
   }
   /** True during initial fetch. False afterwise.  */
   isLoading() {
-    return !this.isUpToDate;
+    return !__privateGet(this, _isUpToDate);
   }
 };
+_error = new WeakMap();
 _fetchClient2 = new WeakMap();
 _messageParser = new WeakMap();
 _subscribers = new WeakMap();
-_upToDateSubscribers = new WeakMap();
 _lastOffset = new WeakMap();
 _liveCacheBuster = new WeakMap();
 _lastSyncedAt = new WeakMap();
@@ -686,9 +605,127 @@ _connected = new WeakMap();
 _shapeHandle = new WeakMap();
 _databaseId = new WeakMap();
 _schema = new WeakMap();
-_error = new WeakMap();
+_onError = new WeakMap();
 _replica = new WeakMap();
 _ShapeStream_instances = new WeakSet();
+start_fn = function() {
+  return __async(this, null, function* () {
+    var _a, _b, _c;
+    try {
+      while (!((_a = this.options.signal) == null ? void 0 : _a.aborted) && !__privateGet(this, _isUpToDate) || this.options.subscribe) {
+        const { url, table, where, columns, signal } = this.options;
+        const fetchUrl = new URL(url);
+        if (this.options.params) {
+          const reservedParams = Object.keys(this.options.params).filter(
+            (key) => RESERVED_PARAMS.has(key)
+          );
+          if (reservedParams.length > 0) {
+            throw new Error(
+              `Cannot use reserved Electric parameter names in custom params: ${reservedParams.join(`, `)}`
+            );
+          }
+          for (const [key, value] of Object.entries(this.options.params)) {
+            fetchUrl.searchParams.set(key, value);
+          }
+        }
+        if (table) fetchUrl.searchParams.set(TABLE_QUERY_PARAM, table);
+        if (where) fetchUrl.searchParams.set(WHERE_QUERY_PARAM, where);
+        if (columns && columns.length > 0)
+          fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, columns.join(`,`));
+        fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, __privateGet(this, _lastOffset));
+        if (__privateGet(this, _isUpToDate)) {
+          fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`);
+          fetchUrl.searchParams.set(
+            LIVE_CACHE_BUSTER_QUERY_PARAM,
+            __privateGet(this, _liveCacheBuster)
+          );
+        }
+        if (__privateGet(this, _shapeHandle)) {
+          fetchUrl.searchParams.set(
+            SHAPE_HANDLE_QUERY_PARAM,
+            __privateGet(this, _shapeHandle)
+          );
+        }
+        if (__privateGet(this, _databaseId)) {
+          fetchUrl.searchParams.set(DATABASE_ID_QUERY_PARAM, __privateGet(this, _databaseId));
+        }
+        if (((_b = __privateGet(this, _replica)) != null ? _b : _ShapeStream.Replica.DEFAULT) != _ShapeStream.Replica.DEFAULT) {
+          fetchUrl.searchParams.set(REPLICA_PARAM, __privateGet(this, _replica));
+        }
+        let response;
+        try {
+          response = yield __privateGet(this, _fetchClient2).call(this, fetchUrl.toString(), {
+            signal,
+            headers: this.options.headers
+          });
+          __privateSet(this, _connected, true);
+        } catch (e) {
+          if (e instanceof FetchBackoffAbortError) break;
+          if (!(e instanceof FetchError)) throw e;
+          if (e.status == 409) {
+            const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER];
+            __privateMethod(this, _ShapeStream_instances, reset_fn).call(this, newShapeHandle);
+            yield __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, e.json);
+            continue;
+          } else if (e.status >= 400 && e.status < 500) {
+            __privateMethod(this, _ShapeStream_instances, sendErrorToSubscribers_fn).call(this, e);
+            throw e;
+          }
+        }
+        const { headers, status } = response;
+        const shapeHandle = headers.get(SHAPE_HANDLE_HEADER);
+        if (shapeHandle) {
+          __privateSet(this, _shapeHandle, shapeHandle);
+        }
+        const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER);
+        if (lastOffset) {
+          __privateSet(this, _lastOffset, lastOffset);
+        }
+        const liveCacheBuster = headers.get(LIVE_CACHE_BUSTER_HEADER);
+        if (liveCacheBuster) {
+          __privateSet(this, _liveCacheBuster, liveCacheBuster);
+        }
+        const getSchema = () => {
+          const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER);
+          return schemaHeader ? JSON.parse(schemaHeader) : {};
+        };
+        __privateSet(this, _schema, (_c = __privateGet(this, _schema)) != null ? _c : getSchema());
+        const messages = status === 204 ? `[]` : yield response.text();
+        if (status === 204) {
+          __privateSet(this, _lastSyncedAt, Date.now());
+        }
+        const batch = __privateGet(this, _messageParser).parse(messages, __privateGet(this, _schema));
+        if (batch.length > 0) {
+          const lastMessage = batch[batch.length - 1];
+          if (isUpToDateMessage(lastMessage)) {
+            __privateSet(this, _lastSyncedAt, Date.now());
+            __privateSet(this, _isUpToDate, true);
+          }
+          yield __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, batch);
+        }
+      }
+    } catch (err) {
+      __privateSet(this, _error, err);
+      if (__privateGet(this, _onError)) {
+        const retryOpts = yield __privateGet(this, _onError).call(this, err);
+        if (typeof retryOpts === `object`) {
+          __privateMethod(this, _ShapeStream_instances, reset_fn).call(this);
+          if (`params` in retryOpts) {
+            this.options.params = retryOpts.params;
+          }
+          if (`headers` in retryOpts) {
+            this.options.headers = retryOpts.headers;
+          }
+          __privateMethod(this, _ShapeStream_instances, start_fn).call(this);
+        }
+        return;
+      }
+      throw err;
+    } finally {
+      __privateSet(this, _connected, false);
+    }
+  });
+};
 publish_fn = function(messages) {
   return __async(this, null, function* () {
     yield Promise.all(
@@ -709,24 +746,14 @@ sendErrorToSubscribers_fn = function(error) {
     errorFn == null ? void 0 : errorFn(error);
   });
 };
-notifyUpToDateSubscribers_fn = function() {
-  __privateGet(this, _upToDateSubscribers).forEach(([callback]) => {
-    callback();
-  });
-};
-sendErrorToUpToDateSubscribers_fn = function(error) {
-  __privateGet(this, _upToDateSubscribers).forEach(
-    ([_, errorCallback]) => errorCallback(error)
-  );
-};
 /**
  * Resets the state of the stream, optionally with a provided
  * shape handle
  */
-reset_fn = function(shapeHandle) {
+reset_fn = function(handle) {
   __privateSet(this, _lastOffset, `-1`);
   __privateSet(this, _liveCacheBuster, ``);
-  __privateSet(this, _shapeHandle, shapeHandle);
+  __privateSet(this, _shapeHandle, handle);
   __privateSet(this, _isUpToDate, false);
   __privateSet(this, _connected, false);
   __privateSet(this, _schema, void 0);
@@ -738,26 +765,20 @@ _ShapeStream.Replica = {
 var ShapeStream = _ShapeStream;
 function validateOptions(options) {
   if (!options.url) {
-    throw new Error(`Invalid shape options. It must provide the url`);
+    throw new MissingShapeUrlError();
   }
   if (options.signal && !(options.signal instanceof AbortSignal)) {
-    throw new Error(
-      `Invalid signal option. It must be an instance of AbortSignal.`
-    );
+    throw new InvalidSignalError();
   }
-  if (options.offset !== void 0 && options.offset !== `-1` && !options.shapeHandle) {
-    throw new Error(
-      `shapeHandle is required if this isn't an initial fetch (i.e. offset > -1)`
-    );
+  if (options.offset !== void 0 && options.offset !== `-1` && !options.handle) {
+    throw new MissingShapeHandleError();
   }
   if (options.params) {
     const reservedParams = Object.keys(options.params).filter(
       (key) => RESERVED_PARAMS.has(key)
     );
     if (reservedParams.length > 0) {
-      throw new Error(
-        `Cannot use reserved Electric parameter names in custom params: ${reservedParams.join(`, `)}`
-      );
+      throw new ReservedParamError(reservedParams);
     }
   }
   return;
@@ -778,15 +799,6 @@ var Shape = class {
       __privateMethod(this, _Shape_instances, process_fn).bind(this),
       __privateMethod(this, _Shape_instances, handleError_fn).bind(this)
     );
-    const unsubscribe = __privateGet(this, _stream).subscribeOnceToUpToDate(
-      () => {
-        unsubscribe();
-      },
-      (e) => {
-        __privateMethod(this, _Shape_instances, handleError_fn).call(this, e);
-        throw e;
-      }
-    );
   }
   get isUpToDate() {
     return __privateGet(this, _stream).isUpToDate;
@@ -794,6 +806,9 @@ var Shape = class {
   get lastOffset() {
     return __privateGet(this, _stream).lastOffset;
   }
+  get handle() {
+    return __privateGet(this, _stream).shapeHandle;
+  }
   get rows() {
     return this.value.then((v) => Array.from(v.values()));
   }