Firestore: Add isEqual() and port DocumentReference array test. (#222)

* Ports the test for the fix I made for Android for DocumentReference objects in arrays (bug not present in Web).
* Implements isEqual() on Query and DocumentReference

Author: mikelehen

packages/firebase/app/index.d.ts

@@ -969,6 +969,14 @@ declare namespace firebase.firestore {
      */
     collection(collectionPath: string): CollectionReference;
 
+    /**
+     * Returns true if this `DocumentReference` is equal to the provided one.
+     *
+     * @param other The `DocumentReference` to compare against.
+     * @return true if this `DocumentReference` is equal to the provided one.
+     */
+    isEqual(other: DocumentReference): boolean;
+
     /**
      * Writes to the document referred to by this `DocumentReference`. If the
      * document does not yet exist, it will be created. If you pass
@@ -1308,6 +1316,14 @@ declare namespace firebase.firestore {
      */
     endAt(...fieldValues: any[]): Query;
 
+    /**
+     * Returns true if this `Query` is equal to the provided one.
+     *
+     * @param other The `Query` to compare against.
+     * @return true if this `Query` is equal to the provided one.
+     */
+    isEqual(other: Query): boolean;
+
     /**
      * Executes the query and returns the results as a QuerySnapshot.
      *

packages/firebase/index.d.ts

@@ -969,6 +969,14 @@ declare namespace firebase.firestore {
      */
     collection(collectionPath: string): CollectionReference;
 
+    /**
+     * Returns true if this `DocumentReference` is equal to the provided one.
+     *
+     * @param other The `DocumentReference` to compare against.
+     * @return true if this `DocumentReference` is equal to the provided one.
+     */
+    isEqual(other: DocumentReference): boolean;
+
     /**
      * Writes to the document referred to by this `DocumentReference`. If the
      * document does not yet exist, it will be created. If you pass
@@ -1308,6 +1316,14 @@ declare namespace firebase.firestore {
      */
     endAt(...fieldValues: any[]): Query;
 
+    /**
+     * Returns true if this `Query` is equal to the provided one.
+     *
+     * @param other The `Query` to compare against.
+     * @return true if this `Query` is equal to the provided one.
+     */
+    isEqual(other: Query): boolean;
+
     /**
      * Executes the query and returns the results as a QuerySnapshot.
      *

packages/firestore/src/api/database.ts

@@ -742,6 +742,13 @@ export class DocumentReference implements firestore.DocumentReference {
     return new CollectionReference(this._key.path.child(path), this.firestore);
   }
 
+  isEqual(other: firestore.DocumentReference): boolean {
+    if (!(other instanceof DocumentReference)) {
+      throw invalidClassError('isEqual', 'DocumentReference', 1, other);
+    }
+    return this.firestore === other.firestore && this._key.equals(other._key);
+  }
+
   set(
     value: firestore.DocumentData,
     options?: firestore.SetOptions
@@ -1240,6 +1247,15 @@ export class Query implements firestore.Query {
     return new Query(this._query.withEndAt(bound), this.firestore);
   }
 
+  isEqual(other: firestore.Query): boolean {
+    if (!(other instanceof Query)) {
+      throw invalidClassError('isEqual', 'Query', 1, other);
+    }
+    return (
+      this.firestore === other.firestore && this._query.equals(other._query)
+    );
+  }
+
   /** Helper function to create a bound from a document or fields */
   private boundFromDocOrFields(
     methodName: string,

packages/firestore/src/typings/firestore.d.ts

@@ -403,6 +403,14 @@ declare namespace firestore {
      */
     collection(collectionPath: string): CollectionReference;
 
+    /**
+     * Returns true if this `DocumentReference` is equal to the provided one.
+     *
+     * @param other The `DocumentReference` to compare against.
+     * @return true if this `DocumentReference` is equal to the provided one.
+     */
+    isEqual(other: DocumentReference): boolean;
+
     /**
      * Writes to the document referred to by this `DocumentReference`. If the
      * document does not yet exist, it will be created. If you pass
@@ -742,6 +750,14 @@ declare namespace firestore {
      */
     endAt(...fieldValues: any[]): Query;
 
+    /**
+     * Returns true if this `Query` is equal to the provided one.
+     *
+     * @param other The `Query` to compare against.
+     * @return true if this `Query` is equal to the provided one.
+     */
+    isEqual(other: Query): boolean;
+
     /**
      * Executes the query and returns the results as a QuerySnapshot.
      *

packages/firestore/test/integration/api/database.test.ts

@@ -468,20 +468,66 @@ apiDescribe('Database', persistence => {
     });
   });
 
-  asyncIt('exposes "database" on document references.', () => {
+  asyncIt('exposes "firestore" on document references.', () => {
     return withTestDb(persistence, db => {
       expect(db.doc('foo/bar').firestore).to.equal(db);
       return Promise.resolve();
     });
   });
 
-  asyncIt('exposes "database" on query references.', () => {
+  asyncIt('exposes "firestore" on query references.', () => {
     return withTestDb(persistence, db => {
       expect(db.collection('foo').limit(5).firestore).to.equal(db);
       return Promise.resolve();
     });
   });
 
+  asyncIt('can compare DocumentReference instances with isEqual().', () => {
+    return withTestDb(persistence, firestore => {
+      return withTestDb(persistence, otherFirestore => {
+        const docRef = firestore.doc('foo/bar');
+        expect(docRef.isEqual(firestore.doc('foo/bar'))).to.be.true;
+        expect(docRef.collection('baz').parent.isEqual(docRef)).to.be.true;
+
+        expect(firestore.doc('foo/BAR').isEqual(docRef)).to.be.false;
+
+        expect(otherFirestore.doc('foo/bar').isEqual(docRef)).to.be.false;
+
+        return Promise.resolve();
+      });
+    });
+  });
+
+  asyncIt('can compare Query instances with isEqual().', () => {
+    return withTestDb(persistence, firestore => {
+      return withTestDb(persistence, otherFirestore => {
+        const query = firestore
+          .collection('foo')
+          .orderBy('bar')
+          .where('baz', '==', 42);
+        const query2 = firestore
+          .collection('foo')
+          .orderBy('bar')
+          .where('baz', '==', 42);
+        expect(query.isEqual(query2)).to.be.true;
+
+        const query3 = firestore
+          .collection('foo')
+          .orderBy('BAR')
+          .where('baz', '==', 42);
+        expect(query.isEqual(query3)).to.be.false;
+
+        const query4 = otherFirestore
+          .collection('foo')
+          .orderBy('bar')
+          .where('baz', '==', 42);
+        expect(query4.isEqual(query)).to.be.false;
+
+        return Promise.resolve();
+      });
+    });
+  });
+
   asyncIt('can traverse collections and documents.', () => {
     return withTestDb(persistence, db => {
       const expected = 'a/b/c/d';

packages/firestore/test/integration/api/type.test.ts

@@ -93,20 +93,14 @@ apiDescribe('Firestore', persistence => {
   });
 
   asyncIt('can read and write document references', () => {
-    // TODO(b/62143881): Implement DocumentReference.equals() so we can use
-    // expectRoundtrip()
     return withTestDoc(persistence, doc => {
-      return doc
-        .set({ a: 42, ref: doc })
-        .then(() => {
-          return doc.get();
-        })
-        .then(docSnap => {
-          expect(docSnap.exists).to.equal(true);
-          expect(docSnap.get('a')).to.equal(42);
-          const readDocRef = docSnap.get('ref') as firestore.DocumentReference;
-          expect(readDocRef.path).to.equal(doc.path);
-        });
+      return expectRoundtrip(doc.firestore, { a: 42, ref: doc });
+    });
+  });
+
+  asyncIt('can read and write document references in an array', () => {
+    return withTestDoc(persistence, doc => {
+      return expectRoundtrip(doc.firestore, { a: 42, refs: [doc] });
     });
   });
 });

packages/firestore/test/util/equality_matcher.ts

@@ -27,8 +27,12 @@ function customDeepEqual(left, right) {
   /**
    * START: Custom compare logic
    */
+  // Internally we use .equals(), but our public API uses .isEqual() so
+  // we handle both.
   if (left && typeof left.equals === 'function') return left.equals(right);
+  if (left && typeof left.isEqual === 'function') return left.isEqual(right);
   if (right && typeof right.equals === 'function') return right.equals(left);
+  if (right && typeof right.isEqual === 'function') return right.isEqual(left);
   /**
    * END: Custom compare logic
    */