electric-sql / electric-sql/electric

Document: dynamic shape patterns (changing WHERE filters)

Open
#3,911 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

## 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

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.