feat(search): update query params build (algolia#8)

Author: aallam

helper_dart/lib/src/utils.dart renamed to helper_dart/lib/src/extensions.dart

@@ -1,5 +1,7 @@
+import 'package:meta/meta.dart';
+
 /// Represents a search filter
-class Filter {
+abstract class Filter {
  const Filter._(this.attribute, this.isNegated);
 
  final String attribute;
@@ -8,10 +10,10 @@ class Filter {
  /// Creates [FilterFacet] instance.
  static FilterFacet facet(
  String attribute,
- dynamic value, [
+ dynamic value, {
  bool isNegated = false,
  int? score,
- ]) =>
+ }) =>
  FilterFacet._(attribute, value, isNegated, score);
 
  /// Creates [FilterTag] instance.
@@ -22,19 +24,23 @@ class Filter {
  static FilterNumeric comparison(
  String attribute,
  NumericOperator operator,
- num number, [
+ num number, {
  bool isNegated = false,
- ]) =>
+ }) =>
  FilterNumeric.comparison(attribute, operator, number, isNegated);
 
  /// Creates [FilterNumeric] instance as numeric range.
  static FilterNumeric range(
- String attribute,
- num lowerBound,
- num upperBound, [
+ String attribute, {
+ required num lowerBound,
+ required num upperBound,
  bool isNegated = false,
- ]) =>
+ }) =>
  FilterNumeric.range(attribute, lowerBound, upperBound, isNegated);
+
+ /// Negates a [FilterFacet].
+ @factory
+ Filter not();
 }
 
 /// A [FilterFacet] matches exactly an [attribute] with a [value].
@@ -84,12 +90,15 @@ class FilterFacet implements Filter {
  bool? isNegated,
  int? score,
  }) =>
- Filter.facet(
+ FilterFacet._(
  attribute ?? this.attribute,
  value ?? this.value,
  isNegated ?? this.isNegated,
  score ?? this.score,
  );
+
+ @override
+ FilterFacet not() => copyWith(isNegated: !isNegated);
 }
 
 /// A [FilterTag] filters on a specific [value].
@@ -127,10 +136,13 @@ class FilterTag implements Filter {
  String? value,
  bool? isNegated,
  }) =>
- Filter.tag(
+ FilterTag._(
  value ?? this.value,
  isNegated ?? this.isNegated,
  );
+
+ @override
+ FilterTag not() => copyWith(isNegated: !isNegated);
 }
 
 /// A [FilterNumeric] filters on a numeric [value].
@@ -176,6 +188,9 @@ class FilterNumeric implements Filter {
  value ?? this.value,
  isNegated ?? this.isNegated,
  );
+
+ @override
+ FilterNumeric not() => copyWith(isNegated: !isNegated);
 }
 
 /// Represents a filter numeric value.

helper_dart/lib/src/filter.dart

@@ -1,5 +1,7 @@
+import 'package:collection/collection.dart';
+
+import 'extensions.dart';
 import 'filter.dart';
-import 'utils.dart';
 
 /// Identifier of a filter group.
 /// The group name is for access purpose only, won't be used for the actual
@@ -39,45 +41,45 @@ class FilterGroupID {
 enum FilterOperator { and, or }
 
 /// Represents a filter group
-abstract class FilterGroup<T> {
- const FilterGroup._(this.groupID, this.filters);
+abstract class FilterGroup<T> extends DelegatingSet<T> {
+ const FilterGroup._(this.groupID, this._filters) : super(_filters);
 
  /// Create [FilterGroup] as [FacetFilterGroup].
- static FacetFilterGroup facet([
+ static FacetFilterGroup facet({
  String name = '',
  Set<FilterFacet> filters = const {},
  FilterOperator operator = FilterOperator.and,
- ]) =>
+ }) =>
  FacetFilterGroup(FilterGroupID(name, operator), filters);
 
  /// Create [FilterGroup] as [TagFilterGroup].
- static TagFilterGroup tag([
+ static TagFilterGroup tag({
  String name = '',
  Set<FilterTag> filters = const {},
  FilterOperator operator = FilterOperator.and,
- ]) =>
+ }) =>
  TagFilterGroup(FilterGroupID(name, operator), filters);
 
  /// Create [FilterGroup] as [NumericFilterGroup].
- static NumericFilterGroup numeric([
+ static NumericFilterGroup numeric({
  String name = '',
  Set<FilterNumeric> filters = const {},
  FilterOperator operator = FilterOperator.and,
- ]) =>
+ }) =>
  NumericFilterGroup(FilterGroupID(name, operator), filters);
 
  /// Create [FilterGroup] as [HierarchicalFilterGroup].
- static HierarchicalFilterGroup hierarchical([
+ static HierarchicalFilterGroup hierarchical({
  String name = '',
  Set<HierarchicalFilter> filters = const {},
- ]) =>
+ }) =>
  HierarchicalFilterGroup(name, filters);
 
  /// Filter group ID (name and operator)
  final FilterGroupID groupID;
 
  /// Set of filters.
- final Set<T> filters;
+ final Set<T> _filters;
 
  /// Create a copy with given parameters.
  FilterGroup<T> copyWith({FilterGroupID? groupID, Set<T>? filters});
@@ -88,10 +90,10 @@ abstract class FilterGroup<T> {
  other is FilterGroup &&
  runtimeType == other.runtimeType &&
  groupID == other.groupID &&
- filters.equals(other.filters);
+ _filters.equals(other._filters);
 
  @override
- int get hashCode => groupID.hashCode ^ filters.hashing();
+ int get hashCode => groupID.hashCode ^ _filters.hashing();
 }
 
 /// Facets filter group
@@ -106,11 +108,12 @@ class FacetFilterGroup extends FilterGroup<FilterFacet> {
  }) =>
  FacetFilterGroup(
  groupID ?? this.groupID,
- filters ?? this.filters,
+ filters ?? _filters,
  );
 
  @override
- String toString() => 'FacetFilterGroup{groupID: $groupID, filters: $filters}';
+ String toString() =>
+ 'FacetFilterGroup{groupID: $groupID, filters: $_filters}';
 }
 
 /// Tags filter group
@@ -125,11 +128,11 @@ class TagFilterGroup extends FilterGroup<FilterTag> {
  }) =>
  TagFilterGroup(
  groupID ?? this.groupID,
- filters ?? this.filters,
+ filters ?? _filters,
  );
 
  @override
- String toString() => 'TagFilterGroup{groupID: $groupID, filters: $filters}';
+ String toString() => 'TagFilterGroup{groupID: $groupID, filters: $_filters}';
 }
 
 /// Numeric facets filter group
@@ -144,20 +147,22 @@ class NumericFilterGroup extends FilterGroup<FilterNumeric> {
  }) =>
  NumericFilterGroup(
  groupID ?? this.groupID,
- filters ?? this.filters,
+ filters ?? _filters,
  );
 
  @override
  String toString() =>
- 'NumericFilterGroup{groupID: $groupID, filters: $filters}';
+ 'NumericFilterGroup{groupID: $groupID, filters: $_filters}';
 }
 
 /// Hierarchical filter group
 class HierarchicalFilterGroup extends FilterGroup<HierarchicalFilter> {
  HierarchicalFilterGroup(String name, Set<HierarchicalFilter> filters)
  : this._(FilterGroupID(name), filters);
 
- const HierarchicalFilterGroup._(super.groupID, super.filters) : super._();
+ HierarchicalFilterGroup._(super.groupID, super.filters) : super._() {
+ assert(groupID.operator == FilterOperator.and);
+ }
 
  /// Make a copy of the hierarchical filters group.
  @override
@@ -167,10 +172,10 @@ class HierarchicalFilterGroup extends FilterGroup<HierarchicalFilter> {
  }) =>
  HierarchicalFilterGroup._(
  groupID ?? this.groupID,
- filters ?? this.filters,
+ filters ?? _filters,
  );
 
  @override
  String toString() =>
- 'HierarchicalFilterGroup{groupID: $groupID, filters: $filters}';
+ 'HierarchicalFilterGroup{groupID: $groupID, filters: $_filters}';
 }

helper_dart/lib/src/filter_group.dart

@@ -0,0 +1,139 @@
+import 'package:collection/collection.dart';
+
+import 'filter.dart';
+import 'filter_group.dart';
+
+/// Converts [FilterGroup] to an SQL like syntax.
+class FilterGroupConverter {
+ /// Creates [FilterGroupConverter] instance.
+ const FilterGroupConverter();
+
+ /// Converts [FilterGroup] to its SQL-like [String] representation.
+ /// Returns `null` if the list is empty.
+ String? sql(Set<FilterGroup> filterGroups) {
+ final groups = filterGroups
+ .whereType<FilterGroup<Filter>>()
+ .whereNot((element) => element.isEmpty);
+ if (groups.isEmpty) return null;
+ return groups.map(_sqlGroup).join(' AND ');
+ }
+
+ /// Same as [sql], but removes quotes for readability purposes.
+ String? unquoted(Set<FilterGroup<Filter>> filterGroups) =>
+ sql(filterGroups)?.replaceAll('\"', '');
+
+ /// Convert a filter group to an SQL-like syntax
+ String _sqlGroup(FilterGroup<Filter> group) {
+ final sql = group
+ .map((filter) => const FilterConverter().sql(filter))
+ .join(_separatorOf(group));
+ return '($sql)';
+ }
+
+ /// Get separator string (i.e. AND/OR) of a [group].
+ String _separatorOf(FilterGroup group) {
+ switch (group.groupID.operator) {
+ case FilterOperator.and:
+ return ' AND ';
+ case FilterOperator.or:
+ return ' OR ';
+ }
+ }
+}
+
+/// Converts [Filter] to an SQL like syntax.
+class FilterConverter {
+ /// Creates [FilterConverter] instance.
+ const FilterConverter();
+
+ /// Converts [Filter] to its SQL-like [String] representation.
+ String sql(Filter filter) {
+ switch (filter.runtimeType) {
+ case FilterFacet:
+ return _sqlFacet(filter as FilterFacet);
+ case FilterTag:
+ return _sqlTag(filter as FilterTag);
+ case FilterNumeric:
+ return _sqlNumeric(filter as FilterNumeric);
+ default:
+ throw ArgumentError('Filter type ${filter.runtimeType} not supported');
+ }
+ }
+
+ /// Converts [FilterFacet] to its SQL-like [String] representation.
+ String _sqlFacet(FilterFacet filter) {
+ final value = _sqlValue(filter.value);
+ final attribute = _escape(filter.attribute);
+ final score = filter.score != null ? '<score=${filter.score}>' : '';
+ final expression = '$attribute:$value$score';
+ return filter.isNegated ? 'NOT $expression' : expression;
+ }
+
+ /// Converts [FilterTag] to its SQL-like [String] representation.
+ String _sqlTag(FilterTag filter) {
+ final attribute = filter.attribute;
+ final escapedValue = _escape(filter.value);
+ final expression = '$attribute:$escapedValue';
+ return filter.isNegated ? 'NOT $expression' : expression;
+ }
+
+ /// Converts [FilterNumeric] to its SQL-like [String] representation.
+ String _sqlNumeric(FilterNumeric filter) {
+ switch (filter.value.runtimeType) {
+ case NumericRange:
+ return _sqlRange(
+ filter.value as NumericRange,
+ filter.attribute,
+ filter.isNegated,
+ );
+ case NumericComparison:
+ return _sqlComparison(
+ filter.value as NumericComparison,
+ filter.attribute,
+ filter.isNegated,
+ );
+ default:
+ throw ArgumentError('Filter type ${filter.runtimeType} not supported');
+ }
+ }
+
+ /// Converts [NumericRange] to its SQL-like [String] representation.
+ String _sqlRange(NumericRange range, String attribute, bool isNegated) {
+ final escapedAttribute = _escape(attribute);
+ final lowerBound = range.lowerBound;
+ final upperBound = range.upperBound;
+ final expression = '$escapedAttribute:$lowerBound TO $upperBound';
+ return isNegated ? 'NOT $expression' : expression;
+ }
+
+ /// Converts [FilterNumeric] with [NumericComparison] value to its SQL-like
+ /// [String] representation.
+ String _sqlComparison(
+ NumericComparison comparison,
+ String attribute,
+ bool isNegated,
+ ) {
+ final escapedAttribute = _escape(attribute);
+ final operator = comparison.operator.operator;
+ final number = comparison.number;
+ final expression = '$escapedAttribute $operator $number';
+ return isNegated ? 'NOT $expression' : expression;
+ }
+
+ /// Converts [value] to its SQL-like [String] representation.
+ String _sqlValue(dynamic value) {
+ switch (value.runtimeType) {
+ case String:
+ return _escape(value as String);
+ case int:
+ case double:
+ case bool:
+ return value.toString();
+ default:
+ throw ArgumentError('value type ${value.runtimeType} not supported');
+ }
+ }
+
+ /// String escape [value].
+ String _escape(String value) => '\"$value\"';
+}

helper_dart/lib/src/filter_group_converter.dart

@@ -1,8 +1,8 @@
 import 'package:meta/meta.dart';
 
+import 'extensions.dart';
 import 'filter.dart';
 import 'filter_group.dart';
-import 'utils.dart';
 
 /// Map of filter groups convenience type.
 typedef FilterGroupMap<T> = Map<FilterGroupID, Set<T>>;