@react-native-firebase/firestore 17.4.3 → 17.5.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [17.5.0](https://github.com/invertase/react-native-firebase/compare/v17.4.3...v17.5.0) (2023-05-11)
+
+### Features
+
+- **firestore:** Firestore `Filter` instance. Use `Filter`, `Filter.or()` & `Filter.and()` in Firestore queries. ([#7045](https://github.com/invertase/react-native-firebase/issues/7045)) ([f7ec3d1](https://github.com/invertase/react-native-firebase/commit/f7ec3d1970f4fa8cc9752bb3cd8f1550b2a457c5))
+
 ### [17.4.3](https://github.com/invertase/react-native-firebase/compare/v17.4.2...v17.4.3) (2023-04-26)
 
 **Note:** Version bump only for package @react-native-firebase/firestore

package/android/src/reactnative/java/io/invertase/firebase/firestore/ReactNativeFirebaseFirestoreQuery.java

@@ -26,6 +26,7 @@ import com.facebook.react.bridge.WritableMap;
 import com.google.android.gms.tasks.Task;
 import com.google.android.gms.tasks.Tasks;
 import com.google.firebase.firestore.FieldPath;
+import com.google.firebase.firestore.Filter;
 import com.google.firebase.firestore.Query;
 import com.google.firebase.firestore.QuerySnapshot;
 import com.google.firebase.firestore.Source;
@@ -65,62 +66,139 @@ public class ReactNativeFirebaseFirestoreQuery {
     for (int i = 0; i < filters.size(); i++) {
       ReadableMap filter = filters.getMap(i);
 
-      ArrayList fieldPathArray = Objects.requireNonNull(filter).getArray("fieldPath").toArrayList();
-      String[] segmentArray = (String[]) fieldPathArray.toArray(new String[0]);
+      if (filter.hasKey("fieldPath")) {
+        ArrayList<Object> fieldPathArray =
+            Objects.requireNonNull(Objects.requireNonNull(filter).getArray("fieldPath"))
+                .toArrayList();
+        String[] segmentArray = (String[]) fieldPathArray.toArray(new String[0]);
+
+        FieldPath fieldPath = FieldPath.of(Objects.requireNonNull(segmentArray));
+        String operator = filter.getString("operator");
+        ReadableArray arrayValue = filter.getArray("value");
+        Object value = parseTypeMap(query.getFirestore(), Objects.requireNonNull(arrayValue));
+
+        switch (Objects.requireNonNull(operator)) {
+          case "EQUAL":
+            query = query.whereEqualTo(Objects.requireNonNull(fieldPath), value);
+            break;
+          case "NOT_EQUAL":
+            query = query.whereNotEqualTo(Objects.requireNonNull(fieldPath), value);
+            break;
+          case "GREATER_THAN":
+            query =
+                query.whereGreaterThan(
+                    Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
+            break;
+          case "GREATER_THAN_OR_EQUAL":
+            query =
+                query.whereGreaterThanOrEqualTo(
+                    Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
+            break;
+          case "LESS_THAN":
+            query =
+                query.whereLessThan(
+                    Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
+            break;
+          case "LESS_THAN_OR_EQUAL":
+            query =
+                query.whereLessThanOrEqualTo(
+                    Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
+            break;
+          case "ARRAY_CONTAINS":
+            query =
+                query.whereArrayContains(
+                    Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
+            break;
+          case "ARRAY_CONTAINS_ANY":
+            query =
+                query.whereArrayContainsAny(
+                    Objects.requireNonNull(fieldPath),
+                    Objects.requireNonNull((List<Object>) value));
+            break;
+          case "IN":
+            query =
+                query.whereIn(
+                    Objects.requireNonNull(fieldPath),
+                    Objects.requireNonNull((List<Object>) value));
+            break;
+          case "NOT_IN":
+            query =
+                query.whereNotIn(
+                    Objects.requireNonNull(fieldPath),
+                    Objects.requireNonNull((List<Object>) value));
+            break;
+        }
+      } else if (filter.hasKey("operator") && filter.hasKey("queries")) {
+        query = query.where(applyFilterQueries(filter));
+      }
+    }
+  }
+
+  private Filter applyFilterQueries(ReadableMap filter) {
+    if (filter.hasKey("fieldPath")) {
+      String operator =
+          (String) Objects.requireNonNull(Objects.requireNonNull(filter).getString("operator"));
+      ReadableMap fieldPathMap = Objects.requireNonNull(filter.getMap("fieldPath"));
+      ReadableArray segments = Objects.requireNonNull(fieldPathMap.getArray("_segments"));
+      int arraySize = segments.size();
+      String[] segmentArray = new String[arraySize];
 
-      FieldPath fieldPath = FieldPath.of(Objects.requireNonNull(segmentArray));
-      String operator = filter.getString("operator");
+      for (int i = 0; i < arraySize; i++) {
+        segmentArray[i] = segments.getString(i);
+      }
+      FieldPath fieldPath = FieldPath.of(segmentArray);
       ReadableArray arrayValue = filter.getArray("value");
+
       Object value = parseTypeMap(query.getFirestore(), Objects.requireNonNull(arrayValue));
 
-      switch (Objects.requireNonNull(operator)) {
+      switch (operator) {
         case "EQUAL":
-          query = query.whereEqualTo(Objects.requireNonNull(fieldPath), value);
-          break;
+          return Filter.equalTo(fieldPath, value);
         case "NOT_EQUAL":
-          query = query.whereNotEqualTo(Objects.requireNonNull(fieldPath), value);
-          break;
-        case "GREATER_THAN":
-          query =
-              query.whereGreaterThan(
-                  Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
-          break;
-        case "GREATER_THAN_OR_EQUAL":
-          query =
-              query.whereGreaterThanOrEqualTo(
-                  Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
-          break;
+          return Filter.notEqualTo(fieldPath, value);
         case "LESS_THAN":
-          query =
-              query.whereLessThan(Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
-          break;
+          return Filter.lessThan(fieldPath, value);
         case "LESS_THAN_OR_EQUAL":
-          query =
-              query.whereLessThanOrEqualTo(
-                  Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
-          break;
+          return Filter.lessThanOrEqualTo(fieldPath, value);
+        case "GREATER_THAN":
+          return Filter.greaterThan(fieldPath, value);
+        case "GREATER_THAN_OR_EQUAL":
+          return Filter.greaterThanOrEqualTo(fieldPath, value);
         case "ARRAY_CONTAINS":
-          query =
-              query.whereArrayContains(
-                  Objects.requireNonNull(fieldPath), Objects.requireNonNull(value));
-          break;
+          return Filter.arrayContains(fieldPath, value);
         case "ARRAY_CONTAINS_ANY":
-          query =
-              query.whereArrayContainsAny(
-                  Objects.requireNonNull(fieldPath), Objects.requireNonNull((List<Object>) value));
-          break;
+          assert value != null;
+          return Filter.arrayContainsAny(fieldPath, (List<?>) value);
         case "IN":
-          query =
-              query.whereIn(
-                  Objects.requireNonNull(fieldPath), Objects.requireNonNull((List<Object>) value));
-          break;
+          assert value != null;
+          return Filter.inArray(fieldPath, (List<?>) value);
         case "NOT_IN":
-          query =
-              query.whereNotIn(
-                  Objects.requireNonNull(fieldPath), Objects.requireNonNull((List<Object>) value));
-          break;
+          assert value != null;
+          return Filter.notInArray(fieldPath, (List<?>) value);
+        default:
+          throw new Error("Invalid operator");
       }
     }
+
+    String operator = Objects.requireNonNull(filter).getString("operator");
+    ReadableArray queries =
+        Objects.requireNonNull(Objects.requireNonNull(filter).getArray("queries"));
+    ArrayList<Filter> parsedFilters = new ArrayList<>();
+    int arraySize = queries.size();
+    for (int i = 0; i < arraySize; i++) {
+      ReadableMap map = queries.getMap(i);
+      parsedFilters.add(applyFilterQueries(map));
+    }
+
+    if (operator.equals("AND")) {
+      return Filter.and(parsedFilters.toArray(new Filter[0]));
+    }
+
+    if (operator.equals("OR")) {
+      return Filter.or(parsedFilters.toArray(new Filter[0]));
+    }
+
+    throw new Error("Missing 'Filter' instance return");
   }
 
   private void applyOrders(ReadableArray orders) {

package/ios/RNFBFirestore/RNFBFirestoreQuery.m

@@ -51,33 +51,98 @@
 
 - (void)applyFilters {
   for (NSDictionary *filter in _filters) {
-    NSArray *fieldPathArray = filter[@"fieldPath"];
+    if (filter[@"fieldPath"]) {
+      NSArray *fieldPathArray = filter[@"fieldPath"];
+
+      FIRFieldPath *fieldPath = [[FIRFieldPath alloc] initWithFields:fieldPathArray];
+      NSString *operator= filter[@"operator"];
+      id value = [RNFBFirestoreSerialize parseTypeMap:_firestore typeMap:filter[@"value"]];
+      if ([operator isEqualToString:@"EQUAL"]) {
+        _query = [_query queryWhereFieldPath:fieldPath isEqualTo:value];
+      } else if ([operator isEqualToString:@"NOT_EQUAL"]) {
+        _query = [_query queryWhereFieldPath:fieldPath isNotEqualTo:value];
+      } else if ([operator isEqualToString:@"GREATER_THAN"]) {
+        _query = [_query queryWhereFieldPath:fieldPath isGreaterThan:value];
+      } else if ([operator isEqualToString:@"GREATER_THAN_OR_EQUAL"]) {
+        _query = [_query queryWhereFieldPath:fieldPath isGreaterThanOrEqualTo:value];
+      } else if ([operator isEqualToString:@"LESS_THAN"]) {
+        _query = [_query queryWhereFieldPath:fieldPath isLessThan:value];
+      } else if ([operator isEqualToString:@"LESS_THAN_OR_EQUAL"]) {
+        _query = [_query queryWhereFieldPath:fieldPath isLessThanOrEqualTo:value];
+      } else if ([operator isEqualToString:@"ARRAY_CONTAINS"]) {
+        _query = [_query queryWhereFieldPath:fieldPath arrayContains:value];
+      } else if ([operator isEqualToString:@"IN"]) {
+        _query = [_query queryWhereFieldPath:fieldPath in:value];
+      } else if ([operator isEqualToString:@"ARRAY_CONTAINS_ANY"]) {
+        _query = [_query queryWhereFieldPath:fieldPath arrayContainsAny:value];
+      } else if ([operator isEqualToString:@"NOT_IN"]) {
+        _query = [_query queryWhereFieldPath:fieldPath notIn:value];
+      }
+    } else if (filter[@"operator"] && filter[@"queries"]) {
+      // Filter query
+      FIRFilter *generatedFilter = [self _applyFilterQueries:filter];
+      _query = [_query queryWhereFilter:generatedFilter];
+    } else {
+      @throw
+          [NSException exceptionWithName:@"InvalidOperator"
+                                  reason:@"The correct signature for a filter has not been parsed"
+                                userInfo:nil];
+    }
+  }
+}
+
+- (FIRFilter *)_applyFilterQueries:(NSDictionary<NSString *, id> *)map {
+  if ([map objectForKey:@"fieldPath"]) {
+    NSString *operator= map[@"operator"];
+    NSArray *fieldPathArray = map[@"fieldPath"][@"_segments"];
+
     FIRFieldPath *fieldPath = [[FIRFieldPath alloc] initWithFields:fieldPathArray];
-    NSString *operator= filter[@"operator"];
-    id value = [RNFBFirestoreSerialize parseTypeMap:_firestore typeMap:filter[@"value"]];
+    id value = [RNFBFirestoreSerialize parseTypeMap:_firestore typeMap:map[@"value"]];
 
     if ([operator isEqualToString:@"EQUAL"]) {
-      _query = [_query queryWhereFieldPath:fieldPath isEqualTo:value];
+      return [FIRFilter filterWhereFieldPath:fieldPath isEqualTo:value];
     } else if ([operator isEqualToString:@"NOT_EQUAL"]) {
-      _query = [_query queryWhereFieldPath:fieldPath isNotEqualTo:value];
-    } else if ([operator isEqualToString:@"GREATER_THAN"]) {
-      _query = [_query queryWhereFieldPath:fieldPath isGreaterThan:value];
-    } else if ([operator isEqualToString:@"GREATER_THAN_OR_EQUAL"]) {
-      _query = [_query queryWhereFieldPath:fieldPath isGreaterThanOrEqualTo:value];
+      return [FIRFilter filterWhereFieldPath:fieldPath isNotEqualTo:value];
     } else if ([operator isEqualToString:@"LESS_THAN"]) {
-      _query = [_query queryWhereFieldPath:fieldPath isLessThan:value];
+      return [FIRFilter filterWhereFieldPath:fieldPath isLessThan:value];
     } else if ([operator isEqualToString:@"LESS_THAN_OR_EQUAL"]) {
-      _query = [_query queryWhereFieldPath:fieldPath isLessThanOrEqualTo:value];
+      return [FIRFilter filterWhereFieldPath:fieldPath isLessThanOrEqualTo:value];
+    } else if ([operator isEqualToString:@"GREATER_THAN"]) {
+      return [FIRFilter filterWhereFieldPath:fieldPath isGreaterThan:value];
+    } else if ([operator isEqualToString:@"GREATER_THAN_OR_EQUAL"]) {
+      return [FIRFilter filterWhereFieldPath:fieldPath isGreaterThanOrEqualTo:value];
     } else if ([operator isEqualToString:@"ARRAY_CONTAINS"]) {
-      _query = [_query queryWhereFieldPath:fieldPath arrayContains:value];
-    } else if ([operator isEqualToString:@"IN"]) {
-      _query = [_query queryWhereFieldPath:fieldPath in:value];
+      return [FIRFilter filterWhereFieldPath:fieldPath arrayContains:value];
     } else if ([operator isEqualToString:@"ARRAY_CONTAINS_ANY"]) {
-      _query = [_query queryWhereFieldPath:fieldPath arrayContainsAny:value];
+      return [FIRFilter filterWhereFieldPath:fieldPath arrayContainsAny:value];
+    } else if ([operator isEqualToString:@"IN"]) {
+      return [FIRFilter filterWhereFieldPath:fieldPath in:value];
     } else if ([operator isEqualToString:@"NOT_IN"]) {
-      _query = [_query queryWhereFieldPath:fieldPath notIn:value];
+      return [FIRFilter filterWhereFieldPath:fieldPath notIn:value];
+    } else {
+      @throw [NSException exceptionWithName:@"InvalidOperator"
+                                     reason:@"Invalid operator"
+                                   userInfo:nil];
     }
   }
+
+  NSString *op = map[@"operator"];
+  NSArray<NSDictionary<NSString *, id> *> *queries = map[@"queries"];
+  NSMutableArray<FIRFilter *> *parsedFilters = [NSMutableArray array];
+
+  for (NSDictionary *query in queries) {
+    [parsedFilters addObject:[self _applyFilterQueries:query]];
+  }
+
+  if ([op isEqual:@"AND"]) {
+    return [FIRFilter andFilterWithFilters:parsedFilters];
+  }
+
+  if ([op isEqualToString:@"OR"]) {
+    return [FIRFilter orFilterWithFilters:parsedFilters];
+  }
+
+  @throw [NSException exceptionWithName:@"InvalidOperator" reason:@"Invalid operator" userInfo:nil];
 }
 
 - (void)applyOrders {

package/lib/FirestoreFilter.js

@@ -0,0 +1,151 @@
+import { isString, isNull, isUndefined, isArray } from '@react-native-firebase/app/lib/common';
+import { fromDotSeparatedString } from './FirestoreFieldPath';
+import { generateNativeData } from './utils/serialize';
+import { OPERATORS } from './FirestoreQueryModifiers';
+const AND_QUERY = 'AND';
+const OR_QUERY = 'OR';
+
+export function Filter(fieldPath, operator, value) {
+  return new _Filter(fieldPath, operator, value);
+}
+
+export function _Filter(fieldPath, operator, value, filterOperator, queries) {
+  if ([AND_QUERY, OR_QUERY].includes(filterOperator)) {
+    // AND or OR Filter (list of Filters)
+    this.operator = filterOperator;
+    this.queries = queries;
+
+    this._toMap = function _toMap() {
+      return {
+        operator: this.operator,
+        queries: this.queries.map(query => query._toMap()),
+      };
+    };
+
+    return this;
+  } else {
+    // Filter
+    this.fieldPath = fieldPath;
+    this.operator = operator;
+    this.value = value;
+
+    this._toMap = function _toMap() {
+      return {
+        fieldPath: this.fieldPath,
+        operator: this.operator,
+        value: this.value,
+      };
+    };
+
+    return this;
+  }
+}
+
+Filter.and = function and(...queries) {
+  if (queries.length > 10 || queries.length < 2) {
+    throw new Error(`Expected 2-10 instances of Filter, but got ${queries.length} Filters`);
+  }
+
+  const validateFilters = queries.every(filter => filter instanceof _Filter);
+
+  if (!validateFilters) {
+    throw new Error('Expected every argument to be an instance of Filter');
+  }
+
+  return new _Filter(null, null, null, AND_QUERY, queries);
+};
+
+function hasOrOperator(obj) {
+  return obj.operator === 'OR' || (Array.isArray(obj.queries) && obj.queries.some(hasOrOperator));
+}
+
+Filter.or = function or(...queries) {
+  if (queries.length > 10 || queries.length < 2) {
+    throw new Error(`Expected 2-10 instances of Filter, but got ${queries.length} Filters`);
+  }
+
+  const validateFilters = queries.every(filter => filter instanceof _Filter);
+
+  if (!validateFilters) {
+    throw new Error('Expected every argument to be an instance of Filter');
+  }
+
+  const hasOr = queries.some(hasOrOperator);
+
+  if (hasOr) {
+    throw new Error('OR Filters with nested OR Filters are not supported');
+  }
+
+  return new _Filter(null, null, null, OR_QUERY, queries);
+};
+
+function mapFieldQuery({ fieldPath, operator, value, queries }, modifiers) {
+  if (operator === AND_QUERY || operator === OR_QUERY) {
+    return {
+      operator,
+      queries: queries.map(filter => mapFieldQuery(filter, modifiers)),
+    };
+  }
+
+  let path;
+  if (isString(fieldPath)) {
+    try {
+      path = fromDotSeparatedString(fieldPath);
+    } catch (e) {
+      throw new Error(`first argument of Filter(*,_ , _) 'fieldPath' ${e.message}.`);
+    }
+  } else {
+    path = fieldPath;
+  }
+
+  if (!modifiers.isValidOperator(operator)) {
+    throw new Error(
+      "second argument of Filter(*,_ , _) 'opStr' is invalid. Expected one of '==', '>', '>=', '<', '<=', '!=', 'array-contains', 'not-in', 'array-contains-any' or 'in'.",
+    );
+  }
+
+  if (isUndefined(value)) {
+    throw new Error("third argument of Filter(*,_ , _) 'value' argument expected.");
+  }
+
+  if (
+    isNull(value) &&
+    !modifiers.isEqualOperator(operator) &&
+    !modifiers.isNotEqualOperator(operator)
+  ) {
+    throw new Error(
+      "third argument of Filter(*,_ , _) 'value' is invalid. You can only perform equals comparisons on null",
+    );
+  }
+
+  if (modifiers.isInOperator(operator)) {
+    if (!isArray(value) || !value.length) {
+      throw new Error(
+        `third argument of Filter(*,_ , _) 'value' is invalid. A non-empty array is required for '${operator}' filters.`,
+      );
+    }
+
+    if (value.length > 10) {
+      throw new Error(
+        `third argument of Filter(*,_ , _) 'value' is invalid. '${operator}' filters support a maximum of 10 elements in the value array.`,
+      );
+    }
+  }
+
+  return {
+    fieldPath: path,
+    operator: OPERATORS[operator],
+    value: generateNativeData(value, true),
+  };
+}
+
+export function generateFilters(filter, modifiers) {
+  const filterMap = filter._toMap();
+
+  const queriesMaps = filterMap.queries.map(filter => mapFieldQuery(filter, modifiers));
+
+  return {
+    operator: filterMap.operator,
+    queries: queriesMaps,
+  };
+}

package/lib/FirestoreQuery.js

@@ -28,6 +28,7 @@ import FirestoreDocumentSnapshot from './FirestoreDocumentSnapshot';
 import FirestoreFieldPath, { fromDotSeparatedString } from './FirestoreFieldPath';
 import FirestoreQuerySnapshot from './FirestoreQuerySnapshot';
 import { parseSnapshotArgs } from './utils';
+import { _Filter, generateFilters } from './FirestoreFilter';
 
 let _id = 0;
 
@@ -406,62 +407,79 @@ export default class FirestoreQuery {
     );
   }
 
-  where(fieldPath, opStr, value) {
-    if (!isString(fieldPath) && !(fieldPath instanceof FirestoreFieldPath)) {
+  where(fieldPathOrFilter, opStr, value) {
+    if (
+      !isString(fieldPathOrFilter) &&
+      !(fieldPathOrFilter instanceof FirestoreFieldPath) &&
+      !(fieldPathOrFilter instanceof _Filter)
+    ) {
       throw new Error(
-        "firebase.firestore().collection().where(*) 'fieldPath' must be a string or instance of FieldPath.",
+        "firebase.firestore().collection().where(*) 'fieldPath' must be a string, instance of FieldPath or instance of Filter.",
       );
     }
 
-    let path;
-
-    if (isString(fieldPath)) {
-      try {
-        path = fromDotSeparatedString(fieldPath);
-      } catch (e) {
-        throw new Error(`firebase.firestore().collection().where(*) 'fieldPath' ${e.message}.`);
-      }
+    let modifiers;
+    if (fieldPathOrFilter instanceof _Filter && fieldPathOrFilter.queries) {
+      //AND or OR filter
+      const filters = generateFilters(fieldPathOrFilter, this._modifiers);
+      modifiers = this._modifiers._copy().filterWhere(filters);
     } else {
-      path = fieldPath;
-    }
-
-    if (!this._modifiers.isValidOperator(opStr)) {
-      throw new Error(
-        "firebase.firestore().collection().where(_, *) 'opStr' is invalid. Expected one of '==', '>', '>=', '<', '<=', '!=', 'array-contains', 'not-in', 'array-contains-any' or 'in'.",
-      );
-    }
+      if (fieldPathOrFilter instanceof _Filter) {
+        // Standard Filter. Usual path.
+        opStr = fieldPathOrFilter.operator;
+        value = fieldPathOrFilter.value;
+        fieldPathOrFilter = fieldPathOrFilter.fieldPath;
+      }
+      let path;
 
-    if (isUndefined(value)) {
-      throw new Error(
-        "firebase.firestore().collection().where(_, _, *) 'value' argument expected.",
-      );
-    }
+      if (isString(fieldPathOrFilter)) {
+        try {
+          path = fromDotSeparatedString(fieldPathOrFilter);
+        } catch (e) {
+          throw new Error(`firebase.firestore().collection().where(*) 'fieldPath' ${e.message}.`);
+        }
+      } else {
+        path = fieldPathOrFilter;
+      }
 
-    if (
-      isNull(value) &&
-      !this._modifiers.isEqualOperator(opStr) &&
-      !this._modifiers.isNotEqualOperator(opStr)
-    ) {
-      throw new Error(
-        "firebase.firestore().collection().where(_, _, *) 'value' is invalid. You can only perform equals comparisons on null",
-      );
-    }
+      if (!this._modifiers.isValidOperator(opStr)) {
+        throw new Error(
+          "firebase.firestore().collection().where(_, *) 'opStr' is invalid. Expected one of '==', '>', '>=', '<', '<=', '!=', 'array-contains', 'not-in', 'array-contains-any' or 'in'.",
+        );
+      }
 
-    if (this._modifiers.isInOperator(opStr)) {
-      if (!isArray(value) || !value.length) {
+      if (isUndefined(value)) {
         throw new Error(
-          `firebase.firestore().collection().where(_, _, *) 'value' is invalid. A non-empty array is required for '${opStr}' filters.`,
+          "firebase.firestore().collection().where(_, _, *) 'value' argument expected.",
         );
       }
 
-      if (value.length > 10) {
+      if (
+        isNull(value) &&
+        !this._modifiers.isEqualOperator(opStr) &&
+        !this._modifiers.isNotEqualOperator(opStr)
+      ) {
         throw new Error(
-          `firebase.firestore().collection().where(_, _, *) 'value' is invalid. '${opStr}' filters support a maximum of 10 elements in the value array.`,
+          "firebase.firestore().collection().where(_, _, *) 'value' is invalid. You can only perform equals comparisons on null",
         );
       }
-    }
 
-    const modifiers = this._modifiers._copy().where(path, opStr, value);
+      if (this._modifiers.isInOperator(opStr)) {
+        if (!isArray(value) || !value.length) {
+          throw new Error(
+            `firebase.firestore().collection().where(_, _, *) 'value' is invalid. A non-empty array is required for '${opStr}' filters.`,
+          );
+        }
+
+        if (value.length > 10) {
+          throw new Error(
+            `firebase.firestore().collection().where(_, _, *) 'value' is invalid. '${opStr}' filters support a maximum of 10 elements in the value array.`,
+          );
+        }
+      }
+
+      modifiers = this._modifiers._copy().where(path, opStr, value);
+    }
 
     try {
       modifiers.validateWhere();

package/lib/FirestoreQueryModifiers.js

@@ -19,7 +19,7 @@ import { isNumber } from '@react-native-firebase/app/lib/common';
 import FirestoreFieldPath, { DOCUMENT_ID } from './FirestoreFieldPath';
 import { buildNativeArray, generateNativeData } from './utils/serialize';
 
-const OPERATORS = {
+export const OPERATORS = {
   '==': 'EQUAL',
   '>': 'GREATER_THAN',
   '>=': 'GREATER_THAN_OR_EQUAL',
@@ -57,6 +57,14 @@ export default class FirestoreQueryModifiers {
     this._startAfter = undefined;
     this._endAt = undefined;
     this._endBefore = undefined;
+
+    // Pulled out of function to preserve their state
+    this.hasInequality = false;
+    this.hasNotEqual = false;
+    this.hasArrayContains = false;
+    this.hasArrayContainsAny = false;
+    this.hasIn = false;
+    this.hasNotIn = false;
   }
 
   _copy() {
@@ -221,118 +229,129 @@ export default class FirestoreQueryModifiers {
     return this;
   }
 
+  filterWhere(filter) {
+    this._filters = this._filters.concat(filter);
+    return this;
+  }
+
   validateWhere() {
-    let hasInequality;
-    let hasNotEqual;
+    if (this._filters.length > 0) {
+      this._filterCheck(this._filters);
+    }
+  }
+
+  _filterCheck(filters) {
+    for (let i = 0; i < filters.length; i++) {
+      const filter = filters[i];
+
+      if (filter.queries) {
+        // Recursively check sub-queries for Filters
+        this._filterCheck(filter.queries);
+        // If it is a Filter query, skip the rest of the loop
+        continue;
+      }
 
-    for (let i = 0; i < this._filters.length; i++) {
-      const filter = this._filters[i];
       // Skip if no inequality
       if (!INEQUALITY[filter.operator]) {
         continue;
       }
 
       if (filter.operator === OPERATORS['!=']) {
-        if (hasNotEqual) {
+        if (this.hasNotEqual) {
           throw new Error("Invalid query. You cannot use more than one '!=' inequality filter.");
         }
         //needs to set hasNotEqual = true  before setting first hasInequality = filter. It is used in a condition check later
-        hasNotEqual = true;
+        this.hasNotEqual = true;
       }
 
       // Set the first inequality
-      if (!hasInequality) {
-        hasInequality = filter;
+      if (!this.hasInequality) {
+        this.hasInequality = filter;
         continue;
       }
 
       // Check the set value is the same as the new one
-      if (INEQUALITY[filter.operator] && hasInequality) {
-        if (hasInequality.fieldPath._toPath() !== filter.fieldPath._toPath()) {
+      if (INEQUALITY[filter.operator] && this.hasInequality) {
+        if (this.hasInequality.fieldPath._toPath() !== filter.fieldPath._toPath()) {
           throw new Error(
-            `Invalid query. All where filters with an inequality (<, <=, >, != or >=) must be on the same field. But you have inequality filters on '${hasInequality.fieldPath._toPath()}' and '${filter.fieldPath._toPath()}'`,
+            `Invalid query. All where filters with an inequality (<, <=, >, != or >=) must be on the same field. But you have inequality filters on '${this.hasInequality.fieldPath._toPath()}' and '${filter.fieldPath._toPath()}'`,
           );
         }
       }
     }
 
-    let hasArrayContains;
-    let hasArrayContainsAny;
-    let hasIn;
-    let hasNotIn;
-
-    for (let i = 0; i < this._filters.length; i++) {
-      const filter = this._filters[i];
+    for (let i = 0; i < filters.length; i++) {
+      const filter = filters[i];
 
       if (filter.operator === OPERATORS['array-contains']) {
-        if (hasArrayContains) {
+        if (this.hasArrayContains) {
           throw new Error('Invalid query. Queries only support a single array-contains filter.');
         }
-        hasArrayContains = true;
+        this.hasArrayContains = true;
       }
 
       if (filter.operator === OPERATORS['array-contains-any']) {
-        if (hasArrayContainsAny) {
+        if (this.hasArrayContainsAny) {
           throw new Error(
             "Invalid query. You cannot use more than one 'array-contains-any' filter.",
           );
         }
 
-        if (hasIn) {
+        if (this.hasIn) {
           throw new Error(
             "Invalid query. You cannot use 'array-contains-any' filters with 'in' filters.",
           );
         }
 
-        if (hasNotIn) {
+        if (this.hasNotIn) {
           throw new Error(
             "Invalid query. You cannot use 'array-contains-any' filters with 'not-in' filters.",
           );
         }
 
-        hasArrayContainsAny = true;
+        this.hasArrayContainsAny = true;
       }
 
       if (filter.operator === OPERATORS.in) {
-        if (hasIn) {
+        if (this.hasIn) {
           throw new Error("Invalid query. You cannot use more than one 'in' filter.");
         }
 
-        if (hasArrayContainsAny) {
+        if (this.hasArrayContainsAny) {
           throw new Error(
             "Invalid query. You cannot use 'in' filters with 'array-contains-any' filters.",
           );
         }
 
-        if (hasNotIn) {
+        if (this.hasNotIn) {
           throw new Error("Invalid query. You cannot use 'in' filters with 'not-in' filters.");
         }
 
-        hasIn = true;
+        this.hasIn = true;
       }
 
       if (filter.operator === OPERATORS['not-in']) {
-        if (hasNotIn) {
+        if (this.hasNotIn) {
           throw new Error("Invalid query. You cannot use more than one 'not-in' filter.");
         }
 
-        if (hasNotEqual) {
+        if (this.hasNotEqual) {
           throw new Error(
             "Invalid query. You cannot use 'not-in' filters with '!=' inequality filters",
           );
         }
 
-        if (hasIn) {
+        if (this.hasIn) {
           throw new Error("Invalid query. You cannot use 'not-in' filters with 'in' filters.");
         }
 
-        if (hasArrayContainsAny) {
+        if (this.hasArrayContainsAny) {
           throw new Error(
             "Invalid query. You cannot use 'not-in' filters with 'array-contains-any' filters.",
           );
         }
 
-        hasNotIn = true;
+        this.hasNotIn = true;
       }
     }
   }
@@ -356,6 +375,10 @@ export default class FirestoreQueryModifiers {
   }
 
   validateOrderBy() {
+    this._validateOrderByCheck(this._filters);
+  }
+
+  _validateOrderByCheck(filters) {
     // Ensure order hasn't been called on the same field
     if (this._orders.length > 1) {
       const orders = this._orders.map($ => $.fieldPath._toPath());
@@ -367,13 +390,20 @@ export default class FirestoreQueryModifiers {
     }
 
     // Skip if no where filters
-    if (this._filters.length === 0) {
+    if (filters.length === 0) {
       return;
     }
 
     // Ensure the first order field path is equal to the inequality filter field path
-    for (let i = 0; i < this._filters.length; i++) {
-      const filter = this._filters[i];
+    for (let i = 0; i < filters.length; i++) {
+      const filter = filters[i];
+
+      if (filter.queries) {
+        // Recursively check sub-queries for Filters
+        this._validateOrderByCheck(filter.queries);
+        // If it is a Filter query, skip the rest of the loop
+        continue;
+      }
       const filterFieldPath = filter.fieldPath._toPath();
 
       for (let k = 0; k < this._orders.length; k++) {

package/lib/FirestoreStatics.js

@@ -21,13 +21,14 @@ import FirestoreFieldPath from './FirestoreFieldPath';
 import FirestoreFieldValue from './FirestoreFieldValue';
 import FirestoreGeoPoint from './FirestoreGeoPoint';
 import FirestoreTimestamp from './FirestoreTimestamp';
-
+import { Filter } from './FirestoreFilter';
 export default {
   Blob: FirestoreBlob,
   FieldPath: FirestoreFieldPath,
   FieldValue: FirestoreFieldValue,
   GeoPoint: FirestoreGeoPoint,
   Timestamp: FirestoreTimestamp,
+  Filter: Filter,
 
   CACHE_SIZE_UNLIMITED: -1,
 

package/lib/index.d.ts

@@ -49,6 +49,47 @@ import { ReactNativeFirebase } from '@react-native-firebase/app';
  */
 export namespace FirebaseFirestoreTypes {
   import FirebaseModule = ReactNativeFirebase.FirebaseModule;
+  /**
+   * An instance of Filter used to generate Firestore Filter queries.
+   */
+
+  export type QueryFilterType = 'OR' | 'AND';
+
+  export interface QueryFilterConstraint {
+    fieldPath: keyof T | FieldPath;
+    operator: WhereFilterOp;
+    value: any;
+  }
+
+  export interface QueryCompositeFilterConstraint {
+    operator: QueryFilterType;
+    queries: QueryFilterConstraint[];
+  }
+  /**
+   * The Filter functions used to generate an instance of Filter.
+   */
+  export interface FilterFunction {
+    /**
+     * The Filter function used to generate an instance of Filter.
+     * e.g. Filter('name', '==', 'Ada')
+     */
+    (fieldPath: keyof T | FieldPath, operator: WhereFilterOp, value: any): QueryFilterConstraint;
+    /**
+     * The Filter.or() static function used to generate a logical OR query using multiple Filter instances.
+     * e.g. Filter.or(Filter('name', '==', 'Ada'), Filter('name', '==', 'Bob'))
+     */
+    or(...queries: QueryFilterConstraint[]): QueryCompositeFilterConstraint;
+    /**
+     * The Filter.and() static function used to generate a logical AND query using multiple Filter instances.
+     * e.g. Filter.and(Filter('name', '==', 'Ada'), Filter('name', '==', 'Bob'))
+     */
+    and(...queries: QueryFilterConstraint[]): QueryCompositeFilterConstraint;
+  }
+  /**
+   * The Filter function used to generate an instance of Filter.
+   * e.g. Filter('name', '==', 'Ada')
+   */
+  export const Filter: FilterFunction;
 
   /**
    * An immutable object representing an array of bytes.

package/lib/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-module.exports = '17.4.3';
+module.exports = '17.5.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-firebase/firestore",
-  "version": "17.4.3",
+  "version": "17.5.0",
   "author": "Invertase <oss@invertase.io> (http://invertase.io)",
   "description": "React Native Firebase - Cloud Firestore is a NoSQL cloud database to store and sync data between your React Native application and Firebase's database. The API matches the Firebase Web SDK whilst taking advantage of the native SDKs performance and offline capabilities.",
   "main": "lib/index.js",
@@ -27,10 +27,10 @@
     "firestore"
   ],
   "peerDependencies": {
-    "@react-native-firebase/app": "17.4.3"
+    "@react-native-firebase/app": "17.5.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "3c47228dcb65ee6f9ac71f30c4dffbe4cf088d2a"
+  "gitHead": "a58ea4bfd72c903d43844da30d4f3bf5feb0f057"
 }