electric-sql / electric-sql/electric

Rename liveCacheBuster to cursor/serverCursor in ShapeStreamState

Open
#3,841 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.