In the previous volume, we talked about how to identify and inject dependencies in our apps. Our application’s dependencies will be repositories or data sources, but they are going to be used by the business logic components (blocs), and then the blocs are going to emit states that the user interface will use to render widgets.

Part of this article will be about state management using my two favorite alternatives: package:bloc and package:riverpod. I have an article about the latter at Riverpod: Rewriting Provider, not yet one for bloc. I’ll try to write one soon but in the meantime, you can check this one made by Ana from Flutter Spain.

What to look for in a state manager

I want to start this discussion by explaining why I like bloc and riverpod, so this is an abstract of state management and can be used to evaluate other options when making this choice.

Predictability

First of all, I think code, in general, should be easy to comprehend, and that way it’s also predictable.

Someone asked me once what I meant with predictable code, to explain that I’m going to quote my teammate Jorge in his Are you saying that my code is boring? Thank you! article:

Producing boring code is the biggest compliment that an engineering team can receive; after all, “surprises” in a project tend to be not so good surprises. No one likes receiving a 2 a.m. emergency call, or spending 8 hours tracking down a bug that is almost impossible to reproduce and as engineers, we don’t like solving the same problem over and over again.

Predictable code is the one that is consistent and somewhat obvious. You know the structure and that allows you to know where things are without having to ask another engineer.

You can see this aspect in package:bloc when you create a new Bloc. The component is created aiming for a feature-driven architecture, so each feature has one Bloc assigned to it. Additionally, you’re always going to have three files related to that Bloc: bloc, event, and state.

💡 When you’re exploring a bloc directory, I recommend going through the files in this order: event, state, bloc. It’s an easy way to see the causes (events), the effects (states) they provoke, and what’s the relation between both (bloc).

On riverpod land, I already recommended a logical structure for your business logic in my article about it, but there’s no official way to organize them as you may have functionality inside another type of Provider that is not a business logic one like StateNotifierProvider.

We can say bloc is more predictable or at least the documentation is more explicit about this aspect.

Testability

Testing is a critical requirement for a project in my opinion. That makes the ease to test an invaluable detail to take into consideration when choosing a state management tool.

You can check more about testing on the article Flutter testing: A very good guide [10 Insights] from Very Good Ventures.

This is a broad topic to talk about, but I can mention some general ideas of what to search for when evaluating a state manager regarding testing.

Shouldn’t depend on lots of packages

If you are unit testing a layer of your architecture, you should have a few dependencies imported for testing it.

For bloc, you have a dedicated test utility called package:bloc_test, which can also be used in conjunction with package:mocktail and used to mock blocs for widget testing.

For riverpod, there is no testing utility to facilitate StateNotifier testing, so it ends up being a common unit test and you could also use mocktail to mock the component’s dependencies.

class MockSharedPreferencesRepository extends Mock
    implements SharedPreferencesRepository {}

void main() {
  late SharedPreferencesRepository preferencesRepository;

  setUp(() {
    preferencesRepository = MockSharedPreferencesRepository();
  });

  blocTest<PreferencesBloc, PreferencesState>(
    'emits [PreferencesEmpty] when PreferencesCleared is added.',
    setUp: () {
      when(preferencesRepository.clearValues).thenAnswer((_) async {});
    },
    build: () => PreferencesBloc(repository: preferencesRepository),
    act: (bloc) => bloc.add(PreferencesCleared()),
    expect: () => const <PreferencesState>[PreferencesEmpty()],
  );
}

Set up should be easy

As we mentioned in the previous volume, state management is a combination between dependency injection and reactive components. That means that to test these reactive components isolated we don’t need any dependency injection other than mocking their dependencies. And when using them to test UI, we should inject them with our DI mechanism easily without additional setup that can be repetitive and frustrating.

void main() {
  group('ProfileBloc', () {
    blocTest<ProfileBloc, ProfileState>(
      'emits [ProfileLoaded] when ProfileAccountAdded is added.',
      build: () => ProfileBloc(),
      act: (bloc) => bloc.add(ProfileAccountAdded(user)),
      expect: () => <ProfileState>[
        ProfileLoaded(
          current: user,
          accounts: [user],
        ),
      ],
    );
  });
}

Both bloc and riverpod are pretty easy to test, but I’d love a utility like bloc_test for state_notifier (not exactly a riverpod related request).

100% coverage is achievable

I’m not saying that your project must have 100% test coverage, but for me it’s a useful metric to at least determine that your project has a decent amount of tests and can also help you to see which parts of your app are not being triggered, helping you to evaluate if it’s critical to test it.

That said, I do think that if you strive for that one-hundred mark, your packages should help you do so by exposing a clean and comprehensible API that won’t stand in your way to get it.

Yes, both picks are good with that.

Unique benefits

I have to say I like these two packages because they both have something unique in their way to do state management. I love how bloc has evolved to simplify the Stream API and reactive concepts from package:rxdart. Also, I’m a big fan of how riverpod has introduced an innovative approach to dependency injection that facilitates communication between components.

I think both are robust solutions to the problems that may appear when developing apps, but I got to give bloc an advantage in this regard that comes from being built on top of the Stream API: package:bloc_concurrency.

This is the most recent addition to the bloc library and has improved the ways to handle events in our blocs by introducing EventTransformers that can apply useful behaviors to process these events.

FileBlocNew({required this.fileRepo}) : super(FileState.initial()) {
    on<LoadFiles>(
      (event, emit) => loadFiles(event, emit.call),
      // If a LoadFiles event is added while a previous LoadFiles event
      // is still processing, the previous LoadFiles event will be cancelled.
      // This is beneficial since we only care about the latest result, and
      // avoids waiting on unnecessary and possibly out of date results.
      transformer: restartable(),
    );
    on<DeleteFile>(
      (event, emit) => deleteFile(event, emit.call),
      // The default behavior of Bloc 7.2+ is to process events in parallel,
      // so we could have left out the transformer here.
      //
      // However, it is worth leaving here to indicate that the writes here
      // don't mutate the states of other files, so we can benefit from
      // concurrent processing.
      //
      // If the order of writes is important, we could have used sequential()
      // here.
      transformer: concurrent(),
    );
  }

That snippet was taken from the bloc_concurrency_demos repository. More about bloc_concurrency in my teammate Joanna’s deep dive article How to use Bloc with streams and concurrency.

Verdict

You can’t go wrong with these two state managers.

State management itself becomes a subjective matter because everyone has different needs. But if you’re thinking about a definitive tool and you know that your app can become a behemoth one day, I think the easiest way is to go with the bloc library.

It’s been around for quite some time now and has proven to be the best way to scale apps. Not to mention that is a library, conjunction of packages that provide pretty sweet functionality that most apps will need if they grow enough.

I still like riverpod as an alternative, and you can use both with my friend Frank’s package:riverbloc, which takes the reactive components and compatibility with the rest of the packages from bloc and the dependency injection used with riverpod to make a cool team-up.

Building widgets based on state

I wanted to add this small section to this article because I think sometimes is underestimated, and that’s how to structure our widgets to handle state properly.

For bloc, we can use flutter_bloc widgets to inject blocs into the widget tree and then render other widgets or even trigger actions based on their state. We’re going to focus on how to structure Bloc injection in our widgets as for riverpod we have a ProviderScope that allows us to use Providers from every widget that is below it on the widget tree.

Page-View pattern

There’s a common issue that gets open every once in a while at the Bloc GitHub repository that has to do with calling a bloc that is not on the context that is being used.

To avoid getting this issue as much as possible, there is the Page-View pattern that uses a Page widget to inject the Bloc via BlocProvider, and then use it on a View widget with a new BuildContext.

class SignUpPage extends StatelessWidget {
  const SignUpPage({Key? key}) : super(key: key);

  static Page page() => const MaterialPage<void>(child: SignUpPage());

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => SignUpBloc(),
      child: const SignUpView(),
    );
  }
}

class SignUpView extends StatelessWidget {
  const SignUpView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return BlocListener<SignUpBloc, SignUpState>(
      listener: (context, state) {
        if (state.complete) {
          Navigator.of(context).pushReplacement<void, void>(
            HomePage.page(),
          );
        }
      },
      child: SignUpForm(),
    );
  }
}

This pattern makes even more sense when you test your widgets. When testing SignUpPage from the snippet above, you only have to pump your page and check if the view is rendered.

void main() {
  testWidgets('renders SignUpView', (tester) async {
    await tester.pumpApp(const SignUpPage());
    expect(find.byType(SignUpView), findsOneWidget);
  });
}

Then, to test the view, you only need to inject a bloc and mock its state to comply with your test’s expectations.

class MockSignUpBloc extends MockBloc<SignUpEvent, SignUpState>
    implements SignUpBloc {}

void main() {
  testWidgets(
    'navigates to HomePage when SignUpState is complete',
    (tester) async {
      const user = User(
        email: 'me@marcossevilla.dev',
        name: 'Marcos',
        biography: "I'm a software engineer",
        pin: '0123',
      );

      final signUpBloc = MockSignUpBloc();

      whenListen(
        signUpBloc,
        Stream.fromIterable([SignUpState(user: user, complete: true)]),
        initialState: SignUpState(user: user),
      );

      await tester.pumpApp(
        BlocProvider<SignUpBloc>.value(
          value: signUpBloc,
          child: const SignUpView(),
        ),
      );
      await tester.pumpAndSettle();

      expect(find.byType(HomePage), findsOneWidget);
    },
  );
}

💡 This pattern forces us to scope our blocs so that they are created right above the “branch” of the widget tree that consumes their state. For example, we have the SignUpBloc scoped to the sign-up feature, not globally created for every part of the tree.

Widget reusability

At last, I want to talk about how to reuse widgets. I’ll probably create a more in-depth article about widget structure and maybe throw some atomic design in the mix, but in the meantime, I’ll give you this short explanation on how to create widgets based on state.

The first question that should come to our minds before creating a widget should be “Am I going to reuse this widget in another part of our app?”

Once we answered that, we can define which widgets are going to be sent to the widgets folder on our feature or to our app component package, if you like to extract the components you reuse in various features.

Then, I suggest you apply the same principle of the bloc injection and maintain your state as the closest parent to the widget that is going to consume it. For example:

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return BlocBuilder(
      builder: (context, count) {
        return Scaffold(
          appBar: AppBar(title: const Text('Counter')),
          body: Center(
            child: Text(
              '$count',
              style: Theme.of(context).textTheme.headline1,
            ),
          ),
          floatingActionButton: Column(
            crossAxisAlignment: CrossAxisAlignment.end,
            mainAxisAlignment: MainAxisAlignment.end,
            children: <Widget>[
              FloatingActionButton(
                child: const Icon(Icons.add),
                onPressed: () => context.read<CounterBloc>().add(Increment()),
              ),
              const SizedBox(height: 4),
              FloatingActionButton(
                child: const Icon(Icons.remove),
                onPressed: () => context.read<CounterBloc>().add(Decrement()),
              ),
              const SizedBox(height: 4),
              FloatingActionButton(
                child: const Icon(Icons.brightness_6),
                onPressed: () => context.read<ThemeCubit>().toggleTheme(),
              ),
            ],
          ),
        );
      },
    );
  }
}

This widget has a BlocBuilder as root widget and just consumes the state on the Text widget located at the body of the Scaffold. Neither the AppBar nor the FloatingActionButton consumes this state, so it can be better organized like this:

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Counter')),
      body: Center(
        child: BlocBuilder<CounterBloc, int>(
          builder: (context, count) {
            return Text(
              '$count',
              style: Theme.of(context).textTheme.headline1,
            );
          },
        ),
      ),
      floatingActionButton: Column(
        crossAxisAlignment: CrossAxisAlignment.end,
        mainAxisAlignment: MainAxisAlignment.end,
        children: <Widget>[
          // buttons...
        ],
      ),
    );
  }
}

In case we want additional functionality to our Text widget, we can do two things. We’re going to reset the counter if we tap on an IconButton right below the count.

class CountDisplay extends StatelessWidget {
  const CountDisplay({
    Key? key,
    required this.count,
  }) : super(key: key);

  final int count;

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Text(
          '$count',
          style: Theme.of(context).textTheme.headline1,
        ),
        IconButton(
          icon: const Icon(Icons.restore),
          onPressed: () => context.read<CounterBloc>().add(Reset()),
        ),
      ],
    );
  }
}

But if we want to reuse this widget with the same IconButton but different functionality, I’d suggest decoupling it from the CounterBloc reset event and parametrize that interaction this way:

class CountDisplay extends StatelessWidget {
  const CountDisplay({
    Key? key,
    required this.count,
    this.onRestore,
  }) : super(key: key);

  final int count;
  final VoidCallback? onRestore;

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Text(
          '$count',
          style: Theme.of(context).textTheme.headline1,
        ),
        IconButton(
          icon: const Icon(Icons.restore),
          onPressed: onRestore,
        ),
      ],
    );
  }
}

Wrap-up

Thanks for completing this series with me! I appreciate all the love people have been giving to these articles, from comments to questions of when the next one was coming out.

I know the last two were a bit late and maybe they won’t feel like part of the same series as the others because my opinions about architecture have changed over this past year, but CleanScope is still a strong option if you want to follow clean architecture as close as possible.

I’ll write another article about architecture and what CleanScope taught me about it down the road, explaining where it succeed and where there was room for improvement.

All I can say is, keep on learning about architecture, it’s a broad topic that requires knowledge on many subtopics as you saw during this series. Remember that if you follow the SOLID principles and the dependency rule, you are most likely to have a robust architecture!

Thanks to my friend Elian for his help on volumes 2 and 5, he put a lot of effort into those and I’m humbled to have him as a writing partner for the whole Cleaner Flutter initiative!

In the first volume, I used an analogy to express how I like to think about projects, apps, and software in general: LEGOs. Those small blocks can fit together to form a bigger structure, more importantly, having the possibility to take one block and reuse it for another structure that we can build later. Talking about efficiency here.

A project can grow unexpectedly and that brings us the popular scalability problem. But how can we plan against it?

Yes, you guessed, dividing and conquering. By splitting our code into small pieces, we can affect fewer parts of our code at the same time when maintaining it. It makes even more sense when we want to isolate one component in an environment that only mocks its dependencies to test expected behaviors atomically.

Identify dependencies

Ok, now that we mentioned dependencies, let’s talk about them.

Now that we have our architecture, we need to follow its patterns. As we already know, we have our domain layer which has repository contracts, and then the data layer that implements those contracts.

Each one of these layers is a dependency on our app. In our app, we have two parts of our architecture that we will cover in the next volume of this series, but for now, we’ve seen data and domain. The data layer is a dependency of the repository layer and can be configured on the app to be used in the domain layer by our repository.

Usually, Dart packages and Flutter plugins are data sources that should be dependencies of our repository in the domain layer, so we don’t need to create a separate package to handle the data layer. But in some cases, the direct use of a package/plugin it’s not enough abstraction to be a dependency for our repository, that’s why we create data sources or API packages. You can see an example of the latter in the flutter_todos example on the bloc library.

In that same example, we can see that abstracting our data layer can allow us to create different implementations of it, an aspect that we remarked on volume 7.

💡 One thing to note is that the abstraction of these dependencies varies depending on the project, sometimes using a package or plugin as a repository dependency can be enough abstraction depending on what we want to do.

What is dependency injection

But first, what is dependency injection? This explanation from freeCodeCamp.com works for us:

So, transferring the task of creating the object to someone else and directly using the dependency is called dependency injection.

Translating... It’s a technique (like Kamehameha) that is based on recognizing a class dependency and not creating it inside that class but instead receiving that class as a property that is created and provided from another source.

See this:

class Foo {
  final bar = Bar();

  void doAnything() {
    bar.doSomething();
  }
}

class Bar {
  void doSomething() {}
}

In this case, Foo depends on Bar, and to use it, it creates an object inside itself to later use one of its methods. We recognize Bar as a dependency of Foo, but Foo it's not following dependency injection.

A pattern to follow

Let’s fix the previous approach by defining an adequate pattern for our code.

class Foo {
  Foo({required this.bar});

  final Bar bar;

  void doAnything() {
    bar.doSomething();
  }
}

class Bar {
  void doSomething() {}
}

Yup, that looks better.

If we ask for our dependency on the object’s constructor, we can give it an instance created in another part of our code and comply with the DI pattern.

This is especially useful when testing our class, that way, we can create a mock instance of our dependency and set up specific behavior to test if our class behaves the way we want to based on the behavior we define.

But still, this can be improved.

You are probably wondering, what’s wrong with that approach?

void main() {
  final foo = Foo(bar: Bar());

  foo.bar.doSomething();
}

Oh no, that doesn’t look good. Our bar property is public, so we can access its methods without using foo explicitly!

We can fix it by making our property private:

class Foo {
  Foo({required Bar bar}) : _bar = bar;

  final Bar _bar;

  void doAnything() {
    _bar.doSomething();
  }
}

class Bar {
  void doSomething() {}
}

void main() {
  final foo = Foo(bar: Bar());

  foo.doAnything();
}

This way, we define a variable of type Bar in our constructor’s scope and then assign its value to our private variable.

Here’s another tip: if you want to have a fallback instance for your dependency and not make it required in your constructor, you can define the constructor instance as nullable.

class Foo {
  Foo({Bar? bar}) : _bar = bar ?? Bar();

  final Bar _bar;

  void doAnything() {
    _bar.doSomething();
  }
}

class Bar {
  void doSomething() {}
}

void main() {
  final foo = Foo();

  foo.doAnything();
}

This will allow you to instantiate your Foo object without passing an instance of Bar. This comes in handy when your dependency doesn’t need any configuration and can be used with its default behavior.

One thing to take into consideration with this last tip is that some of your dependencies will require an explicit instance configured for your class, like a data source that depends on a Dio object (see Better HTTP with Dio) and we assume that object already has a base URL. We can require a new instance to force ourselves to pass an object with that already defined.

And before we move on, please don’t do this...

class Foo {
  Foo(this._bar);

  final Bar _bar;

  void doAnything() {
    _bar.doSomething();
  }
}

class Bar {
  void doSomething() {}
}

You straight-up can’t use named parameters with this approach, and that can be a problem if your class needs to support more dependencies and you want to have a clean API. Just, don’t.

Ways of injection in our apps

There are already different alternatives to implement dependency injection in our apps. As we mentioned on Riverpod: Rewriting Provider, most of the packages that need DI to solve problems like state management (which is DI + reactive state components) use package:provider.

Other alternatives use the service locator pattern, like package:get_it. But as we selected package:riverpod and package:bloc as the two state management alternatives to use in our architecture, we will explain briefly how they implement dependency injection.

How Provider does it

To implement DI, package:flutter_bloc has widgets that use package:provider to inject blocs in our widget tree. That’s by using a Flutter widget called InheritedWidget, which allows us to provide properties to its children.

You can check how to use BlocProvider and dependency injection with bloc on the official documentation.

How Riverpod does it

Aiming to improve the way we do DI with provider, riverpod has a unique way to inject dependencies in our apps, I talk more about that on Riverpod: Rewriting Provider.

What to import in our app

If there’s no configuration for our data layer, we want to import only our repository to the app. This happens when the dependency our repository relies on can create an internal instance without us providing one as I mentioned previously.

That said, if you can create your repository in your app without injecting dependencies, you should only import your repository package and any models or functionality from the data source you may need. Like this:

library todos_repository;

// Here you export your repository and 
// the `Todo` model from your API.
export 'package:todos_api/todos_api.dart' show Todo;
export 'src/todos_repository.dart';

On the other hand, if you need to initialize a data source/API dependency when creating your repository in the app project, then feel free to also import that package into your app.

Flutter's most popular state management tool is package:provider. Ok, maybe there's another one I'm not recommending nor mentioning, but provider it's probably the one that most state management packages use or take inspiration from. At the time I'm writing this, 396 packages depend on provider according to pub.dev.

I'm not going to talk much about provider because I already made a clarification that I consider important in my article on state_notifier. That article is a must-read since it clarifies quite what provider is and it is one of the packages that riverpod incorporates.

But... what is riverpod and why do I like it so much?

Cause

In the state_notifier article, I explained that Provider was a tool that allows us to easily use InheritedWidget, which is the class in Flutter that gives access to its properties to its children in the widget tree.

provider itself has some problems because of this relationship with InheritedWidget.

First, doesn't allow us to create two Providers of the same type unless they are on a different subtree. If we have a class from which we want to create two separate objects to handle similar logic in different modules of the app, it's impossible for us because an InheritedWidget is found in the tree looking for a specific data type --or class--.

This also causes Providers not to be found and leaves us runtime errors that could be avoided in the compilation. Strike one.

Then combining Providers can be cumbersome, more complex than it should, and throw unexpected errors from the same unusual InheritedWidget manipulation. The common way to make a Provider aware of changes in another to react in its logic is by using a ProxyProvider or ChangeNotifierProxyProvider and yet these aren't the best alternatives in synchronization or syntax (it gets very nested). You can make hacky workarounds for this but I'm not into that.

They are a dependency injection and not exactly a listener for events. Strike two.

Finally: depending on InheritedWidget, it depends on Flutter. Which isn't the best if you like to encapsulate your business logic in a separate package and maintain a separation of concerns with your logic independent of the SDK of the user interface.

Strike three... well, not necessarily, but do you see that there are many opportunities for improvement?

Effect

All these problems made the creator of provider, Rémi Rousselet, have the initiative to re-engineer InheritedWidget from scratch, thus creating package:riverpod.

In simple words, riverpod doesn't depend on Flutter so it doesn't depend on InheritedWidget, it allows us to combine Providers to listen to and react to its changes and it guarantees us reliable code from the compilation stage.

Yes, it solves provider's problems, and very well if you ask me.

Let's see it in action and its equivalents with respect to Provider.

Which package do I use

If you do a search in pub.dev, you will find 3 versions of riverpod, let me explain what each one does.

• package:riverpod: Contains the core functionality to use it without depending on Flutter. This is the one to use if you are creating a package for a business logic layer other than the graphical interface.

• package:flutter_riverpod: Contains the core, plus all the classes and widgets used to link the logic with the user interface, depending on Flutter. It's the one that you must use if your project already needs Flutter and you are not separating the logic in another package outside the project. It's the most common because of how projects are usually organized.

• package:hooks_riverpod: Contains the core and adds the necessary functionality to be used in conjunction with package:flutter_hooks, which must also be added as a dependency. It's the one you should use if your project uses hooks to simplify your code in the user interface and Riverpod to access the state. I'm not going to go too deep into this package in this article.

And if it wasn't clear, this image is in the documentation to make it more clear:

Migrating from Provider to Riverpod

From MultiProvider to ProviderScope

Initially, when we wanted to insert a Provider in the widget tree, we did something like this:

void main() {
  runApp(
    MultiProvider(
      providers: [
        Provider(create: (_) => MyProvider()),
      ],
      child: MyApp(),
    ),
  );
}

Here we could have a list of our Providers and it depended on the MultiProvider, a single Provider or ChangeNotifierProvider. This way gave us a scope that determined wherein our widget tree we would be able to use our logic component.

In riverpod, our Providers can be used as global variables that we can also consume in a global scope called ProviderScope and this scope can be overwritten as necessary in the tree.

void main() {
  runApp(
    ProviderScope(
      child: MyApp(),
    ),
  );
}

New way to create Providers

Once our ProviderScope is declared, we can use any Provider below it. Now let's see how we make a Provider.

In the case of provider, we create a class that inherits from ChangeNotifier, StateNotifier, a repository or service class of its own. riverpod comes with StateNotifier by default, so it's easier to implement this alternative, same way there are more types of Providers than we will talk about in a moment.

class NamesNotifier extends StateNotifier<List<String>> {
  NamesNotifier([List<String>? initialNames]) : super(initialNames ?? []);

  void add(String newName) {
    state = [...state, newName];
  }
}

We can use this NamesNotifier both in provider and riverpod because the logic components are not affected by the package, which already takes care of incorporating this component into the widget tree for use.

In provider, we need to include the packages state_notifier and flutter_state_notifier. In riverpod, these are not needed since flutter_riverpod contains the ConsumerWidget (equivalent to the Consumer widget in provider but used more similar to StatelessWidget).

💡 I quickly clarify that the core of the packages is in riverpod and state_notifier, and the other packages that I mentioned that are called the same with the difference of the flutter prefix contain the widgets to communicate the logic of these packages with the user interface.

To create a Provider on riverpod, use the following:

final myProvider = Provider((ref) => MyProvider());

And to create a StateNotifierProvider in riverpod we do this:

final namesNotifierProvider = StateNotifierProvider<NamesNotifier, List<String>>((_) => NamesNotifier());

Once declared, no matter what file it's in, the Provider is in the ProviderScope and is available wherever it is needed via ProviderRef.

I want you to analyze the syntax a bit.

1. We declare them as a final variable.

2. We instance the class Provider, which contains a callback function by which we return the class.

   Note: this function will serve us much later.

3. The callback returns a variable of type ProviderRef, which we call ref, for our use in creating the Provider.

The ref variable is what would be a BuildContext for Providers in riverpod. With it, we can access other Providers in the tree and the good thing is that we can access it in the creation of any Provider.

See why it was good to separate him from Flutter? We no longer need BuildContext.

Use of Providers with Widgets

In provider, we use the BuildContext of the build method of any widget to access our Provider since it is anInheritedWidget.

We can do it in two ways...

• Use ConsumerWidget.

class WidgetToShowNames extends ConsumerWidget {
  const WidgetToShowNames({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final names = ref.watch(namesNotifierProvider);
    return ListView.builder(
      shrinkWrap: true,
      itemCount: names.length,
      itemBuilder: (_, index) {
        final name = names[index];
        return Text(name);
      },
    );
  }
}

• Use Consumer widget.

class WidgetToShowNames extends StatelessWidget {
  const WidgetToShowNames({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Consumer(
      builder: (context, ref, child) {
        final names = ref.watch(namesNotifierProvider);
        return ListView.builder(
          shrinkWrap: true,
          itemCount: names.length,
          itemBuilder: (_, index) {
            final name = names[index];
            return Text(name);
          },
        );
      },
    );
  }
}

Yes, there's a ConsumerWidget that is very similar to aStatelessWidget, but adds a WidgetRef as a parameter to the build method. This new parameter allows us to access any Provider that we create and be listening (or observing) the changes it may have.

Likewise, we can use a StatelessWidget in conjunction with the Consumer widget that works in the same way as in Provider, only that it gives us our WidgetRef instead of the type that we define since there can be multiple Providers with the same type and that no longer guarantees that we will get the value we want when sending the type.

💡 In this section of What Marcos Recommends...

I use ConsumerWidget since I don't like to nest more widgets with Consumer, the code seems much more readable to me and it is easier to find where your Providers are used having classified your widgets in StatelessWidget, StatefulWidget and ConsumerWidget.

Combining Providers

One of the solutions that riverpod brings to Provider problems is easier communication between Providers. We achieve this thanks to the ProviderRef.

The creation of a Provider gives us by default its possible combination with another that is in the reference. This is how we can inject dependencies of Providers and establish behaviors based on those changes.

final authenticateUser = FutureProvider<String>(
  (ref) async {
    await ref.read(authProvider.notifier).login();
    return ref.read(authProvider);
  },
);

final authProvider = StateNotifierProvider<AuthNotifier, String>(
  (_) => AuthNotifier(),
);

class AuthNotifier extends StateNotifier<String> {
  AuthNotifier() : super('no-token');

  Future<String> login() async {
    return await Future.delayed(
      const Duration(seconds: 3),
      () => state = 'token',
    );
  }
}

Suppose we have a Provider with authentication functionality, which we call authProvider, we use its login method that sets an access token as its state. Having the token in the state, we can use that state to call an authentication function and save the value for other queries.

What? What's that FutureProvider thing? Glad you ask...

Everything is a Provider

As you can see, there are many types of Providers, and it's a word that's going to come up everywhere if you work with riverpod.

Just like Flutter tells you to consider everything a widget in the framework, at riverpod I suggest you consider everything a Provider. A Provider can be a function (they are built with functions themselves), a state variable, a global variable (literally), and so on.

Provider types

I'm going to present to you the most common and used types of Providers so far.

• StateProvider: Exposes a value that can be modified from outside. We access the state through the state variable and we can change it. Very similar to ValueNotifier.

• FutureProvider: Constructs an asynchronous value or AsyncValue and has the operation of an ordinary Future. It's useful to load data from a service whose method to obtain this data is asynchronous.

• StreamProvider: Create and expose the last value in a Stream. Ideal for communication in real-time with Firebase or some other API whose events can be interpreted in Stream.

• StateNotifierProvider: Create a StateNotifier and expose its state. The most used for logic components, it allows easy access to state, which is usually a private property that's modified by public methods.

• ScopedProvider: Defines a Provider<T> (of a generic type) that behaves differently somewhere in the project. It's used in conjunction with the overrides property of ProviderScope and defines with the latter the scope where this ScopedProvider is going to be modified.

• ProviderFamily: This type of Provider is a modifier, that is, all of the above can use it. In itself, it defines an additional parameter that's involved in the creation of our Provider, such as a String.

final usersFamily = FutureProvider.family<User, String>(
  (ref, id) async => dio.get('https://my_api.dev/users/$id'),
);

• AutoDisposeProvider: Another modifier that allows us to automatically dispose of our Providers, allowing us to delete the state when the widgets where they are used are destroyed.

final numbersProvider = StreamProvider.autoDispose(
    (ref) {
      final streamController = StreamController<int>();

      ref.onDispose(() {
        streamController.close();
      });

      return streamController.stream;
    },
);

Best practices

How to structure Providers

riverpod has the peculiarity that, as we saw previously, it covers many use cases with different types of Providers, from app state to ephemeral state.

The problem is that there is no guide on how to structure Providers, so I always recommend separating your logic in a good way.

I summarize it in my personal rules:

• Separate project folders by functionalities (features).

• In a specific functionality I try to have a /provider folder where I have all my Providers.

• I don't have more than one logic component (StateNotifier) for functionality.

• In the provider folder, I separate my state, logic component, and Provider in separate files. You can also have a generated freezed file if you use that tool for state union classes.

With the rules that I mentioned before, we have a folder structure like this...

Some things to consider

I was thinking for a long time if there are any downsides or something to say as a warning about riverpod. Being honest and objective, I don't find many things and the ones I do find aren't critical.

riverpod is already in a stable phase, as you can see. You can implement it in your projects from now on and I dare to say that it may be a better option than provider. It's a package that can take your time to master, but once you do, it becomes a very capable tool.

I also clarify that it isn't a replacement for provider yet, since provider still solves many needs. For me, riverpod is becoming a real state management option since more developers are mastering it and the problems it solves are valued. Many have yet to find scenarios where provider shows its flaws.

In general, implementing a repository is straightforward. Since they are only a class that manages the data sources and, through them, creates a complete data flow.

In the previous volume, we saw about DataSources or DataProviders, so we are going to include them as dependencies of our repository.

class SomeRepository implements ISomeRepository {
    SomeRepository({
      required ILocalDataSource localDataSource,
      required IRemoteDataSource remoteDataSource,
    }) :  _localDataSource = localDataSource,
      _remoteDataSource = remoteDataSource;

    final ILocalDataSource _localDataSource;
    final IRemoteDataSource _remoteDataSource;
}

Our repository also implements the interface (or abstract class) repository that we made from the domain layer, overriding its methods later on.

We can also see the dependency injection pattern that I like to follow, keeping variables private and only assigning it the value of a variable declared at the constructor scope.

This way of using private variables with dependency injection limits us to using this dependency indirectly and only through the object's methods, avoiding its direct use as a property (bypassing).

Implementing methods

We are going to override the getModel method that sets our abstract repository to use our data sources and define a specific data flow.

The getModel method is in charge of fetching specific data in a list based on an ID. This method uses the remoteDataSource to query the data to a REST API and from here the flow has two possible scenarios:

1. If the API responds correctly, then the data is stored locally by the localDataSource.
2. If the API had an error, then the last locally saved value is returned. If there is no saved value, a cache error is thrown.

The code looks like this...

class SomeRepository implements ISomeRepository {
    SomeRepository({
      required ILocalDataSource localDataSource,
      required IRemoteDataSource remoteDataSource,
    }) :  _localDataSource = localDataSource,
      _remoteDataSource = remoteDataSource;

    final ILocalDataSource _localDataSource;
    final IRemoteDataSource _remoteDataSource;

    @override
    Future<SomeModel> getModel(int modelId) async {
      try {
        final model = await _remoteDataSource.getModel(modelId);
        await _localDataSource.saveModel(model);
        return model;
      } catch (e) {
        // if the API call fails...
        try {
          final model = _localDataSource.getSavedModel();
          return model;
        } catch (e) {
          throw CacheError();
        }
      }
    }
}

So we can see that our repository was an intermediary for concrete action. We are not interested in whether the data comes via HTTP or some other protocol, a data source takes care of that. Nor if it is saved in user preferences or some secure storage.

We are interested in the specific action of bringing an element, from which come different more steps of the process where several possible ways of interacting with this data converge.

Therefore, we leave interfaces or abstract classes of the DataSource so that they can be easily replaced by other implementations. That allows us to change a data source that uses the package:shared_preferences package to one that uses package:hive and does the same thing. Thus the Liskov Substitution Principle is followed.

The previous volume began with our data layer, a layer where we implement all the actions described in the domain layer to be able to interact with an external service, or a local service (some database on the device or contact with the hardware where we run).

As the title says, let's talk about where the data comes from. We already have our models where we establish what data we are going to use, now we have to go and bring them.

We call classes DataSource and they bring us the "raw" data, convert it into the respective models and pass it to their repository. But there are also other nomenclatures, as in the Bloc library, they are called DataProvider.

You can call it whatever you want, it seems to me that the name DataProvider would be better if Providers of these classes were created.

Since we don't create Providers for DataSources in riverpod, the name is enough for me.

More of this is in the article on business logic.

The source of the data

To define what a DataSource is, I'm going to borrow the concept of DataProvider from bloclibrary.dev...

They provide raw data, they should be generic and versatile. They will usually expose simple APIs to perform CRUD operations.

When I use DataSources I separate them into two folders: local and remote. This is because DataSources are a way to bring information, which as I mentioned before can be on the same device or to an external API where we have to use HTTP or some other internet protocol.

A common question is why we don't use repositories to do everything the DataSource does. Mainly because many possible actions are carried out with the data that we want to bring.

A case that happens to me quite often is that I want to save some data in a local database --my preferred option is hive-- and I bring the data from a REST API. The save-to-device action and the API call action are two different functions. In addition to being two actions that are executed in two different data sources.

Given the above, my repository is in charge of establishing this flow with two different data sources and is in charge of handling the data returned by various data sources and subsequently communicating that result to the business logic.

Implementing a DataSource

LocalDataSource

import 'dart:convert';

import 'package:hive/hive.dart' show Box;

abstract class ILocalDataSource {
  SomeModel getSomeModel();
  Future<void> saveSomeModel(SomeModel model);
}

class LocalDataSource implements ILocalDataSource {
  LocalDataSource({required Box box}) : _box = box;

  final Box _box;

  @override
  SomeModel getSomeModel() {
    try {
      final encodedJson = _box.get('model_key');
      final model = SomeModel.fromJson(json.decode(encodedJson));
      return model;
    } catch (_) {
      throw CacheException();
    }
  }

  @override
  Future<void> saveSomeModel(SomeModel model) async {
    try {
      await _box.put('model_key', json.encode(model.toJson()));
    } catch (_) {
      throw CacheException();
    }
  }
}

This is what a DataSource looks like locally. I reuse this structure to store unique values in a Box, which is the equivalent of a table in SQL.

I always recommend that every class that you are going to test make an abstract class, so it is easier for them to make their mocks with packages like mocktail.

In the same way, define the dependencies that you are going to use as properties of the class to only provide you with an object with which you can perform the actions you need. We will see this last point in more detail in the RemoteDataSource.

RemoteDataSource

import 'package:dio/dio.dart';

abstract class IRemoteDataSource {
  Future<SomeModel> getModel(int modelId);
}

class RemoteDataSource implements IRemoteDataSource {
  RemoteDataSource({
    required Dio client
  }) : _client = client;

  final Dio _client;

  @override
  Future<SomeModel> getModel(int modelId) async {
    try {
      final response = await _client.get('/models/$modelId/');
      if (response.statusCode != 200) throw ServerException();
      return SomeModel.fromJson(response.data);
    } catch (e) {
      throw ServerException();
    }
  }  
}

Some packages make it much easier for us to structure our code and package:dio is one of them. If you want to learn more about dio, check here.

It is a very similar structure to the LocalDataSource. We have a dependency injection pattern where we still define dependencies as properties and pass an instance to our private property. All equal.

The difference lies in the implementation of how we get the data, one accesses the database with hive and the other goes to a remote API to take this data through dio (HTTP).

Other implementations

For both types of DataSources, we can have different implementations so we make an interface that we can implement and define the body of the methods that we are going to use.

import 'package:http/http.dart' show Client;

class AnotherRemoteDataSource implements IRemoteDataSource {
  AnotherRemoteDataSource({
    required Uri url,
    required Client client,
  })   : _url = url,
        _client = client;

  final Uri _url;
  final Client _client;

  @override
  Future<SomeModel> getModel() async {
    try {
      final result = await _client.get(_url);
      if (response.statusCode != 200) throw ServerException();
      final decode = json.decode(result.body);
      return SomeModel.fromJson(decode);
    } catch (e) {
      throw ServerException();
    }
  }
}

This other implementation uses Dart's official http package and we can see that the result will be the same, only with a different way of doing it with another package.

There are 2 great advantages that package:dio offers us compared to HTTP. One is decoding our response from a pure JSON string to a Dart Map <String, dynamic>. We'll look at the other one in the next section.

Reusing code

As you have seen from previous articles, CleanScope focuses on developing a project based on specific features. By abstracting our data logic into DataSources and Repositories we can arrive at a structure that, combined with dio, is very organized.

The following example is following how the creation of our data layer to be used as a dependency for our project would look like using flutter_bloc:

void main() {
  final localDataSource = LocalDataSource(box: Box());
  final remoteDataSource = RemoteDataSource(
    client: Dio(BaseOptions(AppConfig.apiUrl)),
  );

  final someRepository = SomeRepository(
    localDataSource: localDataSource,
    remoteDataSource: remoteDataSource,
  );

  runApp(App(someRepository: someRepository));
}

class App extends StatelessWidget {
  const App({required this.someRepository});

  final SomeRepository someRepository;

  @override
  Widget build(BuildContext context) {
    return RepositoryProvider.value(
      value: someRepository,
      child: const AppView(),
    );
  }
}

In the following article, we are going to go into detail about what the repository already implemented looks like, but for the moment we know that it receives its 2 DataSources as properties.

dio allows us to reuse instances of its clients with specific configurations so that we make direct calls to endpoints without specifying a base URL. This operation can be seen in the GET of the RemoteDataSource that I built previously with dio:

final response = await _client.get('/models/$modelId/');

That's one of the ways our DataSources are best used.

To achieve this in Dart, we have the official package:http. This provides us with functions and classes that fulfill what is necessary to make these HTTP calls in a simple way and without much torture.

http is characterized by being based on the Future data type for requests and can also be used on all stable platforms that Flutter supports.

With http we can make calls in a few lines as follows...

import 'package:http/http.dart' as http;

Future<void> main() async {
  final url = 'https://jsonplaceholder.typicode.com/todos/1';

  final response = await http.get(url);

  print('Response statusCode: ${response.statusCode}');
  print('Response body: ${response.body}');
}

And many examples in the community are made using http because in many cases it solves more than enough.

But not all is so easy. Sometimes we have use cases where our APIs expose us to endpoints that contain more complex functionality like uploading/downloading a file, streaming data, etc.

There are many cases where this functionality can be implemented in http but the detail is that it is not very easy to do it, here you can see an example.

Enter Dio

As always, I like to show you alternatives to the usual packages we use and show you the advantages, disadvantages and why these options are worth trying in your future developments.

package:dio is an alternative to package:http and helps us incorporate everything I was telling you about so we don't have to spend time building on top of http to develop functionality.

Its usage is very similar to http and we just need to instantiate a Dio object which would already be our HTTP client.

import 'package:dio/dio.dart';

Future<void> main() async {
  final url = 'https://jsonplaceholder.typicode.com/todos/1';

  final response = await Dio().get(url);

  print('Response statusCode: ${response.statusCode}');
  print('Response body: ${response.data}');
}

You can see that the only change I made was to change the body property of the Response in http to the data property of the Response in package:dio. The only difference between body and data is that the latter is decoded by Dio if it is a Map.

But hey, that's pretty basic, right?

Let's go with the advantages offered by this package.

BaseOptions

dio allows us to create an object with all the base configurations to interact with our API. We can inject this object as dependencies of our classes in charge of the calls to the API (or APIs).

By the way, we can define different Dio objects, as I mentioned, each one with a different configuration for specific endpoints or APIs. But let's see how this configuration is done.

import 'package:dio/dio.dart';

Future<void> main() async {
  final options = BaseOptions(
    baseUrl: 'https://jsonplaceholder.typicode.com/',
    connectTimeout: 5000,
    receiveTimeout: 3000,
    responseType: ResponseType.json,
  );

  final dio = Dio(options);

  final response = await dio.get('todos/1');

  print('Response statusCode: ${response.statusCode}');
  print('Response body: ${response.data}');
}

If you run this code, you'll notice that we can still use that Dio object to make the same request with a set of our baseUrl. So when using the get method we only need to specify the endpoint we want to access to retrieve that information.

As I said, we can create several objects that contain different BaseOptions in case they implement a microservices architecture where they can have a client for each API they use.

import 'package:dio/dio.dart';

Future<void> main() async {
  // ... previous request

  final optionsRickAndMorty = BaseOptions(
    baseUrl: 'https://rickandmortyapi.com/api',
    connectTimeout: 5000,
    receiveTimeout: 3000,
    responseType: ResponseType.json,
  );

  final dioRickAndMorty = Dio(optionsRickAndMorty);
  final ricksponse = await dioRickAndMorty.get('/episode/1');

  print('Ricksponse statusCode: ${ricksponse.statusCode}');
  print('Ricksponse episode name: ${ricksponse.data['name']}');
}

Here I make a call to another very famous API that my friends from Flutter Spain use, RickAndMortyAPI. In this case, I create another client and another configuration to call that other endpoint and I still show the information of both.

Microservices enthusiasts will highly appreciate this functionality. You can check more of the options by here.

By the way, you can see that data works identically to body when we want to access a specific property of our Response.

Concurrency

This is not a feature of dio but I would like to mention it since many do not know that it exists and it is very useful.

As you saw in the previous example, I am making 2 HTTP requests sequentially and at first glance it is fine, perhaps it would be necessary to separate these functions each one on its own so as not to have such a large main function. But another way we can organize our code is with a Future.wait.

final concurrentResponse = await Future.wait([
    dioPlaceholder.get('todos/1'),
    dioRickAndMorty.get('/episode/1'),
]);

concurrentResponse.forEach((res) => print('\n${res.data}'));

With Future.wait we can send the list of Futures or requests that we are going to make and this method returns a list of responses where we can access each one and in this case simply print it to the console.

Download files

If you have projects that require the internal use of files, they will likely require downloading some files to save on the devices that your app operates.

This can be done with http but it takes us a long time to implement from scratch. Yes, you guessed it, dio makes it easy for us like this:

import 'package:dio/dio.dart';

Future<void> main() async {
  final client = Dio();
  final url = 'https://images.unsplash.com/photo-1567026392301-672e510f3369';

  final directory = await getTemporaryDirectory();
  final fileName = '${directory.path}/downloads';

  await client.download(
    url,
    fileName,
    options: Options(headers: {HttpHeaders.acceptEncodingHeader: '*'}),
    onReceiveProgress: (received, total) {
      if (total != -1) {
        final pos = received / total * 100;
        print(pos);
      }
    },
  );
}

Analyzing how to do these downloads, we must have --as usual-- our Dio client, the url of the file we want to download, a temporary directory that we get using package:path_provider, and also a directory on the device where you save those files you download.

Then with the asynchronous download method, we have all the communication with this file hosted on a remote server. We can optionally assign additional configuration via Options, for example, an acceptEncoding that allows us to tell the server which compression algorithms for the content our client supports.

The most important thing here is that download gives us access to a callback called onReceiveProgress which gives us two integer values: received and total. The first gives us the number of bytes of the file that have been received on the device and the second is the total number of bytes of the file.

Now they can safely download files in their apps.

⚠️ If there is an error somewhere in the download, dio stops and deletes everything that was downloaded.

Upload files

Uploading files is a normal POST request with a few tweaks involved.

import 'package:dio/dio.dart';

Future<void> main() async {
  final client = Dio();
  final url = 'https://some-api.dev/';

  final directory = await getTemporaryDirectory();
  final fileName = '${directory.path}/rant_about_the_world.txt';

  final payload = FormData.fromMap({
    'user': 'marcossevilla',
    'essay': await MultipartFile.fromFile(fileName),
  });

  await client.post(
    '$url/user/new',
    data: payload,
    onSendProgress: (sent, total) {
      final progress = sent / total * 100;
      print(progress);
    },
  );
}

What we do in this part is use a file from the device, whose location we contain --additionally its name-- in fileName. And next, we form a FormData object, similar to the one used in HTML, which is capable of saving the information with a fromMap constructor, and if we want to send a file, which will usually take a moment to upload, we use the class from MultipartFile which contains an asynchronous fromFile method to upload the file.

When uploading the file, we must wait for MultipartFile to finish executing its method, so we use an await.

Likewise, the POST provides us with the two callbacks onReceiveProgress and onSendProgress that allow us to calculate percentages to display download/upload information in our graphical interface.

Bonus tips

I can't leave out my favorite topics: architecture and code structure. I'm not going to make a long article explaining how to use dio for your architectures, but how to structure a data layer based on dio.

Orienting it to a microservices architecture where we have different APIs for separate modules (or even very specific actions), I recommend separating them by API that you use. This way you can have a client for each API with whatever BaseOptions you need.

data/
    |- rick_and_morty_api/
    |- joke_api/
    |- another_api/

Now that we have our API folder, we can separate it into 2–3 main groups:

1. Models: These are the classes that represent the data that we are going to send or receive from the API.

2. Parsers: These are classes that abstract the conversion logic of the String encoded in JSON to a Dart object. This same logic could be implemented either inside the model or in a DataSource or DataProvider. They are not so necessary but many like to use them.

3. Datasources / DataProviders: They are in charge of executing the calls to the APIs through a specific client.

Our folder structure would look like this:

data/
    |- rick_and_morty_api/
        |- models/
        |- parsers/
        |- data_providers/

You are in the first year of your IT career, whichever it is, there is no discrimination here. You go to your first programming class and your teacher (let's identify him as a man) begins to explain what an algorithm is and how they exist everywhere even if they aren't noticeable with the naked eye.

Suddenly he introduces this word of "programming" and mentions to you that there are several types, styles, or as it sounds more intellectual: paradigms. He tells you that they're going to learn the structured paradigm because it's your first class. You hear that he also mentions the object-oriented paradigm, and calm down, you will see that a semester later.

There are several that he mentions that probably won't teach you in college, at least that's the way it happened to me. One of those was functional programming or the functional paradigm. This paradigm is sometimes neglected because not all languages allow it to be implemented as it should.

As the title says, this article is focused on the Dart language and also on package:oxidized. There are other packages for functionally programming in Dart but trusted sources have recommended me oxidized.

The functional paradigm

From that introduction, you can intuit that I'm not an expert in this paradigm, but we are going to focus on the basics so that you can understand the great tricks that can be achieved with it.

Functional programming has the characteristics of being declarative and also treating functions as a primitive data type, or as it sounds nicer, first-class citizens.

Those who already know Dart, know that it fits very well with these characteristics. We can send a function to a class or another function as a property or argument.

void main() {
  final greeting = (String name) {
    return 'Hi $name';
  };

  saySomething(greeting);
}

void saySomething(Function(String) message) {
  print(message('Marcos'));
}

// Hi Marcos

There we create an object that is a function and we can execute it if we pass it as an argument to another. Compatibility with the paradigm, checked.

In itself, functional programming has an origin closely linked to mathematics since it uses this scientific foundation to be able to process more computationally complex tasks thanks to the replacement of loops, which increase complexity many times, by functions that accept other functions as arguments or they return a function as a result. The latter are called higher-order functions.

Advantages

The big question is: what is the advantage of incorporating this paradigm into our code?

I would summarize: it allows us to make code more concise, it reduces the complexity when reading it by not having several control statements in it. It makes testing it much easier as we have function-specific results. The coolest thing, it can be easily combined with other paradigms.

Disadvantages

Not everything is good, there are some problems when we need a variable state since results are returned, this is where combining it with other paradigms is very useful. It can be slow when going into many recursions.

In general, it is not the best alternative for all tasks.

Oxidized

This package contains many tools that make it easy for us to incorporate functional programming into our project. We go by parts.

First, as a basis, we are going to have a Person entity to exemplify some use cases where we can use functional programming tools.

class Person {
  const Person({
    required this.age,
    required this.name,
  });

  final int age;
  final String name;
}

Result

The first class that is super useful is Result. It's an abstract class that represents success or failure, it can return the expected result of an operation or the exception it threw. For example:

Result<String, Exception> getPersonName(Person person) {
  final returnName = Random().nextBool();

  return Result.of(() {
    if (returnName) {
      return person.name;
    } else {
      throw Exception();
    }
  });
}

In this case, we define a function that returns a Result that can contain a value of String or Exception. So our function receives a Person object and based on a random value that we generate, we send a response.

If you notice, we return the name wrapped in a Result.of constructor. This operation can be seen as a try-catch block, but we can forget about handling the exception here and focus on acting upon the err case from the result.

void main() {
  final person = Person(age: 22, name: 'Marcos');

  final result = getPersonName(person);

  result.when(
    ok: (name) => print(name),
    err: (e) => print('Something went wrong... $e'),
  );
}

// Something went wrong... Exception
// Marcos

Now that we instantiate the class and pass it as an argument to our function, something interesting happens. Since our variable can adopt two possible values of Result, we have a very useful method called when that gives us access to two functions that return a data type each to perform some specific action, such as assignments or the execution of another function that needs the argument that it returns.

If that sounds a bit confusing, see when as an if-else for the two possible data types the function can return.

This class is very useful when we call a third-party API that we don't know very well to catch any unknown errors and return them in the function.

Option

Option<int> getAge(Person person) {
  final returnAge = Random().nextBool();

  if (returnAge) {
    return None();
  } else {
    return Some(person.age);
  }
}

One very similar to Result is Option. Sometimes we don't want to return two possible values, and here you will say "ah, that's a normal function" but Option allows us more than that.

First, it allows us to adapt if logic to decide what to do based on the result obtained. It can be used to return validation of the execution of some operation.

void main() {
  final me = Person(age: 22, name: 'Marcos');

  final option = getAge(me);

  option.when(
    none: () => print('None!'),
    some: (age) => print('Aha! Your age is $age'),
  );
}

// None!
// Aha! Your age is 22

We have the new classes that implement it: None and Some. None allows us to return an object that represents that the expected action cannot be performed and Some contains the value that the operation performed was expected to return.

See None as a missing value that could not be returned. This helps us to handle general errors and the composition of our code in a more expressive way.

Oh right...

Result and Option are structures that are called monads. These can be applied to data types to follow a specific sequence of steps. Like when we obtain one of two specific values and execute some action based on what we receive.

The monad types are akin to the sum types found in languages such as OCaml and Rust, as found in package:oxidized's documentation. They encourage safer code by making errors and possible null values (such as None) a necessary part of the code flow, requiring you to deal with these cases appropriately.

Closing remarks

You can go much deeper into other functional programming packages if you want. Some of them like package:dartz contains a lot of functionality that comes in handy if you are into math and categorization theories. I consider myself a bit more pragmatic, I quite like this style and I share these small tips with you because I consider it to be useful in any type of project.

Likewise, the monads that we saw have more methods that can be useful to them. They remind me a lot of the methods we have in the classes that we do with package:freezed but applied to functions --yeah, functional programming-- and their return values.

Very useful to handle different scenarios in your projects, especially possible errors or unforeseen results.

Well, finally we change layers. This time it's up to the data layer, starting with the models.

Data layer

In the domain layer, the base were entities. These defined the proper data types in the project and their essential properties.

In the data layer it happens in the same way, we must establish the types of data that we are going to manipulate in the methods that a repository (now implemented) uses when fetching data.

💡 In this volume, we're going to make a lot of reference to volume 3. If you haven't read it, here you go.

In this new layer, we have our components that already communicate directly with an external API of any type, be it Firebase, a REST API, etc.

The construction of the data layer is based on first creating the models, then we create the data sources that request data directly and finally we call a data source from the repository to return information, either in primitive data types or models.

I clarify that repositories are implementations of other abstract repositories and models are inheritors of entities (which are classes as such, not interfaces), but that does not mean that data sources are a single class.

The data sources must also have an abstract class to be able to do the same as with the repositories: be able to implement its interface with a different package without affecting any external layer and to be able to perform better tests based on the interface.

Let's get to the models.

Models

I suppose you have already defined some folders in your projects called models. Here there isn't much difference, with our entities we wanted to leave as little as possible in properties and methods because our models were going to be in charge of adding that functionality.

A very famous constructor method in Flutter and Dart is the fromJson. This constructor allows us to parse a decoded JSON to a Map and thus serialize our data when we construct the object.

This type of functionality is what a model contains since we can have multiple models that inherit from that entity and define a different behavior based on its implementation.

It also allows us to have entities that can be used regardless of whether it contacts a backend hosted in Firebase or if it is its REST API.

class StoreItem {
  StoreItem({
    required this.id,
    required this.name,
  });

  final int id;
  final String name;
}

StoreItem will be the entity we use as an example. We're going to make our models based on what this entity defines, then we first create a model for the case when it comes from an API, which we are going to name StoreItemAPIModel.

class StoreItemModel extends StoreItem {
  StoreItemModel({
    required int id,
    required String name,
    required this.isAvailable,
  }) : super(id: id, name: name);

  factory StoreItemModel.fromJson(Map<String, dynamic> json) {
    return StoreItemModel(
      id: json['id'],
      name: json['name'],
      isAvailable: json['isAvailable'],
    );
  }

  final bool isAvailable;
}

We only need to extend or inherit from StoreItem to have all our properties.

Notice that the constructor creates the parameters within itself and does not declare properties that we already defined in the entity, we only have to send these variables in the constructor to the parent class called super.

We also add an extra constructor, the popular fromJson. This constructor is the additional functionality that our model will contain for the entity.

And if we want to make another model with the same properties of our entity, it is very easy for us.

import 'package:cloud_firestore/cloud_firestore.dart';

class StoreItemModel extends StoreItem {
  StoreItemModel({
    required int id,
    required String name,
    required this.isAvailable,
  }) : super(id: id, name: name);

  factory StoreItemModel.fromJson(Map<String, dynamic> json) {
    return StoreItemModel(
      id: json['id'],
      name: json['name'],
      isAvailable: json['isAvailable'],
    );
  }

  factory StoreItemModel.fromFirestore(DocumentSnapshot snapshot) {
    return StoreItemModel.fromJson(snapshot.data() as Map<String, dynamic>);
  }

  final bool isAvailable;
}

It's the same as we do with the other one but it has different methods since it is oriented to a different service. Similarly, the isAvailable variable that we define remains only in our model, so we must declare it outside the constructor.

Another thing that we can remark from this model is that we must also implement another fromJson because it doesn't extend from our previous class and the constructors remain at the model level.

This last action can be somewhat annoying and repetitive. To use the fromJson constructor we would have to inherit from StoreItemAPIModel, but it still gets complicated when calling the other constructor. From this last paragraph, stick with the first statement and ignore the rest as it is a complete mess.

Best ways to create models

The way we saw for creating models previously it's plenty for us. But this doesn't mean that the same cannot be automated. There are two packages that I use a lot for my models and in general, any immutable class that it has (a state, for example).

Equatable + json_serializable

I'm going to talk to you about package:equatable. So far this is the package with which I make entities and, consequently, models. It allows us to create a class whose properties don't change, in addition to giving us a method that we must overwrite called props, this returns a list with the properties we want of the class. Very useful and complete.

import 'package:equatable/equatable.dart';

class StoreItemEquatable extends Equatable {
  StoreItemEquatable({
    required this.id,
    required this.name,
  });

  final int id;
  final String name;

  @override
  List<Object> get props => [id, name];
}

Once our entity is created, I suggest you combine Equatable with package:json_serializable and package:json_annotation to create your models with the fromJson constructor and thetoJson method to be able to serialize from any API that returns in JSON format.

import 'package:json_annotation/json_annotation.dart';

import 'store_item_equatable.dart';

part 'store_item_model.g.dart';

@JsonSerializable()
class StoreItemModel extends StoreItemEquatable {
  StoreItemModel({
    required int id,
    required String name,
  }) : super(id: id, name: name);

  factory StoreItemModel.fromJson(Map<String, dynamic> json) {
    return _$StoreItemModelFromJson(json);
  }

  Map<String, dynamic> toJson() => _$StoreItemModelToJson(this);
}

I remind you that json_serializable must generate the code in a file with the extension **.g.dart. To generate the code, you must run the command:

# if your project depends on the Flutter SDK
flutter pub run build_runner build

# if your project doesn't depend on the Flutter SDK, it is written in pure Dart
pub run build_runner build

Likewise, if we want to create our model for Firestore, we just extend the model we created earlier to use its fromJson constructor and that's it.

import 'package:flutter/material.dart';

import 'package:cloud_firestore/cloud_firestore.dart' show DocumentSnapshot;

import 'store_item_model.dart';

class StoreItemFirestore extends StoreItemModel {
  StoreItemFirestore({
    required int id,
    required String name,
  }) : super(id: id, name: name);

  factory StoreItemFirestore.fromFirestore(DocumentSnapshot doc) {
    return StoreItemModel.fromJson(doc.data()!);
  }
}

Although Equatable checks the essentials, and well, it doesn't include an important method of immutable classes: copyWith. For this reason, I'm going to show you the second alternative.

Freezed

To solve the problem of how long it takes to create all those constructors, package:freezed is a great option. To know more about this package, you can see my article here.

freezed includes the following:

• Immutability (copyWith included).
• Value equality.
• Unions.
• Support for json_serializable.

So we can define all the models in the same abstract class and use the methods on themselves like this...

import 'package:cloud_firestore/cloud_firestore.dart' show DocumentSnapshot;
import 'package:freezed_annotation/freezed_annotation.dart';

part 'store_item.freezed.dart';
part 'store_item.g.dart';

@freezed
class StoreItem with _$StoreItem {
  const factory StoreItem.model({
    required int id,
    required String name,
  }) = StoreItemModel;

  const factory StoreItem.firestore({
    required int id,
    required String name,
    required bool isAvailable,
  }) = StoreItemFirestore;

  factory StoreItem.fromJson(Map<String, dynamic> json) =>
      _$StoreItemFromJson(json);

  factory StoreItem.fromFirestore(DocumentSnapshot doc) {
    return StoreItemFirestore.fromJson(doc.data());
  }
}

But not everything is pretty on Freezed, do you notice the problem?

Sure, unions are great for creating all possible constructors without having to create several separate files. But this separation of classes and files is what allows us to have separate entities and models.

A freezed class cannot be a subclass of another and try to extend the functionality of a freezed class is a time investment that isn't worth it and we lose the time we saved generating the code.

Equatable or Freezed?

import 'package:models_sample/store_item.dart' as equatable;
import 'package:models_sample/store_item_model.dart' as freezed;

void main() {
  final aModel = equatable.StoreItemModel.fromJson(
    {'id': 0, 'name': 'Computer'},
  );

  final bModel = freezed.StoreItemModel.fromJson(
    {'id': 0, 'name': 'Computer'},
  );
}

It really has been a matter of personal preference since the result is very similar. But in the case of CleanScope, we prefer to use equatable for entities and models, as it allows us better abstraction and control over the code.

Equatable has the props method which is very useful in many cases. freezed has built-in the copyWith and many other methods that I detail in the article that I quoted earlier, such as the when, maybeWhen, map, maybeMap.

We love freezed we use it to generate the states for the logic in the presentation layer, but it doesn't satisfy us for the level of attraction we need in the models. It's a limitation with code generators, they take away control over your code to a certain extent.

When we finish this series of articles, we'll propose a minimalist version of CleanScope where we'll use freezed for the models as we will have fewer layers of abstraction. But that's going to be another time.

For the moment, we're sticking with equatable for our models, in conjunction with json_serializable.

💡 Note: This article was originally posted in my friend Elian's blog and has been slightly modified for this series. You can check the original here.

Hello and welcome to the last volume where we will talk about the domain layer of our Clean Architecture proposal. Last time we talked about a fundamental part: the repositories, which allow us to create the communication of our software with the outside world.

On this occasion, with the use cases we are going to achieve independence from the specific interactions of the user with the system, using use cases and thus obtain maintainable, reusable code that truly meets the needs of the business.

But before we get into technical matters, we must remember that there are 2 perspectives: a developer's and a business perspective of the product. This differentiation is a very important topic since by being clear about the objectives of the product we can develop software in a better way.

Remember that all software products should first go through a process where their requirements and the interactions of a user with the software product are defined, whether this is a login, addToShoppingCart, or processPayment.

Ok, let's get into it.

What are use cases?

In Uncle Bob's words...

The software in this layer contains the application-specific business rules. These encapsulate and implement all the use cases of the system.

I remind you that the use cases mentioned in the definition do not refer coding part or module, but to the use cases that came from de planning phase of the project.

Each event is an interaction of the user with the system and we can call this a use case. As this is also a business concept the most common way of displaying the use cases of the system is by the use case graph, which looks like this:

Taken from Use Case Tutorial for Dummies.

Here we have objects like:

• Actor: Users who interact with the system (might be another software too).
• UseCase: How the actor uses the system to fulfill some functionality.
• Relationship: The relationship between the actors and the use cases.

The example shows some use cases for a passenger at an airport. Which, as I mentioned before, is the user's interactions with the system, in this case, the logic of an airport.

In code

In my experience, I have noticed that the use case layer is usually bypassed and replaced using methods directly in the software's business logic. But when we implement it we achieve better decoupling and other advantages.

By adding the use cases layer the folder structure for the domain layer would look like this:

Complying with the principles

They end up being simpler repositories. When we create the use cases, we manage to facilitate communication with the repositories and we make sure to have better abstractions that meet the specific objective of that use case, and as we saw in previous articles, with this we comply with the single responsibility principle.

We use interfaces, not implementations. In use cases we are normally going to depend on a repository, which rather must be an interface, this way we would be complying with the Liskov substitution principle, since we could replace the repository with any other that implements the same interface and this will not affect the base logic of our use case.

Implementing in Dart

Like any of the components we've talked about throughout the series, each can be implemented in many ways. This time with the use cases we are going to use one of Dart's not very well-known features.

In Dart, there is something called callable classes. This allows us to use the instance of a class as if it were a function. To achieve this, all we have to do is implement the call method inside the class.

We get something like this:

class CallableClass {
  String call() => 'Thanks for calling!';
}

void main() {
  final callable = CallableClass();
  print(callable()); // Thanks for calling!
}

Using this Dart feature, we can create a class for each of our use cases and implement the call method with the respective functionality.

Putting the pieces together

With all the information we have, we can already see an example with all the pieces that we have carried so far: entities, repositories, and use cases.

The code is simplified to facilitate the example. I also remind you that to understand the examples you must read the previous articles. Here's the previous one.

Let's imagine a very simple case of a signIn, for this, we are going to have a user entity and a repository interface that contains a method to make the signIn using an email and password.

class User {
  const User({
    required this.email,
    required this.password,
  });

  final String email;
  final String password;
}

abstract class AuthRepositoryInterface {
  Future<User> signIn({
    required String email,
    required String password,
  });
}

This is where many developers decide not to implement the use case layer, so they call the repositories directly from the application's business logic.

But since we are using use cases, we create a SignInUser class which will be our use case. This will have a dependency on the AuthRepositoryInterface, then we implement the call method and call signIn. And so we have a use case with sole responsibility and decouple the repositories from the business logic (state manager).

class UserSignIn {
  const UserSignIn({
    required AuthRepositoryInterface authRepository,
  }) : _authRepository = authRepository;

  final AuthRepositoryInterface _authRepository;

  Future<User> call({
    required String email,
    required String password,
  }) async {
    return await _authRepository.signIn(
      email: email,
      password: password,
    );
  }
}

It doesn't matter who wins the endless battle of which is the best state management tool, since it does not matter which one we select. If we even decide to change, this does not affect our implementation at all.

This example is quite simple, but for the moment what we are trying to do is understand each of the components that are part of this Clean Architecture proposal. Later we will make examples and videos applying all the theories with production code.

If you liked Elian's content, you can find even more and keep in touch with him on his social networks:

• GitHub.
• LinkedIn.
• Twitter.
• YouTube.

So I'm not going to give you an introduction to generating code, rather we are going to know a very good tool to generate it. This tool is called freezed.

freezed comes to be a code generator for immutable classes and was created by Rémi Rousselet, who may know him more from package:provider.

Immutability

Immutable classes --as the name implies-- are classes that don't change their properties and this feature is very good for state management and for use in data models. Although you may not notice it, you surely have already used immutable classes.

Take a look at this example...

import 'package:flutter/material.dart';

void main() {
  runApp(
    MaterialApp(
      home: MyWidget(),
    ),
  );
}

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Text(
          'Build some widgets!',
          style: Theme.of(context).textTheme.headline4!.copyWith(
                color: Colors.red,
              ),
        ),
      ),
    );
  }
}

Here we can see that we access the global theme of our app, specifically the property of the textTheme or text theme. The headline4 object contains a default setting that cannot be changed, that is, it is immutable.

That's where the copyWith comes in. This method allows us to return an instance of the same class or an identical object to which we are applying the method, but with the possibility of changing one or more properties as we want.

In the previous example, it allows us to change the color of the headline4 by means ofcopyWith.

And maybe at this point, you are wondering: why do I want immutable objects if I can easily assign another value to a certain property of the object?

Yes, correct. You can do an assignment easily in this case, but the problem is that the properties are exposed and your code becomes "easy to fool" I would call it. This is used quite a bit in state management because it is much better to change state through functions and not have access to internal properties so as not to change them outside of your class.

This even goes back to the Encapsulation principle of Object-Oriented Programming, where properties must be private and accessed or modified by means of methods. However, here we don't do getters and setters, we allow access to the variables through a specific state that contains them. All this without exposing our logic component.

The last thing I mentioned is very typical of state management using StateNotifier, which I use with package:riverpod. In a moment you will understand what I am talking about, if you have not read my article about StateNotifier, I will leave it here.

Value Equality

# Dependencies to include in pubspec.yaml
dependencies:
  freezed_annotation:

dev_dependencies:
  build_runner: 
  freezed:

Leaving out a bit of immutability, Freezed not only helps you make objects immutable but also implements value equality.

If you directly compare two equal instances (in properties), when you run the program it will not return true. Look:

class SomeClass {
  SomeClass({required this.id});

  final int id;
}

void main() {
  final first = SomeClass(id: 0);
  final second = SomeClass(id: 0);

  print(first == second);
}

Run that code on DartPad and you will see that it prints false, even though both objects contain the same id and are essentially the same.

freezed overrides the equality operator (==) and the hashCode getter, that way, we can already compare two or more objects and get true. This is very useful for checks on higher-level layered objects.

We only have to create a class with the decorator @freezed from the package:freezed_annotation, so that Freezed knows that it should generate code for this class.

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user.freezed.dart';

@freezed
class User with _$User {
  factory User({required String name, required int age}) = _User;
}

Once this abstract class User is made, we make a mixin with the class that Freezed will generate. We call this generated class _$User first because we make it private with_ so that it can only be accessed from its own file and we also use$because it is a convenience to indicate this symbol so that the generated classes don't have the same name of the classes that we create.

Finally, our factory constructor ofUser is the class we would use in our code. We can create different constructors like the typical fromJson and we can also create our own methods. We will see this in serialization, meanwhile, we generate our code.

Generating the code

To generate the code we include a dependency called build_runner, which is in charge of running the code generators that are in the project. Have a reference build_runner for other times that use code generators, I didn't recommend it when we talked about FlutterGen because sometimes it can give version problems.

Leave all the dependencies that you include without a specific version, thus avoiding compatibility errors between the versions.

Anyway, the command to run in the root of the project is the following:

# if the project depends on Flutter SDK
flutter pub run build_runner build

# if the project doesn't depend on Flutter - if it's pure Dart
pub run build_runner build

Every time you make a change to your classes you will have to run one of these commands to see the changes in your generated code, in case there are errors.

As a small note, if your project uses a linter like very_good_analysis, I suggest you add these lines to your analysis_options.yaml, that way you don't have errors in your generated files:

analyzer:
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"

Serialization

Data serialization is an essential part of the models since most apps contact third-party services or custom APIs that return responses in JSON format.

We decode these JSONs thanks to the dart:convert module that is already included in Dart, but then we have the need to locate each property of the decoded map that we have left in a data model.

That's where the fromJson constructor comes into play in our classes, which allows us to translate our map into a class, we add it like this:

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user.freezed.dart';
part 'user.g.dart';

@freezed
class User with _$User {
  factory User({required String name, required int age}) = _User;

  // fromJson constructor
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

We add a new part directive that will be from the JSON serializable file, and then we add the new factory that we will have for serialization.

freezed doesn't do this serialization to JSON on its own, it needs us to include the package json_serializable thedev_dependencies from pubspec.yaml.

It can go under freezed.

I have already presented you with many of the very powerful main features that freezed has, now we are going to the last one that I think is one of the coolest that saves many lines of code.

Unions

Unions are a feature that Freezed brings to Dart from other languages like Kotlin. In Kotlin they are called sealed classes. Even the syntax that Freezed offers is very similar.

They are classes that implement a certain abstract class and include a "switch" in their parent class to define actions based on what implementation it is.

This last detail reduces the code a lot and I personally use it to define the states of my logic component. Something like this:

import 'package:freezed_annotation/freezed_annotation.dart';

part 'common_state.freezed.dart';

@freezed
class CommonState with _$CommonState {
  const factory CommonState(int value) = Data;

  const factory CommonState.loading() = Loading;

  const factory CommonState.error([String? message]) = ErrorDetails;
}

And then we can use the when ormaybeWhen methods to perform an operation based on any of those cases, like this:

const state = CommonState(42);

state.maybeWhen(
    null,
    loading: () => 'loading',
    error: (error) => '$error',
    orElse: () => 'fallback',
);

One of the most popular dependency injection and state management packages, riverpod, uses freezed to define its providers as sealed classes and is thus much easier in syntax handling widgets in Flutter that reacts to a specific state.

But as I always say, read the documentation, this is a small introduction so that you know what it is about, what you can do, and above all, lose your fear to explore it.

State management is essential in Flutter. Many confuse it with architecture or believe that architecture depends on a specific state handler. But the truth is that state management is a small part of the great architecture that a project can have.

On previous occasions I have already spoken enough on this subject, so I better leave you references to these talks that I have given:

• Flutter's Six Paths of State (yes, it's a reference to Naruto): It will help you to contemplate different alternatives to manage state in Flutter and choose the one that makes your life easier.
• Talking about State Management + Architecture: It will help you to see what role the state management of your app plays in the architecture of it and serves as a critique for Six Paths of State.

😓 The videos I'll quote or suggest you watch are in Spanish because that's my main language. So I apologize for that.

First of all, Provider

You're probably already familiar with package:provider, which isn't a state manager, but a friendlier way to use InheritedWidget. If you don't know anything about InheritedWidget, here you go.

Simply put, provider allows us to use InheritedWidgets to work with classes or more atomically, values, to handle our state. That makes it a tool for communication between widgets, or dependency injection, not for state management as such.

If at this precise moment I'm destroying the concept you had of provider, I'm accomplishing my mission. The plan is not to confuse you, it is for you to better understand why use state_notifier, which is the subject of this article. We'll get to that, calm down.

provider itself can provide you with information, just like an InheritedWidget does. But the state managers are the classes that contain the data that Provider has. Got it?

BLoC → BLoC pattern

bloc → Library to manage states implementing BLoC

flutter_bloc → package containing the widgets to integrate bloc with Flutter

I call BLoCs or business logic components to those classes. They're in charge of managing this information interacting with external data sources (an API, for example) through data access classes (services or repositories). And basically, the BLoC pattern is followed there. I also have a video talking about it here.

The classes used with Provider are usually ChangeNotifier, ValueNotifier; or some custom class that extends from these. They're classes that notify --as their names say-- to others (widgets included) that are consuming their properties (through Providers). That's the most typical and one of the simplest and most initial ways of handling state with Flutter.

I clarify, there are other packages that use provider for communication of its logic components with its user interfaces.

Some of them are package:bloc in its sibling package:flutter_bloc, and package:mobx.

The problem

The problem is not ChangeNotifier, the problem is that it depends on Flutter.

ChangeNotifier is a good alternative to create classes that serve as BLoC. But as you may know about me --if you read my other articles-- I really enjoy modularizing my code to extract my logic in other packages and making them as uncoupled as possible, that's when it's not enough for me. This is mostly because of its dependency on Flutter.

I like to create my packages separately with the least amount of dependencies possible. If I can avoid the Flutter SDK, better.

I propose this case...

🤔 I'm creating my app logic in Flutter that I can reuse with other interfaces, so I make it a package. That same logic is useful to me for another app that allows me to call Dart code directly, let's remember that Dart can be compiled into binary and that opens it up to more use cases than just apps with Flutter. I already have the logic, but I use ChangeNotifier, which makes me unnecessarily dependent on Flutter.

Hello StateNotifier

StateNotifier is another type of class that serves as a logic component and is a "reimplementation" of ValueNotifier, with the difference that it doesn't depend on Flutter.

This package with the functionality of ValueNotifier abstracted gives us the power to reuse our logic without depending on Flutter, as we wanted. Plus it has better integration with provider via package:flutter_state_notifier because both were made by the same author.

After having learned a lot about flutter_bloc and its structure, I understood how handling states as classes were much more convenient and helped to modularize your widgets based on the current state of the Bloc.

StateNotifier has a lot of things similar to Bloc, including:

• Initial state in the base constructor.
• Changes to the state through methods.

Actually, the last one is related to Cubit not Bloc.

💡 One difference is that StateNotifier assigns the state to the protected variable state (equivalent to value in ValueNotifier) and Bloc uses the Emitter class to emit a state, which uses Stream underneath.

How to use StateNotifier

1. We install the dependencies.

dependencies:
    # * if you use Provider
    provider:
    state_notifier:
    flutter_state_notifier:

    # * if you use `riverpod`, already includes `state_notifier`
    flutter_riverpod:

    # use the latest versions of these dependencies or 
    # the ones compatible with the rest of your project

1. We create the states.

abstract class UserState {}

class UserNotLogged extends UserState {}

class UserLogged extends UserState {
  UserLogged({required this.user});
  final User user;
}

1. We create our StateNotifier.

class UserStateNotifier extends StateNotifier<UserState> {
  // we create our initial state by passing it to super, just like `bloc`.
  UserStateNotifier() : super(UserNotLogged());

  // we change state assigning a new one to the state property.
  void logIn(User user) => state = UserLogged(user: user);
}

1. We inject and then consume our StateNotifier.

void main() {
  runApp(
    StateNotifierProvider<UserStateNotifier, UserState>(
      create: (_) => UserStateNotifier(),
      child: MyApp(),
    ),
  );
}

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final userState = context.watch<UserStateNotifier>();
    return Scaffold(
      body: Center(
        child: Text('${userState.runtimeType}'),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          context.read<UserStateNotifier>().logIn(User());
        },
      ),
    );
  }
}

And that's a simple example of how to start using StateNotifier instead of ChangeNotifier or ValueNotifier.

You can see that another flutter_state_notifier package is used. As well as other packages like bloc and flutter_bloc, a package with the prefix flutter is included since this is the one that contains widgets that are useful to integrate another package with your user interface. In this case, it works for us to use the StateNotifierProvider class.

Creating better states

You can see that we created an abstract state that can be used by any class through inheritance. This is a practice that I first saw in bloc, where defined events alter the current state of a Bloc. It's very good because we define in the Bloc that we're going to send a state that inherits from an abstract state, as we saw in the example.

With StateNotifier, this is excellent when passing a specific type of data (our abstract state) and assigning it as we need.

The problem with this is that it gets a bit slow and we write boilerplate code when we have several possible states. For this reason, we are including another package called package:freezed, which works amazingly with StateNotifier.

We can simplify the code with a union, it would look like this...

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user_state.freezed.dart';

@freezed
class UserState with _$UserState {
  const factory UserState(User user) = UserLogged;
  const factory UserState.notLogged() = UserNotLogged;
}

If you would like to know more about freezed to know how to autogenerate the above code and what it means, I suggest you read my article about this package here.

Goodbye ChangeNotifier and ValueNotifier?

Not really.

Rémi Rousselet, the creator of provider, state_notifier, and freezed; has maintained and created pull requests to the official Flutter repository to improve ChangeNotifier.

So it doesn't mean that StateNotifier is a successor. As usual:

It's one more option that you can choose.

I personally use StateNotifier with riverpod, the provider rewrite, and I quite like the combination as it includes it by default. Handling states much like the way flutter_bloc does seem very convenient and makes code more predictable, which is very good. All this added to the fact that the state assignment syntax is simpler and facilitates its emission.

💡 Remember to show your support with applause or reaction and share so that more people can have access to this information.

In the previous volume, we talked about entities and started looking at the domain layer. As you see in the title, we're going to continue with repositories... and we continue to make contracts. If you don't know what they are, you can see it in the previous volume.

But before we get into repositories, I want to present something that I hadn't shown you before so you can understand the Clean structure that we are implementing and compare it with some other ones.

CleanScope

This diagram can be expressed as the circles in the original Clean Architecture diagram.

We have named the architecture with all the packages and configurations of our preference: CleanScope. In the following articles, we're going to delve much more into what we like to use as tools to facilitate development since we know that there are too many options, for example in state management.

The purpose of implementing Clean is that all our layers are independent, but the only layer that has complete autonomy is the domain. This is because the domain defines both the types of data that we are going to use all around our app (entities) and the actions that are going to be carried out in our project (repositories and use cases).

The domain layer defines the general behaviors of our project, let's say all the classes that are the basics for it to work. The data layer comes to use that domain layer, implementing it in the way you want (using a specific package).

For example:

☝️ The domain layer says:

"I have to develop an API that does [x action] and [y action]"

The data layer says:

"I'm going to develop my API using Go with 4 different endpoints, one for..."

This is why we say that our data layer implements the components of the domain layer. But it is important to note that although a domain layer can serve us for different implementations of a data layer, both layers are used when we incorporate them into our presentation layer.

We are going to talk about the data and presentation layer in the following volumes, I just wanted you to observe the general flow. We will dig into the function of each component in the other layers, later. So don't worry.

Repositories

☝️ Before continuing I want to clarify that, as I said in the first volume, this is one Clean architecture implementation. You can remove and add more layers than those that I am establishing.

Pay attention to this part because you may get a bit confused here.

If you saw in the diagram, the repositories are not totally in the domain layer but are "shared" in turn with the data layer. This is not an error, let's say there are 2 types of repositories:

1. Repositories in domain layer: They are abstract classes, or contracts, and define the properties and methods that our project will need in a specific feature.
2. Repositories in the data layer: These are the implementations of the contracts that we define in the domain layer.

That's why we define...

A repository is in charge of retrieving the data to us.

But that can be abstracted a bit more. Probably in other implementations, you will see that the repository calls an API using the models, and that's fine. But there is a detail, the way it calls that external service or API can vary in implementation depending on the package that is used.

For example, I can have a repository that fetches data from an API and I can implement that with Dart's classic package:http. But it might also be that I decide to use package:dio instead of http and my code should be extensible enough to switch those implementations and have no problems.

There we see that abstracting the logic only in repositories to get the data is a bit short. And I clarify that I make this observation for when the project they are building is medium or large, it is not necessary that for each small application you abstract that much.

In CleanScope, we're going to use data sources to get our information with the package we want, but that will be another time.

abstract class IMovieRepository {
  Future<List<Movie>> getLatestMovies();
}

The method doesn't need a body, that is what its implementations take care of.

That is why we created an abstract repository class to define the methods we need to fetch the information we require. I prefix it with I to specify that it is my interface, so when I use my repository in the business logic that is in the presentation layer, it has a shorter and more expressive name.

Consider that there are developers who use the I as a prefix for the implementation and not for the interface, there is no rule for that and it is a discussion that I've had with Elian.

It seems simpler to me since I will only use the interface in my data layer and the presentation layer I will use the implementation in more places, so in that case, a shorter name suits me better.

class MovieRepository extends IMovieRepository {
  @override
  Future<List<Movie>> getLatestMovies() async {
    // Implementation...
  }
}

That's is the implementation of the repository in the data layer, roughly speaking.

Testing

Another reason why it's good to abstract the interface and not code implementation of the MovieRepository directly, is that it makes unit testing of this class much easier.

I know you probably haven't written a lot of tests in Flutter, I can't say I'm very good at it either, further the unit tests I do on my classes and functions. But it doesn't mean that it's not good to make them, conversely, if you still don't do tests (even if they are units) it's time to start.

We all know it already, but it never hurts to mention again that when we create an abstract class, we are creating a contract so that some implementation of that class complies with the established methods.

That's why by having our abstract class, we can extend from the Mock class of package:mocktail --you don't have to use this necessarily, it's only preference--, implement our interface and that our mock or test class has the methods that we set in the contract.

Like...

import 'package:test/test.dart';
import 'package:mocktail/mocktail.dart';

class MockMovieRepository extends Mock implements IMovieRepository { }

void main() {
  // Unit tests...
}

The test class is used as a dependency for a use case, a little spoiler.

And with the help of mocktail and package:test, we can test our repository to confirm that everything works as it should.

⚠️ As usually in the domain or data layer, we don't have Flutter as a dependency. That's why I use package:test, it doesn't include Flutter either and the same as the layers we're dealing with right now, they are written in pure Dart*.

*Unless you use a package that DOES have Flutter as a dependency.

Recap

I wanted to make some points clearer because the domain layer is covered relatively quickly since it's more theory and then defines all the contracts that we're going to have in the project.

We have already seen the first part of the repositories, which is to create its interface or abstract class to later be able to implement it in the data layer (second part) and incidentally, to facilitate testing.

This layering of modules is the SOLID dependency inversion principle mentioned in volume 2 of this series. We're going to use the abstractions that we're creating as domain contracts so that the implementations in the data layer can replace them by being of the same type, so to speak.

And that substitution ability of implementations to their interfaces is precisely Liskov's substitution principle, which was also covered in volume 2.

And so, my dear readers, that's how the SOLID rules are being complied within our layers and we are fully following Clean architecture.

💡 Never forget that you can implement this architecture simpler or more complex, as it suits you, we simply offer you this proposal so that you can learn the concepts and see how we put them into practice.

So go get your developer glasses and let's get our hands a little dirty.

⚠️ All the code that we're going to write in this article is pure Dart, with no dependencies on the Flutter SDK.

Domain layer

⚠️ I'm going to alternate between these two terms quite a bit in the next section so you don't get confused:

Abstract classes are the same as interfaces. In Dart, there is no keyword for creating an interface, but the abstract class does functionally the same.

Before explaining entities, I notify you that with this article we begin to explain the domain layer, which consists of the contracts that we're going to set up in our project.

We're not going to sign anything, it's an expression. I'll explain what contracts are.

We call the abstract classes, or interfaces if you come from other languages, contracts because they settle rules: properties, actions... that must be fulfilled for a specific class.

abstract class INetworkManager {
  Future<bool> get isConnected;
}

In this example, we can see an abstract class/interface that defines a network manager. This class is called a contract because any class that extends from it has to implement its methods and has access to its properties. As we can see in the following image:

Here we see that since NetworkManager doesn't implement isConnected, it throws an error. Then, NetworkManager is forced to sign a contract to implement INetworkManager.

Got it? Great. And now, why do we make contracts?

As we talked about in the previous articles, we need our code to be scalable and that means it's easy to extend. That way, having abstract classes we can make the implementations that we want of the interfaces taking into consideration different types of technologies, or in the case of Flutter, they can be different packages with a separate implementation for each one.

And in addition to all this, contracts make testing our app much easier, since we can create test classes with packages like mocktail and thus run our tests in classes that have the methods established in our contracts.

Now that we make that clear, let's go with the entities.

Entities

When you are going to start a project from scratch, which part do you code first?

In my case, I code the classes of the data that I'm going to use throughout my entire application. I consider this to be a good practice as it helps us lay down the information that will flow through all of our logic.

The entities can be ordinary classes that represent abstractions of actors in real life, or something very abstract such as classes of a framework like Flutter with RenderObject.

We are not going to complicate it much.

The entities must be our data types or classes that are used in different parts of our software.

At least that's what Uncle Bob says, and it seems right to me. Although everything ends up being an entity even in the outermost layer, we define in our version of Clean that our entities are the objects that can be returned to us --or we can send to-- an API, taking the most famous example.

When we look at the models in the data layer you probably understand the usefulness of first abstracting an entity that simply defines properties and some general behaviors and then extending its functionality into models that implement more specific methods.

Let's say that an entity's purpose is to define the essential characteristics of an object. The specific features are implemented by the model because the models are in charge of being used for specific use cases.

That's a lot specific.

The code would be like this:

class Response {
  const Response({required this.message});

  final String message;
}

Response states the properties that every API response must have. These are simple responses to simplify the example, I know that not all answers in an API will return what this class has. Let me finish.

class ResponseModel extends Response {
  const ResponseModel({
    required String message,
  }) : super(message: message);

  factory ResponseModel.fromJson(Map<String, dynamic> json) {
    return ResponseModel(message: json['message']);
  }

  Map<String, dynamic> toJson() {
    return <String, dynamic>{'message': message};
  }
}

Now that we have our contract, we can create a model that "signs" it, basically I mean implement or extend it. I say to sign because by inheriting from that class we are agreeing to implement all the methods it has and comply with the properties it sets.

For example with ResponseModel, we create a String in the same constructor and simply pass that property to the class we are inheriting from, to fulfill that property.

class ResponseModel extends Response {
  const ResponseModel({
    required String message,
    required this.statusCode,
  }) : super(message: message);

  final int statusCode;

  factory ResponseModel.fromJson(Map<String, dynamic> json) {
    return ResponseModel(
      message: json['message'],
      statusCode: json['statusCode'],
    );
  }

  Map<String, dynamic> toJson() {
    return <String, dynamic>{
      'message': message,
      'statusCode': statusCode,
    };
  }
}

In this other example, we do the same as in the previous one, with the only difference that we add a property that is no longer the basis of our Response entity and thus we fulfill one of the characteristics that we talked about in the previous volumes: we extend the existing functionality without altering it in the process.

A valid extra point to mention is that as this is the basis of our entire graph, when we make a change at the entity level we will have errors in our models and for the same reason, in any other part that these models are used.

There we see the rule of dependency in action and how it helps us to have control of the changes in our code by the parts that depend on others.

Perhaps I have written long and hard on something very simple but I'm interested in understanding the purpose of this separation. We could easily make our models all at once with the features we consider necessary, but the code would become a bit repetitive and even messy.

I hope you have assimilated well the concepts and especially the separation into layers that we are doing to extend the functionality and order of our code.

This was the simplest part and the basis for the rest (out of the concepts), in the next volume we will continue exploring the domain layer with the repositories, I promise you that it will be a little more entertaining.

💡 Note: This article was originally posted in my friend Elian's blog and has been slightly modified for this series. You can check the original here.

After starting in the world of programming we all reach a point where we have to look back on the road and review some of the lines of code that we have written, either 1 day ago to remember an idea or years ago to review the implementation of any module of our software.

Many times in these glances at the code of the past we come across a list of problems such as:

• Having to search among many files for the answer to what we are looking for.
• Not understanding the code we wrote.
• Not understanding why we wrote the code the way we did.

These problems start when we start a project because we do not spend enough time to have a clear idea not only of what we are going to do but also of how we are going to do it.

We have to develop code imagining what would happen if I return in 2 years to review it, this ability to program clean and understandable code is essential to facilitate development, especially if you work in a team.

What are the SOLID principles?

SOLID is the acronym for a set of principles that help us develop more maintainable code that also allows easy extension without compromising code already developed.

In other words...

Write more code without damaging what already works.

We can even see them as a set of guidelines to follow.

Now we are going to explore each of the principles, which can be applied to any programming language, but I am going to cover them using Dart language since it is the language used by the Flutter framework.

Before continuing it is important to note that these were first introduced by Uncle Bob. You can see his explanation here.

S stands for Single Responsibility

A class must have one, and only one, a reason to change.

To explain this principle we can imagine a messy room, as we have all had it at some point, perhaps even now that you are reading this.

But the truth is that within this, everything has its place and everything should be in its designated place. To put the analogy aside, this principle tells us more specifically:

• A class must have a unique responsibility (applies to methods, variables, entities, etc).
• There is a place for everything and everything should be in its place.
• All the variables and methods of the class must be aligned with the objective of the class.

By following these principles, we achieve smaller and simpler classes that have unique objectives. Also, we avoid giant classes with generic properties and methods that can be redundant in development.

Let's see an example:

Let's take a look at this signUp function. This could be the method we call from our UI layer to perform the user sign-up process.

Future<User> signUp({
  required String name,
  required String email,
  required String password,
}) async {
  final isValid = name.isNotEmpty && email.isNotEmpty && password.isNotEmpty;

  if (isValid) {
    final newUser = User(
      name: name,
      email: email,
      password: password,
    );

    final userMap = newUser.toMap();

    await saveToDb(json.encode(userMap));
  }
}

In the code, we see that there is the functionality of creation, conversion to JSON, and even the call to the database that is normally an API call, so we are not fulfilling the principle.

This is one of the most common mistakes, especially in Flutter, since developers easily make the mistake of combining different things within the same class or methods.

⚠️ In other articles we will see how this applies to Clean Architecture...

Done, I got it, now... how do I apply it?

To follow the single responsibility principle correctly, we could create methods and classes with simple and unique functionalities.

In the example method signUp many things are done with different objectives, each of these functionalities could be separated into an individual class with a single objective.

Extracting logic

We could implement a class that is responsible for performing the validation, there are many ways to do this. One of them can be to use package:formz which is a Dart package that allows us to create classes for a data type and perform validations.

import 'package:formz/formz.dart';

/// Define input validation errors
enum NameInputError { empty }

/// Extend FormzInput and provide the input type and error type.
class NameInput extends FormzInput<String, NameInputError> {
  /// Call super.pure to represent an unmodified form input.
  const NameInput.pure() : super.pure('');

  /// Call super.dirty to represent a modified form input.
  const NameInput.dirty({String value = ''}) : super.dirty(value);

  /// Override validator to handle validating a given input value.
  @override
  NameInputError? validator(String value) {
    return value.isNotEmpty == true ? null : NameInputError.empty;
  }
}

Do not focus too much on the logic of the code, the important thing is to understand that now the validation is decoupled from the rest of the logic with the validator method.

Connecting dependencies

The other error is to call an API from the business logic or user interface, this would not fulfill the principle since the connection with the API is a complex functionality by itself, so it would be best to implement a class as Repository to which we pass the parameters that we are going to send and delegate the rest of the process to it.

/// Repository that handles the relationship
/// between app logic and data source or API.
class AuthRepository {
  AuthRepository({
    http.Client? client,
  }) : _client = client ?? http.Client();

  final http.Client _client;

  /// Method that makes the API call to sign-up a user.
  Future<void> signUpUser(User user) async {
    try {
      await _client.post(
        Uri.parse('https://noscope.dev/user/create'),
        body: user.toMap(),
      );
    } catch (e) {
      throw NetworkException();
    }
  }
}

This repository concept is key to meeting clean architecture standards but we can see that the principle of single responsibility is behind this whole idea.

By implementing these classes applying the principle we would achieve a simpler method compared to how we started with:

Future<void> signUp({
  required String name,
  required String password,
  required String email,
}) async {
  final newUser = User(
    email: email,
    password: password,
    name: name,
  );
  await _authRepository.signUpUser(newUser);
}

Simpler, more maintainable, and decoupled.

O stands for Open/Closed

An entity must be open to extending but closed to modify.

This principle tells us that we must extend our classes to add new code, instead of modifying the existing one.

The first time we read this it can be a bit confusing but it just is:

Don't modify what already works, just extend and add new code.

n this way, we can develop without damaging the previously tested code. To understand this principle we can see an example given by Katerina Trjchevska at LaraconEU 2018.

Let's imagine that our app has a payment module that currently only accepts debit/credit cards and PayPal as payment methods.

Future<void> pay(String paymentType) async {
  if (paymentType == 'card') {
    await _paymentRepository.payWithCard();
  } else if (paymentType == 'paypal') {
    await _paymentRepository.payWithPaypal();
  }
}

At a first glance at the code, we may think that everything is fine, but when we analyze its long-term scalability, we realize the problem.

Let's imagine that our client asks us to add a new payment method such as Alipay, gift cards, and others.

Each new payment method implies a new function and a new conditional in the pay method and we could say that this is not a problem, but if we keep adding code within the same class, we would never achieve a stable, ready for production code.

By applying the open/closed principle, we can create an abstract class PayableInterface that serves as a payment interface. In this way, each of our payment methods extends this abstract class and it can be a separate class that is not affected by modifications made to another.

abstract class PayableInterface {
  Future<void> pay();
}

class CardPayment implements PayableInterface {
  @override
  Future<void> pay() async {
    // Card payment logic.
  }
}

class PaypalPayment implements PayableInterface {
  @override
  Future<void> pay() async {
    // Paypal payment logic.
  }
}

class AliPayPayment implements PayableInterface {
  @override
  Future<void> pay() async {
    // AliPay payment logic.
  }
}

After having our payment logic implemented, we can receive a parameter with the paymentType that allows us to select the PayableInterface indicated for the transaction, and in this way we do not have to worry about how the pay method makes the payment, only to make a type of filtering so that the correct instance of the interface is used; be it Card, PayPal or Alipay.

enum PaymentType { card, payPal, aliPay }

class PaymentFactory {
  const PaymentFactory();

  PayableInterface initializePayment(PaymentType paymentType) {
    // Filter by `paymentType` and return the correct [PayableInterface].
    switch (paymentType) {
      case PaymentType.card:
        return CardPayment();
      case PaymentType.payPal:
        return PayPalPayment();
      case PaymentType.aliPay:
        return AliPayPayment();
    }
  }
}

class PaymentRepository {
  PaymentRepository({
    required PaymentFactory paymentFactory,
  }) : _paymentFactory = paymentFactory;

  final PaymentFactory _paymentFactory;

  Future<void> pay(PaymentType paymentType) async {
    // Get the respective payableInterface based on the `paymentType`.
    PayableInterface payment = _paymentFactory.initializePayment(paymentType);

    // Make payment.
    payment.pay();
  }
}

In the end, we would have a method like this where we can see that the code was reduced to only 3 lines and it is much easier to read.

It is also more scalable since if we wanted to add a new type of payment method we would only have to extend from PayableInterface and add it as an option in the filtering method.

👆 These concepts of abstractions and instances are confusing at first but throughout this series of articles and by practice they'll become simple concepts.

L stands for Liskov Substitution

We can change any concrete instance of a class with any class that implements the same interface.

The main objective of this principle is that we should always obtain the expected behavior of the code regardless of the class instance that is being used.

To be able to fulfill this principle correctly, there are 2 important parts:

• Implementation.
• Abstraction.

The first we can see in the previous example of open/closed principle when we have PayableInterface and the payment methods that implement it asCardPayment and PaypalPayment.

In the implementation of the code we see that it doesn't matter with the implementation we choose, our code should continue to work correctly, this is because both make correct implementation of the PayableInterface interface.

With this example, the idea is easy to understand but in practice, there are many times that we perform the abstraction process wrong, so we cannot truly make great use of the principle.

If you are not very familiar with concepts such as interface, implementation, and abstraction this may sound a bit complex but let's see it with a simple example.

This is one of the iconic images of the principle as it makes it easy to understand.

Let's imagine that in our code we have a class called DuckInterface.

This gives us the basic functionality of a duck: fly, swim, and quack. And we would have theRubberDuck class that implements the interface.

abstract class DuckInterface {
  void fly();
  String swim();
  String quack();
}

class RubberDuck implements DuckInterface {
  @override
  void fly() {
    throw Exception('Rubber duck cannot fly');
  }

  @override
  String quack() {
    return "Quack!!!";
  }

  @override
  String swim() {
    return "Duck Swimming";
  }
}

At a first glance, we could say that our abstraction is fine since we are using an interface that gives us the functionality we need, but the fly method does not apply to a rubber duck, imagine that our program is going to have different Animals with shared functionality such as flying and swimming, so it would not make sense to leave this method on the DuckInterface interface.

To solve this and comply with the Liskov principle, we can create more specific interfaces that allow us to reuse code, which also makes our code more maintainable.

abstract class QuackInterface {
  String quack();
}

abstract class FlyInterface {
  String fly();
}

abstract class SwimInterface {
  String swim();
}

class RubberDuck implements QuackInterface, SwimInterface {
  @override
  String quack() {
    return "Quack!!!";
  }

  @override
  String swim() {
    return "Duck Swimming";
  }
}

With this implementation, our RubberDuck class only implements the methods it needs and now, for example, if we need an animal that fulfills a specific function such as swimming, we could use any class that implements the SwimInterface interface. This is because by fulfilling the Liskov principle we can switch any declaration of an abstract class by any class that implements it.

I stands for Interface Segregation

The code should not depend on methods that it does not use.

At first, this could seem to be the simplest principle but for this very reason, in the beginning, it can even confuse us.

In the previous principles, we have seen the importance of interfaces to decouple our code.

This principle ensures that our abstractions for creating interfaces are correct since we cannot create a new instance of an interface without implementing one of the methods defined by them. The above would be violating the principle

This image shows the problem of not fulfilling this principle, we have some instances of classes that do not use all the interface methods, which lead to a dirty code and indicate bad abstraction.

It is easier to see it with the typical anima example, this is very similar to the example we saw from Liskov.

💡 At this point the examples become similar but the important thing is to see the code from another perspective.

We have an abstract class Animal that is our interface, it has 3 methods defined eat, sleep, and fly.

If we create a Bird class that implements the animal interface we don't see any problem, but what if we want to create the Dog class?

Exactly, we realize that we cannot implement the fly method because it does not apply to a dog.

We could leave it like that and avoid the time needed to restructure the code since we logically know that this would not affect our code, but this breaks the principle.

abstract class Animal {
  void eat();
  void sleep();
  void fly();
}

class Bird implements Animal {
  @override
  void eat() {}

  @override
  void sleep() {}

  @override
  void fly() {}
}

class Dog implements Animal {
  @override
  void eat() {}

  @override
  void sleep() {}

  @override
  void fly() => throw Exception('Dogs cannot fly!');
}

The mistake is made by having a bad abstraction in our class and the right thing to do is always refactor to ensure that the principles are being met.

It may take us a little longer at the moment but the results of having a clean and scalable code should always be priorities.

A solution to this could be that our Animal interface only has the methods shared by animals like eat, sleep and we create another interface for the fly method. In this way, only animals that need this method to implement its interface.

abstract class FlyInterface {
  void fly();
}

abstract class Animal {
  void eat();
  void sleep();
}

class Bird implements Animal, FlyInterface {
  @override
  void eat() {}

  @override
  void sleep() {}

  @override
  void fly() {}
}

class Dog implements Animal {
  @override
  void eat() {}

  @override
  void sleep() {}
}

D stands for Dependency Inversion

High-level modules should not depend on low-level modules. Both must depend on abstractions.

This principle tells us:

• You never have to depend on a concrete implementation of a class, only on its abstractions (interfaces).

• Same as the image presented on volume 1, we follow the rule that high-level modules should not strictly rely on low-level modules.

To understand it more simply, let's look at the example.

Nowadays, every app or software that is developed needs to communicate with the outside world. Normally this is done through code repositories that we instantiate and call from the business logic in our software.

class DataRepository {
  Future<void> logInUser() async {}

  Future<void> signUpUser() async {}
}

class BusinessLogic {
  const BusinessLogic({
    required DataRepository repository,
  }) : _repository = repository;

  final DataRepository _repository;

  Future<void> logIn() async {
    await _repository.logInUser();
  }

  Future<void> signUp() async {
    await _repository.signUpUser();
  }
}

Declaring and using a concrete class, such as the DataRepository within BusinessLogic, is a very common practice and is one of the common mistakes that make our code not very scalable. By depending on a particular instance of a class we surely know it will never be stable because you are constantly adding code to it.

To solve this problem, the principle tells us to create an interface that communicates both modules. You can even develop the whole functionality of the business logic and user interface of an app by depending on an interface that hasn't been implemented.

This also allows better communication in a team of developers because when creating an interface, everyone is clear about the objectives of the module, and from that definition, it can be verified that the SOLID principles are being met.

abstract class DataRepositoryInterface {
  Future<void> logInUser();

  Future<void> signUpUser();
}

class DataRepository extends DataRepositoryInterface {
  @override
  Future<void> logInUser() async {
    // Implementation...
  }

  @override
  Future<void> signUpUser() async {
    // Implementation...
  }
}

With this implementation, we create a DataRepositoryInterface that we can then implement inDataRepository and the magic happens inside the class that uses this functionality when we do not depend on a concrete instance but instead on an interface we could pass as parameters any concrete class that implements this interface.

It could be a local or external database and that would not affect the development, I repeat it: we do not depend on a single concrete instance, we can use any class that complies with the implementation of the interface.

And this is what allows us to fulfill the magic word of clean architecture: decoupling!

Wrap-up

I remind you that these are principles, not rules, so there is no single way to follow them, their use and compliance with the code will depend on each project since for many of these the objectives of the project are key to making decisions. Just as something within the scope of a project can be considered small it may under other requirements become something large.

If you liked Elian's content, you can find even more and keep in touch with him on his social networks:

• GitHub.
• LinkedIn.
• Twitter.
• YouTube.

If you are reading this, it may have been a long time since you wrote that little program. The world has changed, it's not like before. We have gotten into projects and experiences much more complex than our first contact with the world of software development.

Challenges

Challenges arise from complexity.

I don't know if anyone said that but it sounded cool.

One of the biggest to come out has been scalability, which in short terms is defined as the ability of a system to grow in workload without dying while trying.

Also, when a project grows, it must be reliable, meaning that we can rest assured that it will not die or at least not easily. To ensure reliability, you have to maintain code with its tests passed. In a nutshell, your code must be properly tested to ensure it works.

Finally, there is a feature that many users do not perceive since they don't see the codebase, but this says a lot about any system that has it. This is called decoupling, which is closely related to code reuse and independence of each piece of software.

We decouple so that our code is modular and we can play with it as if they were LEGO pieces that we can change in size, shape, or color as long as it fits. This way we have reusable parts and we are more productive with organized code.

I could spend a lot of time talking about how we can write better code and good practices, but we better explain Clean.

Clean is an architecture suggested by Robert C. Martin, Uncle Bob for friends. It claims to meet all of the characteristics I mentioned previously and has a ... let's call it golden rule.

The Dependency Rule

To save me complex explanations, I am going to show you a graph. Don't over-analyze it, I just want you to think about the shapes that are presented:

Ignore the words and notice that they are only circles containing smaller ones. That's the graphical representation of the dependency rule, which if paraphrased would be something like:

Dependencies go from the outside in. That said, dependencies don't know anything about the components that depend on them.

Still don't understand? Let's use the words that are there.

The circle that contains everything we can see that has the UI, let's use it in the example. Our rule says the UI depends on the Controllers but a Controller doesn't know what's in the UI. So with the other circles and those that contain them.

Once again and in another way: The small circle is used in the large circle and NOT vice versa.

I hope you understood because from now on I am going to assume that you did. If not, there is more information on Uncle Bob's Clean Coder Blog.

⚠️ Given the most basic concepts of this huge topic, I want to clarify that I'm going to focus the following volumes of this series of articles on the development of apps in Flutter with Clean since that is what I do.

Specifically for Flutter, Clean has a slightly different implementation because of how the framework works in the integration of logic and the graphical interface. We can't decouple much in this case since they are too closely related, but we can extract in two layers:

• Domain: extracts the contracts in the system (interfaces, or abstract classes in Dart).
• Data: implements the contracts and obtains the data that the system uses.

Later we will delve into the components of these layers.

A common use-case

At this point, we have already explained quite a bit of the basics that are required to understand the following articles, but I wanted to make a few last observations and conclude.

Each of the layers or circles that Clean has can work independently of its outer dependencies or the circles that contain them.

I'll give you a practical example of why's that.

Let's say we are doing a project that initially has a REST API to interact with the backend and we make all the models of our application closely linked to the JSON format. Everyone lived together in harmony, but everything changed when we were asked to switch to an API with GraphQL.

Rings a bell? Yes, it happens to the best teams. And if we don't have a good architecture, we will probably have to make that migration from scratch.

The advantage of a good architecture is that our entities allow us to implement models with their own properties based on the technology they have to implement. So that our JSON models have the same properties as GraphQL and only vary in implementation.

Oops, we haven't talked about entities yet, sorry. If something I said didn't make sense to you and left you confused, then calm down, the following volumes are coming for you to understand better.

In the meantime, let's wrap up this article.

Wrap-up

I tried to make a slightly more beginner-friendly version of the original Clean Architecture article on the Clean Coder Blog (I left the link before, but I leave it here again).

So as in that post, I will emphasize that implementing this clean architecture doesn't mean following the graph you saw before. If you search for more on the subject, you will find many more graphics that mention other aspects and that's the point, this changes depending on the project.

What you have to take into consideration is to really implement the architecture by always using the dependency rule. With that principle, we already follow the decoupling as it really should. The level of abstraction you want to implement in your code is up to you. As you become more abstract, even more layers can emerge.

I finish by saying that following this rule is very simple so I hope you do it and we will still have examples and more advice in the following articles (I have already said it a lot but it's for you to stay tuned) so that you do not suffer making and --more importantly-- maintaining good software.

DRY gives us a way to solve problems through code that applies to almost any problem. It is even a way of applying algorithms in our daily lives.

Do not repeat yourself, if you do, there is room for optimization. From a technical point of view, this principle urges us to automate a repetitive process that, at first suggests the implementation of a loop such as for or while as a solution. Or write a script that runs that action that takes us more time and effort than we would like.

There is a type of super useful tool when we're programming, the famous code-gen or code generators. They consist of a program that is incorporated into our project to run in development and create files with all the settings that would have lengthened development time.

Why?

Before getting into business, I would like to show you a typical problem where we can see the reason for these programs.

Image imageFile = Image.asset('assets/img/my_image.png');

In this case, we are declaring an image that is initialized as an asset that we loaded from the same project. To assign this asset, we must provide the path of the .png file to the method. This is not safe because we are human beings and we tend to make errors (typos) that may not be detected by a linter or compiler.

In short, code generation handles these problems as it is responsible for writing the code that we need so that we can use it and we can identify/correct errors more easily.

Now that we know that, let's use these utilities.

⚠️ Disclaimer: 95% of the time I find myself writing Dart code, so this article will be focused on how we can be more efficient when programming apps with Flutter, using code generation tools.

How?

FlutterGen is a relatively new code generator, it takes care of many of the big problems when working with local files, specifically resources that our apps use for branding (the logo, for example).

Well, a good practice is to always store the values that are used many times in the app in variables and classes.

We can move on from this:

Future callToAPI() async {
    await http.get('url_to_my_api.dev/api');
}

Future anotherCallToAPI() async {
    await http.get('url_to_my_api.dev/api/another');
}

To this:

class API {
    static const url = 'url_to_my_api.dev/api';
}

Future callToAPI() async {
    await http.get(API.url);
}

Future anotherCallToAPI() async {
    await http.get('${API.url}/other');
}

A very simple way of only accessing the url property of the API class and that way we can use the same variable in other parts of our app. It is also easier if we change the string that contains url since it would be changed in all the parts where we use it.

Setup

To use FlutterGen, we need to configure it. We have 3 options:

• Homebrew.

brew install FlutterGen/tap/fluttergen

• Pub.

dart pub global activate flutter_gen

• build_runner. With Dart's build system there are usually some versioning conflicts between packages, so let's skip that for now.

My suggestion, use Pub. You will have to update your PATH at the end of the installation, running the following command in the terminal:

export PATH ="$PATH":"$HOME/.pub-cache/bin"

Next, we must do the pubspec.yaml configuration. At this point, we must have assets included in the pubspec. Here is what you can copy and paste at the end of your file, the explanation goes in the comments.

# here goes all the config for flutter_gen
# watch out for the indentations
flutter_gen:
    # by default, the generate files are in `lib/gen/`
    # you can set other directories like `lib/src/gen` using [output]
  output: lib/src/gen/

    # if you use some linter that is line-of-code-sensitive
    # you can satisfy the lines it demands with [lineLength]
    # the default value is 80
  lineLength: 90

  # integrations are optional if you use another 3rd party
    # package, like [flutter_svg] to use .svg files like we
    # do with fonts and images
    #
    # it's important to have your integrations as project dependencies
  integrations:
    flutter_svg: true

    # you can also add color files in XML format
    # if you're reusing from an android project
  colors:
    inputs:
      - assets/color/colors.xml

Ok, that was all the configuration we had to do. Now let's see the magic.

Generation and usage

We run the command:

fluttergen -c pubspec.yaml

Taking into consideration that the path to the pubspec may vary and must be checked in the case of getting an error. If all goes well, you will have a new gen/ folder in the path you specified in the pubspec.

Now we are going to use the generated code. In the case of images, we access through Assets, until we reach the one we're going to use. Since our image becomes an Image object, then it is not necessary to wrap it in the widget, we just call the image() method:

Assets.images.background.image();

If we need text fonts, we have a class called FontFamily, where we have as properties the text strings that contain the identifiers of our fonts. We use them like this:

Text(
  'We\'re using fonts generated by FlutterGen',
  style: TextStyle(fontFamily: FontFamily.googleSans),
);

Finally, in order not to leave you without the example of the colors (in case someone uses them that way), we have a class called ColorName that allows us to access them.

Container(height: 100, width: 100, color: ColorName.justBlack);

Now we have our generated code and we know how to use it, we just have to start implementing it in our apps.

If you have any questions regarding this package, in this link you can browse the documentation and you can also check its source code in its repo from GitHub.