refactor: Filters/FilterState and add disposables (algolia#31)

Author: aallam

helper_dart/lib/algolia_helper.dart

@@ -4,6 +4,7 @@
 /// experiences at a deeper level, in pure Dart.
 library algolia_helper;
 
+export 'src/disposable.dart';
 export 'src/exception.dart';
 export 'src/facet_list.dart';
 export 'src/filter.dart';
@@ -12,7 +13,6 @@ export 'src/filter_state.dart';
 export 'src/filters.dart';
 export 'src/highlighting.dart';
 export 'src/hits_searcher.dart';
-export 'src/immutable_filters.dart';
 export 'src/search_response.dart';
 export 'src/search_state.dart';
 export 'src/selectable_item.dart';

helper_dart/lib/src/disposable.dart

@@ -0,0 +1,90 @@
+import 'disposable_mixin.dart';
+
+/// Represents an object able to release it's resources.
+abstract class Disposable {
+ /// Whether this [Disposable] has already released its resources.
+ bool get isDisposed;
+
+ /// Releases this [Disposable] resources.
+ void dispose();
+}
+
+/// Acts as a container for multiple disposables that can be canceled at once.
+///
+/// Can be cleared or disposed. When disposed, cannot be used again.
+/// ### Example
+/// // init your subscriptions
+/// composite.add(hitsSearcher)
+/// ..add(filterState)
+/// ..add(facetList);
+///
+/// // clear them all at once
+/// composite.clear();
+abstract class CompositeDisposable implements Disposable {
+ /// Creates [CompositeDisposable] instance.
+ factory CompositeDisposable() => _CompositeDisposable();
+
+ /// Returns the total amount of currently added [Disposable]s
+ int get length;
+
+ /// Checks if there currently are no [Disposable]s added
+ bool get isEmpty;
+
+ /// Adds [disposable] to this composite.
+ /// Throws an exception if this composite was disposed
+ Disposable add(Disposable disposable);
+
+ /// Remove [disposable] from this composite and cancel it if it has been
+ /// removed.
+ void remove(Disposable disposable, {bool shouldDispose = true});
+
+ /// Cancels all disposables added to this composite.
+ /// Clears disposables collection.
+ /// This composite can be reused after calling this method.
+ void clear();
+}
+
+/// Default implementation of [CompositeDisposable].
+class _CompositeDisposable with DisposableMixin implements CompositeDisposable {
+ /// List of [Disposable]s.
+ final List<Disposable> _disposables = [];
+
+ @override
+ int get length => _disposables.length;
+
+ @override
+ bool get isEmpty => _disposables.isEmpty;
+
+ @override
+ Disposable add(Disposable disposable) {
+ if (isDisposed) {
+ throw StateError(
+ 'This $runtimeType was disposed, consider checking `isDisposed` or'
+ ' try to use new instance instead');
+ }
+ _disposables.add(disposable);
+ return disposable;
+ }
+
+ @override
+ void remove(
+ Disposable disposable, {
+ bool shouldDispose = true,
+ }) =>
+ _disposables.remove(disposable) && shouldDispose
+ ? disposable.dispose()
+ : null;
+
+ @override
+ void clear() {
+ doDispose();
+ _disposables.clear();
+ }
+
+ @override
+ void doDispose() {
+ for (final disposable in _disposables) {
+ if (!disposable.isDisposed) disposable.dispose();
+ }
+ }
+}

helper_dart/lib/src/disposable_mixin.dart

@@ -0,0 +1,17 @@
+import 'disposable.dart';
+
+/// Mixin to abstract away `isDisposed` logic.
+mixin DisposableMixin implements Disposable {
+ @override
+ bool isDisposed = false;
+
+ @override
+ void dispose() {
+ if (!isDisposed) {
+ doDispose();
+ isDisposed = true;
+ }
+ }
+
+ void doDispose();
+}

helper_dart/lib/src/facet_list.dart

@@ -4,12 +4,14 @@ import 'package:logging/logging.dart';
 import 'package:meta/meta.dart';
 import 'package:rxdart/rxdart.dart';
 
+import 'disposable.dart';
+import 'disposable_mixin.dart';
 import 'extensions.dart';
 import 'filter.dart';
 import 'filter_group.dart';
 import 'filter_state.dart';
+import 'filters.dart';
 import 'hits_searcher.dart';
-import 'immutable_filters.dart';
 import 'logger.dart';
 import 'search_response.dart';
 import 'selectable_item.dart';
@@ -57,7 +59,7 @@ import 'selectable_item.dart';
 /// ```
 @experimental
 @sealed
-abstract class FacetList {
+abstract class FacetList implements Disposable {
  /// Create [FacetList] instance.
  factory FacetList({
  required HitsSearcher searcher,
@@ -102,9 +104,6 @@ abstract class FacetList {
 
  /// Select/deselect the provided facet value depending on the current selection state.
  void toggle(String value);
-
- /// Dispose the component.
- void dispose();
 }
 
 /// Elements selection mode.
@@ -113,8 +112,8 @@ enum SelectionMode { single, multiple }
 /// [Facet] with selection status.
 typedef SelectableFacet = SelectableItem<Facet>;
 
-/// Implementation of [FacetList].
-class _FacetList implements FacetList {
+/// Default implementation of [FacetList].
+class _FacetList with DisposableMixin implements FacetList {
  /// Create [_FacetList] instance.
  _FacetList({
  required this.searcher,
@@ -124,6 +123,14 @@ class _FacetList implements FacetList {
  required this.selectionMode,
  required this.persistent,
  }) {
+ if (searcher.isDisposed) {
+ _log.warning('creating an instance with disposed searcher');
+ }
+
+ if (filterState.isDisposed) {
+ _log.warning('creating an instance with disposed filter state');
+ }
+
  // Setup search state by adding `attribute` to the search state
  searcher.applyState(
  (state) => state.copyWith(
@@ -274,8 +281,8 @@ class _FacetList implements FacetList {
  }
  }
 
- /// Clear filters from [ImmutableFilters] depending
- Future<ImmutableFilters> _clearFilters(ImmutableFilters filters) async {
+ /// Clear filters from [StatelessFilters] depending
+ Future<StatelessFilters> _clearFilters(StatelessFilters filters) async {
  switch (selectionMode) {
  case SelectionMode.single:
  return filters.clear([groupID]);
@@ -300,7 +307,7 @@ class _FacetList implements FacetList {
  }
 
  @override
- void dispose() {
+ void doDispose() {
  _log.finest('FacetList disposed');
  _subscriptions.cancel();
  }

helper_dart/lib/src/filter_state.dart

@@ -1,52 +1,116 @@
 import 'dart:async';
 
 import 'package:logging/logging.dart';
+import 'package:meta/meta.dart';
 import 'package:rxdart/rxdart.dart';
 
+import 'disposable.dart';
+import 'disposable_mixin.dart';
 import 'filter.dart';
 import 'filter_group.dart';
 import 'filters.dart';
-import 'immutable_filters.dart';
 import 'logger.dart';
 
 /// [FilterState] holds one or several filters, organized in groups.
 /// [filters] streams filters changes of added or removed filters,
 /// which will be applied to searches performed by the connected Searcher.
-class FilterState {
+@sealed
+abstract class FilterState implements Disposable {
+ /// FilterState's factory.
+ factory FilterState() => _FilterState();
+
+ /// Filters groups stream (facet, tag, numeric and hierarchical).
+ Stream<Filters> get filters;
+
+ /// Adds [filters] to the provided [groupID].
+ void add(FilterGroupID groupID, Iterable<Filter> filters);
+
+ /// Overrides [filters] with the provided [map].
+ void set(Map<FilterGroupID, Set<Filter>> map);
+
+ /// Removes [filters] from [groupID].
+ void remove(FilterGroupID groupID, Iterable<Filter> filters);
+
+ /// Toggles [filter] in given [groupID].
+ void toggle(FilterGroupID groupID, Filter filter);
+
+ /// Checks if [filter] exists in [groupID].
+ bool contains(FilterGroupID groupID, Filter filter);
+
+ /// Adds [hierarchicalFilter] to given [attribute].
+ void addHierarchical(
+ String attribute,
+ HierarchicalFilter hierarchicalFilter,
+ );
+
+ /// Removes [HierarchicalFilter] of given [attribute].
+ void removeHierarchical(String attribute);
+
+ /// Clears [groupIDs].
+ /// If none provided, all filters will be cleared.
+ void clear([Iterable<FilterGroupID>? groupIDs]);
+
+ /// Clears all except [groupIDs].
+ void clearExcept(Iterable<FilterGroupID> groupIDs);
+
+ /// Get current [filters] value.
+ Filters snapshot();
+
+ /// **Asynchronous** updates [filters] by applying [builder] to current
+ /// filters value.
+ /// Useful to apply multiple consecutive update operations without firing
+ /// multiple filters events.
+ Future<void> modify(AsyncFiltersBuilder builder);
+}
+
+/// Asynchronous stateless filters builder.
+typedef AsyncFiltersBuilder = Future<StatelessFilters> Function(
+ StatelessFilters filters,
+);
+
+/// Default implementation of [FilterState].
+class _FilterState with DisposableMixin implements FilterState {
  /// Filters groups stream (facet, tag, numeric and hierarchical).
+ @override
  Stream<Filters> get filters => _filters.stream.distinct();
 
  /// Events logger
  final Logger _log = algoliaLogger('FilterState');
 
- /// Hot stream controller of [ImmutableFilters].
- final BehaviorSubject<ImmutableFilters> _filters =
- BehaviorSubject.seeded(const ImmutableFilters());
+ /// Hot stream controller of [StatelessFilters].
+ final BehaviorSubject<StatelessFilters> _filters =
+ BehaviorSubject.seeded(StatelessFilters());
 
  /// Adds [filters] to the provided [groupID].
+ @override
  void add(FilterGroupID groupID, Iterable<Filter> filters) {
  _modify((it) => it.add(groupID, filters));
  }
 
  /// Overrides [filters] with the provided [map].
+ @override
  void set(Map<FilterGroupID, Set<Filter>> map) {
  _modify((it) => it.set(map));
  }
 
  /// Removes [filters] from [groupID].
+ @override
  void remove(FilterGroupID groupID, Iterable<Filter> filters) {
  _modify((it) => it.remove(groupID, filters));
  }
 
  /// Toggles [filter] in given [groupID].
+ @override
  void toggle(FilterGroupID groupID, Filter filter) =>
  _modify((it) => it.toggle(groupID, filter));
 
  /// Checks if [filter] exists in [groupID].
+ @override
  bool contains(FilterGroupID groupID, Filter filter) =>
  _filters.value.contains(groupID, filter);
 
  /// Adds [hierarchicalFilter] to given [attribute].
+ @override
  void addHierarchical(
  String attribute,
  HierarchicalFilter hierarchicalFilter,
@@ -55,49 +119,61 @@ class FilterState {
  }
 
  /// Removes [HierarchicalFilter] of given [attribute].
+ @override
  void removeHierarchical(String attribute) {
  _modify((it) => it.removeHierarchical(attribute));
  }
 
  /// Clears [groupIDs].
  /// If none provided, all filters will be cleared.
+ @override
  void clear([Iterable<FilterGroupID>? groupIDs]) {
  _modify((it) => it.clear(groupIDs));
  }
 
  /// Clears all except [groupIDs].
+ @override
  void clearExcept(Iterable<FilterGroupID> groupIDs) {
  _modify((it) => it.clearExcept(groupIDs));
  }
 
  /// Get current [filters] value.
+ @override
  Filters snapshot() => _filters.value;
 
  /// Dispose of underlying resources.
- void dispose() {
+ @override
+ void doDispose() {
  _log.finest('FilterState disposed');
  _filters.close();
  }
 
- /// Updates [filters] by applying [action] to current filters value.
+ /// **Asynchronous** updates [filters] by applying [builder] to current
+ /// filters value.
  /// Useful to apply multiple consecutive update operations without firing
  /// multiple filters events.
- void _modify(ImmutableFilters Function(ImmutableFilters filters) action) {
+ @override
+ Future<void> modify(AsyncFiltersBuilder builder) async {
+ if (_filters.isClosed) {
+ _log.warning('modifying disposed instance');
+ return;
+ }
  final current = _filters.value;
- final updated = action(current);
+ final updated = await builder(current);
  _filters.sink.add(updated);
  _log.finest('FilterState updated: $updated');
  }
 
- /// **Asynchronous** updates [filters] by applying [action] to current filters
- /// value.
+ /// Updates [filters] by applying [builder] to current filters value.
  /// Useful to apply multiple consecutive update operations without firing
  /// multiple filters events.
- Future<void> modify(
- Future<ImmutableFilters> Function(ImmutableFilters filters) action,
- ) async {
+ void _modify(StatelessFilters Function(StatelessFilters) builder) {
+ if (_filters.isClosed) {
+ _log.warning('modifying disposed instance');
+ return;
+ }
  final current = _filters.value;
- final updated = await action(current);
+ final updated = builder(current);
  _filters.sink.add(updated);
  _log.finest('FilterState updated: $updated');
  }