@electric-sql/client 1.0.9 → 1.0.10

package/src/client.ts

@@ -6,7 +6,7 @@ import {
   MaybePromise,
   GetExtensions,
 } from './types'
-import { MessageParser, Parser } from './parser'
+import { MessageParser, Parser, TransformFunction } from './parser'
 import { getOffset, isUpToDateMessage } from './helpers'
 import {
   FetchError,
@@ -28,6 +28,7 @@ import {
   CHUNK_LAST_OFFSET_HEADER,
   LIVE_CACHE_BUSTER_HEADER,
   LIVE_CACHE_BUSTER_QUERY_PARAM,
+  EXPIRED_HANDLE_QUERY_PARAM,
   COLUMNS_QUERY_PARAM,
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
@@ -41,11 +42,13 @@ import {
   FORCE_DISCONNECT_AND_REFRESH,
   PAUSE_STREAM,
   EXPERIMENTAL_LIVE_SSE_QUERY_PARAM,
+  ELECTRIC_PROTOCOL_QUERY_PARAMS,
 } from './constants'
 import {
   EventSourceMessage,
   fetchEventSource,
 } from '@microsoft/fetch-event-source'
+import { expiredShapesCache } from './expired-shapes-cache'
 
 const RESERVED_PARAMS: Set<ReservedParamKeys> = new Set([
   LIVE_CACHE_BUSTER_QUERY_PARAM,
@@ -259,6 +262,7 @@ export interface ShapeStreamOptions<T = never> {
   fetchClient?: typeof fetch
   backoffOptions?: BackoffOptions
   parser?: Parser<T>
+  transformer?: TransformFunction<T>
 
   /**
    * A function for handling shapestream errors.
@@ -293,6 +297,23 @@ export interface ShapeStreamInterface<T extends Row<unknown> = Row> {
   forceDisconnectAndRefresh(): Promise<void>
 }
 
+/**
+ * Creates a canonical shape key from a URL excluding only Electric protocol parameters
+ */
+function canonicalShapeKey(url: URL): string {
+  const cleanUrl = new URL(url.origin + url.pathname)
+
+  // Copy all params except Electric protocol ones that vary between requests
+  for (const [key, value] of url.searchParams) {
+    if (!ELECTRIC_PROTOCOL_QUERY_PARAMS.includes(key)) {
+      cleanUrl.searchParams.set(key, value)
+    }
+  }
+
+  cleanUrl.searchParams.sort()
+  return cleanUrl.toString()
+}
+
 /**
  * Reads updates to a shape from Electric using HTTP requests and long polling or
  * Server-Sent Events (SSE).
@@ -379,7 +400,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
     this.#lastOffset = this.options.offset ?? `-1`
     this.#liveCacheBuster = ``
     this.#shapeHandle = this.options.handle
-    this.#messageParser = new MessageParser<T>(options.parser)
+    this.#messageParser = new MessageParser<T>(
+      options.parser,
+      options.transformer
+    )
     this.#onError = this.options.onError
 
     const baseFetchClient =
@@ -517,6 +541,13 @@ export class ShapeStream<T extends Row<unknown> = Row>
         // with the newly provided shape handle, or a fallback
         // pseudo-handle based on the current one to act as a
         // consistent cache buster
+
+        // Store the current shape URL as expired to avoid future 409s
+        if (this.#shapeHandle) {
+          const shapeKey = canonicalShapeKey(fetchUrl)
+          expiredShapesCache.markExpired(shapeKey, this.#shapeHandle)
+        }
+
         const newShapeHandle =
           e.headers[SHAPE_HANDLE_HEADER] || `${this.#shapeHandle!}-next`
         this.#reset(newShapeHandle)
@@ -602,6 +633,13 @@ export class ShapeStream<T extends Row<unknown> = Row>
       fetchUrl.searchParams.set(SHAPE_HANDLE_QUERY_PARAM, this.#shapeHandle!)
     }
 
+    // Add cache buster for shapes known to be expired to prevent 409s
+    const shapeKey = canonicalShapeKey(fetchUrl)
+    const expiredHandle = expiredShapesCache.getExpiredHandle(shapeKey)
+    if (expiredHandle) {
+      fetchUrl.searchParams.set(EXPIRED_HANDLE_QUERY_PARAM, expiredHandle)
+    }
+
     // sort query params in-place for stable URLs and improved cache hits
     fetchUrl.searchParams.sort()
 

package/src/constants.ts

@@ -5,6 +5,7 @@ export const SHAPE_SCHEMA_HEADER = `electric-schema`
 export const CHUNK_UP_TO_DATE_HEADER = `electric-up-to-date`
 export const COLUMNS_QUERY_PARAM = `columns`
 export const LIVE_CACHE_BUSTER_QUERY_PARAM = `cursor`
+export const EXPIRED_HANDLE_QUERY_PARAM = `expired_handle`
 export const SHAPE_HANDLE_QUERY_PARAM = `handle`
 export const LIVE_QUERY_PARAM = `live`
 export const OFFSET_QUERY_PARAM = `offset`
@@ -22,4 +23,5 @@ export const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string> = [
   SHAPE_HANDLE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   LIVE_CACHE_BUSTER_QUERY_PARAM,
+  EXPIRED_HANDLE_QUERY_PARAM,
 ]

package/src/expired-shapes-cache.ts

@@ -0,0 +1,72 @@
+interface ExpiredShapeCacheEntry {
+  expiredHandle: string
+  lastUsed: number
+}
+
+/**
+ * LRU cache for tracking expired shapes with automatic cleanup
+ */
+export class ExpiredShapesCache {
+  private data: Record<string, ExpiredShapeCacheEntry> = {}
+  private max: number = 250
+  private readonly storageKey = `electric_expired_shapes`
+
+  getExpiredHandle(shapeUrl: string): string | null {
+    const entry = this.data[shapeUrl]
+    if (entry) {
+      // Update last used time when accessed
+      entry.lastUsed = Date.now()
+      this.save()
+      return entry.expiredHandle
+    }
+    return null
+  }
+
+  markExpired(shapeUrl: string, handle: string): void {
+    this.data[shapeUrl] = { expiredHandle: handle, lastUsed: Date.now() }
+
+    const keys = Object.keys(this.data)
+    if (keys.length > this.max) {
+      const oldest = keys.reduce((min, k) =>
+        this.data[k].lastUsed < this.data[min].lastUsed ? k : min
+      )
+      delete this.data[oldest]
+    }
+
+    this.save()
+  }
+
+  private save(): void {
+    if (typeof localStorage === `undefined`) return
+    try {
+      localStorage.setItem(this.storageKey, JSON.stringify(this.data))
+    } catch {
+      // Ignore localStorage errors
+    }
+  }
+
+  private load(): void {
+    if (typeof localStorage === `undefined`) return
+    try {
+      const stored = localStorage.getItem(this.storageKey)
+      if (stored) {
+        this.data = JSON.parse(stored)
+      }
+    } catch {
+      // Ignore localStorage errors, start fresh
+      this.data = {}
+    }
+  }
+
+  constructor() {
+    this.load()
+  }
+
+  clear(): void {
+    this.data = {}
+    this.save()
+  }
+}
+
+// Module-level singleton instance
+export const expiredShapesCache = new ExpiredShapesCache()

package/src/parser.ts

@@ -19,6 +19,10 @@ export type Parser<Extensions = never> = {
   [key: string]: ParseFunction<Extensions>
 }
 
+export type TransformFunction<Extensions = never> = (
+  message: Row<Extensions>
+) => Row<Extensions>
+
 const parseNumber = (value: string) => Number(value)
 const parseBool = (value: string) => value === `true` || value === `t`
 const parseBigInt = (value: string) => BigInt(value)
@@ -94,11 +98,16 @@ export function pgArrayParser<Extensions>(
 
 export class MessageParser<T extends Row<unknown>> {
   private parser: Parser<GetExtensions<T>>
-  constructor(parser?: Parser<GetExtensions<T>>) {
+  private transformer?: TransformFunction<GetExtensions<T>>
+  constructor(
+    parser?: Parser<GetExtensions<T>>,
+    transformer?: TransformFunction<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
     this.parser = { ...defaultParser, ...parser }
+    this.transformer = transformer
   }
 
   parse<Result>(messages: string, schema: Schema): Result {
@@ -118,6 +127,8 @@ export class MessageParser<T extends Row<unknown>> {
         Object.keys(row).forEach((key) => {
           row[key] = this.parseRow(key, row[key] as NullableToken, schema)
         })
+
+        if (this.transformer) value = this.transformer(value)
       }
       return value
     }) as Result

package/src/types.ts

@@ -14,8 +14,14 @@ export type Value<Extensions = never> =
 
 export type Row<Extensions = never> = Record<string, Value<Extensions>>
 
-export type GetExtensions<T extends Row<unknown>> =
-  T extends Row<infer Extensions> ? Extensions : never
+// Check if `T` extends the base Row type without extensions
+// if yes, it has no extensions so we return `never`
+// otherwise, we infer the extensions from the Row type
+export type GetExtensions<T> = [T] extends [Row<never>]
+  ? never
+  : [T] extends [Row<infer E>]
+    ? E
+    : never
 
 export type Offset = `-1` | `${number}_${number}` | `${bigint}_${number}`