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

getExpiredHandle is a read accessor that also persisted the whole cache, and it
runs while building the URL of every shape request. In live mode that is a full
JSON.stringify plus localStorage.setItem once per poll, indefinitely.

lastUsed is still updated in memory, and markExpired reads it from memory when
picking an eviction candidate, so LRU ordering within a session is unchanged.
After a reload the persisted values reflect the last markExpired rather than the
last read, so eviction order at the 250-entry cap can be staler.

Author: PepijnSenders

.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,12 @@ export class ExpiredShapesCache {
   getExpiredHandle(shapeUrl: string): string | null {
     const entry = this.data[shapeUrl]
     if (entry) {
-      // Update last used time when accessed
+      // Update last used time when accessed. Deliberately not persisted: this runs
+      // while building the URL of every shape request, so persisting it writes the
+      // whole cache to localStorage on every poll for as long as the app is open.
+      // `lastUsed` only orders eviction in markExpired, which reads it from memory,
+      // so the only cost of a staler value on disk is eviction order after a reload.
       entry.lastUsed = Date.now()
-      this.save()
       return entry.expiredHandle
     }
     return null

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

@@ -1312,3 +1312,93 @@ describe(`ExpiredShapesCache`, () => {
     expect(snapshotHasCacheBuster).toBe(false)
   })
 })
+
+describe(`ExpiredShapesCache write amplification`, () => {
+  const shapeUrl = `https://example.com/v1/shape?table=test`
+
+  beforeEach(() => {
+    localStorage.clear()
+    vi.restoreAllMocks()
+  })
+
+  // The localStorage mock's setItem is a persistent vi.fn whose call history
+  // survives restoreAllMocks, so measure against a baseline taken here rather
+  // than from zero.
+  function countWrites(): { calls: () => number } {
+    const spy = vi.spyOn(localStorage, `setItem`)
+    const base = spy.mock.calls.length
+    return { calls: () => spy.mock.calls.length - base }
+  }
+
+  // Positive control: without this, a spy that silently failed to attach would
+  // make every "no writes" assertion below pass for the wrong reason.
+  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()
+    // Fill to the 250-entry cap.
+    for (let i = 0; i < 250; i++)
+      cache.markExpired(`${shapeUrl}&i=${i}`, `h${i}`)
+
+    // Touch the oldest so it is no longer the eviction candidate.
+    cache.getExpiredHandle(`${shapeUrl}&i=0`)
+
+    // Overflow by one; the least recently used entry should go, not the touched one.
+    cache.markExpired(`${shapeUrl}&overflow`, `h-overflow`)
+
+    expect(cache.getExpiredHandle(`${shapeUrl}&i=0`)).toBe(`h0`)
+    expect(cache.getExpiredHandle(`${shapeUrl}&i=1`)).toBe(null)
+  })
+})