Merge #296

296: added proper types for facetStats, facetDistributions and matchesPosition r=brunoocasali a=ahmednfwela

# Pull Request

## Related issue
Fixes #294

## What does this PR do?
- Introduces new classes
  1. FacetStat
  2. MatchPosition
- [Breaking] change `Searchable<T>` to have proper types:
    ```diff
    - final Object? facetDistribution;
    + final Map<String, Map<String, int>>? facetDistribution;
    - final Object? matchesPosition;    
    + final Map<String, List<MatchPosition>>? matchesPosition;
    + final Map<String, FacetStat>? facetStats;
    ```
- Internal refactoring to not repeat any deserialization logic between `Searchable<T>` and its subclasses `SearchResult<T>` and `PaginatedSearchResult<T>`

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!

cc `@brunoocasali` 

Co-authored-by: Ahmed Fwela <[email protected]>
Co-authored-by: Ahmed Fwela <[email protected]>

Author: bors[bot]

lib/meilisearch.dart

@@ -3,14 +3,14 @@ library meilisearch;
 export 'src/client.dart';
 export 'src/index.dart';
 export 'src/settings/_exports.dart';
-export 'src/search_result.dart';
+export 'src/facet_stat.dart';
+export 'src/match_position.dart';
 export 'src/searchable.dart';
 export 'src/multi_search_result.dart';
 export 'src/multi_search_query.dart';
 export 'src/search_query.dart';
 export 'src/filter_builder/_exports.dart';
 export 'src/query_parameters/_exports.dart';
-export 'src/paginated_search_result.dart';
 export 'src/matching_strategy_enum.dart';
 export 'src/key.dart';
 export 'src/exception.dart';

lib/src/facet_stat.dart

@@ -0,0 +1,21 @@
+///When using the facets parameter, the distributed facets that contain some numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query.
+///If none of the hits returned by the search query have a numeric value for a facet, this facet is not part of the facetStats object.
+class FacetStat {
+  ///The minimum value for the numerical facet being distributed.
+  final num min;
+
+  ///The maximum value for the numerical facet being distributed.
+  final num max;
+
+  const FacetStat({
+    required this.min,
+    required this.max,
+  });
+
+  factory FacetStat.fromMap(Map<String, Object?> src) {
+    return FacetStat(
+      min: src['min'] as num,
+      max: src['max'] as num,
+    );
+  }
+}

lib/src/match_position.dart

@@ -0,0 +1,16 @@
+class MatchPosition {
+  final int start;
+  final int length;
+
+  const MatchPosition({
+    required this.start,
+    required this.length,
+  });
+
+  factory MatchPosition.fromMap(Map<String, dynamic> map) {
+    return MatchPosition(
+      start: map['start'] as int,
+      length: map['length'] as int,
+    );
+  }
+}

lib/src/paginated_search_result.dart

@@ -1,12 +1,13 @@
-import 'package:meilisearch/src/searchable.dart';
+part of 'searchable.dart';
 
 class PaginatedSearchResult<T> extends Searcheable<T> {
   const PaginatedSearchResult({
     List<T> hits = const [],
-    Object? facetDistribution,
-    Object? matchesPosition,
+    Map<String, Map<String, int>>? facetDistribution,
+    Map<String, List<MatchPosition>>? matchesPosition,
     int? processingTimeMs,
     String? query,
+    Map<String, FacetStat>? facetStats,
     required String indexUid,
     this.hitsPerPage,
     this.page,
@@ -19,6 +20,7 @@ class PaginatedSearchResult<T> extends Searcheable<T> {
           processingTimeMs: processingTimeMs,
           query: query,
           indexUid: indexUid,
+          facetStats: facetStats,
         );
 
   /// Number of documents skipped
@@ -42,12 +44,13 @@ class PaginatedSearchResult<T> extends Searcheable<T> {
       hitsPerPage: map['hitsPerPage'] as int?,
       totalHits: map['totalHits'] as int?,
       totalPages: map['totalPages'] as int?,
-      hits: (map['hits'] as List?)?.cast<Map<String, Object?>>() ?? [],
-      query: map['query'] as String?,
-      processingTimeMs: map['processingTimeMs'] as int?,
-      facetDistribution: map['facetDistribution'],
-      matchesPosition: map['_matchesPosition'],
-      indexUid: indexUid ?? map['indexUid'] as String,
+      hits: _readHits(map),
+      query: _readQuery(map),
+      processingTimeMs: _readProcessingTimeMs(map),
+      facetDistribution: _readFacetDistribution(map),
+      matchesPosition: _readMatchesPosition(map),
+      facetStats: _readFacetStats(map),
+      indexUid: indexUid ?? _readIndexUid(map),
     );
   }
 

lib/src/search_result.dart

@@ -1,12 +1,13 @@
-import 'package:meilisearch/src/searchable.dart';
+part of 'searchable.dart';
 
 class SearchResult<T> extends Searcheable<T> {
   const SearchResult({
     List<T> hits = const [],
-    Object? facetDistribution,
-    Object? matchesPosition,
+    Map<String, Map<String, int>>? facetDistribution,
+    Map<String, List<MatchPosition>>? matchesPosition,
     int? processingTimeMs,
     String? query,
+    Map<String, FacetStat>? facetStats,
     required String indexUid,
     this.offset,
     this.limit,
@@ -18,6 +19,7 @@ class SearchResult<T> extends Searcheable<T> {
           processingTimeMs: processingTimeMs,
           query: query,
           indexUid: indexUid,
+          facetStats: facetStats,
         );
 
   /// Number of documents skipped
@@ -37,12 +39,13 @@ class SearchResult<T> extends Searcheable<T> {
       limit: map['limit'] as int?,
       offset: map['offset'] as int?,
       estimatedTotalHits: map['estimatedTotalHits'] as int?,
-      hits: (map['hits'] as List?)?.cast<Map<String, Object?>>() ?? [],
-      query: map['query'] as String?,
-      processingTimeMs: map['processingTimeMs'] as int?,
-      facetDistribution: map['facetDistribution'],
-      matchesPosition: map['_matchesPosition'],
-      indexUid: indexUid ?? map['indexUid'] as String,
+      hits: _readHits(map),
+      query: _readQuery(map),
+      processingTimeMs: _readProcessingTimeMs(map),
+      facetDistribution: _readFacetDistribution(map),
+      matchesPosition: _readMatchesPosition(map),
+      indexUid: indexUid ?? _readIndexUid(map),
+      facetStats: _readFacetStats(map),
     );
   }
 

lib/src/searchable.dart

@@ -1,6 +1,8 @@
 import 'package:meilisearch/meilisearch.dart';
 
-typedef MeilisearchDocumentMapper<TSrc, TOther> = TOther Function(TSrc src);
+part 'search_result.dart';
+part 'paginated_search_result.dart';
+part 'searchable_helpers.dart';
 
 abstract class Searcheable<T> {
   final String indexUid;
@@ -12,10 +14,13 @@ abstract class Searcheable<T> {
   final List<T> hits;
 
   /// Distribution of the given facets
-  final Object? facetDistribution;
+  final Map<String, Map<String, int>>? facetDistribution;
+
+  /// Distribution of the given facets
+  final Map<String, FacetStat>? facetStats;
 
   /// Contains the location of each occurrence of queried terms across all fields
-  final Object? matchesPosition;
+  final Map<String, List<MatchPosition>>? matchesPosition;
 
   /// Processing time of the query
   final int? processingTimeMs;
@@ -27,6 +32,7 @@ abstract class Searcheable<T> {
     this.facetDistribution,
     this.matchesPosition,
     this.processingTimeMs,
+    this.facetStats,
   });
 
   static Searcheable<Map<String, dynamic>> createSearchResult(
@@ -54,30 +60,3 @@ abstract class Searcheable<T> {
     return src as SearchResult<T>;
   }
 }
-
-extension SearchableExt<T> on Future<Searcheable<T>> {
-  Future<PaginatedSearchResult<T>> asPaginatedResult() =>
-      then((value) => value.asPaginatedResult());
-
-  Future<SearchResult<T>> asSearchResult() =>
-      then((value) => value.asSearchResult());
-
-  Future<Searcheable<TOther>> map<TOther>(
-    MeilisearchDocumentMapper<T, TOther> mapper,
-  ) =>
-      then((value) => value.map(mapper));
-}
-
-extension SearchResultExt<T> on Future<SearchResult<T>> {
-  Future<SearchResult<TOther>> map<TOther>(
-    MeilisearchDocumentMapper<T, TOther> mapper,
-  ) =>
-      then((value) => value.map(mapper));
-}
-
-extension PaginatedSearchResultExt<T> on Future<PaginatedSearchResult<T>> {
-  Future<PaginatedSearchResult<TOther>> map<TOther>(
-    MeilisearchDocumentMapper<T, TOther> mapper,
-  ) =>
-      then((value) => value.map(mapper));
-}

lib/src/searchable_helpers.dart

@@ -0,0 +1,84 @@
+part of 'searchable.dart';
+
+String _readIndexUid(Map<String, Object?> map) => map['indexUid'] as String;
+String? _readQuery(Map<String, Object?> map) => map['query'] as String?;
+
+int? _readProcessingTimeMs(Map<String, Object?> map) =>
+    map['processingTimeMs'] as int?;
+
+List<Map<String, dynamic>> _readHits(Map<String, Object?> map) =>
+    (map['hits'] as List?)?.cast<Map<String, dynamic>>() ?? const [];
+
+Map<String, FacetStat>? _readFacetStats(
+  Map<String, Object?> map,
+) {
+  final facetStatsRaw = map['facetStats'] as Map<String, Object?>?;
+
+  return facetStatsRaw?.map(
+    (key, value) => MapEntry(
+      key,
+      FacetStat.fromMap(value as Map<String, Object?>),
+    ),
+  );
+}
+
+Map<String, Map<String, int>>? _readFacetDistribution(
+  Map<String, Object?> map,
+) {
+  final src = map['facetDistribution'];
+
+  if (src == null) return null;
+
+  return (src as Map<String, Object?>).map(
+    (key, value) => MapEntry(
+      key,
+      (value as Map<String, Object?>).cast<String, int>(),
+    ),
+  );
+}
+
+Map<String, List<MatchPosition>>? _readMatchesPosition(
+  Map<String, Object?> map,
+) {
+  final src = map['_matchesPosition'];
+
+  if (src == null) return null;
+
+  return (src as Map<String, Object?>).map(
+    (key, value) => MapEntry(
+      key,
+      (value as List<Object?>)
+          .map((e) => MatchPosition.fromMap(e as Map<String, Object?>))
+          .toList(),
+    ),
+  );
+}
+
+typedef MeilisearchDocumentMapper<TSrc, TOther> = TOther Function(TSrc src);
+
+extension SearchableExt<T> on Future<Searcheable<T>> {
+  Future<PaginatedSearchResult<T>> asPaginatedResult() =>
+      then((value) => value.asPaginatedResult());
+
+  Future<SearchResult<T>> asSearchResult() =>
+      then((value) => value.asSearchResult());
+
+  Future<Searcheable<TOther>> map<TOther>(
+    MeilisearchDocumentMapper<T, TOther> mapper,
+  ) =>
+      then((value) => value.map(mapper));
+}
+
+extension SearchResultExt<T> on Future<SearchResult<T>> {
+  Future<SearchResult<TOther>> map<TOther>(
+    MeilisearchDocumentMapper<T, TOther> mapper,
+  ) =>
+      then((value) => value.map(mapper));
+}
+
+extension PaginatedSearchResultExt<T> on Future<PaginatedSearchResult<T>> {
+  Future<PaginatedSearchResult<TOther>> map<TOther>(
+    MeilisearchDocumentMapper<T, TOther> mapper,
+  ) =>
+      then((value) => value.map(mapper));
+}

test/search_test.dart

@@ -221,14 +221,36 @@ void main() {
 
       test('facetDistributions parameter', () async {
         var index = await createBooksIndex();
-        var response = await index
+        await index
             .updateSettings(IndexSettings(
-              filterableAttributes: ['tag'],
+              filterableAttributes: [ktag],
             ))
             .waitFor(client: client);
-        expect(response.status, 'succeeded');
+
         var result = await index.search('prince', facets: ['*']);
+
         expect(result.hits, hasLength(2));
+        expect(result.facetDistribution?[ktag]?.length, 2);
+      });
+
+      test('facetStats parameter', () async {
+        final index = client.index(randomUid());
+        final docs = List.generate(
+          10,
+          (index) => <String, Object?>{
+            'id': 100 - index,
+            'year': (index * 2) + 2010,
+          },
+        );
+        await index.addDocuments(docs).waitFor(client: client);
+        await index
+            .updateFilterableAttributes(['year']).waitFor(client: client);
+
+        var result = await index.search('', facets: ['*']);
+
+        expect(result.hits, hasLength(10));
+        expect(result.facetStats?['year']?.min, 2010);
+        expect(result.facetStats?['year']?.max, 2028);
       });
 
       test('Sort parameter', () async {