@electric-sql/client 1.0.4 → 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,
@@ -40,7 +40,12 @@ import {
   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,
@@ -54,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
@@ -100,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
@@ -146,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(
@@ -245,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
@@ -262,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
@@ -282,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.
  *
@@ -298,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`.
  * ```
@@ -324,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<
@@ -349,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 }
@@ -363,13 +386,17 @@ 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(
@@ -377,6 +404,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
       )
     )
 
+    const sseFetchWithBackoffClient = createFetchWithBackoff(
+      baseFetchClient,
+      backOffOpts,
+      true
+    )
+
+    this.#sseFetchClient = createFetchWithResponseHeadersCheck(
+      createFetchWithChunkBuffer(sseFetchWithBackoffClient)
+    )
+
     this.#subscribeToVisibilityChanges()
   }
 
@@ -434,6 +471,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   async #requestShape(): Promise<void> {
     if (this.#state === `pause-requested`) {
       this.#state = `paused`
+
       return
     }
 
@@ -448,7 +486,70 @@ export class ShapeStream<T extends Row<unknown> = Row>
     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),
@@ -511,75 +612,34 @@ export class ShapeStream<T extends Row<unknown> = Row>
     // 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
-    let abortListener: (() => void) | undefined
     if (signal) {
-      abortListener = () => {
+      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)
       }
-    }
 
-    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
-        return this.#requestShape()
-      }
-
-      if (e instanceof FetchBackoffAbortError) {
-        if (
-          this.#requestAbortController.signal.aborted &&
-          this.#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
+      return abortListener
     }
+  }
 
+  async #onInitialResponse(response: Response) {
     const { headers, status } = response
     const shapeHandle = headers.get(SHAPE_HANDLE_HEADER)
     if (shapeHandle) {
@@ -609,23 +669,122 @@ export class ShapeStream<T extends Row<unknown> = Row>
       // 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)
+  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)
     }
+  }
 
-    this.#tickPromiseResolver?.()
-    return this.#requestShape()
+  /**
+   * 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() {
@@ -722,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) {
@@ -830,8 +997,8 @@ function setQueryParam(
 }
 
 function convertWhereParamsToObj(
-  allPgParams: ExternalParamsRecord
-): ExternalParamsRecord {
+  allPgParams: ExternalParamsRecord<Row>
+): ExternalParamsRecord<Row> {
   if (Array.isArray(allPgParams.params)) {
     return {
       ...allPgParams,

package/src/constants.ts

@@ -12,5 +12,6 @@ export const TABLE_QUERY_PARAM = `table`
 export const WHERE_QUERY_PARAM = `where`
 export const REPLICA_PARAM = `replica`
 export const WHERE_PARAMS_PARAM = `params`
+export const EXPERIMENTAL_LIVE_SSE_QUERY_PARAM = `experimental_live_sse`
 export const FORCE_DISCONNECT_AND_REFRESH = `force-disconnect-and-refresh`
 export const PAUSE_STREAM = `pause-stream`

package/src/fetch.ts

@@ -38,7 +38,8 @@ export const BackoffDefaults = {
 
 export function createFetchWithBackoff(
   fetchClient: typeof fetch,
-  backoffOptions: BackoffOptions = BackoffDefaults
+  backoffOptions: BackoffOptions = BackoffDefaults,
+  sseMode: boolean = false
 ): typeof fetch {
   const {
     initialDelay,
@@ -64,7 +65,16 @@ export function createFetchWithBackoff(
       try {
         const result = await fetchClient(...args)
         if (result.ok) return result
-        else throw await FetchError.fromResponse(result, url.toString())
+
+        const err = await FetchError.fromResponse(result, url.toString())
+        if (err.status === 409 && sseMode) {
+          // The json body is [ { headers: { control: 'must-refetch' } } ] in normal mode
+          // and is { headers: { control: 'must-refetch' } } in SSE mode
+          // So in SSE mode we need to wrap it in an array
+          err.json = [err.json]
+        }
+
+        throw err
       } catch (e) {
         onFailedAttempt?.()
         if (options?.signal?.aborted) {

package/src/helpers.ts

@@ -1,4 +1,4 @@
-import { ChangeMessage, ControlMessage, Message, Row } from './types'
+import { ChangeMessage, ControlMessage, Message, Offset, Row } from './types'
 
 /**
  * Type guard for checking {@link Message} is {@link ChangeMessage}.
@@ -51,3 +51,15 @@ export function isUpToDateMessage<T extends Row<unknown> = Row>(
 ): message is ControlMessage & { up_to_date: true } {
   return isControlMessage(message) && message.headers.control === `up-to-date`
 }
+
+/**
+ * Parses the LSN from the up-to-date message and turns it into an offset.
+ * The LSN is only present in the up-to-date control message when in SSE mode.
+ * If we are not in SSE mode this function will return undefined.
+ */
+export function getOffset(message: ControlMessage): Offset | undefined {
+  const lsn = Number(message.headers.global_last_seen_lsn)
+  if (lsn && !isNaN(lsn)) {
+    return `${lsn}_0`
+  }
+}

package/src/types.ts

@@ -26,7 +26,10 @@ interface Header {
 export type Operation = `insert` | `update` | `delete`
 
 export type ControlMessage = {
-  headers: Header & { control: `up-to-date` | `must-refetch` }
+  headers: Header & {
+    control: `up-to-date` | `must-refetch`
+    global_last_seen_lsn?: string
+  }
 }
 
 export type ChangeMessage<T extends Row<unknown> = Row> = {