Saad Query Filters #1

Author: SaadArdati

lib/src/api/mixins.dart

@@ -1123,3 +1123,41 @@ mixin ConditionsMixin {
   /// List of conditions that are applied to this node.
   List<BaseCondition> conditions = [];
 }
+
+/// A mixin that adds the ability to filter a collection of data
+/// on a node.
+mixin QueryableMixin on BaseNode {
+  /// List of where() operations to be applied to the query.
+  List<WhereQueryFilter> whereFilters = [];
+
+  /// List of orderBy() operations to be applied to the query.
+  List<OrderByQueryFilter> orderByOperations = [];
+
+  /// Whether to use cloud database.
+  late bool useCloudDatabase;
+
+  /// The path of the collection to query.
+  late String? collectionPath;
+
+  /// A limit integer to specify the number of documents to be returned.
+  late int limit;
+
+  /// Whether the query operation is going to be restrictive.
+  /// This pertains to Firestore's indexing rules.
+  bool get restrictedIndexing => useCloudDatabase;
+
+  /// Sets the properties of this mixin.
+  void setQueryableMixin({
+    required List<WhereQueryFilter> whereOperations,
+    required List<OrderByQueryFilter> orderByOperations,
+    required bool useCloudDatabase,
+    required String? collectionPath,
+    required int limit,
+  }) {
+    this.whereFilters = whereOperations;
+    this.orderByOperations = orderByOperations;
+    this.useCloudDatabase = useCloudDatabase;
+    this.collectionPath = collectionPath;
+    this.limit = limit;
+  }
+}

lib/src/api/models/cloud_database_queries/order_by_query_filter.dart

@@ -0,0 +1,59 @@
+import 'package:codelessly_json_annotation/codelessly_json_annotation.dart';
+import 'package:equatable/equatable.dart';
+
+import 'query_filter.dart';
+
+part 'order_by_query_filter.g.dart';
+
+/// Enum representing the Firestore order by operations.
+enum OrderByQuerySortOrder {
+  /// Represents an ascending order operation.
+  ascending('asc', 'In Ascending Order'),
+
+  /// Represents a descending order operation.
+  descending('desc', 'In Descending Order');
+
+  /// The operation name.
+  final String value;
+
+  /// The human-readable name of the operation.
+  final String label;
+
+  const OrderByQuerySortOrder(this.value, this.label);
+}
+
+/// Represents the order-by operation in Firestore.
+@JsonSerializable()
+class OrderByQueryFilter extends QueryFilter with EquatableMixin {
+  /// The order-by operation to perform.
+  final OrderByQuerySortOrder sortOrder;
+
+  /// Creates a new [OrderByQueryFilter] instance, given a [field] and an
+  /// [sortOrder].
+  const OrderByQueryFilter({
+    required super.field,
+    this.sortOrder = OrderByQuerySortOrder.ascending,
+  });
+
+  /// Creates a copy of this [OrderByQueryFilter] instance with the given
+  /// parameters.
+  OrderByQueryFilter copyWith({
+    String? field,
+    OrderByQuerySortOrder? operator,
+  }) {
+    return OrderByQueryFilter(
+      field: field ?? this.field,
+      sortOrder: operator ?? this.sortOrder,
+    );
+  }
+
+  /// Converts a JSON object to a [OrderByQueryFilter] instance.
+  factory OrderByQueryFilter.fromJson(Map<String, dynamic> json) =>
+      _$OrderByQueryFilterFromJson(json);
+
+  /// Converts this [OrderByQueryFilter] instance to a JSON object.
+  Map<String, dynamic> toJson() => _$OrderByQueryFilterToJson(this);
+
+  @override
+  List<Object?> get props => [field, sortOrder];
+}

lib/src/api/models/cloud_database_queries/order_by_query_filter.g.dart

@@ -0,0 +1,20 @@
+import 'order_by_query_filter.dart';
+import 'where_query_filter.dart';
+
+/// An abstract class that represents common firestore operations.
+abstract class QueryFilter {
+
+  /// The name of the field to target.
+  final String field;
+
+  /// Creates a new [QueryFilter] instance.
+  const QueryFilter({required this.field});
+
+  /// A convenience getter that returns true if this [QueryFilter] is a
+  /// [WhereQueryFilter].
+  bool get isWhereFilter => this is WhereQueryFilter;
+
+  /// A convenience getter that returns true if this [QueryFilter] is an
+  /// [OrderByQueryFilter].
+  bool get isOrderByFilter => this is OrderByQueryFilter;
+}

lib/src/api/models/cloud_database_queries/query_filter.dart

@@ -0,0 +1,162 @@
+import 'package:codelessly_json_annotation/codelessly_json_annotation.dart';
+import 'package:equatable/equatable.dart';
+
+import 'query_filter.dart';
+
+part 'where_query_filter.g.dart';
+
+/// Enum representing the Firestore where operation.
+///
+/// Reference: https://firebase.google.com/docs/firestore/query-data/queries?hl=en
+///
+/// Cloud Firestore supports the following comparison operators:
+/// < less than
+/// <= less than or equal to
+/// == equal to
+/// > greater than
+/// >= greater than or equal to
+/// != not equal to
+/// array-contains
+/// array-contains-any
+/// in
+/// not-in
+enum WhereQueryOperator {
+  /// Compares two values and returns true if they are equal.
+  equal('Equal To', '=='),
+
+  /// Checks if two values are not equal.
+  notEqual('Not Equal To', '!='),
+
+  /// Compares two values and returns true if the first is less than the second.
+  lessThan('Less Than', '<'),
+
+  /// Compares two values and returns true if the first is less than or equal
+  /// to the second.
+  lessThanOrEqual('Less Than Or Equal To', '<='),
+
+  /// Compares two values and returns true if the first is greater than the
+  /// second.
+  greaterThan('Greater Than', '>'),
+
+  /// Compares two values and returns true if the first is greater than or equal
+  /// to the second.
+  greaterThanOrEqual('Greater Than Or Equal To', '>='),
+
+  /// Checks if an array contains a value.
+  arrayContains('Array Contains', 'array-contains'),
+
+  /// Checks if an array contains any of the values in a given array.
+  arrayContainsAny('Array Contains Any', 'array-contains-any'),
+
+  /// Checks if a value is in a given array.
+  inArray('In Array', 'in'),
+
+  /// Checks if a value is not in a given array.
+  notInArray('Not In Array', 'not-in');
+
+  /// The human-readable name of the operation.
+  final String label;
+
+  /// The operator to use in the query.
+  final String operator;
+
+  const WhereQueryOperator(this.label, this.operator);
+
+  /// Returns true if this operation is a range operation.
+  bool get isRangeOperator =>
+      this == WhereQueryOperator.greaterThan ||
+      this == WhereQueryOperator.greaterThanOrEqual ||
+      this == WhereQueryOperator.lessThan ||
+      this == WhereQueryOperator.lessThanOrEqual;
+
+  /// Returns true if this operation is an inequality operation.
+  bool get isInequalityOperator =>
+      isRangeOperator ||
+      this == WhereQueryOperator.notEqual ||
+      this == WhereQueryOperator.notInArray;
+
+  /// Returns true if this operation is an equality operation.
+  bool get isEqualityOperator =>
+      this == WhereQueryOperator.equal ||
+      this == WhereQueryOperator.arrayContains ||
+      this == WhereQueryOperator.inArray;
+
+  /// Returns a set of all range operators.
+  static Set<WhereQueryOperator> get rangeOperators => {
+        WhereQueryOperator.greaterThan,
+        WhereQueryOperator.greaterThanOrEqual,
+        WhereQueryOperator.lessThan,
+        WhereQueryOperator.lessThanOrEqual,
+      };
+
+  /// Returns a set of all inequality operators.
+  static Set<WhereQueryOperator> get inequalityOperators => {
+        ...rangeOperators,
+        WhereQueryOperator.notEqual,
+        WhereQueryOperator.notInArray,
+      };
+
+  /// Returns a set of all equality operators.
+  static Set<WhereQueryOperator> get equalityOperators => {
+        WhereQueryOperator.equal,
+        WhereQueryOperator.arrayContains,
+        WhereQueryOperator.inArray,
+      };
+
+  /// Returns true if the given [operators] iterable contains any equality
+  /// operator.
+  static bool hasEqualityOperator(Iterable<WhereQueryOperator> operators) {
+    return operators.any((operator) => operator.isEqualityOperator);
+  }
+
+  /// Returns true if the given [operators] iterable contains any inequality
+  /// operator.
+  static bool hasInequalityOperator(Iterable<WhereQueryOperator> operators) {
+    return operators.any((operator) => operator.isInequalityOperator);
+  }
+}
+
+/// Represents the where operation in Codelessly Cloud Database.
+///
+/// Takes three parameters: a field to filter on, a comparison operator, and a value.
+///
+/// Reference: https://firebase.google.com/docs/firestore/query-data/queries?hl=en
+@JsonSerializable()
+class WhereQueryFilter extends QueryFilter with EquatableMixin {
+  /// The where operation to perform.
+  final WhereQueryOperator operator;
+
+  /// The value to compare against.
+  final dynamic value;
+
+  /// Creates a new [WhereQueryFilter] instance, given a [field], an [operator],
+  /// and a [value].
+  const WhereQueryFilter({
+    required super.field,
+    required this.operator,
+    required this.value,
+  });
+
+  /// Creates a copy of this [WhereQueryFilter] instance, given a [field], an
+  /// [operator], and a [value].
+  WhereQueryFilter copyWith({
+    String? field,
+    WhereQueryOperator? operator,
+    dynamic value,
+  }) =>
+      WhereQueryFilter(
+        field: field ?? this.field,
+        operator: operator ?? this.operator,
+        value: value ?? this.value,
+      );
+
+  /// Converts a JSON object to a [WhereQueryFilter] instance.
+  factory WhereQueryFilter.fromJson(Map<String, dynamic> json) =>
+      _$WhereQueryFilterFromJson(json);
+
+  /// Converts this [WhereQueryFilter] instance to a JSON object.
+  Map<String, dynamic> toJson() => _$WhereQueryFilterToJson(this);
+
+  @override
+  List<Object?> get props => [field, operator, value];
+}

lib/src/api/models/cloud_database_queries/where_query_filter.dart

@@ -66,3 +66,6 @@ export 'vec.dart';
 export 'visual_density.dart';
 export 'webview_models.dart';
 export 'grid_delegate_type.dart';
+export 'cloud_database_queries/query_filter.dart';
+export 'cloud_database_queries/where_query_filter.dart';
+export 'cloud_database_queries/order_by_query_filter.dart';