@electric-sql/client 0.6.1 → 0.6.3

package/src/client.ts

@@ -17,6 +17,9 @@ import {
 } from './fetch'
 import {
   CHUNK_LAST_OFFSET_HEADER,
+  LIVE_CACHE_BUSTER_HEADER,
+  LIVE_CACHE_BUSTER_QUERY_PARAM,
+  COLUMNS_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   SHAPE_ID_HEADER,
@@ -35,9 +38,16 @@ export interface ShapeStreamOptions<T = never> {
    */
   url: string
   /**
-   * where clauses for the shape.
+   * The where clauses for the shape.
    */
   where?: string
+
+  /**
+   * The columns to include in the shape.
+   * Must include primary keys, and can only inlude valid columns.
+   */
+  columns?: string[]
+
   /**
    * 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
@@ -143,6 +153,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   >()
 
   #lastOffset: Offset
+  #liveCacheBuster: string // Seconds since our Electric Epoch 😎
   #lastSyncedAt?: number // unix time
   #isUpToDate: boolean = false
   #connected: boolean = false
@@ -153,6 +164,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
     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)
 
@@ -184,7 +196,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   async start() {
     this.#isUpToDate = false
 
-    const { url, where, signal } = this.options
+    const { url, where, columns, signal } = this.options
 
     try {
       while (
@@ -193,10 +205,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
       ) {
         const fetchUrl = new URL(url)
         if (where) fetchUrl.searchParams.set(WHERE_QUERY_PARAM, where)
+        if (columns && columns.length > 0)
+          fetchUrl.searchParams.set(COLUMNS_QUERY_PARAM, columns.join(`,`))
         fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, this.#lastOffset)
 
         if (this.#isUpToDate) {
           fetchUrl.searchParams.set(LIVE_QUERY_PARAM, `true`)
+          fetchUrl.searchParams.set(
+            LIVE_CACHE_BUSTER_QUERY_PARAM,
+            this.#liveCacheBuster
+          )
         }
 
         if (this.#shapeId) {
@@ -248,6 +266,11 @@ export class ShapeStream<T extends Row<unknown> = 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) : {}
@@ -376,6 +399,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
    */
   #reset(shapeId?: string) {
     this.#lastOffset = `-1`
+    this.#liveCacheBuster = ``
     this.#shapeId = shapeId
     this.#isUpToDate = false
     this.#connected = false

package/src/constants.ts

@@ -1,8 +1,11 @@
 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`
 export const SHAPE_ID_QUERY_PARAM = `shape_id`
 export const OFFSET_QUERY_PARAM = `offset`
 export const WHERE_QUERY_PARAM = `where`
+export const COLUMNS_QUERY_PARAM = `columns`
 export const LIVE_QUERY_PARAM = `live`

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
         ) {