@electric-sql/client 1.0.11 → 1.0.13

package/dist/index.d.ts

@@ -118,6 +118,52 @@ type Parser<Extensions = never> = {
 };
 type TransformFunction<Extensions = never> = (message: Row<Extensions>) => Row<Extensions>;
 
+/**
+ * Type guard for checking {@link Message} is {@link ChangeMessage}.
+ *
+ * See [TS docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards)
+ * for information on how to use type guards.
+ *
+ * @param message - the message to check
+ * @returns true if the message is a {@link ChangeMessage}
+ *
+ * @example
+ * ```ts
+ * if (isChangeMessage(message)) {
+ *   const msgChng: ChangeMessage = message // Ok
+ *   const msgCtrl: ControlMessage = message // Err, type mismatch
+ * }
+ * ```
+ */
+declare function isChangeMessage<T extends Row<unknown> = Row>(message: Message<T>): message is ChangeMessage<T>;
+/**
+ * Type guard for checking {@link Message} is {@link ControlMessage}.
+ *
+ * See [TS docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards)
+ * for information on how to use type guards.
+ *
+ * @param message - the message to check
+ * @returns true if the message is a {@link ControlMessage}
+ *
+ *  * @example
+ * ```ts
+ * if (isControlMessage(message)) {
+ *   const msgChng: ChangeMessage = message // Err, type mismatch
+ *   const msgCtrl: ControlMessage = message // Ok
+ * }
+ * ```
+ */
+declare function isControlMessage<T extends Row<unknown> = Row>(message: Message<T>): message is ControlMessage;
+/**
+ * Checks if a transaction is visible in a snapshot.
+ *
+ * @param txid - the transaction id to check
+ * @param snapshot - the information about the snapshot
+ * @returns true if the transaction is visible in the snapshot
+ */
+declare function isVisibleInSnapshot(txid: number | bigint | `${bigint}`, snapshot: PostgresSnapshot | NormalizedPgSnapshot): boolean;
+type ShardSubdomainOption = `always` | `localhost` | `never` | boolean;
+
 declare class FetchError extends Error {
     url: string;
     status: number;
@@ -284,7 +330,43 @@ interface ShapeStreamOptions<T = never> {
     /**
      * Initial data loading mode
      */
-    mode?: LogMode;
+    log?: LogMode;
+    /**
+     * Enable subdomain sharding to bypass browser HTTP/1.1 connection limits.
+     * This is useful in local development and is enabled by default for localhost URLs.
+     *
+     * See https://electric-sql.com/docs/guides/troubleshooting#slow-shapes-mdash-why-are-my-shapes-slow-in-the-browser-in-local-development
+     *
+     * When sharded, each shape stream gets a unique subdomain (e.g., `a7f2c.localhost`),
+     * which bypasses the browser HTTP/1.1 connection limits. This avoids the need to serve
+     * the development server over HTTP/2 (and thus HTTPS) in development.
+     *
+     * Options:
+     * - `'localhost'` - Automatically shard `localhost` and `*.localhost` URLs (the default)
+     * - `'always'` - Shard URLs regardless of the hostname
+     * - `'never'` - Disable sharding
+     * - `true` - Alias for `'always'`
+     * - `false` - Alias for `'never'`
+     *
+     * @default 'localhost'
+     *
+     * @example
+     * { url: 'http://localhost:3000/v1/shape', shardSubdomain: 'localhost' }
+     * // → http://a1c2f.localhost:3000/v1/shape
+     *
+     * @example
+     * { url: 'https://api.example.com', shardSubdomain: 'localhost' }
+     * // → https://api.example.com
+     *
+     * @example
+     * { url: 'https://localhost:3000', shardSubdomain: 'never' }
+     * // → https://localhost:3000
+     *
+     * @example
+     * { url: 'https://api.example.com', shardSubdomain: 'always' }
+     * // → https://b2d3g.api.example.com
+     */
+    shardSubdomain?: ShardSubdomainOption;
     signal?: AbortSignal;
     fetchClient?: typeof fetch;
     backoffOptions?: BackoffOptions;
@@ -490,49 +572,4 @@ declare class Shape<T extends Row<unknown> = Row> {
     get numSubscribers(): number;
 }
 
-/**
- * Type guard for checking {@link Message} is {@link ChangeMessage}.
- *
- * See [TS docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards)
- * for information on how to use type guards.
- *
- * @param message - the message to check
- * @returns true if the message is a {@link ChangeMessage}
- *
- * @example
- * ```ts
- * if (isChangeMessage(message)) {
- *   const msgChng: ChangeMessage = message // Ok
- *   const msgCtrl: ControlMessage = message // Err, type mismatch
- * }
- * ```
- */
-declare function isChangeMessage<T extends Row<unknown> = Row>(message: Message<T>): message is ChangeMessage<T>;
-/**
- * Type guard for checking {@link Message} is {@link ControlMessage}.
- *
- * See [TS docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards)
- * for information on how to use type guards.
- *
- * @param message - the message to check
- * @returns true if the message is a {@link ControlMessage}
- *
- *  * @example
- * ```ts
- * if (isControlMessage(message)) {
- *   const msgChng: ChangeMessage = message // Err, type mismatch
- *   const msgCtrl: ControlMessage = message // Ok
- * }
- * ```
- */
-declare function isControlMessage<T extends Row<unknown> = Row>(message: Message<T>): message is ControlMessage;
-/**
- * Checks if a transaction is visible in a snapshot.
- *
- * @param txid - the transaction id to check
- * @param snapshot - the information about the snapshot
- * @returns true if the transaction is visible in the snapshot
- */
-declare function isVisibleInSnapshot(txid: number | bigint | `${bigint}`, snapshot: PostgresSnapshot | NormalizedPgSnapshot): boolean;
-
-export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, type NormalizedPgSnapshot, type NumericColumn, type Offset, type Operation, type PostgresParams, type PostgresSnapshot, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type SnapshotMetadata, type SubsetParams, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue };
+export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, type NormalizedPgSnapshot, type NumericColumn, type Offset, type Operation, type PostgresParams, type PostgresSnapshot, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type ShardSubdomainOption, type SnapshotMetadata, type SubsetParams, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue };

package/dist/index.legacy-esm.js

@@ -271,6 +271,26 @@ function isVisibleInSnapshot(txid, snapshot) {
   const xip = snapshot.xip_list.map(BigInt);
   return xid < xmin || xid < xmax && !xip.includes(xid);
 }
+function generateShardId() {
+  return Math.floor(Math.random() * 1048575).toString(16).padStart(5, `0`);
+}
+function isLocalhostUrl(url) {
+  const hostname = url.hostname.toLowerCase();
+  return hostname === `localhost` || hostname.endsWith(`.localhost`);
+}
+function applySubdomainSharding(originalUrl, option = `localhost`) {
+  if (option === `never` || option === false) {
+    return originalUrl;
+  }
+  const url = new URL(originalUrl);
+  const shouldShard = option === `always` || option === true || option === `localhost` && isLocalhostUrl(url);
+  if (!shouldShard) {
+    return originalUrl;
+  }
+  const shardId = generateShardId();
+  url.hostname = `${shardId}.${url.hostname}`;
+  return url.toString();
+}
 
 // src/constants.ts
 var LIVE_CACHE_BUSTER_HEADER = `electric-cursor`;
@@ -749,6 +769,10 @@ var ShapeStream = class {
     var _a, _b, _c, _d;
     this.options = __spreadValues({ subscribe: true }, options);
     validateOptions(this.options);
+    this.options.url = applySubdomainSharding(
+      this.options.url,
+      this.options.shardSubdomain
+    );
     __privateSet(this, _lastOffset, (_a = this.options.offset) != null ? _a : `-1`);
     __privateSet(this, _liveCacheBuster, ``);
     __privateSet(this, _shapeHandle, this.options.handle);
@@ -757,7 +781,7 @@ var ShapeStream = class {
       options.transformer
     ));
     __privateSet(this, _onError, this.options.onError);
-    __privateSet(this, _mode, (_b = this.options.mode) != null ? _b : `full`);
+    __privateSet(this, _mode, (_b = this.options.log) != null ? _b : `full`);
     const baseFetchClient = (_c = options.fetchClient) != null ? _c : (...args) => fetch(...args);
     const backOffOpts = __spreadProps(__spreadValues({}, (_d = options.backoffOptions) != null ? _d : BackoffDefaults), {
       onFailedAttempt: () => {