@electric-sql/client 0.6.4 → 0.7.0

package/src/client.ts

@@ -22,21 +22,38 @@ import {
   COLUMNS_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
-  SHAPE_ID_HEADER,
-  SHAPE_ID_QUERY_PARAM,
+  SHAPE_HANDLE_HEADER,
+  SHAPE_HANDLE_QUERY_PARAM,
   SHAPE_SCHEMA_HEADER,
   WHERE_QUERY_PARAM,
+  DATABASE_ID_QUERY_PARAM,
+  TABLE_QUERY_PARAM,
+  REPLICA_PARAM,
 } from './constants'
 
+type Replica = `full` | `default`
+
 /**
  * Options for constructing a ShapeStream.
  */
 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`
+   * The full URL to where the Shape is served. 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`
    */
   url: string
+
+  /**
+   * Which database to use.
+   * This is optional unless Electric is used with multiple databases.
+   */
+  databaseId?: string
+
+  /**
+   * The root table for the shape.
+   */
+  table: string
+
   /**
    * The where clauses for the shape.
    */
@@ -48,12 +65,23 @@ export interface ShapeStreamOptions<T = never> {
    */
   columns?: string[]
 
+  /**
+   * If `replica` is `default` (the default) then Electric will only send the
+   * changed columns in an update.
+   *
+   * If it's `full` Electric will send the entire row with both changed and
+   * unchanged values.
+   *
+   * Setting `replica` to `full` will obviously result in higher bandwidth
+   * usage and so is not recommended.
+   */
+  replica?: Replica
   /**
    * The "offset" on the shape log. This is typically not set as the ShapeStream
    * will handle this automatically. A common scenario where you might pass an offset
    * is if you're maintaining a local cache of the log. If you've gone offline
    * and are re-starting a ShapeStream to catch-up to the latest state of the Shape,
-   * you'd pass in the last offset and shapeId you'd seen from the Electric server
+   * you'd pass in the last offset and shapeHandle you'd seen from the Electric server
    * so it knows at what point in the shape to catch you up from.
    */
   offset?: Offset
@@ -61,7 +89,7 @@ export interface ShapeStreamOptions<T = never> {
    * Similar to `offset`, this isn't typically used unless you're maintaining
    * a cache of the shape log.
    */
-  shapeId?: string
+  shapeHandle?: string
   backoffOptions?: BackoffOptions
 
   /**
@@ -98,7 +126,7 @@ export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
   isConnected(): boolean
 
   isUpToDate: boolean
-  shapeId?: string
+  shapeHandle?: string
 }
 
 /**
@@ -135,6 +163,11 @@ export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
 export class ShapeStream<T extends Row<unknown> = Row>
   implements ShapeStreamInterface<T>
 {
+  static readonly Replica = {
+    FULL: `full` as Replica,
+    DEFAULT: `default` as Replica,
+  }
+
   readonly options: ShapeStreamOptions<GetExtensions<T>>
 
   readonly #fetchClient: typeof fetch
@@ -157,16 +190,21 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #lastSyncedAt?: number // unix time
   #isUpToDate: boolean = false
   #connected: boolean = false
-  #shapeId?: string
+  #shapeHandle?: string
+  #databaseId?: string
   #schema?: Schema
+  #error?: unknown
+  #replica?: Replica
 
   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.#shapeHandle = this.options.shapeHandle
+    this.#databaseId = this.options.databaseId
     this.#messageParser = new MessageParser<T>(options.parser)
+    this.#replica = this.options.replica
 
     const baseFetchClient =
       options.fetchClient ??
@@ -185,18 +223,22 @@ export class ShapeStream<T extends Row<unknown> = Row>
     this.start()
   }
 
-  get shapeId() {
-    return this.#shapeId
+  get shapeHandle() {
+    return this.#shapeHandle
   }
 
   get isUpToDate() {
     return this.#isUpToDate
   }
 
+  get error() {
+    return this.#error
+  }
+
   async start() {
     this.#isUpToDate = false
 
-    const { url, where, columns, signal } = this.options
+    const { url, table, where, columns, signal } = this.options
 
     try {
       while (
@@ -204,6 +246,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
         this.options.subscribe
       ) {
         const fetchUrl = new URL(url)
+        fetchUrl.searchParams.set(TABLE_QUERY_PARAM, table)
         if (where) fetchUrl.searchParams.set(WHERE_QUERY_PARAM, where)
         if (columns && columns.length > 0)
           fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, columns.join(`,`))
@@ -217,9 +260,23 @@ export class ShapeStream<T extends Row<unknown> = Row>
           )
         }
 
-        if (this.#shapeId) {
+        if (this.#shapeHandle) {
           // This should probably be a header for better cache breaking?
-          fetchUrl.searchParams.set(SHAPE_ID_QUERY_PARAM, this.#shapeId!)
+          fetchUrl.searchParams.set(
+            SHAPE_HANDLE_QUERY_PARAM,
+            this.#shapeHandle!
+          )
+        }
+
+        if (this.#databaseId) {
+          fetchUrl.searchParams.set(DATABASE_ID_QUERY_PARAM, this.#databaseId!)
+        }
+
+        if (
+          (this.#replica ?? ShapeStream.Replica.DEFAULT) !=
+          ShapeStream.Replica.DEFAULT
+        ) {
+          fetchUrl.searchParams.set(REPLICA_PARAM, this.#replica as string)
         }
 
         let response!: Response
@@ -232,17 +289,11 @@ export class ShapeStream<T extends Row<unknown> = Row>
         } catch (e) {
           if (e instanceof FetchBackoffAbortError) break // interrupted
           if (!(e instanceof FetchError)) throw e // should never happen
-          if (e.status == 400) {
-            // The request is invalid, most likely because the shape has been deleted.
-            // We should start from scratch, this will force the shape to be recreated.
-            this.#reset()
-            await this.#publish(e.json as Message<T>[])
-            continue
-          } else if (e.status == 409) {
+          if (e.status == 409) {
             // Upon receiving a 409, we should start from scratch
-            // with the newly provided shape ID
-            const newShapeId = e.headers[SHAPE_ID_HEADER]
-            this.#reset(newShapeId)
+            // 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 if (e.status >= 400 && e.status < 500) {
@@ -250,15 +301,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
             this.#sendErrorToUpToDateSubscribers(e)
             this.#sendErrorToSubscribers(e)
 
-            // 400 errors are not actionable without additional user input, so we're throwing them.
+            // 400 errors are not actionable without additional user input,
+            // so we exit the loop
             throw e
           }
         }
 
         const { headers, status } = response
-        const shapeId = headers.get(SHAPE_ID_HEADER)
-        if (shapeId) {
-          this.#shapeId = shapeId
+        const shapeHandle = headers.get(SHAPE_HANDLE_HEADER)
+        if (shapeHandle) {
+          this.#shapeHandle = shapeHandle
         }
 
         const lastOffset = headers.get(CHUNK_LAST_OFFSET_HEADER)
@@ -301,6 +353,8 @@ export class ShapeStream<T extends Row<unknown> = Row>
           }
         }
       }
+    } catch (err) {
+      this.#error = err
     } finally {
       this.#connected = false
     }
@@ -395,12 +449,12 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
   /**
    * Resets the state of the stream, optionally with a provided
-   * shape ID
+   * shape handle
    */
-  #reset(shapeId?: string) {
+  #reset(shapeHandle?: string) {
     this.#lastOffset = `-1`
     this.#liveCacheBuster = ``
-    this.#shapeId = shapeId
+    this.#shapeHandle = shapeHandle
     this.#isUpToDate = false
     this.#connected = false
     this.#schema = undefined
@@ -409,7 +463,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
 function validateOptions<T>(options: Partial<ShapeStreamOptions<T>>): void {
   if (!options.url) {
-    throw new Error(`Invalid shape option. It must provide the url`)
+    throw new Error(`Invalid shape options. It must provide the url`)
+  }
+  if (!options.table) {
+    throw new Error(`Invalid shape options. It must provide the table`)
   }
   if (options.signal && !(options.signal instanceof AbortSignal)) {
     throw new Error(
@@ -420,10 +477,10 @@ function validateOptions<T>(options: Partial<ShapeStreamOptions<T>>): void {
   if (
     options.offset !== undefined &&
     options.offset !== `-1` &&
-    !options.shapeId
+    !options.shapeHandle
   ) {
     throw new Error(
-      `shapeId is required if this isn't an initial fetch (i.e. offset > -1)`
+      `shapeHandle is required if this isn't an initial fetch (i.e. offset > -1)`
     )
   }
   return

package/src/constants.ts

@@ -1,11 +1,14 @@
-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 LIVE_CACHE_BUSTER_HEADER = `electric-cursor`
+export const SHAPE_HANDLE_HEADER = `electric-handle`
+export const CHUNK_LAST_OFFSET_HEADER = `electric-offset`
 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 CHUNK_UP_TO_DATE_HEADER = `electric-up-to-date`
+export const DATABASE_ID_QUERY_PARAM = `database_id`
 export const COLUMNS_QUERY_PARAM = `columns`
+export const LIVE_CACHE_BUSTER_QUERY_PARAM = `cursor`
+export const SHAPE_HANDLE_QUERY_PARAM = `handle`
 export const LIVE_QUERY_PARAM = `live`
+export const OFFSET_QUERY_PARAM = `offset`
+export const TABLE_QUERY_PARAM = `table`
+export const WHERE_QUERY_PARAM = `where`
+export const REPLICA_PARAM = `replica`

package/src/fetch.ts

@@ -3,8 +3,8 @@ import {
   CHUNK_UP_TO_DATE_HEADER,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
-  SHAPE_ID_HEADER,
-  SHAPE_ID_QUERY_PARAM,
+  SHAPE_HANDLE_HEADER,
+  SHAPE_HANDLE_QUERY_PARAM,
 } from './constants'
 import { FetchError, FetchBackoffAbortError } from './error'
 
@@ -245,13 +245,13 @@ class PrefetchQueue {
  * 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 shapeHandle = res.headers.get(SHAPE_HANDLE_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
+  // only prefetch if shape handle and offset for next chunk are available, and
   // response is not already up-to-date
-  if (!shapeId || !lastOffset || isUpToDate) return
+  if (!shapeHandle || !lastOffset || isUpToDate) return
 
   const nextUrl = new URL(url)
 
@@ -259,7 +259,7 @@ function getNextChunkUrl(url: string, res: Response): string | void {
   // potentially miss more recent data
   if (nextUrl.searchParams.has(LIVE_QUERY_PARAM)) return
 
-  nextUrl.searchParams.set(SHAPE_ID_QUERY_PARAM, shapeId)
+  nextUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, shapeHandle)
   nextUrl.searchParams.set(OFFSET_QUERY_PARAM, lastOffset)
   return nextUrl.toString()
 }
@@ -271,7 +271,7 @@ function getNextChunkUrl(url: string, res: Response): string | void {
  */
 function chainAborter(
   aborter: AbortController,
-  sourceSignal?: AbortSignal
+  sourceSignal?: AbortSignal | null
 ): AbortSignal {
   if (!sourceSignal) return aborter.signal
   if (sourceSignal.aborted) aborter.abort()

package/src/shape.ts

@@ -4,13 +4,14 @@ import { FetchError } from './error'
 import { ShapeStreamInterface } from './client'
 
 export type ShapeData<T extends Row<unknown> = Row> = Map<string, T>
-export type ShapeChangedCallback<T extends Row<unknown> = Row> = (
+export type ShapeChangedCallback<T extends Row<unknown> = Row> = (data: {
   value: ShapeData<T>
-) => void
+  rows: T[]
+}) => void
 
 /**
  * A Shape is an object that subscribes to a shape log,
- * keeps a materialised shape `.value` in memory and
+ * keeps a materialised shape `.rows` in memory and
  * notifies subscribers when the value has changed.
  *
  * It can be used without a framework and as a primitive
@@ -20,23 +21,23 @@ export type ShapeChangedCallback<T extends Row<unknown> = Row> = (
  * @param {ShapeStream<T extends Row>} - the underlying shape stream
  * @example
  * ```
- * const shapeStream = new ShapeStream<{ foo: number }>(url: 'http://localhost:3000/v1/shape/foo'})
+ * const shapeStream = new ShapeStream<{ foo: number }>(url: `http://localhost:3000/v1/shape`, table: `foo`})
  * const shape = new Shape(shapeStream)
  * ```
  *
- * `value` returns a promise that resolves the Shape data once the Shape has been
+ * `rows` 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
+ *     const rows = await shape.rows
  *
- * `valueSync` returns the current data synchronously:
+ * `currentRows` returns the current data synchronously:
  *
- *     const value = shape.valueSync
+ *     const rows = shape.currentRows
  *
  *  Subscribe to updates. Called whenever the shape updates in Postgres.
  *
- *     shape.subscribe(shapeData => {
- *       console.log(shapeData)
+ *     shape.subscribe(({ rows }) => {
+ *       console.log(rows)
  *     })
  */
 export class Shape<T extends Row<unknown> = Row> {
@@ -69,21 +70,29 @@ export class Shape<T extends Row<unknown> = Row> {
     return this.#stream.isUpToDate
   }
 
+  get rows(): Promise<T[]> {
+    return this.value.then((v) => Array.from(v.values()))
+  }
+
+  get currentRows(): T[] {
+    return Array.from(this.currentValue.values())
+  }
+
   get value(): Promise<ShapeData<T>> {
     return new Promise((resolve, reject) => {
       if (this.#stream.isUpToDate) {
-        resolve(this.valueSync)
+        resolve(this.currentValue)
       } else {
-        const unsubscribe = this.subscribe((shapeData) => {
+        const unsubscribe = this.subscribe(({ value }) => {
           unsubscribe()
           if (this.#error) reject(this.#error)
-          resolve(shapeData)
+          resolve(value)
         })
       }
     })
   }
 
-  get valueSync() {
+  get currentValue() {
     return this.#data
   }
 
@@ -192,7 +201,7 @@ export class Shape<T extends Row<unknown> = Row> {
 
   #notify(): void {
     this.#subscribers.forEach((callback) => {
-      callback(this.valueSync)
+      callback({ value: this.currentValue, rows: this.currentRows })
     })
   }
 }