How to Use DartExceptor: A Lighter Way to Handle Errors in Dart 3

<p>If you've worked with Flutter for any meaningful length of time, you've likely written this:</p> <pre><code class="language-dart">try { final user = await repo.getUser(); print(user.name); } catch (e) { print('Something went wrong: $e'); } </code></pre> <p>It compiles. It ships. And six months later, a bug report lands from a user staring at a blank screen, because somewhere, a <code>catch (e)</code> swallowed the real failure.</p> <p>This snippet looks harmless, but it has three problems that only surface under pressure.</p> <p>First, the failure is invisible in the signature. Whatever <code>repo.getUser()</code> returns tells you nothing about what happens when the network drops, the token expires, or the response is malformed. You only find out by reading the implementation, or by hitting the bug in production.</p> <p>Second, the compiler can't help you. If a teammate forgets the <code>try/catch</code> somewhere else in the codebase, the app compiles fine. Nothing warns you. The crash happens at runtime, in front of a real user, not at build time in front of you.</p> <p>Third, <code>catch (e)</code> catches everything indiscriminately. A typo, a null dereference, an actual network failure, and a malformed JSON response all land in the same block. You can't tell them apart without inspecting the error string, and that's fragile since it breaks the moment the message changes.</p> <p>Put together, every failure path becomes a social contract between a function's author and its caller instead of something the type system enforces. Social contracts break under pressure, in large teams, and at 2am during an incident.</p> <p>A few weeks ago, I wrote <a href="https://www.freecodecamp.org/news/advanced-error-handling-in-dart-records-result-types-monads-and-freezed-exceptions/">Advanced Error Handling in Dart: Records, Result Types, Monads, and Freezed Exceptions</a> to walk through fixing exactly this, using Records, sealed Result types, the Monad pattern, <code>dartz</code>, and Freezed exceptions to make failure typed, visible, and impossible to ignore.</p> <p>This article is meant to stand on its own, so we'll start with a quick recap of where that one landed before we pick the thread back up.</p> <h3 id="heading-what-well-cover">What We'll Cover:</h3> <ol> <li><p><a href="#heading-recap-where-the-previous-article-left-off">Recap: Where the Previous Article Left Off</a></p> </li> <li><p><a href="#heading-the-problem-after-the-pattern">The Problem After the Pattern</a></p> </li> <li><p><a href="#heading-how-dart-exceptor-works">How DartExceptor Works</a></p> </li> <li><p><a href="#heading-the-core-type">The Core Type</a></p> </li> <li><p><a href="#heading-the-api-four-methods-each-with-one-job">The API: Four Methods, Each With One Job</a></p> </li> <li><p><a href="#heading-where-this-fits-in-clean-architecture">Where This Fits in Clean Architecture</a></p> </li> <li><p><a href="#heading-why-not-just-use-dartz">Why Not Just Use dartz?</a></p> </li> <li><p><a href="#heading-try-it-out">Try it Out</a></p> </li> </ol> <h2 id="heading-recap-where-the-previous-article-left-off">Recap: Where the Previous Article Left Off</h2> <p>That article moved through several layers, each one fixing a limitation in the layer before it.</p> <p>It started with Dart Records as the simplest possible fix, a typed tuple with nullable fields for success and failure:</p> <pre><code class="language-dart">typedef Result&lt;E, T&gt; = ({E? e, T? data}); </code></pre> <p>This is already better than a bare exception because the return type now admits a function can fail.</p> <p>But records have a real limitation. Nothing stops you from forgetting to check which field is populated, and there's no way to transform a result without manually unwrapping it first.</p> <p>That gap is what led to a proper sealed Result type, <code>AppResult&lt;T&gt;</code>, which replaces the nullable-field record with two structurally distinct subclasses, <code>AppSuccess</code> and <code>AppFailure</code>, plus a <code>when()</code> method that forces both cases to be handled:</p> <pre><code class="language-dart">sealed class AppResult&lt;T&gt; { const AppResult(); R when&lt;R&gt;({ required R Function(T value) success, required R Function(AppFailure failure) failure, }); } class AppSuccess&lt;T&gt; extends AppResult&lt;T&gt; { const AppSuccess(this.value); final T value; @override R when&lt;R&gt;({ required R Function(T value) success, required R Function(AppFailure failure) failure, }) =&gt; success(value); } class AppFailure&lt;T&gt; extends AppResult&lt;T&gt; { const AppFailure(this.error); final AppError error; @override R when&lt;R&gt;({ required R Function(T value) success, required R Function(AppFailure failure) failure, }) =&gt; failure(this); } </code></pre> <p>Because <code>AppResult</code> is <code>sealed</code>, the compiler enforces exhaustiveness. You genuinely can't forget the failure branch the way you could with a record or a <code>try/catch</code>.</p> <p>From there, the article extended <code>AppResult</code> into a proper Monad by adding <code>map</code> and <code>flatMap</code>, so results could be transformed and chained without ever leaving the wrapper, and brought in <code>dartz</code>'s <code>Either</code> as the more conventional functional programming equivalent for teams who wanted that vocabulary. It closed with Freezed-based typed exceptions, so even the failure side carried structured, pattern-matchable data instead of a bare string.</p> <p>By the end, the pattern looked like this across a full stack: a sealed result type, structured exceptions, and <code>map</code>/<code>flatMap</code> for transformation, wired consistently through the repository, domain, and presentation layers.</p> <p>If you want the full derivation, why each layer was added, the <code>dartz</code> integration, and the Freezed exception setup, that article covers it in depth. What follows here only assumes the shape above, not the journey to it.</p> <h2 id="heading-the-problem-after-the-pattern">The Problem After the Pattern</h2> <p>Here's what happened after I published that article.</p> <p>Every time I started a new project, I found myself doing the same thing: recreating the sealed <code>Result</code> class, rewriting <code>Ok</code> and <code>Err</code>, re-implementing <code>map</code>, <code>flatMap</code>, and the rest. Copying the same roughly 150 lines from project to project, tweaking small things, occasionally introducing inconsistencies between projects because I forgot what I'd named something last time.</p> <p>The pattern was right. The repetition wasn't.</p> <p>A pattern you have to rewrite every time isn't a pattern, it's a chore. So I packaged it.</p> <h2 id="heading-how-dartexceptor-works">How DartExceptor Works</h2> <p><a href="https://pub.dev/packages/dart_exceptor"><strong>DartExceptor</strong></a> is a lightweight, zero-dependency Dart 3 package that implements the exact pattern from the previous article, <code>Trace&lt;T, E&gt;</code>, <code>Ok</code>, <code>Err</code>, and a small, intentional set of monadic operations, as a reusable package.</p> <p>No <code>dartz</code>, no Freezed, and no build_runner. Just <code>Trace&lt;T, E&gt;</code>, two implementations, and four methods.</p> <pre><code class="language-dart">dependencies: dart_exceptor: ^1.1.2 </code></pre> <pre><code class="language-dart">import 'package:dart_exceptor/dart_exceptor.dart'; </code></pre> <p>That's the entire setup.</p> <h2 id="heading-the-core-type">The Core Type</h2> <p>Every operation in DartExceptor returns a <code>Trace&lt;T, E&gt;</code>:</p> <ul> <li><p><code>T</code> is the success type</p> </li> <li><p><code>E</code> is the error type</p> </li> </ul> <p><code>Trace</code> has exactly two implementations:</p> <pre><code class="language-dart">return Ok(user); // success return Err(AppException(code: 404, e: 'Not found')); // failure </code></pre> <p>You never construct <code>Trace</code> directly. You return <code>Ok</code> or <code>Err</code>, and program against <code>Trace</code> everywhere else. The function signature now tells the truth about what can happen:</p> <pre><code class="language-dart">Future&lt;Trace&lt;User, AppException&gt;&gt; getUser(String id); </code></pre> <p>Anyone reading that signature immediately knows this can succeed with a <code>User</code>, or fail with an <code>AppException</code>. No surprises six months later.</p> <h2 id="heading-the-api-four-methods-each-with-one-job">The API: Four Methods, Each With One Job</h2> <p>If the previous article's <code>Result</code> type had <code>map</code>, <code>flatMap</code>, and a <code>when()</code> for pattern matching, DartExceptor takes that same shape and refines it into four focused methods.</p> <h3 id="heading-split-the-exit-point"><code>split</code>, the Exit Point</h3> <p><code>split</code> is where you leave the <code>Trace</code> world. Both handlers are required, so you can't accidentally ignore a failure path.</p> <pre><code class="language-dart">result.split( data: (user) =&gt; print(user.name), e: (e) =&gt; print(e.message), ); </code></pre> <h3 id="heading-map-extract-and-transform-success"><code>map</code>, Extract and Transform Success</h3> <p><code>map</code> unwraps the value from an <code>Ok</code> and lets you transform it directly:</p> <pre><code class="language-dart">final activeUsers = result.map( data: (users) =&gt; users.where((u) =&gt; u.isActive).toList(), ); </code></pre> <h3 id="heading-maperror-extract-and-transform-failure"><code>mapError</code>, Extract and Transform Failure</h3> <p>This is the mirror of <code>map</code>, for the error side. It's useful when crossing architectural boundaries where your data layer's exception type differs from your domain layer's:</p> <pre><code class="language-dart">final domainError = result.mapError( e: (e) =&gt; AppException(code: e.statusCode, e: e.toString()), ); </code></pre> <h3 id="heading-bind-chain-operations-that-return-trace"><code>bind&lt;B&gt;</code>, Chain Operations That Return <code>Trace</code></h3> <p>This is the one that does the real work. <code>bind&lt;B&gt;</code> lets you chain operations that themselves return a <code>Trace</code>, transforming the success type at each step. If any step fails, everything downstream is skipped automatically.</p> <pre><code class="language-dart">result .bind&lt;User&gt;( n: (users) { try { return Ok(users.firstWhere((u) =&gt; u.id == id)); } catch (e) { return Err(AppException(code: 404, e: 'User not found')); } }, ) .bind&lt;String&gt;(n: (user) =&gt; Ok(user.firstName)) .split( data: (name) =&gt; print('User: $name'), e: (e) =&gt; print('Error: ${e.e}'), ); </code></pre> <p><code>List&lt;User&gt;</code> becomes <code>User</code> becomes <code>String</code>. Each <code>bind&lt;B&gt;</code> transforms the type, the compiler checks every step, and a failure anywhere in the chain short-circuits straight to the <code>e</code> handler in <code>split</code>. This is the previous article's <code>flatMap</code> discussion, taken to its logical conclusion.</p> <h2 id="heading-where-this-fits-in-clean-architecture">Where This Fits in Clean Architecture</h2> <p>The pattern from the original article was always about more than syntax. It was about making failure visible across layers. DartExceptor slots into that exact structure with zero modification:</p> <pre><code class="language-dart">// Data layer abstract class DataSource { Future&lt;Trace&lt;List&lt;User&gt;, AppException&gt;&gt; getAllUsers(); } // Repository layer abstract class IUserRepository { Future&lt;Trace&lt;List&lt;User&gt;, AppException&gt;&gt; getAllUsers(); } // Use case layer class UserUseCase { Future&lt;Trace&lt;List&lt;User&gt;, AppException&gt;&gt; getAllUsers() =&gt; repository.getAllUsers(); } // Presentation layer void loadUsers() async { final result = await useCase.getAllUsers(); result.split( data: (users) =&gt; print('Loaded ${users.length} users'), e: (e) =&gt; print('Failed: ${e.e}'), ); } </code></pre> <p>The same layers, same separation, and same typed failure paths, just without rewriting the foundation every time.</p> <h2 id="heading-why-not-just-use-dartz">Why Not Just Use <code>dartz</code>?</h2> <p>The previous article covered <code>dartz</code>'s <code>Either</code> in depth, and it's a genuinely solid choice if your team is comfortable with its API surface and the dependency footprint isn't a concern.</p> <p>DartExceptor exists for a narrower case, when you want the result type pattern without importing a library built around Haskell-style functional programming conventions. Theres no <code>Left</code>/<code>Right</code>, no <code>fold</code>, and no transitive dependencies. Just <code>Trace</code>, <code>Ok</code>, <code>Err</code>, and four methods that map directly onto how the previous article's pattern was actually used in practice.</p> <table> <thead> <tr> <th></th> <th>DartExceptor</th> <th>dartz</th> </tr> </thead> <tbody><tr> <td>Dependencies</td> <td>Zero</td> <td>Multiple</td> </tr> <tr> <td>Dart 3 native</td> <td>Yes</td> <td>No</td> </tr> <tr> <td>API surface</td> <td>4 methods</td> <td>Large</td> </tr> <tr> <td>Haskell concepts required</td> <td>No</td> <td>Yes</td> </tr> <tr> <td>Type-safe chaining (<code>bind&lt;B&gt;</code>)</td> <td>Yes</td> <td>Yes (<code>flatMap</code>)</td> </tr> </tbody></table> <h2 id="heading-try-it-out">Try It Out</h2> <p>DartExceptor is live on pub.dev:</p> <pre><code class="language-dart">dependencies: dart_exceptor: ^1.1.2 </code></pre> <p>Package: <a href="https://pub.dev/packages/dart_exceptor">pub.dev/packages/dart_exceptor</a> Source: <a href="https://github.com/seyifunmi92/Dart-Exceptor-Plugin">GitHub</a></p> <p>If you've read the previous article and built something like this yourself, I'd genuinely love to hear how your version compares. And if DartExceptor saves you from rewriting that pattern one more time, a star on GitHub goes a long way.</p>