types(firestore): make withConverter retro compatible (#7441)

posva · dconeybe · web-flow · commit cca47353c9db · 2023-09-29T12:31:58.000-04:00
* types(firestore): make `withConverter` retro compatible

* style: format

* changeset added

* reference.ts: add default DocumentData parameter type for NewDbModelType to the other withConverter() functions

* add tests

* database.test.ts: move an inline comment to be above the appropriate line

* yarn docgen devsite

---------

Co-authored-by: Denver Coneybeare &lt;dconeybe@google.com&gt;
diff --git a/.changeset/flat-cups-agree.md b/.changeset/flat-cups-agree.md
@@ -0,0 +1,6 @@
+---
+'@firebase/firestore': minor
+'firebase': minor
+---
+
+Added a default template type parameter to withConverter() functions to improve backwards compatibility with the v9 SDK
diff --git a/common/api-review/firestore-lite.api.md b/common/api-review/firestore-lite.api.md
@@ -86,7 +86,7 @@ export class CollectionReference<AppModelType = DocumentData, DbModelType extend
     get parent(): DocumentReference<DocumentData, DocumentData> | null;
     get path(): string;
     readonly type = "collection";
-    withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
+    withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
     withConverter(converter: null): CollectionReference<DocumentData, DocumentData>;
 }
 
@@ -126,7 +126,7 @@ export class DocumentReference<AppModelType = DocumentData, DbModelType extends
     get parent(): CollectionReference<AppModelType, DbModelType>;
     get path(): string;
     readonly type = "document";
-    withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
+    withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
     withConverter(converter: null): DocumentReference<DocumentData, DocumentData>;
 }
 
@@ -270,7 +270,7 @@ export class Query<AppModelType = DocumentData, DbModelType extends DocumentData
     readonly firestore: Firestore;
     readonly type: 'query' | 'collection';
     withConverter(converter: null): Query<DocumentData, DocumentData>;
-    withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
+    withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
 }
 
 // @public
diff --git a/common/api-review/firestore.api.md b/common/api-review/firestore.api.md
@@ -92,7 +92,7 @@ export class CollectionReference<AppModelType = DocumentData, DbModelType extend
     get parent(): DocumentReference<DocumentData, DocumentData> | null;
     get path(): string;
     readonly type = "collection";
-    withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
+    withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
     withConverter(converter: null): CollectionReference<DocumentData, DocumentData>;
 }
 
@@ -152,7 +152,7 @@ export class DocumentReference<AppModelType = DocumentData, DbModelType extends
     get parent(): CollectionReference<AppModelType, DbModelType>;
     get path(): string;
     readonly type = "document";
-    withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
+    withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
     withConverter(converter: null): DocumentReference<DocumentData, DocumentData>;
 }
 
@@ -525,7 +525,7 @@ export class Query<AppModelType = DocumentData, DbModelType extends DocumentData
     readonly firestore: Firestore;
     readonly type: 'query' | 'collection';
     withConverter(converter: null): Query<DocumentData, DocumentData>;
-    withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
+    withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
 }
 
 // @public
diff --git a/docs-devsite/firestore_.collectionreference.md b/docs-devsite/firestore_.collectionreference.md
@@ -82,7 +82,7 @@ Applies a custom data converter to this `CollectionReference`<!-- -->, allowing
 <b>Signature:</b>
 
 ```typescript
-withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
+withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
 ```
 
 ### Parameters
diff --git a/docs-devsite/firestore_.documentreference.md b/docs-devsite/firestore_.documentreference.md
@@ -103,7 +103,7 @@ Applies a custom data converter to this `DocumentReference`<!-- -->, allowing yo
 <b>Signature:</b>
 
 ```typescript
-withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
+withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
 ```
 
 ### Parameters
diff --git a/docs-devsite/firestore_.query.md b/docs-devsite/firestore_.query.md
@@ -108,7 +108,7 @@ Applies a custom data converter to this query, allowing you to use your own cust
 <b>Signature:</b>
 
 ```typescript
-withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
+withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
 ```
 
 ### Parameters
diff --git a/docs-devsite/firestore_lite.collectionreference.md b/docs-devsite/firestore_lite.collectionreference.md
@@ -82,7 +82,7 @@ Applies a custom data converter to this `CollectionReference`<!-- -->, allowing
 <b>Signature:</b>
 
 ```typescript
-withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
+withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): CollectionReference<NewAppModelType, NewDbModelType>;
 ```
 
 ### Parameters
diff --git a/docs-devsite/firestore_lite.documentreference.md b/docs-devsite/firestore_lite.documentreference.md
@@ -103,7 +103,7 @@ Applies a custom data converter to this `DocumentReference`<!-- -->, allowing yo
 <b>Signature:</b>
 
 ```typescript
-withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
+withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): DocumentReference<NewAppModelType, NewDbModelType>;
 ```
 
 ### Parameters
diff --git a/docs-devsite/firestore_lite.query.md b/docs-devsite/firestore_lite.query.md
@@ -108,7 +108,7 @@ Applies a custom data converter to this query, allowing you to use your own cust
 <b>Signature:</b>
 
 ```typescript
-withConverter<NewAppModelType, NewDbModelType extends DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
+withConverter<NewAppModelType, NewDbModelType extends DocumentData = DocumentData>(converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
 ```
 
 ### Parameters
diff --git a/packages/firestore/src/lite-api/reference.ts b/packages/firestore/src/lite-api/reference.ts
@@ -159,10 +159,16 @@ export class Query<
    * @param converter - Converts objects to and from Firestore.
    * @returns A `Query` that uses the provided converter.
    */
-  withConverter<NewAppModelType, NewDbModelType extends DocumentData>(
+  withConverter<
+    NewAppModelType,
+    NewDbModelType extends DocumentData = DocumentData
+  >(
     converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>
   ): Query<NewAppModelType, NewDbModelType>;
-  withConverter<NewAppModelType, NewDbModelType extends DocumentData>(
+  withConverter<
+    NewAppModelType,
+    NewDbModelType extends DocumentData = DocumentData
+  >(
     converter: FirestoreDataConverter<NewAppModelType, NewDbModelType> | null
   ): Query<NewAppModelType, NewDbModelType> {
     return new Query<NewAppModelType, NewDbModelType>(
@@ -246,7 +252,10 @@ export class DocumentReference<
    * @param converter - Converts objects to and from Firestore.
    * @returns A `DocumentReference` that uses the provided converter.
    */
-  withConverter<NewAppModelType, NewDbModelType extends DocumentData>(
+  withConverter<
+    NewAppModelType,
+    NewDbModelType extends DocumentData = DocumentData
+  >(
     converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>
   ): DocumentReference<NewAppModelType, NewDbModelType>;
   /**
@@ -257,7 +266,10 @@ export class DocumentReference<
    * use a converter.
    */
   withConverter(converter: null): DocumentReference<DocumentData, DocumentData>;
-  withConverter<NewAppModelType, NewDbModelType extends DocumentData>(
+  withConverter<
+    NewAppModelType,
+    NewDbModelType extends DocumentData = DocumentData
+  >(
     converter: FirestoreDataConverter<NewAppModelType, NewDbModelType> | null
   ): DocumentReference<NewAppModelType, NewDbModelType> {
     return new DocumentReference<NewAppModelType, NewDbModelType>(
@@ -328,7 +340,10 @@ export class CollectionReference<
    * @param converter - Converts objects to and from Firestore.
    * @returns A `CollectionReference` that uses the provided converter.
    */
-  withConverter<NewAppModelType, NewDbModelType extends DocumentData>(
+  withConverter<
+    NewAppModelType,
+    NewDbModelType extends DocumentData = DocumentData
+  >(
     converter: FirestoreDataConverter<NewAppModelType, NewDbModelType>
   ): CollectionReference<NewAppModelType, NewDbModelType>;
   /**
@@ -341,7 +356,10 @@ export class CollectionReference<
   withConverter(
     converter: null
   ): CollectionReference<DocumentData, DocumentData>;
-  withConverter<NewAppModelType, NewDbModelType extends DocumentData>(
+  withConverter<
+    NewAppModelType,
+    NewDbModelType extends DocumentData = DocumentData
+  >(
     converter: FirestoreDataConverter<NewAppModelType, NewDbModelType> | null
   ): CollectionReference<NewAppModelType, NewDbModelType> {
     return new CollectionReference<NewAppModelType, NewDbModelType>(
diff --git a/packages/firestore/test/integration/api/database.test.ts b/packages/firestore/test/integration/api/database.test.ts
@@ -1813,6 +1813,67 @@ apiDescribe('Database', persistence => {
         expect(refEqual(untypedDocRef, ref)).to.be.true;
       });
     });
+
+    it('DocumentReference.withConverter() default DbModelType', () => {
+      const converter = {
+        toFirestore: (value: number) => {
+          return { value };
+        },
+        fromFirestore: (snapshot: QueryDocumentSnapshot) => {
+          return snapshot.data()['value'] as number;
+        }
+      };
+      return withTestDoc(persistence, async docRef => {
+        // The line below should compile since the DbModelType type parameter of
+        // DocumentReference.withConverter() has a default value.
+        const typedDocRef = docRef.withConverter<number>(converter);
+        await setDoc(typedDocRef, 42);
+        const snapshot = await getDoc(typedDocRef);
+        expect(snapshot.data()).to.equal(42);
+      });
+    });
+
+    it('CollectionReference.withConverter() default DbModelType', () => {
+      const converter = {
+        toFirestore: (value: number) => {
+          return { value };
+        },
+        fromFirestore: (snapshot: QueryDocumentSnapshot) => {
+          return snapshot.data()['value'] as number;
+        }
+      };
+      const testDocs = { doc1: { value: 42 } };
+      return withTestCollection(persistence, testDocs, async collectionRef => {
+        // The line below should compile since the DbModelType type parameter of
+        // CollectionReference.withConverter() has a default value.
+        const typedCollectionRef =
+          collectionRef.withConverter<number>(converter);
+        const snapshot = await getDocs(typedCollectionRef);
+        expect(snapshot.size).to.equal(1);
+        expect(snapshot.docs[0].data()).to.equal(42);
+      });
+    });
+
+    it('Query.withConverter() default DbModelType', () => {
+      const converter = {
+        toFirestore: (value: number) => {
+          return { value };
+        },
+        fromFirestore: (snapshot: QueryDocumentSnapshot) => {
+          return snapshot.data()['value'] as number;
+        }
+      };
+      const testDocs = { doc1: { value: 42 } };
+      return withTestCollection(persistence, testDocs, async collectionRef => {
+        const query_ = query(collectionRef, where('value', '==', 42));
+        // The line below should compile since the DbModelType type parameter of
+        // Query.withConverter() has a default value.
+        const typedQuery = query_.withConverter<number>(converter);
+        const snapshot = await getDocs(typedQuery);
+        expect(snapshot.size).to.equal(1);
+        expect(snapshot.docs[0].data()).to.equal(42);
+      });
+    });
   });
 
   // TODO(b/196858864): This test regularly times out on CI.
