Enhancements to the Result Pattern Documentation

[luketg8]

Page URL

https://docs.flutter.dev/app-architecture/design-patterns/result#using-the-result-pattern

Page source

No response

Describe the problem

The Result class is useful for encapsulating success and error outcomes. However, it has some undocumented limitations.

Loss of Stack Traces: The Error class only stores the Exception object but not the associated StackTrace. Without the stack trace, debugging becomes more difficult and you don't get the most out of services like Crashlytics.

Loss of Centralized Error Handling Developers relying on FlutterError.onError as their centralised error-handling mechanism, may not realise that errors wrapped in Result instances are excluded unless they explicitly log them.

Lack of Documentation: There is no guidance on handling this effectively whilst using this pattern, which could lead to suppressed exceptions or silent failures.

Expected fix

Enhance the Error Class: Add a StackTrace field to preserve this information:

class Error<T> extends Result<T> {
  final Exception exception;
  final StackTrace stackTrace;

  Error(this.exception, [this.stackTrace = StackTrace.current]);
}

Update Documentation: Include best practices for: Handling Error cases (e.g., logging or rethrowing exceptions). Preserving StackTraces for debugging.

Show How to Report to Crash Reporting Solutions: Show how developers can bridge the gap between the Result class and FlutterError.onError to ensure exceptions are still reported. For example:

if (result is Error) {
  FlutterError.reportError(FlutterErrorDetails(
    exception: result.exception,
    stack: result.stackTrace,
  ));
}

Additional context

No response

I would like to fix this problem.

• [ ] I will try and fix this problem on docs.flutter.dev.