Add support for Typescript Custom Mapping

packages/firebase/index.d.ts

@@ -7087,11 +7087,62 @@ declare namespace firebase.firestore {
    */
   export function setLogLevel(logLevel: LogLevel): void;
 
+  /**
+   * Converter used by `withConverter()` to transform user objects into
+   * Firestore data.
+   *
+   * Using the converter allows you to specify generic type arguments when
+   * storing and retrieving objects from Firestore.
+   *
+   * @example
+   *  ```typescript
+   * class Post {
+   *   constructor(readonly title: string, readonly author: string) {}
+   *     byline(): string {
+   *     return this.title + ', by ' + this.author;
+   *   }
+   * }
+   *
+   * const PostConverter = {
+   *   toFirestore(post: Post): DocumentData {
+   *     return {title: post.title, author: post.author};
+   *   },
+   *   fromFirestore(snapshot: DocumentSnapshot, options: SnapshotOptions): Post
+   *     {const data = snapshot.data(options)!;
+   *     return new Post(data.title, data.author);
+   *   }
+   * };
+   *
+   * const postSnap = await firebase.firestore()
+   *   .collection('posts')
+   *   .withConverter(PostConverter)
+   *   .doc().get();
+   * const post = postSnap.data();
+   * if (post !== undefined) {
+   *   post.title; // string
+   *   post.byline(); // Should be defined
+   *   post.someNonExistentProperty; // TS error
+   * }
+   * ```
+   */
   export interface FirestoreDataConverter<T> {
-    // Converts a model object of type T into plain Firestore DocumentData.
+    /**
+     * Called by the Firestore SDK to convert a custom model object of type T
+     * into a plain Javacsript object (suitable for writing directly to the
+     * Firestore database).
+     */
     toFirestore(modelObject: T): DocumentData;
-    // Converts a Firestore DocumentSnapshot into a model object of type T.
-    fromFirestore(snapshot: DocumentSnapshot, options: SnapshotOptions): T;
+
+    /**
+     * Called by the Firestore SDK to convert Firestore data into an object of
+     * type T. You can access your data by calling:
+     *
+     * snapshot.data(options)
+     *
+     * @param snapshot A DocumentSnapshot containing your data and metadata.
+     * @param options The SnapshotOptions from the intial call to data().
+     */
+    fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions): T;
   }
 
   /**
@@ -7140,7 +7191,7 @@ declare namespace firebase.firestore {
      * @param collectionPath A slash-separated path to a collection.
      * @return The `CollectionReference` instance.
      */
-    collection(collectionPath: string): CollectionReference;
+    collection(collectionPath: string): CollectionReference<DocumentData>;
 
     /**
      * Gets a `DocumentReference` instance that refers to the document at the
@@ -7149,7 +7200,7 @@ declare namespace firebase.firestore {
      * @param documentPath A slash-separated path to a document.
      * @return The `DocumentReference` instance.
      */
-    doc(documentPath: string): DocumentReference;
+    doc(documentPath: string): DocumentReference<DocumentData>;
 
     /**
      * Creates and returns a new Query that includes all documents in the
@@ -7161,7 +7212,7 @@ declare namespace firebase.firestore {
      * will be included. Cannot contain a slash.
      * @return The created Query.
      */
-    collectionGroup(collectionId: string): Query;
+    collectionGroup(collectionId: string): Query<DocumentData>;
 
     /**
      * Executes the given `updateFunction` and then attempts to commit the changes
@@ -7925,7 +7976,11 @@ declare namespace firebase.firestore {
     ): () => void;
 
     /**
-     * Converts a DocumentReference into a DocumentReference<U>.
+     * Applies a custom data converter to this DocumentReference, allowing you
+     * to use your own custom model objects with Firestore. When you call
+     * set(), get(), etc. on the returned DocumentReference instance, it will
+     * use the provided converter to convert data to/from type U (your custom
+     * model object type).
      *
      * @param converter Converts objects to and from Firestore
      * @return A DocumentReference<U> that uses the provided converter
@@ -8303,7 +8358,7 @@ declare namespace firebase.firestore {
      * the snapshot listener.
      */
     onSnapshot(observer: {
-      next?: (snapshot: QuerySnapshot) => void;
+      next?: (snapshot: QuerySnapshot<T>) => void;
       error?: (error: Error) => void;
       complete?: () => void;
     }): () => void;
@@ -8324,7 +8379,7 @@ declare namespace firebase.firestore {
     onSnapshot(
       options: SnapshotListenOptions,
       observer: {
-        next?: (snapshot: QuerySnapshot) => void;
+        next?: (snapshot: QuerySnapshot<T>) => void;
         error?: (error: Error) => void;
         complete?: () => void;
       }
@@ -8346,7 +8401,7 @@ declare namespace firebase.firestore {
      * the snapshot listener.
      */
     onSnapshot(
-      onNext: (snapshot: QuerySnapshot) => void,
+      onNext: (snapshot: QuerySnapshot<T>) => void,
       onError?: (error: Error) => void,
       onCompletion?: () => void
     ): () => void;
@@ -8369,10 +8424,21 @@ declare namespace firebase.firestore {
      */
     onSnapshot(
       options: SnapshotListenOptions,
-      onNext: (snapshot: QuerySnapshot) => void,
+      onNext: (snapshot: QuerySnapshot<T>) => void,
       onError?: (error: Error) => void,
       onCompletion?: () => void
     ): () => void;
+
+    /**
+     * Applies a custom data converter to this Query, allowing you to use your
+     * own custom model objects with Firestore. When you call data() on the
+     * underlying QueryDocumentSnapshot, it will use the provided converter to
+     * convert data to/from type U (your custom model object type).
+     *
+     * @param converter Converts objects to and from Firestore
+     * @return A Query<U> that uses the provided converter
+     */
+    withConverter<U>(converter: FirestoreDataConverter<U>): Query<U>;
   }
 
   /**
@@ -8433,7 +8499,7 @@ declare namespace firebase.firestore {
      * @param other The `QuerySnapshot` to compare against.
      * @return true if this `QuerySnapshot` is equal to the provided one.
      */
-    isEqual(other: QuerySnapshot): boolean;
+    isEqual(other: QuerySnapshot<T>): boolean;
   }
 
   /**
@@ -8450,7 +8516,7 @@ declare namespace firebase.firestore {
     readonly type: DocumentChangeType;
 
     /** The document affected by this change. */
-    readonly doc: QueryDocumentSnapshot;
+    readonly doc: QueryDocumentSnapshot<T>;
 
     /**
      * The index of the changed document in the result set immediately prior to
@@ -8509,7 +8575,7 @@ declare namespace firebase.firestore {
      * @return A Promise resolved with a `DocumentReference` pointing to the
      * newly created document after it has been written to the backend.
      */
-    add(data: DocumentData): Promise<DocumentReference<T>>;
+    add(data: T): Promise<DocumentReference<T>>;
 
     /**
      * Returns true if this `CollectionReference` is equal to the provided one.
@@ -8520,7 +8586,11 @@ declare namespace firebase.firestore {
     isEqual(other: CollectionReference<T>): boolean;
 
     /**
-     * Converts a CollectionReference into a CollectionReference<U>.
+     * Applies a custom data converter to this CollectionReference, allowing you
+     * to use your own custom model objects with Firestore. When you call
+     * set(), get(), etc. on the underlying DocumentReference instance, it will
+     * use the provided converter to convert data to/from type U (your custom
+     * model object type).
      *
      * @param converter Converts objects to and from Firestore
      * @return A CollectionReference<U> that uses the provided converter

packages/firestore-types/index.d.ts

@@ -41,10 +41,9 @@ export type LogLevel = 'debug' | 'error' | 'silent';
 export function setLogLevel(logLevel: LogLevel): void;
 
 export interface FirestoreDataConverter<T> {
-  // Converts a model object of type T into plain Firestore DocumentData.
   toFirestore(modelObject: T): DocumentData;
-  // Converts a Firestore DocumentSnapshot into a model object of type T.
-  fromFirestore(snapshot: DocumentSnapshot, options: SnapshotOptions): T;
+
+  fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions): T;
 }
 
 export class FirebaseFirestore {
@@ -247,7 +246,6 @@ export interface SnapshotOptions {
   readonly serverTimestamps?: 'estimate' | 'previous' | 'none';
 }
 
-/** Metadata about a snapshot, describing the state of the snapshot. */
 export interface SnapshotMetadata {
   readonly hasPendingWrites: boolean;
   readonly fromCache: boolean;
@@ -351,12 +349,6 @@ export class Query<T = DocumentData> {
     onCompletion?: () => void
   ): () => void;
 
-  /**
-   * Converts a Query into a Query<U>.
-   *
-   * @param converter Converts objects to and from Firestore
-   * @return A Query<U> that uses the provided converter
-   */
   withConverter<U>(converter: FirestoreDataConverter<U>): Query<U>;
 }