electric-sql / electric-sql/electric
Rename liveCacheBuster to cursor/serverCursor in ShapeStreamState
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 375
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 18
Description
## Summary
`liveCacheBuster` in `SharedStateFields` (packages/typescript-client/src/shape-stream-state.ts) is misleadingly named. It's not a cache buster — it's the server-assigned cursor from the `electric-cursor` response header, used as the `live_cache_buster` query parameter.
The name creates confusion when reading the state machine code because:
- "Cache buster" implies a random/rotating value used to bypass caches
- It's actually a server-assigned cursor that identifies a position in the change stream
- There's a separate `staleCacheBuster` field that IS an actual cache buster (randomly generated)
## Suggestion
Rename `liveCacheBuster` to `cursor` or `serverCursor` throughout the state machine. The query parameter name (`live_cache_buster`) is a server protocol concern and can stay as-is in the URL construction.
## Affected code
- `SharedStateFields.liveCacheBuster` → `cursor` / `serverCursor`
- All references in `shape-stream-state.ts`, `client.ts`, tests, and SPEC.md
- The constant `LIVE_CACHE_BUSTER_QUERY_PARAM` can keep its name (it maps to the protocol)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Contributor guide
Assessment
This issue has not been assessed yet.