fix(firestore): allow null value to isEqualsTo & isNotEqualsTo …

…in `where()` query (#11896)

* fix(firestore): allow `null` value to `isEqualsTo` `isNotEqualsTo` & `arrayContains` for `where()` queries

* test(firestore): allow `null` value to `isEqualsTo` `isNotEqualsTo` & `arrayContains` for `where()` queries

* chore: analyze and format issues

* refactor: cannot use `null` with `arrayContains` to query. doesn't work

* chore: fix typo

* feat: export the "where" sentinel value for usage in the ODM

* fix(firestore): revert named param types back to original

* feat: Support `whereField(isEqualTo: null)` and similar

* chore: Revert header removal

* chore: fix analyze

* chore: header again....

---------

Co-authored-by: Remi Rousselet <darky12s@gmail.com>

packages/cloud_firestore/cloud_firestore/example/integration_test/query_e2e.dart

@@ -1813,6 +1813,56 @@ void runQueryTests() {
         expect(snapshot.docs.length, equals(1));
         expect(snapshot.docs[0].get('foo'), equals(ref));
       });
+
+      testWidgets('pass `null` to `isEqualTo`', (_) async {
+        CollectionReference<Map<String, dynamic>> collection =
+            await initializeTest('where-null-isEqualTo');
+
+        await Future.wait([
+          collection.add({
+            'foo': 1,
+          }),
+          collection.add({'foo': 2}),
+          collection.add({
+            'foo': null,
+          }),
+          collection.add({
+            'foo': null,
+          }),
+        ]);
+
+        QuerySnapshot<Map<String, dynamic>> snapshot =
+            await collection.where('foo', isEqualTo: null).get();
+
+        expect(snapshot.docs.length, equals(2));
+        expect(snapshot.docs[0].get('foo'), equals(null));
+        expect(snapshot.docs[1].get('foo'), equals(null));
+      });
+
+      testWidgets('pass `null` to `isNotEqualTo`', (_) async {
+        CollectionReference<Map<String, dynamic>> collection =
+            await initializeTest('where-null-isNotEqualTo');
+
+        await Future.wait([
+          collection.add({
+            'foo': 11,
+          }),
+          collection.add({'foo': 11}),
+          collection.add({
+            'foo': null,
+          }),
+          collection.add({
+            'foo': null,
+          }),
+        ]);
+
+        QuerySnapshot<Map<String, dynamic>> snapshot =
+            await collection.where('foo', isNotEqualTo: null).get();
+
+        expect(snapshot.docs.length, equals(2));
+        expect(snapshot.docs[0].get('foo'), equals(11));
+        expect(snapshot.docs[1].get('foo'), equals(11));
+      });
     });
 
     group('Query.where() with Filter class', () {

packages/cloud_firestore/cloud_firestore/lib/src/query.dart

@@ -4,6 +4,10 @@
 
 part of cloud_firestore;
 
+/// Sentinel value to check whether user passed values explicitly through .where() method
+@internal
+const notSetQueryParam = Object();
+
 /// Represents a [Query] over the data at a particular location.
 ///
 /// Can construct refined [Query] objects by adding filters and ordering.
@@ -595,13 +599,13 @@ class _JsonQuery implements Query<Map<String, dynamic>> {
   @override
   Query<Map<String, dynamic>> where(
     Object fieldOrFilter, {
-    Object? isEqualTo,
-    Object? isNotEqualTo,
-    Object? isLessThan,
-    Object? isLessThanOrEqualTo,
-    Object? isGreaterThan,
-    Object? isGreaterThanOrEqualTo,
-    Object? arrayContains,
+    Object? isEqualTo = notSetQueryParam,
+    Object? isNotEqualTo = notSetQueryParam,
+    Object? isLessThan = notSetQueryParam,
+    Object? isLessThanOrEqualTo = notSetQueryParam,
+    Object? isGreaterThan = notSetQueryParam,
+    Object? isGreaterThanOrEqualTo = notSetQueryParam,
+    Object? arrayContains = notSetQueryParam,
     Iterable<Object?>? arrayContainsAny,
     Iterable<Object?>? whereIn,
     Iterable<Object?>? whereNotIn,
@@ -611,13 +615,13 @@ class _JsonQuery implements Query<Map<String, dynamic>> {
 
     if (fieldOrFilter is Filter) {
       assert(
-        isEqualTo == null &&
-            isNotEqualTo == null &&
-            isLessThan == null &&
-            isLessThanOrEqualTo == null &&
-            isGreaterThan == null &&
-            isGreaterThanOrEqualTo == null &&
-            arrayContains == null &&
+        identical(isEqualTo, notSetQueryParam) &&
+            identical(isNotEqualTo, notSetQueryParam) &&
+            identical(isLessThan, notSetQueryParam) &&
+            identical(isLessThanOrEqualTo, notSetQueryParam) &&
+            identical(isGreaterThan, notSetQueryParam) &&
+            identical(isGreaterThanOrEqualTo, notSetQueryParam) &&
+            identical(arrayContains, notSetQueryParam) &&
             arrayContainsAny == null &&
             whereIn == null &&
             whereNotIn == null &&
@@ -655,17 +659,29 @@ class _JsonQuery implements Query<Map<String, dynamic>> {
       conditions.add(condition);
     }
 
-    if (isEqualTo != null) addCondition(field, '==', isEqualTo);
-    if (isNotEqualTo != null) addCondition(field, '!=', isNotEqualTo);
-    if (isLessThan != null) addCondition(field, '<', isLessThan);
-    if (isLessThanOrEqualTo != null) {
+    if (!identical(isEqualTo, notSetQueryParam)) {
+      addCondition(field, '==', isEqualTo);
+    }
+
+    if (!identical(isNotEqualTo, notSetQueryParam)) {
+      addCondition(field, '!=', isNotEqualTo);
+    }
+
+    if (!identical(isLessThan, notSetQueryParam)) {
+      addCondition(field, '<', isLessThan);
+    }
+
+    if (!identical(isLessThanOrEqualTo, notSetQueryParam)) {
       addCondition(field, '<=', isLessThanOrEqualTo);
     }
-    if (isGreaterThan != null) addCondition(field, '>', isGreaterThan);
-    if (isGreaterThanOrEqualTo != null) {
+    if (!identical(isGreaterThan, notSetQueryParam)) {
+      addCondition(field, '>', isGreaterThan);
+    }
+
+    if (!identical(isGreaterThanOrEqualTo, notSetQueryParam)) {
       addCondition(field, '>=', isGreaterThanOrEqualTo);
     }
-    if (arrayContains != null) {
+    if (!identical(arrayContains, notSetQueryParam)) {
       addCondition(field, 'array-contains', arrayContains);
     }
     if (arrayContainsAny != null) {
@@ -952,13 +968,13 @@ class _WithConverterQuery<T extends Object?> implements Query<T> {
   @override
   Query<T> where(
     Object field, {
-    Object? isEqualTo,
-    Object? isNotEqualTo,
-    Object? isLessThan,
-    Object? isLessThanOrEqualTo,
-    Object? isGreaterThan,
-    Object? isGreaterThanOrEqualTo,
-    Object? arrayContains,
+    Object? isEqualTo = notSetQueryParam,
+    Object? isNotEqualTo = notSetQueryParam,
+    Object? isLessThan = notSetQueryParam,
+    Object? isLessThanOrEqualTo = notSetQueryParam,
+    Object? isGreaterThan = notSetQueryParam,
+    Object? isGreaterThanOrEqualTo = notSetQueryParam,
+    Object? arrayContains = notSetQueryParam,
     Iterable<Object?>? arrayContainsAny,
     Iterable<Object?>? whereIn,
     Iterable<Object?>? whereNotIn,