@electric-sql/client 0.5.0 → 0.6.0

package/src/constants.ts

@@ -0,0 +1,8 @@
+export const SHAPE_ID_HEADER = `electric-shape-id`
+export const CHUNK_LAST_OFFSET_HEADER = `electric-chunk-last-offset`
+export const CHUNK_UP_TO_DATE_HEADER = `electric-chunk-up-to-date`
+export const SHAPE_SCHEMA_HEADER = `electric-schema`
+export const SHAPE_ID_QUERY_PARAM = `shape_id`
+export const OFFSET_QUERY_PARAM = `offset`
+export const WHERE_QUERY_PARAM = `where`
+export const LIVE_QUERY_PARAM = `live`

package/src/error.ts

@@ -0,0 +1,50 @@
+export class FetchError extends Error {
+  status: number
+  text?: string
+  json?: object
+  headers: Record<string, string>
+
+  constructor(
+    status: number,
+    text: string | undefined,
+    json: object | undefined,
+    headers: Record<string, string>,
+    public url: string,
+    message?: string
+  ) {
+    super(
+      message ||
+        `HTTP Error ${status} at ${url}: ${text ?? JSON.stringify(json)}`
+    )
+    this.name = `FetchError`
+    this.status = status
+    this.text = text
+    this.json = json
+    this.headers = headers
+  }
+
+  static async fromResponse(
+    response: Response,
+    url: string
+  ): Promise<FetchError> {
+    const status = response.status
+    const headers = Object.fromEntries([...response.headers.entries()])
+    let text: string | undefined = undefined
+    let json: object | undefined = undefined
+
+    const contentType = response.headers.get(`content-type`)
+    if (contentType && contentType.includes(`application/json`)) {
+      json = (await response.json()) as object
+    } else {
+      text = await response.text()
+    }
+
+    return new FetchError(status, text, json, headers, url)
+  }
+}
+
+export class FetchBackoffAbortError extends Error {
+  constructor() {
+    super(`Fetch with backoff aborted`)
+  }
+}

package/src/fetch.ts

@@ -0,0 +1,272 @@
+import {
+  CHUNK_LAST_OFFSET_HEADER,
+  CHUNK_UP_TO_DATE_HEADER,
+  LIVE_QUERY_PARAM,
+  OFFSET_QUERY_PARAM,
+  SHAPE_ID_HEADER,
+  SHAPE_ID_QUERY_PARAM,
+} from './constants'
+import { FetchError, FetchBackoffAbortError } from './error'
+
+export interface BackoffOptions {
+  /**
+   * Initial delay before retrying in milliseconds
+   */
+  initialDelay: number
+  /**
+   * Maximum retry delay in milliseconds
+   */
+  maxDelay: number
+  multiplier: number
+  onFailedAttempt?: () => void
+  debug?: boolean
+}
+
+export const BackoffDefaults = {
+  initialDelay: 100,
+  maxDelay: 10_000,
+  multiplier: 1.3,
+}
+
+export function createFetchWithBackoff(
+  fetchClient: typeof fetch,
+  backoffOptions: BackoffOptions = BackoffDefaults
+): typeof fetch {
+  const {
+    initialDelay,
+    maxDelay,
+    multiplier,
+    debug = false,
+    onFailedAttempt,
+  } = backoffOptions
+  return async (...args: Parameters<typeof fetch>): Promise<Response> => {
+    const url = args[0]
+    const options = args[1]
+
+    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
+        else throw await FetchError.fromResponse(result, url.toString())
+      } catch (e) {
+        onFailedAttempt?.()
+        if (options?.signal?.aborted) {
+          throw new FetchBackoffAbortError()
+        } else if (
+          e instanceof FetchError &&
+          e.status >= 400 &&
+          e.status < 500
+        ) {
+          // Any client errors cannot be backed off on, leave it to the caller to handle.
+          throw e
+        } else {
+          // Exponentially backoff on errors.
+          // Wait for the current delay duration
+          await new Promise((resolve) => setTimeout(resolve, delay))
+
+          // Increase the delay for the next attempt
+          delay = Math.min(delay * multiplier, maxDelay)
+
+          if (debug) {
+            attempt++
+            console.log(`Retry attempt #${attempt} after ${delay}ms`)
+          }
+        }
+      }
+    }
+  }
+}
+
+interface ChunkPrefetchOptions {
+  maxChunksToPrefetch: number
+}
+
+const ChunkPrefetchDefaults = {
+  maxChunksToPrefetch: 2,
+}
+
+/**
+ * Creates a fetch client that prefetches subsequent log chunks for
+ * consumption by the shape stream without waiting for the chunk bodies
+ * themselves to be loaded.
+ *
+ * @param fetchClient the client to wrap
+ * @param prefetchOptions options to configure prefetching
+ * @returns wrapped client with prefetch capabilities
+ */
+export function createFetchWithChunkBuffer(
+  fetchClient: typeof fetch,
+  prefetchOptions: ChunkPrefetchOptions = ChunkPrefetchDefaults
+): typeof fetch {
+  const { maxChunksToPrefetch } = prefetchOptions
+
+  let prefetchQueue: PrefetchQueue
+
+  const prefetchClient = async (...args: Parameters<typeof fetchClient>) => {
+    const url = args[0].toString()
+
+    // try to consume from the prefetch queue first, and if request is
+    // not present abort the prefetch queue as it must no longer be valid
+    const prefetchedRequest = prefetchQueue?.consume(...args)
+    if (prefetchedRequest) {
+      return prefetchedRequest
+    }
+
+    prefetchQueue?.abort()
+
+    // perform request and fire off prefetch queue if request is eligible
+    const response = await fetchClient(...args)
+    const nextUrl = getNextChunkUrl(url, response)
+    if (nextUrl) {
+      prefetchQueue = new PrefetchQueue({
+        fetchClient,
+        maxPrefetchedRequests: maxChunksToPrefetch,
+        url: nextUrl,
+        requestInit: args[1],
+      })
+    }
+
+    return response
+  }
+
+  return prefetchClient
+}
+
+class PrefetchQueue {
+  readonly #fetchClient: typeof fetch
+  readonly #maxPrefetchedRequests: number
+  readonly #prefetchQueue = new Map<
+    string,
+    [Promise<Response>, AbortController]
+  >()
+  #queueHeadUrl: string | void
+  #queueTailUrl: string
+
+  constructor(options: {
+    url: Parameters<typeof fetch>[0]
+    requestInit: Parameters<typeof fetch>[1]
+    maxPrefetchedRequests: number
+    fetchClient?: typeof fetch
+  }) {
+    this.#fetchClient =
+      options.fetchClient ??
+      ((...args: Parameters<typeof fetch>) => fetch(...args))
+    this.#maxPrefetchedRequests = options.maxPrefetchedRequests
+    this.#queueHeadUrl = options.url.toString()
+    this.#queueTailUrl = this.#queueHeadUrl
+    this.#prefetch(options.url, options.requestInit)
+  }
+
+  abort(): void {
+    this.#prefetchQueue.forEach(([_, aborter]) => aborter.abort())
+  }
+
+  consume(...args: Parameters<typeof fetch>): Promise<Response> | void {
+    const url = args[0].toString()
+
+    const request = this.#prefetchQueue.get(url)?.[0]
+    // only consume if request is in queue and is the queue "head"
+    // if request is in the queue but not the head, the queue is being
+    // consumed out of order and should be restarted
+    if (!request || url !== this.#queueHeadUrl) return
+    this.#prefetchQueue.delete(url)
+
+    // fire off new prefetch since request has been consumed
+    request
+      .then((response) => {
+        const nextUrl = getNextChunkUrl(url, response)
+        this.#queueHeadUrl = nextUrl
+        if (!this.#prefetchQueue.has(this.#queueTailUrl)) {
+          this.#prefetch(this.#queueTailUrl, args[1])
+        }
+      })
+      .catch(() => {})
+
+    return request
+  }
+
+  #prefetch(...args: Parameters<typeof fetch>): void {
+    const url = args[0].toString()
+
+    // only prefetch when queue is not full
+    if (this.#prefetchQueue.size >= this.#maxPrefetchedRequests) return
+
+    // initialize aborter per request, to avoid aborting consumed requests that
+    // are still streaming their bodies to the consumer
+    const aborter = new AbortController()
+
+    try {
+      const request = this.#fetchClient(url, {
+        ...(args[1] ?? {}),
+        signal: chainAborter(aborter, args[1]?.signal),
+      })
+      this.#prefetchQueue.set(url, [request, aborter])
+      request
+        .then((response) => {
+          // only keep prefetching if response chain is uninterrupted
+          if (!response.ok || aborter.signal.aborted) return
+
+          const nextUrl = getNextChunkUrl(url, response)
+
+          // only prefetch when there is a next URL
+          if (!nextUrl || nextUrl === url) return
+
+          this.#queueTailUrl = nextUrl
+          return this.#prefetch(nextUrl, args[1])
+        })
+        .catch(() => {})
+    } catch (_) {
+      // ignore prefetch errors
+    }
+  }
+}
+
+/**
+ * Generate the next chunk's URL if the url and response are valid
+ */
+function getNextChunkUrl(url: string, res: Response): string | void {
+  const shapeId = res.headers.get(SHAPE_ID_HEADER)
+  const lastOffset = res.headers.get(CHUNK_LAST_OFFSET_HEADER)
+  const isUpToDate = res.headers.has(CHUNK_UP_TO_DATE_HEADER)
+
+  // only prefetch if shape ID and offset for next chunk are available, and
+  // response is not already up-to-date
+  if (!shapeId || !lastOffset || isUpToDate) return
+
+  const nextUrl = new URL(url)
+
+  // don't prefetch live requests, rushing them will only
+  // potentially miss more recent data
+  if (nextUrl.searchParams.has(LIVE_QUERY_PARAM)) return
+
+  nextUrl.searchParams.set(SHAPE_ID_QUERY_PARAM, shapeId)
+  nextUrl.searchParams.set(OFFSET_QUERY_PARAM, lastOffset)
+  return nextUrl.toString()
+}
+
+/**
+ * Chains an abort controller on an optional source signal's
+ * aborted state - if the source signal is aborted, the provided abort
+ * controller will also abort
+ */
+function chainAborter(
+  aborter: AbortController,
+  sourceSignal?: AbortSignal
+): AbortSignal {
+  if (!sourceSignal) return aborter.signal
+  if (sourceSignal.aborted) aborter.abort()
+  else
+    sourceSignal.addEventListener(`abort`, () => aborter.abort(), {
+      once: true,
+    })
+  return aborter.signal
+}

package/src/helpers.ts

@@ -45,3 +45,9 @@ export function isControlMessage<T extends Row = Row>(
 ): message is ControlMessage {
   return !isChangeMessage(message)
 }
+
+export function isUpToDateMessage<T extends Row = Row>(
+  message: Message<T>
+): message is ControlMessage & { up_to_date: true } {
+  return isControlMessage(message) && message.headers.control === `up-to-date`
+}

package/src/index.ts

@@ -1,3 +1,6 @@
 export * from './client'
+export * from './shape'
 export * from './types'
-export * from './helpers'
+export { isChangeMessage, isControlMessage } from './helpers'
+export { FetchError } from './error'
+export { type BackoffOptions, BackoffDefaults } from './fetch'

package/src/shape.ts

@@ -0,0 +1,197 @@
+import { Message, Row } from './types'
+import { isChangeMessage, isControlMessage } from './helpers'
+import { FetchError } from './error'
+import { ShapeStreamInterface } from './client'
+
+export type ShapeData<T extends Row = Row> = Map<string, T>
+export type ShapeChangedCallback<T extends Row = Row> = (
+  value: ShapeData<T>
+) => void
+
+/**
+ * A Shape is an object that subscribes to a shape log,
+ * keeps a materialised shape `.value` in memory and
+ * notifies subscribers when the value has changed.
+ *
+ * It can be used without a framework and as a primitive
+ * to simplify developing framework hooks.
+ *
+ * @constructor
+ * @param {ShapeStream<T extends Row>} - the underlying shape stream
+ * @example
+ * ```
+ * const shapeStream = new ShapeStream<{ foo: number }>(url: 'http://localhost:3000/v1/shape/foo'})
+ * const shape = new Shape(shapeStream)
+ * ```
+ *
+ * `value` returns a promise that resolves the Shape data once the Shape has been
+ * fully loaded (and when resuming from being offline):
+ *
+ *     const value = await shape.value
+ *
+ * `valueSync` returns the current data synchronously:
+ *
+ *     const value = shape.valueSync
+ *
+ *  Subscribe to updates. Called whenever the shape updates in Postgres.
+ *
+ *     shape.subscribe(shapeData => {
+ *       console.log(shapeData)
+ *     })
+ */
+export class Shape<T extends Row = Row> {
+  readonly #stream: ShapeStreamInterface<T>
+
+  readonly #data: ShapeData<T> = new Map()
+  readonly #subscribers = new Map<number, ShapeChangedCallback<T>>()
+
+  #hasNotifiedSubscribersUpToDate: boolean = false
+  #error: FetchError | false = false
+
+  constructor(stream: ShapeStreamInterface<T>) {
+    this.#stream = stream
+    this.#stream.subscribe(
+      this.#process.bind(this),
+      this.#handleError.bind(this)
+    )
+    const unsubscribe = this.#stream.subscribeOnceToUpToDate(
+      () => {
+        unsubscribe()
+      },
+      (e) => {
+        this.#handleError(e)
+        throw e
+      }
+    )
+  }
+
+  get isUpToDate(): boolean {
+    return this.#stream.isUpToDate
+  }
+
+  get value(): Promise<ShapeData<T>> {
+    return new Promise((resolve, reject) => {
+      if (this.#stream.isUpToDate) {
+        resolve(this.valueSync)
+      } else {
+        const unsubscribe = this.subscribe((shapeData) => {
+          unsubscribe()
+          if (this.#error) reject(this.#error)
+          resolve(shapeData)
+        })
+      }
+    })
+  }
+
+  get valueSync() {
+    return this.#data
+  }
+
+  get error() {
+    return this.#error
+  }
+
+  /** Unix time at which we last synced. Undefined when `isLoading` is true. */
+  lastSyncedAt(): number | undefined {
+    return this.#stream.lastSyncedAt()
+  }
+
+  /** Time elapsed since last sync (in ms). Infinity if we did not yet sync. */
+  lastSynced() {
+    return this.#stream.lastSynced()
+  }
+
+  /** True during initial fetch. False afterwise.  */
+  isLoading() {
+    return this.#stream.isLoading()
+  }
+
+  /** Indicates if we are connected to the Electric sync service. */
+  isConnected(): boolean {
+    return this.#stream.isConnected()
+  }
+
+  subscribe(callback: ShapeChangedCallback<T>): () => void {
+    const subscriptionId = Math.random()
+
+    this.#subscribers.set(subscriptionId, callback)
+
+    return () => {
+      this.#subscribers.delete(subscriptionId)
+    }
+  }
+
+  unsubscribeAll(): void {
+    this.#subscribers.clear()
+  }
+
+  get numSubscribers() {
+    return this.#subscribers.size
+  }
+
+  #process(messages: Message<T>[]): void {
+    let dataMayHaveChanged = false
+    let isUpToDate = false
+    let newlyUpToDate = false
+
+    messages.forEach((message) => {
+      if (isChangeMessage(message)) {
+        dataMayHaveChanged = [`insert`, `update`, `delete`].includes(
+          message.headers.operation
+        )
+
+        switch (message.headers.operation) {
+          case `insert`:
+            this.#data.set(message.key, message.value)
+            break
+          case `update`:
+            this.#data.set(message.key, {
+              ...this.#data.get(message.key)!,
+              ...message.value,
+            })
+            break
+          case `delete`:
+            this.#data.delete(message.key)
+            break
+        }
+      }
+
+      if (isControlMessage(message)) {
+        switch (message.headers.control) {
+          case `up-to-date`:
+            isUpToDate = true
+            if (!this.#hasNotifiedSubscribersUpToDate) {
+              newlyUpToDate = true
+            }
+            break
+          case `must-refetch`:
+            this.#data.clear()
+            this.#error = false
+            isUpToDate = false
+            newlyUpToDate = false
+            break
+        }
+      }
+    })
+
+    // Always notify subscribers when the Shape first is up to date.
+    // FIXME this would be cleaner with a simple state machine.
+    if (newlyUpToDate || (isUpToDate && dataMayHaveChanged)) {
+      this.#hasNotifiedSubscribersUpToDate = true
+      this.#notify()
+    }
+  }
+
+  #handleError(e: Error): void {
+    if (e instanceof FetchError) {
+      this.#error = e
+      this.#notify()
+    }
+  }
+
+  #notify(): void {
+    this.#subscribers.forEach((callback) => {
+      callback(this.valueSync)
+    })
+  }
+}

package/src/types.ts

@@ -108,3 +108,5 @@ export type TypedMessages<T extends Row = Row> = {
   messages: Array<Message<T>>
   schema: ColumnInfo
 }
+
+export type MaybePromise<T> = T | Promise<T>