@electric-sql/client 0.7.3 → 0.9.0

package/dist/index.mjs

@@ -58,6 +58,91 @@ var __async = (__this, __arguments, generator) => {
   });
 };
 
+// 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`;
@@ -159,7 +244,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;
     }
@@ -181,61 +266,12 @@ 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`;
 var CHUNK_LAST_OFFSET_HEADER = `electric-offset`;
 var SHAPE_SCHEMA_HEADER = `electric-schema`;
 var CHUNK_UP_TO_DATE_HEADER = `electric-up-to-date`;
-var DATABASE_ID_QUERY_PARAM = `database_id`;
 var COLUMNS_QUERY_PARAM = `columns`;
 var LIVE_CACHE_BUSTER_QUERY_PARAM = `cursor`;
 var SHAPE_HANDLE_QUERY_PARAM = `handle`;
@@ -328,7 +364,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();
@@ -421,6 +457,7 @@ function getNextChunkUrl(url, res) {
   if (nextUrl.searchParams.has(LIVE_QUERY_PARAM)) return;
   nextUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, shapeHandle);
   nextUrl.searchParams.set(OFFSET_QUERY_PARAM, lastOffset);
+  nextUrl.searchParams.sort();
   return nextUrl.toString();
 }
 function chainAborter(aborter, sourceSignal) {
@@ -435,24 +472,26 @@ function chainAborter(aborter, sourceSignal) {
 
 // src/client.ts
 var RESERVED_PARAMS = /* @__PURE__ */ new Set([
-  DATABASE_ID_QUERY_PARAM,
-  COLUMNS_QUERY_PARAM,
   LIVE_CACHE_BUSTER_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   LIVE_QUERY_PARAM,
-  OFFSET_QUERY_PARAM,
-  TABLE_QUERY_PARAM,
-  WHERE_QUERY_PARAM,
-  REPLICA_PARAM
+  OFFSET_QUERY_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 _ShapeStream = class _ShapeStream {
+function toInternalParams(params) {
+  const result = {};
+  for (const [key, value] of Object.entries(params)) {
+    result[key] = Array.isArray(value) ? value.join(`,`) : value;
+  }
+  return result;
+}
+var _error, _fetchClient2, _messageParser, _subscribers, _lastOffset, _liveCacheBuster, _lastSyncedAt, _isUpToDate, _connected, _shapeHandle, _schema, _onError, _ShapeStream_instances, start_fn, publish_fn, sendErrorToSubscribers_fn, reset_fn;
+var ShapeStream = class {
   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 😎
@@ -461,19 +500,16 @@ var _ShapeStream = class _ShapeStream {
     __privateAdd(this, _isUpToDate, false);
     __privateAdd(this, _connected, false);
     __privateAdd(this, _shapeHandle);
-    __privateAdd(this, _databaseId);
     __privateAdd(this, _schema);
-    __privateAdd(this, _error);
-    __privateAdd(this, _replica);
+    __privateAdd(this, _onError);
     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, _databaseId, this.options.databaseId);
+    __privateSet(this, _shapeHandle, this.options.handle);
     __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: () => {
@@ -485,131 +521,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 () => {
@@ -619,16 +546,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);
@@ -644,24 +561,145 @@ 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();
 _isUpToDate = new WeakMap();
 _connected = new WeakMap();
 _shapeHandle = new WeakMap();
-_databaseId = new WeakMap();
 _schema = new WeakMap();
-_error = new WeakMap();
-_replica = new WeakMap();
+_onError = new WeakMap();
 _ShapeStream_instances = new WeakSet();
+start_fn = function() {
+  return __async(this, null, function* () {
+    var _a, _b;
+    try {
+      while (!((_a = this.options.signal) == null ? void 0 : _a.aborted) && !__privateGet(this, _isUpToDate) || this.options.subscribe) {
+        const { url, 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(`, `)}`
+            );
+          }
+          const params = toInternalParams(this.options.params);
+          if (params.table)
+            fetchUrl.searchParams.set(TABLE_QUERY_PARAM, params.table);
+          if (params.where)
+            fetchUrl.searchParams.set(WHERE_QUERY_PARAM, params.where);
+          if (params.columns)
+            fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, params.columns);
+          if (params.replica)
+            fetchUrl.searchParams.set(REPLICA_PARAM, params.replica);
+          const customParams = __spreadValues({}, params);
+          delete customParams.table;
+          delete customParams.where;
+          delete customParams.columns;
+          delete customParams.replica;
+          for (const [key, value] of Object.entries(customParams)) {
+            fetchUrl.searchParams.set(key, value);
+          }
+        }
+        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)
+          );
+        }
+        fetchUrl.searchParams.sort();
+        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, (_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 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(
@@ -682,55 +720,38 @@ 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);
 };
-_ShapeStream.Replica = {
+ShapeStream.Replica = {
   FULL: `full`,
   DEFAULT: `default`
 };
-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;
@@ -751,15 +772,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;
@@ -767,6 +779,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()));
   }