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
armando-navarro added a commit that referenced this pull request Nov 19, 2026
…nt (#3838)

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.

(cherry picked from commit d21d243)
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