@electric-sql/client 0.7.3 → 0.8.0

package/dist/index.legacy-esm.js

@@ -38,6 +38,89 @@ var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
+// 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 async fromResponse(response, url) {
+    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 = await response.json();
+    } else {
+      text = await 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`;
@@ -139,7 +222,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;
     }
@@ -161,52 +244,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 async fromResponse(response, url) {
-    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 = await response.json();
-    } else {
-      text = await 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`;
@@ -306,7 +343,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();
@@ -423,14 +460,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 😎
@@ -441,17 +478,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: () => {
@@ -463,129 +501,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);
-  }
-  async start() {
-    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 = await __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);
-            await __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 ? `[]` : await 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);
-          }
-          await __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 () => {
@@ -595,16 +526,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);
@@ -620,13 +541,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();
@@ -635,9 +556,125 @@ _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 = async 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 = await __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);
+          await __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 ? `[]` : await 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);
+        }
+        await __privateMethod(this, _ShapeStream_instances, publish_fn).call(this, batch);
+      }
+    }
+  } catch (err) {
+    __privateSet(this, _error, err);
+    if (__privateGet(this, _onError)) {
+      const retryOpts = await __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 = async function(messages) {
   await Promise.all(
     Array.from(__privateGet(this, _subscribers).values()).map(async ([callback, __]) => {
@@ -656,24 +693,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);
@@ -685,26 +712,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;
@@ -725,15 +746,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;
@@ -741,6 +753,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()));
   }