electric-sql / electric-sql/electric
Document: dynamic shape patterns (changing WHERE filters)
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 375
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 18
Description
## Context
Shapes are immutable per subscription — once a ShapeStream is created with a WHERE clause, the filter can't change without creating a new stream. AGENTS.md mentions "use collection factory function to make dynamic" but doesn't elaborate on the pattern.
This is a common scenario: a user navigating between pages/views where each view needs a different WHERE filter (e.g., todo list filtering by project, paginated data, user switching contexts).
## Questions to answer
1. **What's the recommended pattern for dynamic shapes?** Create/destroy on navigation? Pre-create a pool? Factory function approach?
2. **What are the lifecycle implications?** Does creating many short-lived shapes cause performance issues server-side (replication slot churn, shape log growth)?
3. **How does this interact with the React hooks cache?** `getShapeStream` caches by sorted options hash — does changing the WHERE clause create a new cached entry, and when does the old one get cleaned up?
4. **AbortSignal cleanup:** Is the pattern to pass an AbortController signal and abort when navigating away? What happens to in-flight data?
5. **TanStack DB collections:** How do dynamic shapes work with `electricCollectionOptions`? Can you swap the underlying shape of a collection?
## Output
- Add a "Dynamic Shapes" section to the `electric-shapes` skill
- Include concrete code examples for the factory function pattern
- Document cleanup/lifecycle best practices
## Source
Identified during domain discovery skill test run (skill-domain-discovery v2.1).
Contributor guide
Assessment
This issue has not been assessed yet.