feat: Add client-side cache buster for expired shapes to prevent 409s (#3103)

## Summary
- Implements client-side caching of 409'd shapes using localStorage
- Adds cache_buster parameter to prevent redundant 409 responses  
- Reduces app loading latency when shapes expire

## Changes
- Add `SHAPE_CACHE_BUSTER_QUERY_PARAM` constant for expired shape
requests
- Store expired shape handles in localStorage when 409 responses occur
- Check for expired shapes during URL construction and add cache buster
- Gracefully handle localStorage availability and errors

## Test plan
- [ ] Test 409 response handling stores shape in localStorage
- [ ] Verify subsequent requests include cache_buster parameter
- [ ] Confirm behavior works correctly when localStorage unavailable
- [ ] Test multiple expired shapes don't interfere with each other

Fixes #3100

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: KyleAMathews

.changeset/wicked-moments-study.md

@@ -0,0 +1,7 @@
+---
+"@electric-sql/client": patch
+---
+
+Add client-side cache buster for expired shapes to prevent 409s
+
+When a shape 409s, the client now stores this information in localStorage and adds a `expired_handle` parameter to future requests for that shape, preventing redundant 409 responses and reducing app loading latency.

packages/typescript-client/package.json

@@ -21,13 +21,15 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.1.3",
     "glob": "^10.3.10",
+    "jsdom": "^26.1.0",
     "pg": "^8.12.0",
     "prettier": "^3.3.2",
     "shx": "^0.3.4",
     "tsup": "^8.0.1",
     "typescript": "^5.5.2",
     "uuid": "^10.0.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "vitest-localstorage-mock": "^0.1.2"
   },
   "type": "module",
   "exports": {

packages/typescript-client/src/client.ts

@@ -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,
@@ -294,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).
@@ -521,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)
@@ -606,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()
 

packages/typescript-client/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,
 ]

packages/typescript-client/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()