feat: add v5.3.0 improvements with AsyncResult and new functional methods

- Fix Error.getOrThrow() to pass <S, E> to SuccessResultNotFoundException
- Add Result.tryCatch static factory for wrapping throwing functions
- Add getOrElse, onSuccess, onError, flatMapError, recover, swap methods
- Add AsyncResult<S,E> zero-cost extension type for async chaining
- Bump version to 5.3.0, tighten SDK constraint to >=3.3.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: higorlapa

CHANGELOG.md

@@ -1,3 +1,18 @@
+## 5.3.0 03/14/2026
+
+### Bug Fixes
+* `Error.getOrThrow()` now correctly passes `<S, E>` to `SuccessResultNotFoundException`, so `toString()` shows the actual types instead of `dynamic`.
+
+### New Features
+* `Result.tryCatch(action, onError)` — static factory that wraps a potentially-throwing synchronous computation.
+* `getOrElse(orElse)` — returns the success value or a fallback computed from the error.
+* `onSuccess(action)` / `onError(action)` — side-effect tap methods that execute an action without transforming the result, returning `this` for chaining.
+* `flatMapError(mapper)` — symmetric counterpart to `flatMap` for the error channel.
+* `recover(mapper)` — alias for `flatMapError`.
+* `swap()` — converts `Success` to `Error` and vice versa.
+* `AsyncResult<S, E>` — zero-cost `Future<Result<S, E>>` wrapper via Dart extension types, with a full mirrored API (`mapSuccess`, `mapError`, `map`, `flatMap`, `flatMapAsync`, `flatMapError`, `swap`, `onSuccess`, `onError`, `getOrThrow`, `getOrElse`, `tryGetSuccess`, `tryGetError`, `when`, `isSuccess`, `isError`, and `tryCatch`).
+* `AsyncResultOf<S, E>` typedef alias for `AsyncResult<S, E>`.
+
 ## 5.2.0 04/29/2025
 
 * Improves README.md

README.md

@@ -251,6 +251,91 @@ The key difference between `mapSuccess` and `flatMap`:
 - `mapSuccess` takes a function that returns a value `T` and wraps it in a Result
 - `flatMap` takes a function that returns a Result directly, avoiding nested Results
 
+### Using `Result.tryCatch`
+
+Replace try/catch blocks with `Result.tryCatch` to convert a throwing operation directly into a `Result`:
+
+```dart
+final result = Result.tryCatch(
+  () => int.parse(userInput),
+  (error, stackTrace) => ParseError(error.toString()),
+);
+// result is Success(42) or Error(ParseError(...))
+```
+
+### Using `getOrElse`
+
+Provide a fallback value computed from the error instead of throwing:
+
+```dart
+final value = result.getOrElse((error) => defaultValue);
+```
+
+### Using `onSuccess` / `onError`
+
+Run side effects (e.g. logging) in the middle of a chain without breaking it:
+
+```dart
+result
+    .onSuccess((data) => logger.info('Got $data'))
+    .onError((error) => logger.error('Failed: $error'))
+    .mapSuccess((data) => data.toUpperCase());
+```
+
+### Using `flatMapError` / `recover`
+
+Handle errors and recover into a new `Result`, symmetric to `flatMap`:
+
+```dart
+final result = fetchUser(id)
+    .flatMapError((e) => fetchUserFromCache(id));
+
+// or with the alias:
+final result = fetchUser(id)
+    .recover((e) => fetchUserFromCache(id));
+```
+
+### Using `swap`
+
+Convert a `Success` into an `Error` and vice versa — useful for inverting validation logic:
+
+```dart
+final inverted = result.swap();
+// Success('x') becomes Error('x'), Error(e) becomes Success(e)
+```
+
+## Async Results with `AsyncResult`
+
+`AsyncResult<S, E>` is a zero-cost wrapper around `Future<Result<S, E>>` using Dart extension types. It lets you chain transformations on async results fluently without awaiting at each step.
+
+```dart
+// Wrap a Future<Result> as AsyncResult
+AsyncResult<User, ApiError> fetchUser(int id) =>
+    AsyncResult(api.get('/users/$id').then((r) => r.toResult()));
+
+// Chain operations without intermediate awaits
+final greeting = await fetchUser(42)
+    .mapSuccess((user) => user.name.toUpperCase())
+    .onError((e) => logger.error('Failed: $e'))
+    .getOrElse((_) => 'Anonymous');
+```
+
+Use `AsyncResult.tryCatch` to wrap a potentially-throwing async function:
+
+```dart
+final result = AsyncResult.tryCatch(
+  () async => await api.fetchUser(id),
+  (error, stack) => NetworkError(error.toString()),
+);
+```
+
+Use `flatMapAsync` to chain operations that are themselves async:
+
+```dart
+final result = fetchUser(42)
+    .flatMapAsync((user) => fetchPosts(user.id));
+```
+
 ## Unit Type
 
 Some results don't need a specific return value. Use the Unit type to signal an empty return:

lib/multiple_result.dart

@@ -2,3 +2,4 @@ library multiple_result;
 
 export 'src/result.dart';
 export 'src/unit.dart';
+export 'src/async_result.dart';

lib/src/async_result.dart

@@ -0,0 +1,141 @@
+import 'result.dart';
+
+/// A zero-cost wrapper around [Future<Result<S, E>>] using Dart extension types.
+///
+/// [AsyncResult] lets you chain and transform asynchronous [Result] values
+/// using the same API as synchronous [Result], without allocating any
+/// intermediate wrapper objects at runtime.
+///
+/// Example:
+/// ```dart
+/// AsyncResult<String, Exception> fetchUser(int id) =>
+///     AsyncResult(fetchUserJson(id).then((json) => Success(json['name'])));
+///
+/// final name = await fetchUser(42)
+///     .mapSuccess((n) => n.toUpperCase())
+///     .getOrElse((_) => 'unknown');
+/// ```
+extension type AsyncResult<S, E>(Future<Result<S, E>> _future) {
+  /// Returns the inner [Future<Result<S, E>>].
+  Future<Result<S, E>> get future => _future;
+
+  // ── Transformations ─────────────────────────────────────────────────────────
+
+  /// Transforms the success value if this resolves to a [Success].
+  AsyncResult<U, E> mapSuccess<U>(U Function(S success) mapper) =>
+      AsyncResult(_future.then((r) => r.mapSuccess(mapper)));
+
+  /// Transforms the error value if this resolves to an [Error].
+  AsyncResult<S, F> mapError<F>(F Function(E error) mapper) =>
+      AsyncResult(_future.then((r) => r.mapError(mapper)));
+
+  /// Transforms both success and error values.
+  AsyncResult<U, F> map<U, F>({
+    required U Function(S success) successMapper,
+    required F Function(E error) errorMapper,
+  }) =>
+      AsyncResult(
+        _future.then(
+          (r) => r.map(successMapper: successMapper, errorMapper: errorMapper),
+        ),
+      );
+
+  /// Chains an operation that returns a synchronous [Result].
+  AsyncResult<U, E> flatMap<U>(Result<U, E> Function(S success) mapper) =>
+      AsyncResult(_future.then((r) => r.flatMap(mapper)));
+
+  /// Chains an operation that returns an [AsyncResult].
+  AsyncResult<U, E> flatMapAsync<U>(
+    AsyncResult<U, E> Function(S success) mapper,
+  ) =>
+      AsyncResult(
+        _future.then(
+          (r) => switch (r) {
+            Success(:final success) => mapper(success)._future,
+            Error(:final error) => Future.value(Result<U, E>.error(error)),
+          },
+        ),
+      );
+
+  /// Chains error recovery that returns a synchronous [Result].
+  AsyncResult<S, F> flatMapError<F>(
+    Result<S, F> Function(E error) mapper,
+  ) =>
+      AsyncResult(_future.then((r) => r.flatMapError(mapper)));
+
+  /// Returns a new [AsyncResult] with [Success] and [Error] swapped.
+  AsyncResult<E, S> swap() => AsyncResult(_future.then((r) => r.swap()));
+
+  // ── Side effects ────────────────────────────────────────────────────────────
+
+  /// Executes [action] as a side effect if the result is a [Success],
+  /// then propagates the result unchanged.
+  AsyncResult<S, E> onSuccess(void Function(S success) action) =>
+      AsyncResult(_future.then((r) => r.onSuccess(action)));
+
+  /// Executes [action] as a side effect if the result is an [Error],
+  /// then propagates the result unchanged.
+  AsyncResult<S, E> onError(void Function(E error) action) =>
+      AsyncResult(_future.then((r) => r.onError(action)));
+
+  // ── Extraction ──────────────────────────────────────────────────────────────
+
+  /// Awaits the result and returns the success value, or throws
+  /// [SuccessResultNotFoundException] if it is an [Error].
+  Future<S> getOrThrow() => _future.then((r) => r.getOrThrow());
+
+  /// Awaits the result and returns the success value, or calls [orElse] with
+  /// the error and returns that value.
+  Future<S> getOrElse(S Function(E error) orElse) =>
+      _future.then((r) => r.getOrElse(orElse));
+
+  /// Awaits the result and returns the success value, or null.
+  Future<S?> tryGetSuccess() => _future.then((r) => r.tryGetSuccess());
+
+  /// Awaits the result and returns the error value, or null.
+  Future<E?> tryGetError() => _future.then((r) => r.tryGetError());
+
+  /// Awaits and calls [whenSuccess] or [whenError] based on the result.
+  Future<W> when<W>(
+    W Function(S success) whenSuccess,
+    W Function(E error) whenError,
+  ) =>
+      _future.then((r) => r.when(whenSuccess, whenError));
+
+  /// Awaits and checks whether the result is a [Success].
+  Future<bool> isSuccess() => _future.then((r) => r.isSuccess());
+
+  /// Awaits and checks whether the result is an [Error].
+  Future<bool> isError() => _future.then((r) => r.isError());
+
+  // ── Factory ─────────────────────────────────────────────────────────────────
+
+  /// Wraps a potentially-throwing async operation.
+  ///
+  /// If [action] completes normally, returns an [AsyncResult] wrapping [Success].
+  /// If [action] throws, calls [onError] and returns an [AsyncResult] wrapping [Error].
+  ///
+  /// Example:
+  /// ```dart
+  /// final result = AsyncResult.tryCatch(
+  ///   () async => await fetchUser(id),
+  ///   (err, stack) => NetworkError(err.toString()),
+  /// );
+  /// ```
+  static AsyncResult<S, E> tryCatch<S, E>(
+    Future<S> Function() action,
+    E Function(Object error, StackTrace stackTrace) onError,
+  ) =>
+      AsyncResult(
+        Future(() async {
+          try {
+            return Success<S, E>(await action());
+          } catch (e, s) {
+            return Error<S, E>(onError(e, s));
+          }
+        }),
+      );
+}
+
+/// Alias for [AsyncResult].
+typedef AsyncResultOf<S, E> = AsyncResult<S, E>;

lib/src/result.dart

@@ -20,6 +20,30 @@ sealed class Result<S, E> {
   /// Creates a [Result] that represents a failed operation.
   const factory Result.error(E e) = Error;
 
+  /// Executes [action] and wraps the result.
+  ///
+  /// If [action] completes normally, returns [Success] with its return value.
+  /// If [action] throws, calls [onError] with the caught object and stack trace
+  /// and returns [Error] with the result.
+  ///
+  /// Example:
+  /// ```dart
+  /// final result = Result.tryCatch(
+  ///   () => int.parse(input),
+  ///   (err, stack) => ParseFailure(err.toString()),
+  /// );
+  /// ```
+  static Result<S, E> tryCatch<S, E>(
+    S Function() action,
+    E Function(Object error, StackTrace stackTrace) onError,
+  ) {
+    try {
+      return Success<S, E>(action());
+    } catch (e, s) {
+      return Error<S, E>(onError(e, s));
+    }
+  }
+
   /// Gets the success value if this result is a [Success].
   ///
   /// Throws [SuccessResultNotFoundException] if this result is an [Error].
@@ -109,6 +133,37 @@ sealed class Result<S, E> {
   ///
   /// This method is useful for chaining operations that might fail without nesting results.
   Result<U, E> flatMap<U>(Result<U, E> Function(S success) mapper);
+
+  /// Returns the success value if this is [Success], otherwise calls [orElse]
+  /// with the error value and returns the result.
+  S getOrElse(S Function(E error) orElse);
+
+  /// Executes [action] as a side effect if this is a [Success], then returns
+  /// this result unchanged. Useful for logging or other side effects in a chain.
+  Result<S, E> onSuccess(void Function(S success) action);
+
+  /// Executes [action] as a side effect if this is an [Error], then returns
+  /// this result unchanged. Useful for logging or other side effects in a chain.
+  Result<S, E> onError(void Function(E error) action);
+
+  /// Transforms the error value of this result to another result.
+  ///
+  /// If this result is an [Error], applies [mapper] to the error to produce a
+  /// new result. If this result is a [Success], returns a new success result
+  /// carrying the same success value.
+  ///
+  /// This is the symmetric counterpart of [flatMap] for the error channel.
+  Result<S, F> flatMapError<F>(Result<S, F> Function(E error) mapper);
+
+  /// Alias for [flatMapError]. Recovers from an error by producing a new result.
+  Result<S, F> recover<F>(Result<S, F> Function(E error) mapper) =>
+      flatMapError(mapper);
+
+  /// Returns a new result with [Success] and [Error] swapped.
+  ///
+  /// A [Success] value becomes an [Error], and an [Error] value becomes a
+  /// [Success].
+  Result<E, S> swap();
 }
 
 /// Success Result.
@@ -196,6 +251,26 @@ final class Success<S, E> extends Result<S, E> {
   Result<U, E> flatMap<U>(Result<U, E> Function(S success) mapper) {
     return mapper(_success);
   }
+
+  @override
+  S getOrElse(S Function(E error) orElse) => _success;
+
+  @override
+  Result<S, E> onSuccess(void Function(S success) action) {
+    action(_success);
+    return this;
+  }
+
+  @override
+  Result<S, E> onError(void Function(E error) action) => this;
+
+  @override
+  Result<S, F> flatMapError<F>(Result<S, F> Function(E error) mapper) {
+    return Success<S, F>(_success);
+  }
+
+  @override
+  Result<E, S> swap() => Error<E, S>(_success);
 }
 
 /// Error Result.
@@ -238,7 +313,7 @@ final class Error<S, E> extends Result<S, E> {
       whenError(_error);
 
   @override
-  S getOrThrow() => throw SuccessResultNotFoundException();
+  S getOrThrow() => throw SuccessResultNotFoundException<S, E>();
 
   @override
   E tryGetError() => _error;
@@ -277,6 +352,26 @@ final class Error<S, E> extends Result<S, E> {
   Result<U, E> flatMap<U>(Result<U, E> Function(S success) mapper) {
     return Error<U, E>(_error);
   }
+
+  @override
+  S getOrElse(S Function(E error) orElse) => orElse(_error);
+
+  @override
+  Result<S, E> onSuccess(void Function(S success) action) => this;
+
+  @override
+  Result<S, E> onError(void Function(E error) action) {
+    action(_error);
+    return this;
+  }
+
+  @override
+  Result<S, F> flatMapError<F>(Result<S, F> Function(E error) mapper) {
+    return mapper(_error);
+  }
+
+  @override
+  Result<E, S> swap() => Success<E, S>(_error);
 }
 
 /// Exception thrown when attempting to access a success value that doesn't exist.