Skip to content

docs(firestore): type reads with a converter instead of a type argument - #3838

Merged
armando-navarro merged 2 commits into
angular:mainfrom
armando-navarro:docs-typed-firestore-reads
Nov 6, 2026
Merged

armando-navarro merged 2 commits into
angular:mainfrom
armando-navarro:docs-typed-firestore-reads

Conversation

@armando-navarro

Copy link
Copy Markdown
Collaborator

Checklist

Description

The README, the quickstart (docs/install-and-setup.md) and the v7 upgrade guide show collectionData<Item>(collection(firestore, 'items')), which doesn't compile.

collection() returns a reference typed DocumentData, and collectionData<Item> asks for Query<Item>, so TypeScript reports TS2345.

docs/firestore.md casts instead, collectionData(ref) as Observable<UserProfile[]>, which compiles but checks nothing about the stored documents. #3081 and #3073 are readers asking for a typed collection<T>(), and the thread workarounds are the cast and a helper service.

The signature comes from the Firebase SDK, where the type lives on the reference through withConverter() (see #2931). The docs now teach that.

Changes

  • README.md and docs/install-and-setup.md: the Item example attaches a FirestoreDataConverter<Item> whose fromFirestore substitutes '' for a missing or non-string name, reads through collection(...).withConverter(itemConverter), and calls collectionData() with no type argument. One sentence under the example links to the new section.

  • docs/firestore.md: the UserProfile example gets the same converter, the cast goes, and a new "Typed reads" subsection explains why the two shortcuts do not give a typed read, where the default-versus-throw choice lives (fromFirestore runs on every document, so a throw there errors the observable at the first bad document), and that idField performs no validation.

  • docs/version-7-upgrade.md: a sentence above the v6-to-v7 table defines docRef as a converter-typed reference, the collection<T>(docRef, 'bar') // CollectionReference<T> row is corrected (both collection(reference, path) overloads return CollectionReference<DocumentData>), docData's return type gains | undefined, and the code-splitting snippet uses a converter and imports concatMap.

Checked on a fresh Angular 22.2.4 app with @angular/fire 22.0.0-rc.0: the quickstart text builds as written, the previous collectionData<Item>(aCollection) line fails the same build with TS2345, and against the Firestore emulator the documented converter keeps emitting on malformed documents while a throwing one ends the subscription.

Not changed: site/src/get-started/quick-start.md still shows the cast. site/ is the unbuilt duplicate docs tree whose fate is a separate decision.

Fixes #3081
Fixes #3073

The README, the quickstart and the v7 upgrade guide showed
collectionData<Item>(collection(firestore, 'items')), which fails with
TS2345: collection() returns a reference typed DocumentData and the type
argument asks for Item. docs/firestore.md cast the result with
`as Observable<UserProfile[]>` instead, which compiles but checks nothing.

The examples now attach a FirestoreDataConverter through withConverter,
the Firebase SDK's way to type a reference, with a fromFirestore that
substitutes a default for a missing or wrong field. A new "Typed reads"
section in docs/firestore.md says why the two shortcuts do not give a
typed read, where the default-versus-throw choice lives, and that idField
performs no validation.
@armando-navarro armando-navarro added backport: 21.1.x Cherry-pick onto the 21.1.x branch for a 21.1 minor release bump: patch Size of the change: a fix or docs change that reaches users comp: docs Documentation. comp: firestore Cloud Firestore (src/firestore). type: chore Maintenance with no user-facing behavior change. labels Nov 5, 2026
@armando-navarro armando-navarro added this to the 22.0.0-rc.1 milestone Nov 5, 2026
@armando-navarro
armando-navarro merged commit d21d243 into angular:main Nov 6, 2026
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport: 21.1.x Cherry-pick onto the 21.1.x branch for a 21.1 minor release bump: patch Size of the change: a fix or docs change that reaches users comp: docs Documentation. comp: firestore Cloud Firestore (src/firestore). type: chore Maintenance with no user-facing behavior change.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

collection() missing type arguments collection function has no generic type

2 participants