@electric-sql/client 1.0.3 → 1.0.5

package/src/client.ts

@@ -7,7 +7,7 @@ import {
   GetExtensions,
 } from './types'
 import { MessageParser, Parser } from './parser'
-import { isUpToDateMessage } from './helpers'
+import { getOffset, isUpToDateMessage } from './helpers'
 import {
   FetchError,
   FetchBackoffAbortError,
@@ -39,7 +39,13 @@ import {
   TABLE_QUERY_PARAM,
   REPLICA_PARAM,
   FORCE_DISCONNECT_AND_REFRESH,
+  PAUSE_STREAM,
+  EXPERIMENTAL_LIVE_SSE_QUERY_PARAM,
 } from './constants'
+import {
+  EventSourceMessage,
+  fetchEventSource,
+} from '@microsoft/fetch-event-source'
 
 const RESERVED_PARAMS: Set<ReservedParamKeys> = new Set([
   LIVE_CACHE_BUSTER_QUERY_PARAM,
@@ -53,15 +59,17 @@ type Replica = `full` | `default`
 /**
  * PostgreSQL-specific shape parameters that can be provided externally
  */
-export interface PostgresParams {
+export interface PostgresParams<T extends Row<unknown> = Row> {
   /** The root table for the shape. Not required if you set the table in your proxy. */
   table?: string
 
   /**
    * The columns to include in the shape.
    * Must include primary keys, and can only include valid columns.
+   * Defaults to all columns of the type `T`. If provided, must include primary keys, and can only include valid columns.
+
    */
-  columns?: string[]
+  columns?: (keyof T)[]
 
   /** The where clauses for the shape */
   where?: string
@@ -99,11 +107,9 @@ type ParamValue =
  * External params type - what users provide.
  * Excludes reserved parameters to prevent dynamic variations that could cause stream shape changes.
  */
-export type ExternalParamsRecord = {
-  [K in string as K extends ReservedParamKeys ? never : K]:
-    | ParamValue
-    | undefined
-} & Partial<PostgresParams>
+export type ExternalParamsRecord<T extends Row<unknown> = Row> = {
+  [K in string]: ParamValue | undefined
+} & Partial<PostgresParams<T>> & { [K in ReservedParamKeys]?: never }
 
 type ReservedParamKeys =
   | typeof LIVE_CACHE_BUSTER_QUERY_PARAM
@@ -145,7 +151,7 @@ export async function resolveValue<T>(
  * Helper function to convert external params to internal format
  */
 async function toInternalParams(
-  params: ExternalParamsRecord
+  params: ExternalParamsRecord<Row>
 ): Promise<InternalParamsRecord> {
   const entries = Object.entries(params)
   const resolvedEntries = await Promise.all(
@@ -244,6 +250,11 @@ export interface ShapeStreamOptions<T = never> {
    */
   subscribe?: boolean
 
+  /**
+   * Experimental support for Server-Sent Events (SSE) for live updates.
+   */
+  experimentalLiveSse?: boolean
+
   signal?: AbortSignal
   fetchClient?: typeof fetch
   backoffOptions?: BackoffOptions
@@ -261,7 +272,9 @@ export interface ShapeStreamOptions<T = never> {
 
 export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
   subscribe(
-    callback: (messages: Message<T>[]) => MaybePromise<void>,
+    callback: (
+      messages: Message<T>[]
+    ) => MaybePromise<void> | { columns?: (keyof T)[] },
     onError?: (error: FetchError | Error) => void
   ): () => void
   unsubscribeAll(): void
@@ -281,8 +294,9 @@ export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
 }
 
 /**
- * Reads updates to a shape from Electric using HTTP requests and long polling. Notifies subscribers
- * when new messages come in. Doesn't maintain any history of the
+ * Reads updates to a shape from Electric using HTTP requests and long polling or
+ * Server-Sent Events (SSE).
+ * Notifies subscribers when new messages come in. Doesn't maintain any history of the
  * log but does keep track of the offset position and is the best way
  * to consume the HTTP `GET /v1/shape` api.
  *
@@ -297,6 +311,14 @@ export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
  * })
  * ```
  *
+ * To use Server-Sent Events (SSE) for real-time updates:
+ * ```
+ * const stream = new ShapeStream({
+ *   url: `http://localhost:3000/v1/shape`,
+ *   experimentalLiveSse: true
+ * })
+ * ```
+ *
  * To abort the stream, abort the `signal`
  * passed in via the `ShapeStreamOptions`.
  * ```
@@ -323,6 +345,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #error: unknown = null
 
   readonly #fetchClient: typeof fetch
+  readonly #sseFetchClient: typeof fetch
   readonly #messageParser: MessageParser<T>
 
   readonly #subscribers = new Map<
@@ -334,6 +357,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   >()
 
   #started = false
+  #state = `active` as `active` | `pause-requested` | `paused`
   #lastOffset: Offset
   #liveCacheBuster: string // Seconds since our Electric Epoch 😎
   #lastSyncedAt?: number // unix time
@@ -347,6 +371,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #tickPromise?: Promise<void>
   #tickPromiseResolver?: () => void
   #tickPromiseRejecter?: (reason?: unknown) => void
+  #messageChain = Promise.resolve<void[]>([]) // promise chain for incoming messages
 
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
@@ -361,19 +386,35 @@ export class ShapeStream<T extends Row<unknown> = Row>
       options.fetchClient ??
       ((...args: Parameters<typeof fetch>) => fetch(...args))
 
-    const fetchWithBackoffClient = createFetchWithBackoff(baseFetchClient, {
+    const backOffOpts = {
       ...(options.backoffOptions ?? BackoffDefaults),
       onFailedAttempt: () => {
         this.#connected = false
         options.backoffOptions?.onFailedAttempt?.()
       },
-    })
+    }
+    const fetchWithBackoffClient = createFetchWithBackoff(
+      baseFetchClient,
+      backOffOpts
+    )
 
     this.#fetchClient = createFetchWithConsumedMessages(
       createFetchWithResponseHeadersCheck(
         createFetchWithChunkBuffer(fetchWithBackoffClient)
       )
     )
+
+    const sseFetchWithBackoffClient = createFetchWithBackoff(
+      baseFetchClient,
+      backOffOpts,
+      true
+    )
+
+    this.#sseFetchClient = createFetchWithResponseHeadersCheck(
+      createFetchWithChunkBuffer(sseFetchWithBackoffClient)
+    )
+
+    this.#subscribeToVisibilityChanges()
   }
 
   get shapeHandle() {
@@ -392,189 +433,11 @@ export class ShapeStream<T extends Row<unknown> = Row>
     return this.#lastOffset
   }
 
-  async #start() {
-    if (this.#started) throw new Error(`Cannot start stream twice`)
+  async #start(): Promise<void> {
     this.#started = true
 
     try {
-      while (
-        (!this.options.signal?.aborted && !this.#isUpToDate) ||
-        this.options.subscribe
-      ) {
-        const { url, signal } = this.options
-
-        // Resolve headers and params in parallel
-        const [requestHeaders, params] = await Promise.all([
-          resolveHeaders(this.options.headers),
-          this.options.params
-            ? toInternalParams(convertWhereParamsToObj(this.options.params))
-            : undefined,
-        ])
-
-        // Validate params after resolution
-        if (params) {
-          validateParams(params)
-        }
-
-        const fetchUrl = new URL(url)
-
-        // Add PostgreSQL-specific parameters
-        if (params) {
-          if (params.table)
-            setQueryParam(fetchUrl, TABLE_QUERY_PARAM, params.table)
-          if (params.where)
-            setQueryParam(fetchUrl, WHERE_QUERY_PARAM, params.where)
-          if (params.columns)
-            setQueryParam(fetchUrl, COLUMNS_QUERY_PARAM, params.columns)
-          if (params.replica)
-            setQueryParam(fetchUrl, REPLICA_PARAM, params.replica)
-          if (params.params)
-            setQueryParam(fetchUrl, WHERE_PARAMS_PARAM, params.params)
-
-          // Add any remaining custom parameters
-          const customParams = { ...params }
-          delete customParams.table
-          delete customParams.where
-          delete customParams.columns
-          delete customParams.replica
-          delete customParams.params
-
-          for (const [key, value] of Object.entries(customParams)) {
-            setQueryParam(fetchUrl, key, value)
-          }
-        }
-
-        // Add Electric's internal parameters
-        fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, this.#lastOffset)
-
-        if (this.#isUpToDate) {
-          if (!this.#isRefreshing) {
-            fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`)
-          }
-          fetchUrl.searchParams.set(
-            LIVE_CACHE_BUSTER_QUERY_PARAM,
-            this.#liveCacheBuster
-          )
-        }
-
-        if (this.#shapeHandle) {
-          // This should probably be a header for better cache breaking?
-          fetchUrl.searchParams.set(
-            SHAPE_HANDLE_QUERY_PARAM,
-            this.#shapeHandle!
-          )
-        }
-
-        // sort query params in-place for stable URLs and improved cache hits
-        fetchUrl.searchParams.sort()
-
-        // Create a new AbortController for this request
-        this.#requestAbortController = new AbortController()
-
-        // If user provided a signal, listen to it and pass on the reason for the abort
-        let abortListener: (() => void) | undefined
-        if (signal) {
-          abortListener = () => {
-            this.#requestAbortController?.abort(signal.reason)
-          }
-          signal.addEventListener(`abort`, abortListener, { once: true })
-          if (signal.aborted) {
-            // If the signal is already aborted, abort the request immediately
-            this.#requestAbortController?.abort(signal.reason)
-          }
-        }
-
-        let response!: Response
-        try {
-          response = await this.#fetchClient(fetchUrl.toString(), {
-            signal: this.#requestAbortController.signal,
-            headers: requestHeaders,
-          })
-          this.#connected = true
-        } catch (e) {
-          // Handle abort error triggered by refresh
-          if (
-            (e instanceof FetchError || e instanceof FetchBackoffAbortError) &&
-            this.#requestAbortController.signal.aborted &&
-            this.#requestAbortController.signal.reason ===
-              FORCE_DISCONNECT_AND_REFRESH
-          ) {
-            // Loop back to the top of the while loop to start a new request
-            continue
-          }
-
-          if (e instanceof FetchBackoffAbortError) break // interrupted
-          if (!(e instanceof FetchError)) throw e // should never happen
-
-          if (e.status == 409) {
-            // Upon receiving a 409, we should start from scratch
-            // with the newly provided shape handle
-            const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER]
-            this.#reset(newShapeHandle)
-            await this.#publish(e.json as Message<T>[])
-            continue
-          } else {
-            // Notify subscribers
-            this.#sendErrorToSubscribers(e)
-
-            // errors that have reached this point are not actionable without
-            // additional user input, such as 400s or failures to read the
-            // body of a response, so we exit the loop
-            throw e
-          }
-        } finally {
-          if (abortListener && signal) {
-            signal.removeEventListener(`abort`, abortListener)
-          }
-          this.#requestAbortController = undefined
-        }
-
-        const { headers, status } = response
-        const shapeHandle = headers.get(SHAPE_HANDLE_HEADER)
-        if (shapeHandle) {
-          this.#shapeHandle = shapeHandle
-        }
-
-        const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER)
-        if (lastOffset) {
-          this.#lastOffset = lastOffset as Offset
-        }
-
-        const liveCacheBuster = headers.get(LIVE_CACHE_BUSTER_HEADER)
-        if (liveCacheBuster) {
-          this.#liveCacheBuster = liveCacheBuster
-        }
-
-        const getSchema = (): Schema => {
-          const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER)
-          return schemaHeader ? JSON.parse(schemaHeader) : {}
-        }
-        this.#schema = this.#schema ?? getSchema()
-
-        // NOTE: 204s are deprecated, the Electric server should not
-        // send these in latest versions but this is here for backwards
-        // compatibility
-        if (status === 204) {
-          // There's no content so we are live and up to date
-          this.#lastSyncedAt = Date.now()
-        }
-
-        const messages = (await response.text()) || `[]`
-        const batch = this.#messageParser.parse(messages, this.#schema)
-
-        // Update isUpToDate
-        if (batch.length > 0) {
-          const lastMessage = batch[batch.length - 1]
-          if (isUpToDateMessage(lastMessage)) {
-            this.#lastSyncedAt = Date.now()
-            this.#isUpToDate = true
-          }
-
-          await this.#publish(batch)
-        }
-
-        this.#tickPromiseResolver?.()
-      }
+      await this.#requestShape()
     } catch (err) {
       this.#error = err
       if (this.#onError) {
@@ -605,6 +468,338 @@ export class ShapeStream<T extends Row<unknown> = Row>
     }
   }
 
+  async #requestShape(): Promise<void> {
+    if (this.#state === `pause-requested`) {
+      this.#state = `paused`
+
+      return
+    }
+
+    if (
+      !this.options.subscribe &&
+      (this.options.signal?.aborted || this.#isUpToDate)
+    ) {
+      return
+    }
+
+    const resumingFromPause = this.#state === `paused`
+    this.#state = `active`
+
+    const { url, signal } = this.options
+    const { fetchUrl, requestHeaders } = await this.#constructUrl(
+      url,
+      resumingFromPause
+    )
+    const abortListener = await this.#createAbortListener(signal)
+    const requestAbortController = this.#requestAbortController! // we know that it is not undefined because it is set by `this.#createAbortListener`
+
+    try {
+      await this.#fetchShape({
+        fetchUrl,
+        requestAbortController,
+        headers: requestHeaders,
+        resumingFromPause: true,
+      })
+    } catch (e) {
+      // Handle abort error triggered by refresh
+      if (
+        (e instanceof FetchError || e instanceof FetchBackoffAbortError) &&
+        requestAbortController.signal.aborted &&
+        requestAbortController.signal.reason === FORCE_DISCONNECT_AND_REFRESH
+      ) {
+        // Start a new request
+        return this.#requestShape()
+      }
+
+      if (e instanceof FetchBackoffAbortError) {
+        if (
+          requestAbortController.signal.aborted &&
+          requestAbortController.signal.reason === PAUSE_STREAM
+        ) {
+          this.#state = `paused`
+        }
+        return // interrupted
+      }
+      if (!(e instanceof FetchError)) throw e // should never happen
+
+      if (e.status == 409) {
+        // Upon receiving a 409, we should start from scratch
+        // with the newly provided shape handle
+        const newShapeHandle = e.headers[SHAPE_HANDLE_HEADER]
+        this.#reset(newShapeHandle)
+        await this.#publish(e.json as Message<T>[])
+        return this.#requestShape()
+      } else {
+        // Notify subscribers
+        this.#sendErrorToSubscribers(e)
+
+        // errors that have reached this point are not actionable without
+        // additional user input, such as 400s or failures to read the
+        // body of a response, so we exit the loop
+        throw e
+      }
+    } finally {
+      if (abortListener && signal) {
+        signal.removeEventListener(`abort`, abortListener)
+      }
+      this.#requestAbortController = undefined
+    }
+
+    this.#tickPromiseResolver?.()
+    return this.#requestShape()
+  }
+
+  async #constructUrl(url: string, resumingFromPause: boolean) {
+    // Resolve headers and params in parallel
+    const [requestHeaders, params] = await Promise.all([
+      resolveHeaders(this.options.headers),
+      this.options.params
+        ? toInternalParams(convertWhereParamsToObj(this.options.params))
+        : undefined,
+    ])
+
+    // Validate params after resolution
+    if (params) {
+      validateParams(params)
+    }
+
+    const fetchUrl = new URL(url)
+
+    // Add PostgreSQL-specific parameters
+    if (params) {
+      if (params.table) setQueryParam(fetchUrl, TABLE_QUERY_PARAM, params.table)
+      if (params.where) setQueryParam(fetchUrl, WHERE_QUERY_PARAM, params.where)
+      if (params.columns)
+        setQueryParam(fetchUrl, COLUMNS_QUERY_PARAM, params.columns)
+      if (params.replica) setQueryParam(fetchUrl, REPLICA_PARAM, params.replica)
+      if (params.params)
+        setQueryParam(fetchUrl, WHERE_PARAMS_PARAM, params.params)
+
+      // Add any remaining custom parameters
+      const customParams = { ...params }
+      delete customParams.table
+      delete customParams.where
+      delete customParams.columns
+      delete customParams.replica
+      delete customParams.params
+
+      for (const [key, value] of Object.entries(customParams)) {
+        setQueryParam(fetchUrl, key, value)
+      }
+    }
+
+    // Add Electric's internal parameters
+    fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, this.#lastOffset)
+
+    if (this.#isUpToDate) {
+      // If we are resuming from a paused state, we don't want to perform a live request
+      // because it could be a long poll that holds for 20sec
+      // and during all that time `isConnected` will be false
+      if (!this.#isRefreshing && !resumingFromPause) {
+        fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`)
+      }
+      fetchUrl.searchParams.set(
+        LIVE_CACHE_BUSTER_QUERY_PARAM,
+        this.#liveCacheBuster
+      )
+    }
+
+    if (this.#shapeHandle) {
+      // This should probably be a header for better cache breaking?
+      fetchUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, this.#shapeHandle!)
+    }
+
+    // sort query params in-place for stable URLs and improved cache hits
+    fetchUrl.searchParams.sort()
+
+    return {
+      fetchUrl,
+      requestHeaders,
+    }
+  }
+
+  async #createAbortListener(signal?: AbortSignal) {
+    // Create a new AbortController for this request
+    this.#requestAbortController = new AbortController()
+
+    // If user provided a signal, listen to it and pass on the reason for the abort
+    if (signal) {
+      const abortListener = () => {
+        this.#requestAbortController?.abort(signal.reason)
+      }
+
+      signal.addEventListener(`abort`, abortListener, { once: true })
+
+      if (signal.aborted) {
+        // If the signal is already aborted, abort the request immediately
+        this.#requestAbortController?.abort(signal.reason)
+      }
+
+      return abortListener
+    }
+  }
+
+  async #onInitialResponse(response: Response) {
+    const { headers, status } = response
+    const shapeHandle = headers.get(SHAPE_HANDLE_HEADER)
+    if (shapeHandle) {
+      this.#shapeHandle = shapeHandle
+    }
+
+    const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER)
+    if (lastOffset) {
+      this.#lastOffset = lastOffset as Offset
+    }
+
+    const liveCacheBuster = headers.get(LIVE_CACHE_BUSTER_HEADER)
+    if (liveCacheBuster) {
+      this.#liveCacheBuster = liveCacheBuster
+    }
+
+    const getSchema = (): Schema => {
+      const schemaHeader = headers.get(SHAPE_SCHEMA_HEADER)
+      return schemaHeader ? JSON.parse(schemaHeader) : {}
+    }
+    this.#schema = this.#schema ?? getSchema()
+
+    // NOTE: 204s are deprecated, the Electric server should not
+    // send these in latest versions but this is here for backwards
+    // compatibility
+    if (status === 204) {
+      // There's no content so we are live and up to date
+      this.#lastSyncedAt = Date.now()
+    }
+  }
+
+  async #onMessages(messages: string, schema: Schema, isSseMessage = false) {
+    const batch = this.#messageParser.parse(messages, schema)
+
+    // Update isUpToDate
+    if (batch.length > 0) {
+      const lastMessage = batch[batch.length - 1]
+      if (isUpToDateMessage(lastMessage)) {
+        if (isSseMessage) {
+          // Only use the offset from the up-to-date message if this was an SSE message.
+          // If we would use this offset from a regular fetch, then it will be wrong
+          // and we will get an "offset is out of bounds for this shape" error
+          const offset = getOffset(lastMessage)
+          if (offset) {
+            this.#lastOffset = offset
+          }
+        }
+        this.#lastSyncedAt = Date.now()
+        this.#isUpToDate = true
+      }
+
+      await this.#publish(batch)
+    }
+  }
+
+  /**
+   * Fetches the shape from the server using either long polling or SSE.
+   * Upon receiving a successfull response, the #onInitialResponse method is called.
+   * Afterwards, the #onMessages method is called for all the incoming updates.
+   * @param opts - The options for the request.
+   * @returns A promise that resolves when the request is complete (i.e. the long poll receives a response or the SSE connection is closed).
+   */
+  async #fetchShape(opts: {
+    fetchUrl: URL
+    requestAbortController: AbortController
+    headers: Record<string, string>
+    resumingFromPause?: boolean
+  }): Promise<void> {
+    if (
+      this.#isUpToDate &&
+      this.options.experimentalLiveSse &&
+      !this.#isRefreshing &&
+      !opts.resumingFromPause
+    ) {
+      opts.fetchUrl.searchParams.set(EXPERIMENTAL_LIVE_SSE_QUERY_PARAM, `true`)
+      return this.#requestShapeSSE(opts)
+    }
+
+    return this.#requestShapeLongPoll(opts)
+  }
+
+  async #requestShapeLongPoll(opts: {
+    fetchUrl: URL
+    requestAbortController: AbortController
+    headers: Record<string, string>
+  }): Promise<void> {
+    const { fetchUrl, requestAbortController, headers } = opts
+    const response = await this.#fetchClient(fetchUrl.toString(), {
+      signal: requestAbortController.signal,
+      headers,
+    })
+
+    this.#connected = true
+    await this.#onInitialResponse(response)
+
+    const schema = this.#schema! // we know that it is not undefined because it is set by `this.#onInitialResponse`
+    const res = await response.text()
+    const messages = res || `[]`
+
+    await this.#onMessages(messages, schema)
+  }
+
+  async #requestShapeSSE(opts: {
+    fetchUrl: URL
+    requestAbortController: AbortController
+    headers: Record<string, string>
+  }): Promise<void> {
+    const { fetchUrl, requestAbortController, headers } = opts
+    const fetch = this.#sseFetchClient
+    try {
+      await fetchEventSource(fetchUrl.toString(), {
+        headers,
+        fetch,
+        onopen: async (response: Response) => {
+          this.#connected = true
+          await this.#onInitialResponse(response)
+        },
+        onmessage: (event: EventSourceMessage) => {
+          if (event.data) {
+            // Process the SSE message
+            // The event.data is a single JSON object, so we wrap it in an array
+            const messages = `[${event.data}]`
+            const schema = this.#schema! // we know that it is not undefined because it is set in onopen when we call this.#onInitialResponse
+            this.#onMessages(messages, schema, true)
+          }
+        },
+        onerror: (error: Error) => {
+          // rethrow to close the SSE connection
+          throw error
+        },
+        signal: requestAbortController.signal,
+      })
+    } catch (error) {
+      if (requestAbortController.signal.aborted) {
+        // During an SSE request, the fetch might have succeeded
+        // and we are parsing the incoming stream.
+        // If the abort happens while we're parsing the stream,
+        // then it won't be caught by our `createFetchWithBackoff` wrapper
+        // and instead we will get a raw AbortError here
+        // which we need to turn into a `FetchBackoffAbortError`
+        // such that #start handles it correctly.`
+        throw new FetchBackoffAbortError()
+      }
+      throw error
+    }
+  }
+
+  #pause() {
+    if (this.#started && this.#state === `active`) {
+      this.#state = `pause-requested`
+      this.#requestAbortController?.abort(PAUSE_STREAM)
+    }
+  }
+
+  #resume() {
+    if (this.#started && this.#state === `paused`) {
+      this.#start()
+    }
+  }
+
   subscribe(
     callback: (messages: Message<T>[]) => MaybePromise<void>,
     onError: (error: Error) => void = () => {}
@@ -648,6 +843,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
     return this.#started
   }
 
+  isPaused(): boolean {
+    return this.#state === `paused`
+  }
+
   /** Await the next tick of the request loop */
   async #nextTick() {
     if (this.#tickPromise) {
@@ -682,18 +881,26 @@ export class ShapeStream<T extends Row<unknown> = Row>
     this.#isRefreshing = false
   }
 
-  async #publish(messages: Message<T>[]): Promise<void> {
-    await Promise.all(
-      Array.from(this.#subscribers.values()).map(async ([callback, __]) => {
-        try {
-          await callback(messages)
-        } catch (err) {
-          queueMicrotask(() => {
-            throw err
-          })
-        }
-      })
+  async #publish(messages: Message<T>[]): Promise<void[]> {
+    // We process messages asynchronously
+    // but SSE's `onmessage` handler is synchronous.
+    // We use a promise chain to ensure that the handlers
+    // execute sequentially in the order the messages were received.
+    this.#messageChain = this.#messageChain.then(() =>
+      Promise.all(
+        Array.from(this.#subscribers.values()).map(async ([callback, __]) => {
+          try {
+            await callback(messages)
+          } catch (err) {
+            queueMicrotask(() => {
+              throw err
+            })
+          }
+        })
+      )
     )
+
+    return this.#messageChain
   }
 
   #sendErrorToSubscribers(error: Error) {
@@ -702,6 +909,24 @@ export class ShapeStream<T extends Row<unknown> = Row>
     })
   }
 
+  #subscribeToVisibilityChanges() {
+    if (
+      typeof document === `object` &&
+      typeof document.hidden === `boolean` &&
+      typeof document.addEventListener === `function`
+    ) {
+      const visibilityHandler = () => {
+        if (document.hidden) {
+          this.#pause()
+        } else {
+          this.#resume()
+        }
+      }
+
+      document.addEventListener(`visibilitychange`, visibilityHandler)
+    }
+  }
+
   /**
    * Resets the state of the stream, optionally with a provided
    * shape handle
@@ -772,8 +997,8 @@ function setQueryParam(
 }
 
 function convertWhereParamsToObj(
-  allPgParams: ExternalParamsRecord
-): ExternalParamsRecord {
+  allPgParams: ExternalParamsRecord<Row>
+): ExternalParamsRecord<Row> {
   if (Array.isArray(allPgParams.params)) {
     return {
       ...allPgParams,