feat: add support for Typescript Custom Mapping

[thebrianchen]

Fixes #856

Added withConverter() methods on CollectionReference, DocumentReference, and Query that allow developers to use Firestore classes with generics.

Example usage:

class Post {
  constructor(readonly title: string, readonly author: string) {}
  toString(): string {
    return this.title + ', by ' + this.author;
  }
}

const PostConverter = {
  toFirestore(post: Post): DocumentData {
    return {title: post.title, author: post.author};
  },
  fromFirestore(data: DocumentData): Post {
    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.toString(); // Should be defined with your overload
  post.someNonExistentProperty; // TS error
}

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@a810aa5). Click here to learn what that means.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master     #828   +/-   ##
=========================================
  Coverage          ?   96.58%           
=========================================
  Files             ?       25           
  Lines             ?    15418           
  Branches          ?     1137           
=========================================
  Hits              ?    14891           
  Misses            ?      519           
  Partials          ?        8

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a810aa5...6d4aebc. Read the comment docs.

[schmidt-sebastian]

Thank you! I am super stoked that this coming together.

[schmidt-sebastian]

I am undecided whether this should be fieldsProto or _ fieldsProto. This is a public field for internal consumption.

[thebrianchen]

I've renamed to _fieldsProto so that external developers know that it's not intended for external consumption.

[thebrianchen]

thanks for the edits and trying out the queryOptions + stream stuff on your own!

[thebrianchen]

I've renamed to _fieldsProto so that external developers know that it's not intended for external consumption.

[schmidt-sebastian]

Some final comments, but looks good. We should probably change the title to something less generic... 'generics' are the tool we used to implement withConverter, but it does not describe the feature very well.

[schmidt-sebastian]

Can you also make the description of the PR a bit more expressive so that users can use it as a guide for how this feature works?