fix(client): stop ExpiredShapesCache writing to localStorage on every read

.changeset/expired-shapes-cache-read-write.md

@@ -0,0 +1,10 @@
+---
+'@electric-sql/client': patch
+---
+
+Stop `ExpiredShapesCache.getExpiredHandle` writing the whole cache to
+`localStorage` on every read. The LRU touch it performs runs while building the
+URL of every shape request, so in live mode it persisted the entire cache once
+per poll for as long as the app stayed open. `lastUsed` is now updated in memory
+only; it is read from memory when `markExpired` picks an eviction candidate, so
+the sole effect is that eviction order can be staler after a reload.

packages/typescript-client/src/expired-shapes-cache.ts

@@ -14,9 +14,9 @@ export class ExpiredShapesCache {
   getExpiredHandle(shapeUrl: string): string | null {
     const entry = this.data[shapeUrl]
     if (entry) {
-      // Update last used time when accessed
+      // Not persisted: this runs on every shape request, and markExpired reads
+      // lastUsed from memory.
       entry.lastUsed = Date.now()
-      this.save()
       return entry.expiredHandle
     }
     return null

packages/typescript-client/test/expired-shapes-cache.test.ts

@@ -1312,3 +1312,85 @@ describe(`ExpiredShapesCache`, () => {
     expect(snapshotHasCacheBuster).toBe(false)
   })
 })
+
+describe(`ExpiredShapesCache write amplification`, () => {
+  const shapeUrl = `https://example.com/v1/shape?table=test`
+
+  beforeEach(() => {
+    localStorage.clear()
+    vi.restoreAllMocks()
+  })
+
+  // setItem is a persistent mock whose history survives restoreAllMocks.
+  function countWrites(): { calls: () => number } {
+    const spy = vi.spyOn(localStorage, `setItem`)
+    const base = spy.mock.calls.length
+    return { calls: () => spy.mock.calls.length - base }
+  }
+
+  it(`counts a write when the cache is mutated`, () => {
+    const cache = new ExpiredShapesCache()
+    const writes = countWrites()
+    cache.markExpired(shapeUrl, `handle-1`)
+    expect(writes.calls()).toBe(1)
+  })
+
+  it(`does not write to localStorage when reading an existing entry`, () => {
+    const cache = new ExpiredShapesCache()
+    cache.markExpired(shapeUrl, `handle-1`)
+
+    const writes = countWrites()
+    for (let i = 0; i < 25; i++) {
+      expect(cache.getExpiredHandle(shapeUrl)).toBe(`handle-1`)
+    }
+
+    expect(writes.calls()).toBe(0)
+  })
+
+  it(`does not write to localStorage when reading a missing entry`, () => {
+    const cache = new ExpiredShapesCache()
+
+    const writes = countWrites()
+    expect(cache.getExpiredHandle(shapeUrl)).toBe(null)
+
+    expect(writes.calls()).toBe(0)
+  })
+
+  it(`still persists the entry so a later cache reloads it`, () => {
+    const cache = new ExpiredShapesCache()
+    cache.markExpired(shapeUrl, `handle-1`)
+    for (let i = 0; i < 25; i++) cache.getExpiredHandle(shapeUrl)
+
+    const reloaded = new ExpiredShapesCache()
+    expect(reloaded.getExpiredHandle(shapeUrl)).toBe(`handle-1`)
+  })
+
+  it(`still persists a changed handle`, () => {
+    const cache = new ExpiredShapesCache()
+    cache.markExpired(shapeUrl, `handle-1`)
+    cache.getExpiredHandle(shapeUrl)
+    cache.markExpired(shapeUrl, `handle-2`)
+
+    expect(new ExpiredShapesCache().getExpiredHandle(shapeUrl)).toBe(`handle-2`)
+  })
+
+  it(`still persists a delete`, () => {
+    const cache = new ExpiredShapesCache()
+    cache.markExpired(shapeUrl, `handle-1`)
+    cache.delete(shapeUrl)
+
+    expect(new ExpiredShapesCache().getExpiredHandle(shapeUrl)).toBe(null)
+  })
+
+  it(`keeps LRU ordering accurate in memory despite not persisting each touch`, () => {
+    const cache = new ExpiredShapesCache()
+    for (let i = 0; i < 250; i++)
+      cache.markExpired(`${shapeUrl}&i=${i}`, `h${i}`)
+
+    cache.getExpiredHandle(`${shapeUrl}&i=0`)
+    cache.markExpired(`${shapeUrl}&overflow`, `h-overflow`)
+
+    expect(cache.getExpiredHandle(`${shapeUrl}&i=0`)).toBe(`h0`)
+    expect(cache.getExpiredHandle(`${shapeUrl}&i=1`)).toBe(null)
+  })
+})