feature - add convenience methods scope.getStates{orNull}

lib/dart_scope.dart

@@ -47,6 +47,7 @@ export 'src/dart_scope/dart_scope.dart'
     ScopeValueNotExposedError,
     DisposableSink,
     DisposableSinkX,
+    ScopeGetStatesX,
     ScopeGet,
     ScopeGetX,
     ScopeExpose,

lib/src/dart_scope/dart_scope.dart

@@ -41,6 +41,9 @@ export 'scope_methods/disposable_sink.dart'
   show
     DisposableSink,
     DisposableSinkX;
+export 'scope_methods/scope_get_states_x.dart'
+  show
+    ScopeGetStatesX;
 export 'scope_methods/scope_get.dart'
   show
     ScopeGet,

lib/src/dart_scope/scope_methods/scope_get_states_x.dart

@@ -0,0 +1,34 @@
+
+import '../../dart_observable/states/states.dart';
+
+import 'scope_get.dart';
+
+/// `ScopeGetStatesX` is an extension to `ScopeGet`
+/// that adds convenience methods like `scope.getStates`, 
+/// `scope.getStatesOrNull` and `scope.hasStates`.
+extension ScopeGetStatesX on ScopeGet {
+
+  /// Use `scope.getStatesOrNull<T>(...)` to safely resolve states.
+  /// 
+  /// It is a convenience method for `scope.getOrNull<States<T>>(...)`.
+  /// 
+  States<T>? getStatesOrNull<T>({
+    Object? name,
+  }) => getOrNull<States<T>>(name: name);
+
+  /// Use `scope.getStates<T>(...)` to resolve states from current scope.
+  /// 
+  /// It is a convenience method for `scope.get<States<T>>(...)`.
+  /// 
+  States<T> getStates<T>({
+    Object? name,
+  }) => get<States<T>>(name: name);
+
+  /// Use `scope.hasStates<T>(...)` to check if states has been exposed.
+  /// 
+  /// It is a convenience method for `scope.has<States<T>>(...)`.
+  /// 
+  bool hasStates<T>({
+    Object? name,
+  }) => has<States<T>>(name: name);
+}

test/dart_scope/dart_scope_test.dart

@@ -7,6 +7,7 @@ import 'configurables/final_test.dart' as final_test;
 import 'configurables/final_states_test.dart' as final_states_test;
 import 'configurables/final_states_convertible_test.dart' as final_states_convertible_test;
 import 'scope_methods/disposable_test.dart' as disposable_test;
+import 'scope_methods/scope_get_states_x_test.dart' as scope_get_states_x_test;
 import 'scope_methods/scope_get_test.dart' as scope_get_test;
 import 'scope_methods/scope_push_test.dart' as scope_push_test;
 import 'scopes/scope_test.dart' as scope_test;
@@ -20,6 +21,7 @@ void main() {
   final_states_test.main();
   final_states_convertible_test.main();
   disposable_test.main();
+  scope_get_states_x_test.main();
   scope_get_test.main();
   scope_push_test.main();
   scope_test.main();

test/dart_scope/scope_methods/scope_get_states_x_test.dart

@@ -0,0 +1,152 @@
+
+import 'package:test/test.dart';
+import 'package:dart_scope/dart_scope.dart';
+
+final _emptyStates = States<String>((_) {
+  return Disposable.empty;
+});
+
+void main() {
+
+  test('`scope.getStatesOrNull` return states if states exposed', () async {
+
+    final scope = await Scope.root([
+      Final<States<String>>(equal: (_) => _emptyStates),
+    ]);
+
+    final states = scope.getStatesOrNull<String>();
+
+    expect(states, _emptyStates);
+  });
+
+  test('`scope.getStatesOrNull` return null if states not exposed', () async {
+
+    final scope = await Scope.root([]);
+
+    final states = scope.getStatesOrNull<String>();
+
+    expect(states, null);
+  });
+
+  test('`scope.getStatesOrNull` return states if states exposed with name', () async {
+
+    final scope = await Scope.root([
+      Final<States<String>>(name: 'states', equal: (_) => _emptyStates),
+    ]);
+
+    final states = scope.getStatesOrNull<String>(name: 'states');
+
+    expect(states, _emptyStates);
+  });
+
+  test('`scope.getStatesOrNull` return null if states not exposed with name', () async {
+
+    final scope = await Scope.root([]);
+
+    final states = scope.getStatesOrNull<String>(name: 'states');
+
+    expect(states, null);
+  });
+
+  test('`scope.getStates` return states if states exposed', () async {
+
+    final scope = await Scope.root([
+      Final<States<String>>(equal: (_) => _emptyStates),
+    ]);
+
+    final states = scope.getStates<String>();
+
+    expect(states, _emptyStates);
+  });
+
+  test('`scope.getStates` throws if states not exposed', () async {
+
+    final scope = await Scope.root([]);
+
+    expect(
+      () {
+        scope.getStates<String>();
+      },
+      throwsA(
+        isA<ScopeValueNotExposedError<States<String>>>()
+          .having(
+            (error) => '$error',
+            'description',
+            contains('`States<String>` is not exposed in current scope'),
+          )
+      ),
+    );
+  });
+
+  test('`scope.getStates` return states if states exposed with name', () async {
+
+    final scope = await Scope.root([
+      Final<States<String>>(name: 'states', equal: (_) => _emptyStates),
+    ]);
+
+    final states = scope.getStates<String>(name: 'states');
+
+    expect(states, _emptyStates);
+  });
+
+  test('`scope.getStates` throws if states not exposed with name', () async {
+
+    final scope = await Scope.root([]);
+
+    expect(
+      () {
+        scope.getStates<String>(name: 'states');
+      },
+      throwsA(
+        isA<ScopeValueNotExposedError<States<String>>>()
+          .having(
+            (error) => '$error',
+            'description',
+            contains('`States<String> states` is not exposed in current scope'),
+          )
+      ),
+    );
+  });
+
+  test('`scope.hasStates` return true if states exposed', () async {
+
+    final scope = await Scope.root([
+      Final<States<String>>(equal: (_) => _emptyStates),
+    ]);
+
+    final hasStates = scope.hasStates<String>();
+
+    expect(hasStates, true);
+  });
+
+
+  test('`scope.hasStates` return false if states not exposed', () async {
+
+    final scope = await Scope.root([]);
+
+    final hasStates = scope.hasStates<String>();
+
+    expect(hasStates, false);
+  });
+
+  test('`scope.hasStates` return true if states exposed with name', () async {
+
+    final scope = await Scope.root([
+      Final<States<String>>(name: 'states', equal: (_) => _emptyStates),
+    ]);
+
+    final hasStates = scope.hasStates<String>(name: 'states');
+
+    expect(hasStates, true);
+  });
+
+  test('`scope.hasStates` return false if states not exposed with name', () async {
+
+    final scope = await Scope.root([]);
+
+    final hasStates = scope.hasStates<String>(name: 'states');
+
+    expect(hasStates, false);
+  });
+
+}