@electric-sql/client 0.6.0 → 0.6.2

package/src/client.ts

@@ -1,4 +1,11 @@
-import { Message, Offset, Schema, Row, MaybePromise } from './types'
+import {
+  Message,
+  Offset,
+  Schema,
+  Row,
+  MaybePromise,
+  GetExtensions,
+} from './types'
 import { MessageParser, Parser } from './parser'
 import { isUpToDateMessage } from './helpers'
 import { FetchError, FetchBackoffAbortError } from './error'
@@ -10,6 +17,8 @@ import {
 } from './fetch'
 import {
   CHUNK_LAST_OFFSET_HEADER,
+  LIVE_CACHE_BUSTER_HEADER,
+  LIVE_CACHE_BUSTER_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   SHAPE_ID_HEADER,
@@ -21,7 +30,7 @@ import {
 /**
  * Options for constructing a ShapeStream.
  */
-export interface ShapeStreamOptions {
+export interface ShapeStreamOptions<T = never> {
   /**
    * The full URL to where the Shape is hosted. This can either be the Electric server
    * directly or a proxy. E.g. for a local Electric instance, you might set `http://localhost:3000/v1/shape/foo`
@@ -46,6 +55,13 @@ export interface ShapeStreamOptions {
    */
   shapeId?: string
   backoffOptions?: BackoffOptions
+
+  /**
+   * HTTP headers to attach to requests made by the client.
+   * Can be used for adding authentication headers.
+   */
+  headers?: Record<string, string>
+
   /**
    * Automatically fetch updates to the Shape. If you just want to sync the current
    * shape and stop, pass false.
@@ -53,10 +69,10 @@ export interface ShapeStreamOptions {
   subscribe?: boolean
   signal?: AbortSignal
   fetchClient?: typeof fetch
-  parser?: Parser
+  parser?: Parser<T>
 }
 
-export interface ShapeStreamInterface<T extends Row = Row> {
+export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
   subscribe(
     callback: (messages: Message<T>[]) => MaybePromise<void>,
     onError?: (error: FetchError | Error) => void
@@ -108,10 +124,10 @@ export interface ShapeStreamInterface<T extends Row = Row> {
  * ```
  */
 
-export class ShapeStream<T extends Row = Row>
+export class ShapeStream<T extends Row<unknown> = Row>
   implements ShapeStreamInterface<T>
 {
-  readonly options: ShapeStreamOptions
+  readonly options: ShapeStreamOptions<GetExtensions<T>>
 
   readonly #fetchClient: typeof fetch
   readonly #messageParser: MessageParser<T>
@@ -129,16 +145,18 @@ export class ShapeStream<T extends Row = Row>
   >()
 
   #lastOffset: Offset
+  #liveCacheBuster: string // Seconds since our Electric Epoch 😎
   #lastSyncedAt?: number // unix time
   #isUpToDate: boolean = false
   #connected: boolean = false
   #shapeId?: string
   #schema?: Schema
 
-  constructor(options: ShapeStreamOptions) {
+  constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     validateOptions(options)
     this.options = { subscribe: true, ...options }
     this.#lastOffset = this.options.offset ?? `-1`
+    this.#liveCacheBuster = ``
     this.#shapeId = this.options.shapeId
     this.#messageParser = new MessageParser<T>(options.parser)
 
@@ -183,6 +201,10 @@ export class ShapeStream<T extends Row = Row>
 
         if (this.#isUpToDate) {
           fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`)
+          fetchUrl.searchParams.set(
+            LIVE_CACHE_BUSTER_QUERY_PARAM,
+            this.#liveCacheBuster
+          )
         }
 
         if (this.#shapeId) {
@@ -192,7 +214,10 @@ export class ShapeStream<T extends Row = Row>
 
         let response!: Response
         try {
-          response = await this.#fetchClient(fetchUrl.toString(), { signal })
+          response = await this.#fetchClient(fetchUrl.toString(), {
+            signal,
+            headers: this.options.headers,
+          })
           this.#connected = true
         } catch (e) {
           if (e instanceof FetchBackoffAbortError) break // interrupted
@@ -231,6 +256,11 @@ export class ShapeStream<T extends Row = Row>
           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) : {}
@@ -359,6 +389,7 @@ export class ShapeStream<T extends Row = Row>
    */
   #reset(shapeId?: string) {
     this.#lastOffset = `-1`
+    this.#liveCacheBuster = ``
     this.#shapeId = shapeId
     this.#isUpToDate = false
     this.#connected = false
@@ -366,7 +397,7 @@ export class ShapeStream<T extends Row = Row>
   }
 }
 
-function validateOptions(options: Partial<ShapeStreamOptions>): void {
+function validateOptions<T>(options: Partial<ShapeStreamOptions<T>>): void {
   if (!options.url) {
     throw new Error(`Invalid shape option. It must provide the url`)
   }

package/src/constants.ts

@@ -1,4 +1,6 @@
 export const SHAPE_ID_HEADER = `electric-shape-id`
+export const LIVE_CACHE_BUSTER_HEADER = `electric-next-cursor`
+export const LIVE_CACHE_BUSTER_QUERY_PARAM = `cursor`
 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`

package/src/fetch.ts

@@ -8,6 +8,10 @@ import {
 } from './constants'
 import { FetchError, FetchBackoffAbortError } from './error'
 
+// Some specific 4xx and 5xx HTTP status codes that we definitely
+// want to retry
+const HTTP_RETRY_STATUS_CODES = [429]
+
 export interface BackoffOptions {
   /**
    * Initial delay before retrying in milliseconds
@@ -63,6 +67,7 @@ export function createFetchWithBackoff(
           throw new FetchBackoffAbortError()
         } else if (
           e instanceof FetchError &&
+          !HTTP_RETRY_STATUS_CODES.includes(e.status) &&
           e.status >= 400 &&
           e.status < 500
         ) {

package/src/helpers.ts

@@ -17,7 +17,7 @@ import { ChangeMessage, ControlMessage, Message, Row } from './types'
  * }
  * ```
  */
-export function isChangeMessage<T extends Row = Row>(
+export function isChangeMessage<T extends Row<unknown> = Row>(
   message: Message<T>
 ): message is ChangeMessage<T> {
   return `key` in message
@@ -40,13 +40,13 @@ export function isChangeMessage<T extends Row = Row>(
  * }
  * ```
  */
-export function isControlMessage<T extends Row = Row>(
+export function isControlMessage<T extends Row<unknown> = Row>(
   message: Message<T>
 ): message is ControlMessage {
   return !isChangeMessage(message)
 }
 
-export function isUpToDateMessage<T extends Row = Row>(
+export function isUpToDateMessage<T extends Row<unknown> = Row>(
   message: Message<T>
 ): message is ControlMessage & { up_to_date: true } {
   return isControlMessage(message) && message.headers.control === `up-to-date`

package/src/parser.ts

@@ -1,17 +1,23 @@
-import { ColumnInfo, Message, Row, Schema, Value } from './types'
+import { ColumnInfo, GetExtensions, Message, Row, Schema, Value } from './types'
 
 type NullToken = null | `NULL`
 type Token = Exclude<string, NullToken>
 type NullableToken = Token | NullToken
-export type ParseFunction = (
+export type ParseFunction<Extensions = never> = (
   value: Token,
   additionalInfo?: Omit<ColumnInfo, `type` | `dims`>
-) => Value
-type NullableParseFunction = (
+) => Value<Extensions>
+type NullableParseFunction<Extensions = never> = (
   value: NullableToken,
   additionalInfo?: Omit<ColumnInfo, `type` | `dims`>
-) => Value
-export type Parser = { [key: string]: ParseFunction }
+) => Value<Extensions>
+/**
+ * @typeParam Extensions - Additional types that can be parsed by this parser beyond the standard SQL types.
+ *                         Defaults to no additional types.
+ */
+export type Parser<Extensions = never> = {
+  [key: string]: ParseFunction<Extensions>
+}
 
 const parseNumber = (value: string) => Number(value)
 const parseBool = (value: string) => value === `true` || value === `t`
@@ -31,7 +37,10 @@ export const defaultParser: Parser = {
 }
 
 // Taken from: https://github.com/electric-sql/pglite/blob/main/packages/pglite/src/types.ts#L233-L279
-export function pgArrayParser(value: Token, parser?: ParseFunction): Value {
+export function pgArrayParser<Extensions>(
+  value: Token,
+  parser?: ParseFunction<Extensions>
+): Value<Extensions> {
   let i = 0
   let char = null
   let str = ``
@@ -39,7 +48,7 @@ export function pgArrayParser(value: Token, parser?: ParseFunction): Value {
   let last = 0
   let p: string | undefined = undefined
 
-  function loop(x: string): Value[] {
+  function loop(x: string): Array<Value<Extensions>> {
     const xs = []
     for (; i < x.length; i++) {
       char = x[i]
@@ -79,9 +88,9 @@ export function pgArrayParser(value: Token, parser?: ParseFunction): Value {
   return loop(value)[0]
 }
 
-export class MessageParser<T extends Row> {
-  private parser: Parser
-  constructor(parser?: Parser) {
+export class MessageParser<T extends Row<unknown>> {
+  private parser: Parser<GetExtensions<T>>
+  constructor(parser?: Parser<GetExtensions<T>>) {
     // Merge the provided parser with the default parser
     // to use the provided parser whenever defined
     // and otherwise fall back to the default parser
@@ -96,7 +105,7 @@ export class MessageParser<T extends Row> {
       // But `typeof null === 'object'` so we need to make an explicit check.
       if (key === `value` && typeof value === `object` && value !== null) {
         // Parse the row values
-        const row = value as Record<string, Value>
+        const row = value as Record<string, Value<GetExtensions<T>>>
         Object.keys(row).forEach((key) => {
           row[key] = this.parseRow(key, row[key] as NullableToken, schema)
         })
@@ -106,7 +115,11 @@ export class MessageParser<T extends Row> {
   }
 
   // Parses the message values using the provided parser based on the schema information
-  private parseRow(key: string, value: NullableToken, schema: Schema): Value {
+  private parseRow(
+    key: string,
+    value: NullableToken,
+    schema: Schema
+  ): Value<GetExtensions<T>> {
     const columnInfo = schema[key]
     if (!columnInfo) {
       // We don't have information about the value
@@ -137,11 +150,11 @@ export class MessageParser<T extends Row> {
   }
 }
 
-function makeNullableParser(
-  parser: ParseFunction,
+function makeNullableParser<Extensions>(
+  parser: ParseFunction<Extensions>,
   columnInfo: ColumnInfo,
   columnName?: string
-): NullableParseFunction {
+): NullableParseFunction<Extensions> {
   const isNullable = !(columnInfo.not_null ?? false)
   // The sync service contains `null` value for a column whose value is NULL
   // but if the column value is an array that contains a NULL value

package/src/shape.ts

@@ -3,8 +3,8 @@ 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> = (
+export type ShapeData<T extends Row<unknown> = Row> = Map<string, T>
+export type ShapeChangedCallback<T extends Row<unknown> = Row> = (
   value: ShapeData<T>
 ) => void
 
@@ -39,7 +39,7 @@ export type ShapeChangedCallback<T extends Row = Row> = (
  *       console.log(shapeData)
  *     })
  */
-export class Shape<T extends Row = Row> {
+export class Shape<T extends Row<unknown> = Row> {
   readonly #stream: ShapeStreamInterface<T>
 
   readonly #data: ShapeData<T> = new Map()

package/src/types.ts

@@ -1,13 +1,21 @@
-export type Value =
+/**
+ * Default types for SQL but can be extended with additional types when using a custom parser.
+ * @typeParam Extensions - Additional value types.
+ */
+export type Value<Extensions = never> =
   | string
   | number
   | boolean
   | bigint
   | null
-  | Value[]
-  | { [key: string]: Value }
+  | Extensions
+  | Value<Extensions>[]
+  | { [key: string]: Value<Extensions> }
+
+export type Row<Extensions = never> = Record<string, Value<Extensions>>
 
-export type Row = { [key: string]: Value }
+export type GetExtensions<T extends Row<unknown>> =
+  T extends Row<infer Extensions> ? Extensions : never
 
 export type Offset = `-1` | `${number}_${number}`
 
@@ -19,7 +27,7 @@ export type ControlMessage = {
   headers: Header & { control: `up-to-date` | `must-refetch` }
 }
 
-export type ChangeMessage<T extends Row = Row> = {
+export type ChangeMessage<T extends Row<unknown> = Row> = {
   key: string
   value: T
   headers: Header & { operation: `insert` | `update` | `delete` }
@@ -27,7 +35,9 @@ export type ChangeMessage<T extends Row = Row> = {
 }
 
 // Define the type for a record
-export type Message<T extends Row = Row> = ControlMessage | ChangeMessage<T>
+export type Message<T extends Row<unknown> = Row> =
+  | ControlMessage
+  | ChangeMessage<T>
 
 /**
  * Common properties for all columns.
@@ -104,7 +114,7 @@ export type ColumnInfo =
 
 export type Schema = { [key: string]: ColumnInfo }
 
-export type TypedMessages<T extends Row = Row> = {
+export type TypedMessages<T extends Row<unknown> = Row> = {
   messages: Array<Message<T>>
   schema: ColumnInfo
 }