@electric-sql/client 0.7.2 → 0.8.0

package/src/error.ts

@@ -46,5 +46,71 @@ export class FetchError extends Error {
 export class FetchBackoffAbortError extends Error {
   constructor() {
     super(`Fetch with backoff aborted`)
+    this.name = `FetchBackoffAbortError`
+  }
+}
+
+export class InvalidShapeOptionsError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = `InvalidShapeOptionsError`
+  }
+}
+
+export class MissingShapeUrlError extends Error {
+  constructor() {
+    super(`Invalid shape options: missing required url parameter`)
+    this.name = `MissingShapeUrlError`
+  }
+}
+
+export class InvalidSignalError extends Error {
+  constructor() {
+    super(`Invalid signal option. It must be an instance of AbortSignal.`)
+    this.name = `InvalidSignalError`
+  }
+}
+
+export class MissingShapeHandleError extends Error {
+  constructor() {
+    super(
+      `shapeHandle is required if this isn't an initial fetch (i.e. offset > -1)`
+    )
+    this.name = `MissingShapeHandleError`
+  }
+}
+
+export class ReservedParamError extends Error {
+  constructor(reservedParams: string[]) {
+    super(
+      `Cannot use reserved Electric parameter names in custom params: ${reservedParams.join(`, `)}`
+    )
+    this.name = `ReservedParamError`
+  }
+}
+
+export class ParserNullValueError extends Error {
+  constructor(columnName: string) {
+    super(`Column "${columnName ?? `unknown`}" does not allow NULL values`)
+    this.name = `ParserNullValueError`
+  }
+}
+
+export class ShapeStreamAlreadyRunningError extends Error {
+  constructor() {
+    super(`ShapeStream is already running`)
+    this.name = `ShapeStreamAlreadyRunningError`
+  }
+}
+
+export class MissingHeadersError extends Error {
+  constructor(url: string, missingHeaders: Array<string>) {
+    let msg = `The response for the shape request to ${url} didn't include the following required headers:\n`
+    missingHeaders.forEach((h) => {
+      msg += `- ${h}\n`
+    })
+    msg += `\nThis is often due to a proxy not setting CORS correctly so that all Electric headers can be read by the client.`
+    msg += `\nFor more information visit the troubleshooting guide: /docs/guides/troubleshooting/missing-headers`
+    super(msg)
   }
 }

package/src/fetch.ts

@@ -6,7 +6,11 @@ import {
   SHAPE_HANDLE_HEADER,
   SHAPE_HANDLE_QUERY_PARAM,
 } from './constants'
-import { FetchError, FetchBackoffAbortError } from './error'
+import {
+  FetchError,
+  FetchBackoffAbortError,
+  MissingHeadersError,
+} from './error'
 
 // Some specific 4xx and 5xx HTTP status codes that we definitely
 // want to retry
@@ -146,6 +150,53 @@ export function createFetchWithChunkBuffer(
   return prefetchClient
 }
 
+export const requiredElectricResponseHeaders = [
+  `electric-offset`,
+  `electric-handle`,
+]
+
+export const requiredLiveResponseHeaders = [`electric-cursor`]
+
+export const requiredNonLiveResponseHeaders = [`electric-schema`]
+
+export function createFetchWithResponseHeadersCheck(
+  fetchClient: typeof fetch
+): typeof fetch {
+  return async (...args: Parameters<typeof fetchClient>) => {
+    const response = await fetchClient(...args)
+
+    if (response.ok) {
+      // Check that the necessary Electric headers are present on the response
+      const headers = response.headers
+      const missingHeaders: Array<string> = []
+
+      const addMissingHeaders = (requiredHeaders: Array<string>) =>
+        missingHeaders.push(...requiredHeaders.filter((h) => !headers.has(h)))
+      addMissingHeaders(requiredElectricResponseHeaders)
+
+      const input = args[0]
+      const urlString = input.toString()
+      const url = new URL(urlString)
+      if (url.searchParams.has(LIVE_QUERY_PARAM, `true`)) {
+        addMissingHeaders(requiredLiveResponseHeaders)
+      }
+
+      if (
+        !url.searchParams.has(LIVE_QUERY_PARAM) ||
+        url.searchParams.has(LIVE_QUERY_PARAM, `false`)
+      ) {
+        addMissingHeaders(requiredNonLiveResponseHeaders)
+      }
+
+      if (missingHeaders.length > 0) {
+        throw new MissingHeadersError(urlString, missingHeaders)
+      }
+    }
+
+    return response
+  }
+}
+
 class PrefetchQueue {
   readonly #fetchClient: typeof fetch
   readonly #maxPrefetchedRequests: number

package/src/parser.ts

@@ -1,4 +1,5 @@
 import { ColumnInfo, GetExtensions, Message, Row, Schema, Value } from './types'
+import { ParserNullValueError } from './error'
 
 type NullToken = null | `NULL`
 type Token = Exclude<string, NullToken>
@@ -162,7 +163,7 @@ function makeNullableParser<Extensions>(
   return (value: NullableToken) => {
     if (isPgNull(value)) {
       if (!isNullable) {
-        throw new Error(`Column ${columnName ?? `unknown`} is not nullable`)
+        throw new ParserNullValueError(columnName ?? `unknown`)
       }
       return null
     }

package/src/shape.ts

@@ -1,4 +1,4 @@
-import { Message, Row } from './types'
+import { Message, Offset, Row } from './types'
 import { isChangeMessage, isControlMessage } from './helpers'
 import { FetchError } from './error'
 import { ShapeStreamInterface } from './client'
@@ -55,21 +55,20 @@ export class Shape<T extends Row<unknown> = Row> {
       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 lastOffset(): Offset {
+    return this.#stream.lastOffset
+  }
+
+  get handle(): string | undefined {
+    return this.#stream.shapeHandle
+  }
+
   get rows(): Promise<T[]> {
     return this.value.then((v) => Array.from(v.values()))
   }