feat: add onSuccess and onError; refactor: rename add try nomenclature to tryGetSuccess and tryGetError

Author: higorlapa

README.md

@@ -16,11 +16,11 @@ In the return of a function, set it to return a Result type;
 ```dart
 Result getSomethingPretty();
 ```
-then add the Error and the Success types.
+then add the Success and the Error types.
 
 ```dart
 
-Result<Exception, String> getSomethingPretty() {
+Result<String, Exception> getSomethingPretty() {
 
 }
 
@@ -41,7 +41,7 @@ The function should look something like this:
 
 ```dart
 
-Result<Exception, String> getSomethingPretty() {
+Result<String, Exception> getSomethingPretty() {
     if(isOk) {
         return Success('OK!');
     } else {
@@ -69,9 +69,32 @@ void main() {
 }
 ```
 
+#### Handling the Result with `onSuccess` or `onError`
+
+```dart 
+    final result = getSomethingPretty();
+    // notice the [onSuccess] or [onError] will only be executed if
+    // the result is a Success or an Error respectivaly. 
+    final output = result.onSuccess((name) {
+        // handle here the success
+        return "";
+    });
+    
+    final result = getSomethingPretty();
+    
+    // [result] is NOT an Error, this [output] will be null.
+    final output = result.onError((exception) {
+        // handle here the error
+        return "";
+    });
+```
 
 #### Handling the Result with `get`
 
+```
+note: [get] is now deprecated and will be removed in the next version.
+```
+
 ```dart
 void main() {
     final result = getSomethingPretty();
@@ -84,30 +107,30 @@ void main() {
 ```
 
 
-#### Handling the Result with `getSuccess`
+#### Handling the Result with `tryGetSuccess`
 
 ```dart
 void main() {
     final result = getSomethingPretty();
 
     String? mySuccessResult;
     if (result.isSuccess()) {
-      mySuccessResult = result.getSuccess();
+      mySuccessResult = result.tryGetSuccess();
     }
 }
 
 ```
 
 
-#### Handling the Result with `getError`
+#### Handling the Result with `tryGetError`
 
 ```dart
 void main() {
     final result = getSomethingPretty();
 
     Exception? myException;
     if (result.isError()) {
-      myException = result.getError();
+      myException = result.tryGetError();
     }
 }
 ```

example/lib/main.dart

@@ -53,13 +53,20 @@ class _MyHomePageState extends State<MyHomePage> {
       floatingActionButton: FloatingActionButton(
         onPressed: () {
           final result = _shouldIncrement(_counter);
-          if (result.isSuccess()) {
-            setState(() {
-              _counter++;
-            });
-          } else {
-            ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text("Counter cannot be bigger than 9")));
-          }
+          result.when(
+            (success) {
+              setState(() {
+                _counter++;
+              });
+            },
+            (error) {
+              ScaffoldMessenger.of(context).showSnackBar(
+                SnackBar(
+                  content: Text(error.message),
+                ),
+              );
+            },
+          );
         },
         tooltip: 'Increment',
         child: Icon(Icons.add),

example/pubspec.lock

@@ -7,7 +7,7 @@ packages:
       name: async
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "2.5.0"
+    version: "2.9.0"
   boolean_selector:
     dependency: transitive
     description:
@@ -21,35 +21,28 @@ packages:
       name: characters
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.1.0"
-  charcode:
-    dependency: transitive
-    description:
-      name: charcode
-      url: "https://pub.dartlang.org"
-    source: hosted
-    version: "1.2.0"
+    version: "1.2.1"
   clock:
     dependency: transitive
     description:
       name: clock
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.1.0"
+    version: "1.1.1"
   collection:
     dependency: transitive
     description:
       name: collection
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.15.0"
+    version: "1.16.0"
   fake_async:
     dependency: transitive
     description:
       name: fake_async
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.2.0"
+    version: "1.3.1"
   flutter:
     dependency: "direct main"
     description: flutter
@@ -66,28 +59,35 @@ packages:
       name: matcher
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "0.12.10"
+    version: "0.12.12"
+  material_color_utilities:
+    dependency: transitive
+    description:
+      name: material_color_utilities
+      url: "https://pub.dartlang.org"
+    source: hosted
+    version: "0.1.5"
   meta:
     dependency: transitive
     description:
       name: meta
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.3.0"
+    version: "1.8.0"
   multiple_result:
     dependency: "direct main"
     description:
       path: ".."
       relative: true
     source: path
-    version: "1.0.1"
+    version: "1.0.4"
   path:
     dependency: transitive
     description:
       name: path
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.8.0"
+    version: "1.8.2"
   sky_engine:
     dependency: transitive
     description: flutter
@@ -99,7 +99,7 @@ packages:
       name: source_span
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.8.0"
+    version: "1.9.0"
   stack_trace:
     dependency: transitive
     description:
@@ -120,34 +120,27 @@ packages:
       name: string_scanner
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.1.0"
+    version: "1.1.1"
   term_glyph:
     dependency: transitive
     description:
       name: term_glyph
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "1.2.0"
+    version: "1.2.1"
   test_api:
     dependency: transitive
     description:
       name: test_api
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "0.2.19"
-  typed_data:
-    dependency: transitive
-    description:
-      name: typed_data
-      url: "https://pub.dartlang.org"
-    source: hosted
-    version: "1.3.0"
+    version: "0.4.12"
   vector_math:
     dependency: transitive
     description:
       name: vector_math
       url: "https://pub.dartlang.org"
     source: hosted
-    version: "2.1.0"
+    version: "2.1.2"
 sdks:
-  dart: ">=2.12.0 <3.0.0"
+  dart: ">=2.17.0-0 <3.0.0"

lib/multiple_result.dart

@@ -24,13 +24,16 @@ abstract class Result<S, E> {
   /// ```
   ///
   /// before casting the value;
+  @Deprecated('Will be removed in the next version. '
+      'Use `tryGetSuccess` or `tryGetError` instead.'
+      'You may also use `onSuccess` and on `onError` for similar result.')
   dynamic get();
 
-  /// Returns the value of [S].
-  S? getSuccess();
+  /// Returns the value of [S] if any.
+  S? tryGetSuccess();
 
-  /// Returns the value of [E].
-  E? getError();
+  /// Returns the value of [E] if any.
+  E? tryGetError();
 
   /// Returns true if the current result is an [Error].
   bool isError();
@@ -47,6 +50,16 @@ abstract class Result<S, E> {
     W Function(S success) whenSuccess,
     W Function(E error) whenError,
   );
+
+  /// Execute [whenSuccess] if the [Result] is a success.
+  R? onSuccess<R>(
+    R Function(S success) whenSuccess,
+  );
+
+  /// Execute [whenError] if the [Result] is an error.
+  R? onError<R>(
+    R Function(E error) whenError,
+  );
 }
 
 /// Success Result.
@@ -78,7 +91,8 @@ class Success<S, E> implements Result<S, E> {
   int get hashCode => _success.hashCode;
 
   @override
-  bool operator ==(Object other) => other is Success && other._success == _success;
+  bool operator ==(Object other) =>
+      other is Success && other._success == _success;
 
   @override
   W when<W>(
@@ -89,10 +103,18 @@ class Success<S, E> implements Result<S, E> {
   }
 
   @override
-  E? getError() => null;
+  E? tryGetError() => null;
 
   @override
-  S? getSuccess() => _success;
+  S tryGetSuccess() => _success;
+
+  @override
+  R? onError<R>(R Function(E error) whenError) => null;
+
+  @override
+  R onSuccess<R>(R Function(S success) whenSuccess) {
+    return whenSuccess(_success);
+  }
 }
 
 /// Error Result.
@@ -133,25 +155,34 @@ class Error<S, E> implements Result<S, E> {
   }
 
   @override
-  E? getError() => _error;
+  E tryGetError() => _error;
+
+  @override
+  S? tryGetSuccess() => null;
+
+  @override
+  R onError<R>(R Function(E error) whenError) => whenError(_error);
 
   @override
-  S? getSuccess() => null;
+  R? onSuccess<R>(R Function(S success) whenSuccess) => null;
+
 }
 
 /// Default success class.
 ///
 /// Instead of returning void, as
 /// ```dart
-///   Result<Exception, void>
+///   Result<void, Exception>
 /// ```
 /// return
 /// ```dart
-///   Result<Exception, SuccessResult>
+///   Result<SuccessResult, Exception>
 /// ```
 class SuccessResult {
   const SuccessResult._internal();
 }
 
 /// Default success case.
 const success = SuccessResult._internal();
+
+

pubspec.yaml

@@ -1,10 +1,10 @@
 name: multiple_result
 description: Multiple results for dart. Inspired by dartz's Either and Kotlin's sealed classes
-version: 1.0.4
-homepage: https://github.com/higorlapa/result
+version: 2.0.0
+repository: https://github.com/higorlapa/result
 
 environment:
-  sdk: ">=2.12.0 <3.0.0"
+  sdk: ">=2.15.1 <3.0.0"
 
 dependencies:
   meta: ^1.3.0