[danReynolds]

Adds read-only subtype views: a collection of Animal can be read as its Dogs, by ID or through queries, with snapshots typed as Dog.

final CollectionView<Dog> dogs = animals.view<Dog>();

final Dog? rex = dogs.doc('rex').get()?.data; // null if rex is missing or not a dog

dogs
    .where((snap) => snap.data.age >= 2)
    .sortBy((a, b) => a.data.name.compareTo(b.data.name))
    .stream();

How it works

collection.view<S>() and query.view<S>() add a type test to the underlying query, and a view's where() adds its filter to that query too. The query therefore selects the view's documents and handles hydration, dependency invalidation and incremental updates as it does for any query. A document that enters or leaves the view, by changing type or by starting or stopping to pass a filter, appears in the view's change stream as added or removed. The view wraps each result in a DocumentSnapshotView<S> whose data is typed as S, and applies sortBy to the wrapped snapshots.

CollectionView.doc(id) returns a DocumentView<S>, which reads its document as absent while it is missing or not an S; its stream emits a single null for that time. Views are created only through view() and doc(), so every view's query includes its type test.

The views live in lib/src/views.dart, a part of the core library. Besides view() on Collection and Query, the only engine change is that a query without filters returns its results without copying them.

Notes

• Views are read-only. Write through the collection, as in animals.doc(snap.id).update(...).
• Each read or emission wraps every result once, and view snapshots compare by identity.
• A where filter wraps each snapshot it checks. Against filtering after the query, get() measured the same, and the time from a write to its stream emission was 20–30% shorter, because only the changed document is rechecked.
• Views don't plug into QueryStreamBuilder or DocumentStreamBuilder. To build from a view, observe it and use a StreamBuilder.
• Earlier commits in this PR used extension types. Those were replaced because their lists rejected view-typed values (reduce and orElse threw) and views had no runtime type of their own.

Validation

• test/core/collection_view_test.dart has 20 tests, passing on the VM and in Chrome. They cover reads by type and ID, typed filters and sorting, membership changes in values and change streams (including filter transitions), hydration through the parent codec, dependency writes, ancestor deletion, multicast observers, widening a view's static type, and list operations that take view-typed values.
• Locally, 182 core, 90 native and 42 web tests pass, both CI benchmark workload checks pass, and flutter analyze reports no issues for the package and the example.
• Removing the query-side type test, the query-side filters, the sort or the document stream's null deduplication each fails the suite.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The advertised stream-builder APIs are missing, and the documentation overstates the runtime allocation benefits.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• Promised view stream builders are missing and unexported · New
• Incorrectly claims views add no runtime allocations · New
• Incorrectly claims views add no runtime cost · New

What changed in this PR

Adds read-only subtype views over collections using Dart extension types.

Changes:

• Introduces subtype-filtered collection, query, document, and snapshot views.
• Raises the minimum Dart SDK to 3.3 and documents the API.
• Adds extensive subtype-view tests and supporting test models.

File	Description
lib/​src/​views.dart	Implements subtype view APIs.
lib/​loon.dart	Exports the view API.
pubspec.yaml	Requires Dart 3.3.
README.md	Documents subtype views.
CHANGELOG.md	Records the feature and SDK requirement.
test/​core/​collection_view_test.dart	Tests view reads, streams, hydration, and caching.
test/​models/​test_animal_model.dart	Adds a polymorphic test model.
test/​models/​test_persistor.dart	Generalizes persistence seed snapshots.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.