@electric-sql/client 1.0.13 → 1.1.0

package/src/client.ts

@@ -9,13 +9,7 @@ import {
   SnapshotMetadata,
 } from './types'
 import { MessageParser, Parser, TransformFunction } from './parser'
-import {
-  getOffset,
-  isUpToDateMessage,
-  isChangeMessage,
-  applySubdomainSharding,
-  ShardSubdomainOption,
-} from './helpers'
+import { getOffset, isUpToDateMessage, isChangeMessage } from './helpers'
 import {
   FetchError,
   FetchBackoffAbortError,
@@ -50,6 +44,7 @@ import {
   FORCE_DISCONNECT_AND_REFRESH,
   PAUSE_STREAM,
   EXPERIMENTAL_LIVE_SSE_QUERY_PARAM,
+  LIVE_SSE_QUERY_PARAM,
   ELECTRIC_PROTOCOL_QUERY_PARAMS,
   LOG_MODE_QUERY_PARAM,
   SUBSET_PARAM_WHERE,
@@ -279,51 +274,19 @@ export interface ShapeStreamOptions<T = never> {
   subscribe?: boolean
 
   /**
-   * Experimental support for Server-Sent Events (SSE) for live updates.
+   * @deprecated No longer experimental, use {@link liveSse} instead.
    */
   experimentalLiveSse?: boolean
 
   /**
-   * Initial data loading mode
+   * Use Server-Sent Events (SSE) for live updates.
    */
-  log?: LogMode
+  liveSse?: boolean
 
   /**
-   * 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
+   * Initial data loading mode
    */
-  shardSubdomain?: ShardSubdomainOption
+  log?: LogMode
 
   signal?: AbortSignal
   fetchClient?: typeof fetch
@@ -415,7 +378,7 @@ function canonicalShapeKey(url: URL): string {
  * ```
  * const stream = new ShapeStream({
  *   url: `http://localhost:3000/v1/shape`,
- *   experimentalLiveSse: true
+ *   liveSse: true
  * })
  * ```
  *
@@ -482,10 +445,6 @@ export class ShapeStream<T extends Row<unknown> = Row>
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
     validateOptions(this.options)
-    this.options.url = applySubdomainSharding(
-      this.options.url,
-      this.options.shardSubdomain
-    )
     this.#lastOffset = this.options.offset ?? `-1`
     this.#liveCacheBuster = ``
     this.#shapeHandle = this.options.handle
@@ -645,7 +604,13 @@ export class ShapeStream<T extends Row<unknown> = Row>
         const newShapeHandle =
           e.headers[SHAPE_HANDLE_HEADER] || `${this.#shapeHandle!}-next`
         this.#reset(newShapeHandle)
-        await this.#publish(e.json as Message<T>[])
+
+        // must refetch control message might be in a list or not depending
+        // on whether it came from an SSE request or long poll - handle both
+        // cases for safety here but worth revisiting 409 handling
+        await this.#publish(
+          (Array.isArray(e.json) ? e.json : [e.json]) as Message<T>[]
+        )
         return this.#requestShape()
       } else {
         // Notify subscribers
@@ -862,13 +827,15 @@ export class ShapeStream<T extends Row<unknown> = Row>
     headers: Record<string, string>
     resumingFromPause?: boolean
   }): Promise<void> {
+    const useSse = this.options.liveSse ?? this.options.experimentalLiveSse
     if (
       this.#isUpToDate &&
-      this.options.experimentalLiveSse &&
+      useSse &&
       !this.#isRefreshing &&
       !opts.resumingFromPause
     ) {
       opts.fetchUrl.searchParams.set(EXPERIMENTAL_LIVE_SSE_QUERY_PARAM, `true`)
+      opts.fetchUrl.searchParams.set(LIVE_SSE_QUERY_PARAM, `true`)
       return this.#requestShapeSSE(opts)
     }
 

package/src/constants.ts

@@ -13,7 +13,11 @@ export const TABLE_QUERY_PARAM = `table`
 export const WHERE_QUERY_PARAM = `where`
 export const REPLICA_PARAM = `replica`
 export const WHERE_PARAMS_PARAM = `params`
+/**
+ * @deprecated Use {@link LIVE_SSE_QUERY_PARAM} instead.
+ */
 export const EXPERIMENTAL_LIVE_SSE_QUERY_PARAM = `experimental_live_sse`
+export const LIVE_SSE_QUERY_PARAM = `live_sse`
 export const FORCE_DISCONNECT_AND_REFRESH = `force-disconnect-and-refresh`
 export const PAUSE_STREAM = `pause-stream`
 export const LOG_MODE_QUERY_PARAM = `log`

package/src/fetch.ts

@@ -59,13 +59,7 @@ export function createFetchWithBackoff(
     let delay = initialDelay
     let attempt = 0
 
-    /* eslint-disable no-constant-condition -- we re-fetch the shape log
-     * continuously until we get a non-ok response. For recoverable errors,
-     * we retry the fetch with exponential backoff. Users can pass in an
-     * AbortController to abort the fetching an any point.
-     * */
     while (true) {
-      /* eslint-enable no-constant-condition */
       try {
         const result = await fetchClient(...args)
         if (result.ok) return result
@@ -118,6 +112,10 @@ export function createFetchWithConsumedMessages(fetchClient: typeof fetch) {
       const text = await res.text()
       return new Response(text, res)
     } catch (err) {
+      if (args[1]?.signal?.aborted) {
+        throw new FetchBackoffAbortError()
+      }
+
       throw new FetchError(
         res.status,
         undefined,

package/src/helpers.ts

@@ -97,41 +97,3 @@ export function isVisibleInSnapshot(
 
   return xid < xmin || (xid < xmax && !xip.includes(xid))
 }
-
-export function generateShardId(): string {
-  return Math.floor(Math.random() * 0xfffff)
-    .toString(16)
-    .padStart(5, `0`)
-}
-
-export function isLocalhostUrl(url: URL): boolean {
-  const hostname = url.hostname.toLowerCase()
-  return hostname === `localhost` || hostname.endsWith(`.localhost`)
-}
-
-export type ShardSubdomainOption = `always` | `localhost` | `never` | boolean
-
-export function applySubdomainSharding(
-  originalUrl: string,
-  option: ShardSubdomainOption = `localhost`
-): string {
-  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()
-}

package/src/index.ts

@@ -5,7 +5,6 @@ export {
   isChangeMessage,
   isControlMessage,
   isVisibleInSnapshot,
-  type ShardSubdomainOption,
 } from './helpers'
 export { FetchError } from './error'
 export { type BackoffOptions, BackoffDefaults } from './fetch'