DEV Community: marwaMejri

Where Dart stops and Freezed starts

marwaMejri — Mon, 21 Sep 2026 18:30:24 +0000

The short version

One Note model written four ways, against a shared contract of sixteen tests:
twelve behavioural, four for JSON. Freezed with primary constructors ships
without JSON, so it cannot be scored on those four , and why is one of the
results.

	Freezed 4	Equatable	Pure Dart	Freezed + primary ctors
Lines you write	21	46	46	17
Lines generated	673	138	27	511
Lines per new field	+1	+2	+3.5	+1
Contract, 12 tests	12/12	11/12	9/12	12/12
JSON, 4 tests	4/4	4/4	2/4	won't compile

Equatable's 11/12 is a bug I planted on purpose, to see what would catch it.
Repaired, it scores 12/12 (finding 4).

The table is the cheap part. What it hides is where each one broke: one of the
four fails a test that has nothing to do with the model, one cannot even be asked
four of the questions, and the build times turned out to mean nothing, which took
seven runs to establish.

The rest of the article is about how I measured it, and what I would change in a
real project. All the code is in the repo.

Introduction

On 12 August 2026, Dart 3.13 made primary constructors stable. Freezed 4.0.0 added support for them ten days later, and 4.0.1 followed on 29 August.

Between them, they reopen a question the Dart community had parked while it waited for macros: do we still need Freezed?

Not because Freezed has deteriorated. Because Dart has improved, in several of the exact places Freezed was created to patch. In 2020 the language had no data classes and no sealed classes; Freezed filled both gaps. Dart 3.0 brought records, patterns and class modifiers. Macros were cancelled, and the team shipped smaller, targeted features instead: private named parameters in 3.12, primary constructors in 3.13.

So the language has been quietly reclaiming Freezed's territory for three years.
The question is how much of it remains.

This article doesn't answer that from changelogs. I wrote the same Note model four ways (Freezed 4, Equatable with a copyWith generator, pure Dart 3.13, and Freezed 4 with primary constructors) and measured them on what actually costs a team time: lines written, lines generated, build time, how many places you touch to add a field, and what each one breaks without telling you.

No approach won outright. What came out was a default, and the exceptions where that default stops making sense.

1. Why Freezed had to exist

What a data class is, and why Dart makes it hard

Most classes do something: a repository, a service, a controller. A data class holds something. And Dart doesn't give an ordinary class the semantics we expect from one:

class Note {
  Note(this.title);
  final String title;
}

final a = Note('Groceries');
final b = Note('Groceries');

print(a == b); // false

== defaults to identity: is this the same object? That is right for a
service and wrong for a value. It shows up fast:

final notes = {Note('Groceries'), Note('Groceries')};

print(notes.length); // 2
print(notes.contains(Note('Groceries'))); // false

So when developers say data class, they usually mean a class where four things are taken care of:

Immutable fields: the state can't change after construction.
Value-based == and hashCode: same values, considered equal.
copyWith: a new instance with one field changed.
A useful toString: contents, not Instance of 'Note'.

Kotlin has a keyword for three of them: data class generates equals,hashCode, toString and copy, while immutability still depends on val or var. Dart has never had that keyword, and still doesn't.

What that cost in 2020

In February 2020 the current release was Dart 2.7: no null safety, no records, no patterns, no class modifiers. Making that Note behave like a value meant writing every piece by hand.

class Note {
  const Note({required this.title, required this.body});

  final String title;
  final String body;

  Note copyWith({String? title, String? body}) =>
      Note(title: title ?? this.title, body: body ?? this.body);

  @override
  bool operator ==(Object other) =>
      other is Note && other.title == title && other.body == body;

  @override
  int get hashCode => Object.hash(title, body);

  @override
  String toString() => 'Note(title: $title, body: $body)';
}

Two fields, and most of the class is machinery around them. Add a field and you have to remember six places: the constructor, the declaration, copyWith, ==, hashCode, toString. Miss one and two objects that look identical behave differently.

There was a second gap, and it was worse. A screen state isn't one shape: it's loading, or loaded, or failed. Dart had no way to say "these are all of them":

abstract class NoteListState {}

class Loading extends NoteListState {}

class Success extends NoteListState {
  Success(this.notes);
  final List<Note> notes;
}

What hurt there was not the verbosity but the hierarchy being open. Anyone could add a subclass tomorrow, and nothing told you that your if (state is ...) chain was now incomplete. It compiled, and failed at runtime, on a screen you weren't looking at.

Missing data-class support cost you boilerplate. A missing closed hierarchy cost you a correctness check.

What Freezed did about it

Freezed landed in February 2020 and became the default answer to both. Describe the model once, let code generation supply the rest: the four data-class behaviours, plus unions with generated helpers, plus JSON through json_serializable.

That last part is why it spread. Freezed wasn't only a data-class generator; it became the foundation for network-backed models, where immutable state, equality, copyWith, unions and serialisation all hang off one declaration. You accepted build_runner and generated files, and never wrote the boilerplate again.

Then Dart started taking some of the work back.

2. What Dart shipped instead

Dart 3.0, May 2023

Three features, none announced as a Freezed replacement, two of which quietly turned out to be one.

sealed confines a class's direct subtypes to the library that declares it, so the analyzer knows every possible case:

sealed class NoteListState {
  const NoteListState();
}

final class Loading extends NoteListState {
  const Loading();
}

final class Success extends NoteListState {
  const Success(this.notes);
  final List<Note> notes;
}

final class Failure extends NoteListState {
  const Failure(this.message);
  final String message;
}

Patterns then let you match on it, and the analyzer checks you covered
everything:

String describe(NoteListState state) => switch (state) {
      Loading() => 'loading',
      Success(:final notes) => '${notes.length} notes',
      Failure(:final message) => 'error: $message',
    };

Remove a case and it won't compile. That pair , closed hierarchy plus exhaustive matching , is the language doing what Freezed's when did. Freezed's own documentation now points you at pattern matching first.

One piece of folklore to correct, because I repeated it myself before checking.
Freezed 3.0.0's changelog says "Removed map/when and variants". Open the file freezed 4.0.1 generates for the union in this repo and they are all still there,
moved onto an extension:

extension NoteListStatePatterns on NoteListState {
  TResult map<TResult>(...);      TResult maybeMap<TResult>(...);
  TResult when<TResult>(...);     TResult maybeWhen<TResult>(...);
  TResult? mapOrNull<TResult>(...);  TResult? whenOrNull<TResult>(...);
}

Relocated, not deleted. What changed is which one you reach for first.

Records brought structural equality, but only for the record itself:

final a = ('n1', 'Groceries', true);
final b = ('n1', 'Groceries', true);

print(a == b); // true

You can use one as a compact equality key, and variant C below does exactly that:

(String, String, bool) get _key => (id, title, pinned);

@override
bool operator ==(Object other) => other is Note && other._key == _key;

But you still write the == and hashCode yourself. Dart 3.0 gave you a
primitive for value semantics; it did not give ordinary classes value equality.

Macros, and why they matter here

Macros would have run code generation inside the compiler: no part directive, no generated file, members visible to the analyzer as you typed. The flagship experiment was @JsonCodable().

The Dart team stopped work on them on 29 January 2025. The introspection they needed regressed "incremental compilation (the first step of a hot reload)". What matters here is what the same announcement promised instead: tailored language features, rather than one mechanism that generates everything.

Primary constructors are one of those features. So the question is no longer "will macros replace Freezed", but "how much does a targeted feature take back".

The smaller pieces

Dart 3.12, May 2026 , private named parameters. Initialise a private field from a named parameter without an initialiser list:

class NoteQuota {
  const NoteQuota({required this._maxNotes});
  final int _maxNotes;
}

final quota = NoteQuota(maxNotes: 100); // public at the call site

Dart 3.13, August 2026 , primary constructors. Fields and constructor in one
declaration:

class Note({
  required final String id,
  required final String title,
  required final String body,
  final bool pinned = false,
});

A note on the word, because it collides. Freezed users often call the main const factory Note(...) = _Note; inside a Freezed class its primary constructor. That is not what Dart means. Dart's definition puts the parameters in the class header: "Primary constructors provide a concise way to declare a class's fields and its main constructor in a single line." The factory-in-the-body form is variant A below; the header form is variants C and D.
That distinction decides the whole of finding 5, and I have watched people talk past each other over it.

What primary constructors don't do: generate ==, hashCode, toString or copyWith. They don't make the class a data class, and they don't make it immutable , final or var still decides that. Bob Nystrom put it plainly on the Dart blog:

"Primary constructors don't let you do anything you can't already do in Dart.
They're just a different—hopefully better!—syntax for what you can already
express."

One constraint to know before migrating: a class with a primary constructor cannot declare another non-redirecting generative constructor. Write one and the analyzer stops you:

Classes with primary constructors can't have non-redirecting generative
constructors.

Factories are fine, so fromJson stays possible, and a redirecting one is fine too:

Note.empty() : this(id: '', title: '', body: '');

What you can't add is a constructor that initialises the fields itself.

The scoreboard

Dart has taken over the type-system and syntax problems around data models.
It has left the generated-behaviour problems where they were.

What Freezed helped with	Where it stands today
Immutable data models	`final` fields were always available; primary constructors make declarations shorter
Value equality	Still not automatic for ordinary classes; records have structural equality
Union types	Language , `sealed` classes
Exhaustive case handling	Language , patterns + exhaustive `switch`
Equality between union cases	Still nothing , `sealed` closes the hierarchy, it doesn't compare the cases
Concise fields + constructor	Language , primary constructors
`copyWith`	Still nothing native
JSON serialisation	Still outside the language , code generation, typically `json_serializable`

That's a more interesting picture than "Freezed is obsolete". Dart learned to
express more of the model. It still doesn't generate the operations around
the model. Which leaves one question:

If build_runner has to run anyway for JSON, what else is the generator
still earning its place with?

3. The same model, four ways

One Note model, six fields: id, title, body, pinned, tags,reminder. The first four are scalars. The last two are there on purpose: tags is a List<String>, where equality breaks, and reminder is a nullable you must be able to clear, which is where copyWith breaks. Without them, all four approaches look identical.

Three of the four use json_serializable, and that is deliberate. JSON makes build_runner run whatever you choose, so the question was never "generator or no generator" , it is what the generator does besides JSON. The fourth ships without JSON, and why is one of the results.

A — Freezed 4, the classic syntax

This is the Freezed style most existing codebases will recognise.

What you write:

import 'package:freezed_annotation/freezed_annotation.dart';

part 'note_a.freezed.dart';
part 'note_a.g.dart';

@freezed
abstract class Note with _$Note {
  const factory Note({
    required String id,
    required String title,
    required String body,
    @Default(false) bool pinned,
    @Default(<String>[]) List<String> tags,
    String? reminder,
  }) = _Note;

  factory Note.fromJson(Map<String, Object?> json) => _$NoteFromJson(json);
}

@freezed
sealed class NoteListState with _$NoteListState {
  const factory NoteListState.loading() = Loading;
  const factory NoteListState.success(List<Note> notes) = Success;
  const factory NoteListState.failure(String message) = Failure;
}


You get	`==`, `hashCode`, `toString`, `copyWith`, the union subclasses, JSON
You write	none of the data-class mechanics
It costs	two `part` directives, generated files, a `build_runner` step, and a declaration that points at `_Note` rather than at a class you wrote

This is the baseline. Freezed no longer competes on syntax. It competes on
how much behaviour it generates.

B — Equatable + `copy_with_extension`

Drop Freezed, keep generators for the two tedious parts: equality and copyWith.

What you write:

import 'package:copy_with_extension/copy_with_extension.dart';
import 'package:equatable/equatable.dart';
import 'package:json_annotation/json_annotation.dart';

part 'note_b.g.dart';

@CopyWith()
@JsonSerializable()
class Note extends Equatable {
  const Note({
    required this.id,
    required this.title,
    required this.body,
    this.pinned = false,
    this.tags = const [],
    this.reminder,
  });

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

  final String id;
  final String title;
  final String body;
  final bool pinned;
  final List<String> tags;
  final String? reminder;

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

  // `tags` is missing here on purpose. See finding 4.
  @override
  List<Object?> get props => [id, title, body, pinned, reminder];
}

sealed class NoteListState extends Equatable {
  const NoteListState();

  @override
  List<Object?> get props => const [];
}

final class Loading extends NoteListState {
  const Loading();
}

final class Success extends NoteListState {
  const Success(this.notes);
  final List<Note> notes;

  @override
  List<Object?> get props => [notes];
}

final class Failure extends NoteListState {
  const Failure(this.message);
  final String message;

  @override
  List<Object?> get props => [message];
}


You get	equality and `hashCode` from Equatable, `copyWith` from the generator, JSON from `json_serializable`, exhaustiveness from the language
You write	the fields, the constructor, `props`, and every class in the union
It costs	one `part` directive; both generators write into the same `.g.dart`

Look at props, because that is where the risk lives. props is the list Equatable actually compares , not your fields. So you write your fields twice:
once as fields, once in props. Nothing makes sure the two lists say the same thing. Add a field to the class, forget it in props, and equality quietly stops seeing it. That is finding 4, and it is the bug I planted in this variant on purpose.

C — Pure Dart 3.13

Drop both. The only generator left is json_serializable, because JSON is still not a language feature.

What you write:

import 'package:json_annotation/json_annotation.dart';

part 'note_c.g.dart';

@JsonSerializable()
class const Note({
  required final String id,
  required final String title,
  required final String body,
  final bool pinned = false,
  final List<String> tags = const [],
  final String? reminder,
}) {
  factory Note.fromJson(Map<String, dynamic> json) => _$NoteFromJson(json);

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

  Note copyWith({String? id, String? title, String? body, bool? pinned,
    List<String>? tags, String? reminder}) =>
      Note(
        id: id ?? this.id,
        title: title ?? this.title,
        body: body ?? this.body,
        pinned: pinned ?? this.pinned,
        tags: tags ?? this.tags,
        reminder: reminder ?? this.reminder,
      );

  (String, String, String, bool, List<String>, String?) get _key =>
      (id, title, body, pinned, tags, reminder);

  @override
  bool operator ==(Object other) => other is Note && other._key == _key;

  @override
  int get hashCode => _key.hashCode;

  @override
  String toString() => 'Note$_key';
}

sealed class NoteListState {
  const NoteListState();
}

final class Loading extends NoteListState {
  const Loading();
}

final class Success extends NoteListState {
  const Success(this.notes);
  final List<Note> notes;
}

final class Failure extends NoteListState {
  const Failure(this.message);
  final String message;
}

Two things in that code will look odd, and neither is a style choice.

It says class const, not class. A primary constructor is not const unless you ask, and if you forget, you lose const Note(...) everywhere in your app.

And @JsonSerializable() is sitting on top of a primary constructor. Nothing in json_serializable's documentation says that works. It does. Both of these are finding 7.

Now the equality, which is the part worth looking at:

(String, String, String, bool, List<String>, String?) get _key =>
    (id, title, body, pinned, tags, reminder);

Dart records compare by value: two records holding the same things are equal. So
that one line does the job of six comparisons plus a hash, and you only have to
keep one list of fields up to date.

The catch is that a record is only as good as what you put in it. Each field
still compares with its own ==. For String, int, bool, enum and
DateTime, that is exactly what you want. For a List, it is not: Dart compares
lists by identity, so two lists holding the same strings are not equal.

Our model has tags, and tags is a List. Section 4 is where that bill
arrives.


You get	the declaration from the primary constructor, equality from a language primitive, exhaustiveness from `sealed` + patterns, JSON from `json_serializable`
You write	`copyWith`, the equality delegation, `toString`, the union hierarchy
It costs	one generated file, and no dependency at all for the data-class behaviour

D — Freezed 4 with primary constructors

Keep Freezed, give it Dart 3.13's syntax. Freezed 4.0.0 added support for it:

import 'package:freezed_annotation/freezed_annotation.dart';

part 'note_d.freezed.dart';

@freezed
class const Note({
  required final String id,
  required final String title,
  required final String body,
  final bool pinned = false,
  final List<String> tags = const [],
  final String? reminder,
}) with _$Note;

@freezed
sealed class NoteListState with _$NoteListState {
  const factory NoteListState.loading() = Loading;
  const factory NoteListState.success(List<Note> notes) = Success;
  const factory NoteListState.failure(String message) = Failure;
}

No abstract, no factory, no = _Note redirection. Fields where you read them, and class const for the same reason as variant C.

There is no part 'note_d.g.dart' and no fromJson here, and that is not brevity. Adding them is what variants/note_d_json.dart does, and that file ships so you can watch it fail. Finding 5 is the sequence.

One small gain along the way: default values stop being an annotation.

@Default(false) bool pinned,   // A
final bool pinned = false,     // D

It is a plain Dart default now, so the compiler checks it against the field's type. @Default was just an annotation, and nothing checked it.

The bigger change is one word, and it does not read like a change at all.
Variant A says abstract class Note; variant D says class Note. In A you can never build a Note yourself , every note in your program is the generated _Note. In D you can. That sounds like an improvement, and finding 5 is the bill for it.


You get	`==`, `hashCode`, `toString`, `copyWith` and the union, all generated , everything A gives you except JSON
You write	none of it
It costs	the same dependency and the same generation pipeline as A, minus the serialisation A gets

Primary constructors make Freezed shorter to write. They don't make it less necessary.

You type 17 lines instead of 21. Freezed still generates the same amount of code, and still does all the work: equality, hashCode, copyWith, the union. You saved four lines of typing. You did not remove the generator, and you did not remove anything it produces.

What the four have in common, and what they don't

Strip the syntax away and the four differ on one axis only: who maintains the behaviour the class declaration does not state.

Freezed derives it from the declaration.
Equatable asks you to restate it in props.
Plain Dart asks you to write it.

That axis is the whole comparison, and reading the four files will not show it to you: all four look correct on the page. It only shows up when you run them.

4. What the numbers say

How this was measured

Four files, one per variant: same Note model, same NoteListState union, one shared test suite.

The test suite is the referee. Comparing four implementations is only fair if they do the same thing, and the suite is what decides. A variant that fails a test is not interchangeable with the others. That says more than any timing.

build_runner compiles the whole package, so only one variant sits in lib/ at a time. A script copies it in, rewrites its part directives, clears .dart_tool/build, and measures it alone. One script per variant, all in the repo.

What the tests actually check

Sixteen tests, in three files. They ask five questions.

Is equality by value? Two notes with the same content must be equal, must share a hashCode, and must collapse into one entry in a Set.
Does equality survive a collection? tags is a List<String>. Same tags must mean equal. Different tags must mean not equal.
Does copyWith do its job? Change one field and leave the rest alone. Clear a nullable field back to null , that is what reminder is for. And when nothing changed, hand back something that still equals the original.
Do the union states behave? Two identical states must be equal, and the switch over them must be exhaustive.
Does JSON survive the round trip? In both directions: did the values arrive correctly, and is what came back equal to what went out.

Three files, not one, for a practical reason: a variant that cannot compile a
file scores nothing on it. Together, one missing method would wipe out a whole
result. Apart, every variant is scored on everything it can be asked.

File	Tests	Needs
`contract_test.dart`	12	nothing , all five variants compile it
`json_in_test.dart`	2	`fromJson`
`json_out_test.dart`	2	`fromJson` and `toJson`

The one detail the whole suite rests on

Every test starts from the same helper, and it is deliberately not const:

Note build() => Note(id: 'n1', title: 'Groceries', body: 'Milk, bread');

Dart canonicalises constant objects: two identical const expressions are one
instance, not two. Make that helper const and every equality test passes by
identity without ever reaching ==. The first test in the contract proves it
instead of assuming it:

expect(identical(const Loading(), const Loading()), isTrue);

It passes on all five variants. That is why nothing in the suite is const.

The tests themselves

If you want the assertions rather than the summary, here they are.

// Two notes with the same content must be equal.
expect(build(), equals(build()));

// A Set must collapse them into one. This needs BOTH == and hashCode.
expect({build(), build()}.length, equals(1));

// Same tag list → still equal. (The collection test.)
expect(build().copyWith(tags: ['x']), equals(build().copyWith(tags: ['x'])));

// Different tag lists → must NOT be equal.
// This one catches a field left out of the equality definition.
expect(build().copyWith(tags: ['x']),
    isNot(equals(build().copyWith(tags: ['y']))));

// Set a nullable field, then try to clear it again.
final withReminder = build().copyWith(reminder: 'tomorrow');
expect(withReminder.copyWith(reminder: null).reminder, isNull);

// pinned is already false, so the copy must equal the original.
// Does copyWith hand back the same runtime type the constructor does?
expect(build().copyWith(pinned: false), equals(build()));

// Two states built the same way must be equal.
expect(Loading(), equals(Loading()));
expect(Success([build()]), equals(Success([build()])));

// The switch over the union is exhaustive , remove a case and it won't compile.
String describe(NoteListState state) => switch (state) {
      Loading() => 'loading',
      Success(:final notes) => '${notes.length} notes',
      Failure(:final message) => 'error: $message',
    };

And the JSON ones:

// json_in: is a parsed note equal to the same note built in code?
expect(parsed, equals(build()));
// json_in: did the values arrive correctly?
expect(parsed.title, 'Groceries');

// json_out: does a note survive being serialised and parsed back?
expect(Note.fromJson(build().toJson()), equals(build()));

Asking about the values and the equality is what separates "the generator is
wrong" from "the generator is fine and the equality is wrong". It turned out
to matter.

The results

Flutter 3.47.2 / Dart 3.13.2, on Windows. Six fields: four scalars, plus tags
(a List<String>) and reminder (a nullable String).

	A Freezed	B Equatable	C Pure Dart	D Freezed + primary
Hand-written lines	21	46	46	17
Generated lines	673	138	27	511
Generated files	2	1	1	1
Contract (12 tests)	12/12	11/12	9/12	12/12
JSON in (2 tests)	2/2	2/2	1/2	won't compile
JSON out (2 tests)	2/2	2/2	1/2	won't compile

Build times are not in the table. Finding 6 has all seven runs, and explains why one number for them would mislead.

About B's 11/12. That failure is a bug I planted. Put tags back into
props and B scores 12/12 and 4/4, the same as Freezed. Finding 4 is about how invisible the bug is, not about Equatable being wrong.

About the two line counts. They are not measured the same way. Hand-written excludes blank lines and comments; generated is the raw file, licence header and all. D's generated file is 511 lines raw and 261 once stripped. Read that row as an order of magnitude, not a ratio.

Two rows are worth a closer look.

D passes the entire contract. Equality, hashCode, copyWith, the union, const behaviour: all correct. Only JSON is broken, and finding 5 is why.

C's JSON is 1 out of 2, not 0. The values arrive correctly and the equality fails. Serialisation is fine; the model cannot recognise its own output.

What one more field costs you

The table above is a snapshot. What matters is what happens when a model grows,so I wrote it with four fields and with six, and halved the difference.

	A Freezed	B Equatable	C Pure Dart	D Freezed + primary
Lines added per field	+1	+2	+3.5	+1

This is the number that follows you home. Ten models with six fields each:
60 lines with Freezed, 210 with pure Dart. Build time on a four-file project tells you nothing about a real app. This does.

Two honest notes. The four-field version is not in the repo, so this is the one number you cannot re-run as published , add a seventh field and run git diff --stat to get it in reverse. And D's +1 is reasoned rather than measured, because its fromJson was removed between the two versions.

Where the lines actually are

Freezed's saving is usually credited to the union: three cases in three lines instead of one class each. Split the counts and it is the other way round.

	The model	The union	Total
A Freezed	15	6	21
C Pure Dart	32	14	46

The union costs C eight lines more. The model costs it seventeen.

So if you are going to write something by hand, write the union. The model is where the generator earns its keep.

Finding 1 — the record trick breaks on collections, silently

The record key from section 3 is elegant. It stops working the moment one field is a List.

Expected: Note:<Note(n1, Groceries, Milk, bread, false, [x], null)>
  Actual: Note:<Note(n1, Groceries, Milk, bread, false, [x], null)>

Two identical lines. The objects are not equal.

Why. Dart compares lists by identity, not by contents. ['x'] == ['x'] is false , two different objects. Put a list inside a record and the record inherits that.

Nothing warns you. It compiles, dart analyze finds no issues, and your Set fills with duplicates.

And it hides. In your own code, tags defaults to const []. Dart shares that one empty list between every note, so two notes really are equal. The suite runs clean until it reaches the first test that puts a real tag in the list.

It breaks when a note comes from JSON:

a parsed note carries the right values ..................... PASS
a parsed note equals the same note built in code ........... FAIL

The parser is fine. It writes (json['tags'] as List?)?.map(...).toList() ?? const [], so "tags": [] builds a new empty list while your default is the shared one. Two empty lists, two objects, not equal.

Now look at the ?? const []. Had the payload left tags out, you would have got the shared list back and this test would have passed. The bug depends on how your backend writes an empty array.

The fix. Compare the lists properly, with DeepCollectionEquality from package:collection. That is exactly what Freezed generates:

const DeepCollectionEquality().equals(other.tags, _this.tags)

So this is not a limit of pure Dart. It is a limit of the one-line version: a record key does not give you deep collection equality, and it fails without saying so. Fix it and you are maintaining a real == again.

Finding 2 — a hand-written union has no equality at all

The one I did not see coming, and the most consequential for Flutter.

Expected: <Instance of 'Loading'>
  Actual: <Instance of 'Loading'>

Loading has no fields. It is the emptiest class in the repository. Two of them are not equal, because in variant C nobody wrote == for the union cases. A, B and D pass: Freezed generates equality per case, Equatable derives it from props.

Read the section-3 code again:

final class Loading extends NoteListState {
  const Loading();
}

Nothing is missing on the page. That is the problem.

On a model, you call == yourself. You compare two notes, or you put them in a Set. There is a line of your code to look at.

On a state, you never call it. Your state manager does, behind your back. bloc says "emit does nothing if the state being emitted is equal to the current state".
ValueNotifier skips its notification the same way. buildWhen and listenWhen exist to compare states.

So if == always answers "different", none of that ever fires. Every emit
rebuilds the widget, even when nothing changed , and there is no line of your code to open, because the comparison happens inside the library. (That part is documented rather than measured here. What the test proves is only that two Loading objects are not equal.)

And a naive test won't catch it. Write this and it passes:

expect(const Loading(), equals(const Loading()));  // PASSES

const Loading() twice is the same object in memory, so == answers "equal" without running. The states that really break are the ones built at runtime with data in them , and those are the expensive rebuilds.

The fix. == and hashCode on each case: about fifteen lines for three cases, plus collection-aware equality on Success, for the reason finding 1 gives.

Finding 3 — the obvious `copyWith` cannot clear a nullable field

Expected: null
  Actual: 'tomorrow'

This is the failure reminder was added to catch. The expression
reminder ?? this.reminder reads an explicit null as "you passed nothing", so the old value survives.

Freezed handles it. So does copy_with_extension_gen, with a
$CopyWithPlaceholder sentinel. The hand-written version cannot tell the two cases apart at all. To fix it you have to invent a sentinel of your own.

Finding 4 — Equatable loses a field without telling you

In variant B I added tags to the class and left it out of props, on purpose.

The compiler said nothing. dart analyze said No issues found! One test caught
it:

Expected: not Note:<Note(n1, Groceries, Milk, bread, false, null)>
  Actual: Note:<Note(n1, Groceries, Milk, bread, false, null)>

Two notes with different tags, considered equal.

Now look at what the message prints. There is no tag list in it:

B:  Note(n1, Groceries, Milk, bread, false, null)
C:  Note(n1, Groceries, Milk, bread, false, [x], null)

Equatable builds toString from props too, and that is on by default in debug builds. So the field you forgot vanishes from your console as well. The object you stare at while hunting the bug is the one place it will never appear.

props is a copy of your field list, and copies go stale. Freezed derives
equality from the class itself, so it cannot.

But do not over-read B's 11/12. Put tags back and B scores 12/12 on the contract and 4/4 on JSON , the same as Freezed, on every question the suite asks. It even handles the case that breaks variant C: a note parsed from "tags": [] equals the one you built in code. Equatable compares collections by value, which its documentation never says.

So finding 4 is not "Equatable is risky". It is: Equatable is as correct as Freezed, until someone adds a field and forgets the second list.

Finding 5 — on freezed 4.0.1, a primary constructor and JSON don't mix

Who this concerns. Only Dart 3.13's primary constructors , fields in the class header, variants C and D. Variant A, the classic const factory Note(...) = _Note form, serialises perfectly: 2/2 on both JSON files. If your models look like A, skip this one.

And only JSON. Variant D passes all twelve contract tests. Equality,
copyWith, the union, const behaviour: all correct.

Freezed's documentation says a fromJson factory makes it "automatically ask json_serializable to generate all the necessary fromJson/toJson", and it documents primary constructors. It never shows the two together, and toJson: false appears nowhere in it. Versions are pinned in the repo, so a later release may close this gap.

It took three attempts to find out.

One: the documented path doesn't compile. variants/note_d_json.dart adds a fromJson factory, exactly as documented. build_runner is happy , two files, 673 generated lines. Then dart analyze returns one error:

lib/note_under_test.dart:49:13: Error: The non-abstract class 'Note' is missing
implementations for these members:
 - _$Note.toJson

lib/note_under_test.freezed.dart:27:24: Context: '_$Note.toJson' is defined here.
Map<String, dynamic> toJson();

Freezed declares toJson() on its mixin and leaves the implementation to
_Note, the subclass the classic = _Note redirection creates. A primary
constructor has no redirection, so nothing implements it. You cannot write it yourself either: the generated function is Map<String, dynamic> _$NoteToJson(_Note instance), and you are holding a Note.

All three test files fail to load at this point. A file that will not compile scores nothing.

Two: one switch fixes the compile. @Freezed(toJson: false) stops freezed declaring the member, json_serializable emits only _$NoteFromJson, and everything builds. So outbound JSON is impossible, and you have to ask for that in the annotation.

Three: what comes back is not what you built.

a parsed note carries the right values ..................... PASS
a parsed note equals the same note built in code ........... FAIL

Expected: Note:<Note(id: n1, title: Groceries, ..., tags: [], reminder: null)>
  Actual: _Note:<Note(id: n1, title: Groceries, ..., tags: [], reminder: null)>

Every field matches. Look at the type: Note against _Note. json_serializable generates _Note _$NoteFromJson(...), so a note from your API is freezed's internal subclass. And freezed's generated equality starts like this:

bool operator ==(Object other) {
  final _this = this as Note;
  return identical(this, other) ||
      (other.runtimeType == runtimeType && other is Note && ...);
}

other.runtimeType == runtimeType. A _Note fails that, and the comparison stops before reading a field. Parsing goes up the hierarchy, which is always legal , that is why the values arrive intact. Equality goes sideways, and runtimeType is not a subtype question.

Why variant A escapes. One word: abstract class Note. You cannot build a Note yourself there, so every note in your program is a _Note, including the ones your tests build. The types always match. A primary constructor makes the class concrete, and that breaks it.

Where that leaves you. On freezed 4.0.1 with json_serializable 6.14.1, a primary-constructor model can parse JSON if you disable toJson, cannot serialise at all, and what it parses will not equal what you construct. Behind an API the last one is the expensive one: put the model in a bloc state and deduplication stops working, with no error message.

The fix. Keep the classic syntax for any model that touches JSON. That is why variant D ships without it.

One number to keep. note_d_json.dart is 20 hand-written lines against variant A's 21. Had this worked, the whole benefit would have been one line.

Finding 6 — build time is not an argument at this scale

Variant A's first build took 30.4 seconds. 24 of them were
compiling builders/aot , build_runner compiling itself. About 4 went to generating code.

Then I ran it again. And again. Seven cold builds, same machine, files that never changed:

Cold build	A	B	C	D	Fastest
Run 1	30.4s	48.1s	38.3s	37.3s	A
Run 2	46.6s	31.1s	29.6s	29.6s	C / D
Run 3	77.4s	71.6s	83.7s	39.2s	D
Run 4	33.6s	32.0s	32.1s	—	B
Run 5	56.1s	48.9s	68.3s	69.9s	B
Run 6	54.3s	38.2s	46.1s	38.2s	B / D
Run 7	38.1s	83.1s	41.6s	41.9s	A

Four different winners in seven runs. But here is the number that settles it:
each variant varies with itself by a factor of about 2.5. A went from 30.4s to 77.4s. C went from 29.6s to 83.7s. The gap between variants inside one run is smaller than the gap each variant has with itself.

When the noise is bigger than the effect, you are not measuring. Run 4 says the same from the other side: quiet machine, three variants within 1.6 seconds of each other.

What does hold still: incremental builds between 1.9s and 5.1s, analysis between 1.1s and 2.8s across the four variants, no variant consistently ahead.

So there is no ranking here, and I would be suspicious of any article that reports one from a project this size. Choose on maintenance cost and on correctness. At this scale, build time separates nothing.

Finding 7 — two things to check before you migrate

json_serializable reads a primary constructor. This was an open question:
version 6.14.1 shipped on 30 July 2026, before Dart 3.13 introduced primary constructors, and its changelog never mentions them. It works anyway: a valid fromJson/toJson pair for variant C, in 27 lines, every field coming back with the right value. Whether that object is equal to one you built is finding 1's problem, not the generator's.

A primary constructor is not const by default. const Note(...) fails with "Cannot invoke a non-'const' constructor where a const expression is expected."
You ask for it either in the header , class const Note({...}), the form
dart.dev documents , or in the body, with a const new() member, the form
Bob Nystrom's post shows. Two placements, not two competing answers. I used the header one and did not test the other.

It is documented, and people still trip over it, because the default runs the opposite way from every constructor they have written before. In Flutter it costs more than style: no const, no const models, no const Loading() for your states.

5. The arbitration

Freezed clears all sixteen tests. Freezed with primary constructors clears the twelve it can be asked. Equatable clears everything once you repair the bug i planted. Pure Dart is asked all sixteen and fails five.

Here is what I would actually do:

Your model	Use
Talks to an API, holds a list, or has a nullable you must clear	Freezed, classic syntax
Only scalar fields, and no JSON	Pure Dart 3.13
Only scalar fields, but needs JSON	Freezed , `build_runner` runs either way
A union, or your screen states	`sealed`, always , plus equality from Freezed if it is already there, otherwise from Equatable

The rest of this section is why.

The default: keep Freezed

Use Freezed for any model that talks to an API, holds a collection, or has a nullable field you need to clear. In the apps I have worked on, that is most of them.

One line per field against three and a half. Equality that cannot drift from the class. The only option that answered all sixteen questions without an asterisk.

The price is 673 generated lines and a build_runner step. The measurements say that price is smaller than it feels, because the build cost is mostly build_runner starting up , and that is the same whichever approach you pick.

The exception: pure Dart, for models that stay simple

Drop Freezed when the model has only scalar fields and no nullable field you need to clear. Value objects, config holders, small internal models. There pure Dart 3.13 wins outright: 27 generated lines against 673, and no dependency at all for the data-class behaviour.

One thing to get right: pure Dart is not how you avoid JSON.
json_serializable reads a primary constructor perfectly well, which is finding

What decides it is whether build_runner has to run anyway.

The model needs JSON. build_runner runs either way, so removing Freezed saves you a dependency and nothing else , while Freezed keeps handling equality, collections and copyWith. Keep it.
The model needs no JSON. Now you remove code generation from that model entirely: no part directive, no generated file, nothing to run before it compiles, and no red squiggles when a colleague clones the repo and forgets build_runner. Worth having, and for a simple model it costs you nothing.

And to be fair to pure Dart: you can fix all three of C's failures by hand , a DeepCollectionEquality for the list, a sentinel for the nullable, == on each union case. But DeepCollectionEquality lives in package:collection, so the variant with no dependency acquires one, and 46 lines become more than 60. That is a trade, not a win.

For your states: sealed classes, or Freezed?

First, sealed is not what is being decided here. All four variants use it , Freezed generates a sealed class too. It is what gives you the closed hierarchy and the exhaustive switch, and you keep it whatever you choose. The only question is where == comes from.

A bare sealed hierarchy, nothing added, looks like the easy case for
dropping Freezed. Closed hierarchy, exhaustive switch, nothing missing on the page.

Except the cases have no equality, and that is finding 2. On a state you never call == yourself: emit, ValueNotifier and buildWhen do it for you, so there is no line of your own code to look at when it misbehaves.

In order of what I would do:

Freezed already in the project? Declare the union with Freezed. Three lines for three cases, equality generated, collection-aware on any case carrying a list.
Want no generator in your state layer? Extend Equatable on the sealed parent and list every field in props on each case. One line per case. Just remember finding 4.
By hand, only if you have a reason. Budget about fifteen lines per union, plus DeepCollectionEquality on any case holding a list.

A bare sealed hierarchy with no equality is a bug the moment your app uses bloc, a Cubit, a ValueNotifier or buildWhen. Without them it is a perfectly reasonable design. If you are not sure which one you wrote, run this:

test('states dedupe', () {
  expect(MyLoading(), equals(MyLoading()));  // no const (see section 4)
});

Equatable: correct, and twice the size

I had this one filed under "avoid" until the last run corrected me.

Equatable is not less correct than Freezed. Fill in props properly and variant B scores 12/12 on the contract and 4/4 on JSON , the same as Freezed, on every question this suite asks. It even compares collections by value, which is the exact case that breaks pure Dart's record key, and which its documentation never mentions.

So the argument against it is not behaviour. It is two other things.

Twice the code for the same result. 46 hand-written lines against Freezed's 21, two lines per new field against one , for the same build_runner step and the same generated file. You pay Freezed's price and decline Freezed's benefit.
props is a second field list. Freezed derives equality from the class, so it cannot drift. Equatable asks you to restate it, and finding 4 is what happens when the restatement falls behind.

Against pure Dart it is a real trade rather than a defeat. B and C both sit at 46 lines, but at that price C fails five of the sixteen tests and B fails one, the planted one. Bring C up to B's behaviour and it passes 60 lines. So B buys about fifteen lines back in exchange for one extra generator.

Already on Equatable and happy with it? Nothing here says migrate. For a new model, next to Freezed, it is more code for the same behaviour.

And primary constructors?

They improve how you declare a model: one line per field, fields where you read them, const available once you ask for it.

They are not a reason to leave Freezed , and "Freezed + primary constructors is broken" would be wrong too. Variant D passes the whole contract. What you lose is JSON: outbound entirely, and inbound in the sense that what you parse will not equal what you build. The saving left is one line: 20 hand-written against variant A's 21.

Used without Freezed, they shorten the declaration and leave equality and
copyWith exactly where they were.

Which is what the whole article comes down to: primary constructors shorten what you type. They do not shorten what the generator writes, and they do not replace what it does.

So, do we still need Freezed?

Less often than in 2020, and for narrower reasons.

The language took back the declaration, the union hierarchy, and the
exhaustiveness check. What it did not take back is generated behaviour: equality that follows the class without being restated , on the model and on every case of the union , a copyWith that can express null, and serialisation.

Dart moved the line. It didn't erase it.

Flutter Clean Architecture [2]: An Overview & Project Structure

marwaMejri — Tue, 13 Jun 2023 15:14:51 +0000

You can find the completed project repository here

In the initial section, we learn the fundamentals of clean architecture and set up the necessary folders to organize each layer. Now let's dive into these empty folders, starting with the Domain layer.
So let's start the party, enough talking.

Domain Layer

Entity

First, we add our entity that represents the weather data.
To determine which fields this class must have, we must examine the Weather API response. The following JSON response is returned by this API:

{
  "coord": {
    "lon": 10.637,
    "lat": 35.8254
  },
  "weather": [
    {
      "id": 801,
      "main": "Clouds",
      "description": "few clouds",
      "icon": "02d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 304.03,
    "feels_like": 307.27,
    "temp_min": 303.02,
    "temp_max": 304.03,
    "pressure": 1014,
    "humidity": 58
  },
  "visibility": 10000,
  "wind": {
    "speed": 5.66,
    "deg": 100
  },
  "clouds": {
    "all": 20
  },
  "dt": 1663066385,
  "sys": {
    "type": 1,
    "id": 1193,
    "country": "TN",
    "sunrise": 1663045105,
    "sunset": 1663090127
  },
  "timezone": 3600,
  "id": 2464915,
  "name": "Sousse",
  "cod": 200
}

Except for the coord, base, and cod fields, we are interested in the majority of the fields in this answer. As a result, our entity will resemble this:

class WeatherInfoEntity extends Equatable {
  const WeatherInfoEntity({
    this.weather,
    this.main,
    this.visibility,
    this.wind,
    this.clouds,
    this.dt,
    this.sys,
    this.timezone,
    this.id,
    this.name,
    this.weatherTheme,
  });
  final List<WeatherDescriptionEntity?>? weather;
  final MainWeatherInfoEntity? main;
  final String? visibility;
  final WindInfoEntity? wind;
  final CloudsEntity? clouds;
  final String? dt;
  final SunsetSunriseEntity? sys;
  final int? timezone;
  final int? id;
  final String? name;
  final WeatherThemeEntity? weatherTheme;

  @override
  List<Object?> get props => <Object?>[
        weather,
        main,
        visibility,
        wind,
        clouds,
        dt,
        sys,
        timezone,
        id,
        name,
        weatherTheme,
      ];
}

The WeatherInfoEntity class extends the Equatable class from the equatable plugin to allow for simple value comparisons without all the boilerplate, as Dart only supports referential equality by default. Also, if you notice that I added a new field of type WeatherThemeEntity, this field will help me specify the proper theme for a certain weather. It is not required to provide such a field, but it allows for a greater connection with the application.

class WeatherThemeEntity {

  WeatherThemeEntity({
    this.firstColor,
    this.secondColor,
  });
  Color? firstColor;
  Color? secondColor;
}

So, the WeatherThemeEntity class will have two color type fields, in which I will add a gradient background for each type of weather.

Repository & Error handling

As indicated earlier, the repository belongs to both the domain and data layers. In fact, it will be defined in the domain first and then implemented in data. This enables 100% independence of the domain layer and also helps with developing tests for the use cases without having an actual repository implementation. So, how will the repository contract look?

In our contract, we define three methods for our weather functionality: one to retrieve weather data by coordinates, another to obtain weather for a specific city, and a third to retrieve all saved weather information locally. Logically, the return types for the first two methods should be Future, and for the final method, Future>. However, error handling is also an important consideration. We have two options: allowing exceptions to propagate and handling them elsewhere, or catching exceptions early and returning an error object from the methods.

In our architecture, I have chosen the second approach. This means that any method in the repository or use case will return both the entity and failure objects, providing a clear way to handle both successful outcomes and potential errors.

So , to implement it, I used the freezed plugin to create a sealed class named *ApiResultModel * that will return either failure with an error object or success with the specific data.

sealed classes are used to represent restricted class hierarchies, where a value can have one of a restricted set's types but not another. They are also an extension of enum classes, except that an enum constant can only have one instance, but a sealed class can have several instances.

Furthermore, the freezed plugin will generate extra functionality like copyWith and toString methods, but more importantly, it will give us access to some pattern-matching syntax.

To use this plugin, you must first install the following dependencies:

  cupertino_icons: ^1.0.5
  equatable: ^2.0.5
  freezed: ^2.3.3
  get_it: ^7.6.0
  injectable: ^2.1.2
  json_annotation: ^4.7.0

Following that, I created a 'commondomain' subfolder under the 'core' folder. This 'commondomain' subfolder will further include an 'entities' subfolder. Additionally, I have introduced a 'based_api_result' subfolder intended for storing entities that will be shared across different sections of our project:

Creating the sealed class

The ApiResultModel sealed class will have two states: success and failure. The success state will return the data type specified when calling our sealed class. For example, if we want the method to return a WeatherInfoEntity on success, the return type should be ApiResultModel. When a problem occurs, the return type is an ErrorResultModel object, as defined in the failure state.

To create the two states, we employ factory constructors and include the necessary annotations and keywords. Make sure to add the '@freezed' annotation and the 'part' keyword at the top of the file so the plugin can build the methods specified previously:

part 'api_result_model.freezed.dart';

@freezed
class ApiResultModel<T> with _$ApiResultModel<T> {
  const factory ApiResultModel.success({required T data}) = Success<T>;

  const factory ApiResultModel.failure(
      {required ErrorResultModel errorResultEntity}) = Failure<T>;
}

The error object includes two attributes: one for the API error status code and one for the message:

class ErrorResultModel extends Equatable {
  const ErrorResultModel({
    this.statusCode,
    this.message,
  });

  final int? statusCode;
  final String? message;

  @override
  List<Object?> get props => <Object?>[
        statusCode,
        message,
      ];
}

Creating the repository contract with the use of the sealed class

So, in our abstract repository class, we'll have three methods: getWeatherDataByCoordinates, getWeatherDataByCity, and getAllLocalWeathers. These methods return Future>, where T is the data type:

abstract class WeatherRepository {
  Future<ApiResultModel<WeatherInfoEntity?>> getWeatherDataByCoordinates(
      {WeatherByCoordinatesRequestModel? weatherByCoordinatesRequestModel});

  Future<ApiResultModel<WeatherInfoEntity?>> getWeatherDataByCity(
      {String? cityName});

  Future<ApiResultModel<List<WeatherInfoEntity?>?>> getAllLocalWeathers();
}

Use cases & callable classes

Any use case must have the *WeatherRepository * object, which will be provided in the constructor, as we know the use case corresponds to a repository method. In light of this, we need to add three use cases to our application: one for retrieving weather data based on coordinates, one for retrieving weather data based on city, and one for obtaining all previously stored weathers from a local database.

To begin, I will add the required repository for the GetWeatherDataByCoordinates use case:

@injectable
class GetWeatherDataByCoordinates {
  GetWeatherDataByCoordinates(this.weatherRepository);

  final WeatherRepository weatherRepository;

}

Next, all that remains is to add the function that will retrieve the data from the repository:

@injectable
class GetWeatherDataByCoordinates {
  GetWeatherDataByCoordinates(this.weatherRepository);

  final WeatherRepository weatherRepository;

  Future<ApiResultModel<WeatherInfoEntity?>> getWeatherData(
      WeatherByCoordinatesRequestModel? weatherByCoordinatesRequestModel) {
    return weatherRepository.getWeatherDataByCoordinates(
        weatherByCoordinatesRequestModel: weatherByCoordinatesRequestModel);
  }
}

So far, we have made good progress on our weather app. We have created an Entity, a Repository contract, and the first use case. To complete the work at the domain layer, we only need to create the remaining two use cases.

In regards to use cases, it is important to remember that each should have a return method that interacts with the repository. It makes no difference whether the logic inside the useCase retrieves a WeatherInfoEntity or something else, the goal is the same. And to improve the solution further, we could create a base class with a method that returns a generic type that can be extended by each specific use case.

creating the base use case class

To create the base useCase class, I implemented an explicit interface (in Dart, this is an abstract class) located in the core/commondomain/usecases directory since this class can be shared across multiple features of our app:

abstract class BaseParamsUseCase<Type, Request> {
  Future<ApiResultModel<Type>> call(Request? params);
}

class NoParams extends Equatable {
  @override
  List<Object> get props => <Object>[];
}

As you can see, we added two type parameters to the BaseParamsUseCase: one represents the data type in case of success, and the Request type is for the parameters that will be passed through the use case, such as the latitude and longitude for the previous 'GetWeatherDataByCoordinates'. So, in order to implement the base class, each use case must specify the parameter Request that will be passed to the "call" method. However, if a use case does not require any parameters, we can use the NoParams class as the Request type, as in the case of 'GetAllLocalWeathers'.
The name of the 'call' method was not picked randomly. In fact, the 'call' method in the Dart programming language allows you to define a class as callable, meaning that you can use an instance of the class as if it were a function. This method is well-suited for use cases where the class names are verbs, such as 'GetWeatherDataByCoordinates'.

Extending the Base Class

Adding a use case is now very simple: each use case should implement the previous base class and override the calling method. For example, for 'GetWeatherDataByCoordinates', we implement the 'BaseParamsUseCase' with the addition of two parameters: one representing the return type of this use case and the other representing the parameters to be passed into it, which in our case is the 'WeatherByCoordinatesRequestModel', which holds the required latitude and longitude values:

class GetWeatherDataByCoordinates
    implements
        BaseParamsUseCase<WeatherInfoEntity?,
            WeatherByCoordinatesRequestModel> {
  GetWeatherDataByCoordinates(this.weatherRepository);

  final WeatherRepository weatherRepository;

  @override
  Future<ApiResultModel<WeatherInfoEntity?>> call(
      WeatherByCoordinatesRequestModel? weatherByCoordinatesRequestModel) {
    return weatherRepository.getWeatherDataByCoordinates(
        weatherByCoordinatesRequestModel: weatherByCoordinatesRequestModel);
  }
}

class WeatherByCoordinatesRequestModel {
  WeatherByCoordinatesRequestModel({
    this.lat,
    this.lon,
  });

  final double? lat;
  final double? lon;
}

The other two use cases will follow the same logic as the one previously mentioned:

@injectable
class GetWeatherDataByCity
    implements BaseParamsUseCase<WeatherInfoEntity?, String> {
  GetWeatherDataByCity(this.weatherRepository);

  final WeatherRepository weatherRepository;

  @override
  Future<ApiResultModel<WeatherInfoEntity?>> call(String? cityName) {
    return weatherRepository.getWeatherDataByCity(cityName: cityName);
  }
}

@injectable
class GetAllLocalWeathers
    implements BaseParamsUseCase<List<WeatherInfoEntity?>?, NoParams> {
  GetAllLocalWeathers(this.weatherRepository);

  final WeatherRepository weatherRepository;

  @override
  Future<ApiResultModel<List<WeatherInfoEntity?>?>> call(NoParams? params) {
    return weatherRepository.getAllLocalWeathers();

  }
}

Next up

In the next part, we will start working on the data layer containing the Repository implementation and Data Sources: Next

Flutter Clean Architecture [3]: An Overview & Project Structure

marwaMejri — Tue, 13 Jun 2023 15:14:30 +0000

You can find the completed project repository here

In the previous section, we exposed the secure center layer of our app, which operates independently of other layers. Now, let's explore how our app interacts with the outside world, including APIs and third-party libraries.

Data Layer

The data layer is composed of repositories, data sources, and models. The repositories are classes that can interact with zero or some data sources in order to expose the data to the rest of the app, while the data sources, as the name implies, are in charge of giving the app the data it needs to perform a function. They can represent data from a variety of sources, including the network, a local database, files, and even memory.

Each data source function should produce a model that captures the information that was retrieved from a particular source. The model is actually an entity with some extra functionality on top of it. In our case, we'll add to/from JSON functions to each model in order to convert it to Dart objects.

Implementing the Models

The model file will be located in the data/models folder:

Each model represents the API data, as was already mentioned. However, we also know that each interface of the app will interact with entities to create its UI, so what should we do?

I came up with an abstract class called DataMapper whose main role is to map a model into the desired entity. This class will be shared among all app models and will be located within the 'core/utils/mapper' folder:

abstract class DataMapper<Type> {
  Type mapToEntity();
}

The DataMapper class, as we can see, only has one function that returns the entity Type. To map the appropriate entity, each model will now extend this class and override the mapToEntity function.

Creating the model class with the use of the data mapper class

So, under data/models/weather_info_remote_response_model, I created a new class called WeatherInfoResponseModel to represent the weather data:

class WeatherInfoResponseModel extends DataMapper<WeatherInfoEntity> {
  WeatherInfoResponseModel(
      {this.coordinateData,
      this.weatherDescription,
      this.mainWeatherData,
      this.weatherVisibility,
      this.windData,
      this.cloudsData,
      this.date,
      this.sunsetAndSunriseData,
      this.timezone,
      this.id,
      this.cityName,
     });
  CoordinateResponseModel? coordinateData;
  List<WeatherDescriptionResponseModel>? weatherDescription;
  MainWeatherInfoResponseModel? mainWeatherData;
  int? weatherVisibility;
  WindInfoResponseModel? windData;
  CloudsResponseModel? cloudsData;
  int? date;
  SunsetSunriseResponseModel? sunsetAndSunriseData;
  int? timezone;
  int? id;
  String? cityName;
  @override
  WeatherInfoEntity mapToEntity() {
    final List<WeatherDescriptionEntity>? _weatherDescription =
        weatherDescription
            ?.map((WeatherDescriptionResponseModel weatherDescriptionEntity) =>
                weatherDescriptionEntity.mapToEntity())
            .toList();
    final WeatherTypeEnum? weatherTypeEnum =
        _weatherDescription?[0].main?.toWeatherType();
    return WeatherInfoEntity(
      main: mainWeatherData?.mapToEntity() ?? const MainWeatherInfoEntity(),
      id: id ?? 0,
      visibility: weatherVisibility?.toKM() ?? '',
      clouds: cloudsData?.mapToEntity() ?? const CloudsEntity(),
      weather: _weatherDescription,
      dt: date?.fromTimestampToDate(),
      name: cityName ?? '',
      sys: sunsetAndSunriseData?.mapToEntity() ?? const SunsetSunriseEntity(),
      timezone: timezone ?? 0,
      wind: windData?.mapToEntity() ?? const WindInfoEntity(),
      weatherTheme: weatherTypeEnum.toWeatherTheme(),
    );
  }
}

To map this model into the WeatherInfoEntity class:

1. Each sub-model in the WeatherInfoResponseModel should override the mapToEntity function(ex: coordinateData,mainWeatherData,windData..).
2. To ensure that WeatherInfoEntity is suitable for creating our interfaces, it is essential to define the appropriate value for each field. For example, I provided an alternative value for null output and made some conversions to meet the desired result, such as converting the visibility field from meters to kilometers.

All that is left is to add to/from JSON functions:

 WeatherModel.fromJson(Map<String, dynamic> json) {
    coord = json['coord'] != null ? Coord.fromJson(json['coord']) : null;
    if (json['weather'] != null) {
      weather = <Weather>[];
      json['weather'].forEach((Weather v) {
        weather?.add(Weather.fromJson(v));
      });
    }
    base = json['base'];
    main = json['main'] != null ? Main.fromJson(json['main']) : null;
    visibility = json['visibility'];
    wind = json['wind'] != null ? Wind.fromJson(json['wind']) : null;
    clouds = json['clouds'] != null ? Clouds.fromJson(json['clouds']) : null;
    dt = json['dt'];
    sys = json['sys'] != null ? Sys.fromJson(json['sys']) : null;
    timezone = json['timezone'];
    id = json['id'];
    name = json['name'];
    cod = json['cod'];
  }

  Map<String, dynamic> toJson() {
    final Map<String, dynamic> map = <String, dynamic>{};
    if (coord != null) {
      map['coord'] = coord?.toJson();
    }
    if (weather != null) {
      map['weather'] = weather?.map((Weather v) => v.toJson()).toList();
    }
    map['base'] = base;
    if (main != null) {
      map['main'] = main?.toJson();
    }
    map['visibility'] = visibility;
    if (wind != null) {
      map['wind'] = wind?.toJson();
    }
    if (clouds != null) {
      map['clouds'] = clouds?.toJson();
    }
    map['dt'] = dt;
    if (sys != null) {
      map['sys'] = sys?.toJson();
    }
    map['timezone'] = timezone;
    map['id'] = id;
    map['name'] = name;
    map['cod'] = cod;
    return map;
  }

In the following code snippet, I have to write every line of those functions myself, and if I want to add or delete an attribute of my model, I have to edit it all over again, which makes maintainability difficult.

After researching, I found that the most popular JSON serialization solution for Flutter is the 'json_serializable' package created by Google developers. By using this package in combination with 'build_runner' and 'json_annotation' packages, the fromJSON and toJSON functions can be automatically generated for models that are properly configured and annotated. This eliminates the need for manually writing out all the JSON keys.
As a result of adding configurations, the WeatherInfoResponseModel will look like this:

part 'weather_info_response_model.g.dart';
@JsonSerializable()
class WeatherInfoResponseModel extends DataMapper<WeatherInfoEntity> {
  WeatherInfoResponseModel(
      {this.coordinateData,
      this.weatherDescription,
      this.mainWeatherData,
      this.weatherVisibility,
      this.windData,
      this.cloudsData,
      this.date,
      this.sunsetAndSunriseData,
      this.timezone,
      this.id,
      this.cityName,
     });
  factory WeatherInfoResponseModel.fromJson(Map<String, dynamic> json) =>
      _$WeatherInfoResponseModelFromJson(json);
  @JsonKey(name: 'coord')
  CoordinateResponseModel? coordinateData;
  @JsonKey(name: 'weather')
  List<WeatherDescriptionResponseModel>? weatherDescription;
  @JsonKey(name: 'main')
  MainWeatherInfoResponseModel? mainWeatherData;
  @JsonKey(name: 'visibility')
  int? weatherVisibility;
  @JsonKey(name: 'wind')
  WindInfoResponseModel? windData;
  @JsonKey(name: 'clouds')
  CloudsResponseModel? cloudsData;
  @JsonKey(name: 'dt')
  int? date;
  @JsonKey(name: 'sys')
  SunsetSunriseResponseModel? sunsetAndSunriseData;
  int? timezone;
  int? id;
  @JsonKey(name: 'name')
  String? cityName;
  @override
  WeatherInfoEntity mapToEntity() {
    final List<WeatherDescriptionEntity>? _weatherDescription =
        weatherDescription
            ?.map((WeatherDescriptionResponseModel weatherDescriptionEntity) =>
                weatherDescriptionEntity.mapToEntity())
            .toList();
    final WeatherTypeEnum? weatherTypeEnum =
        _weatherDescription?[0].main?.toWeatherType();
    return WeatherInfoEntity(
      main: mainWeatherData?.mapToEntity() ?? const MainWeatherInfoEntity(),
      id: id ?? 0,
      visibility: weatherVisibility?.toKM() ?? '',
      clouds: cloudsData?.mapToEntity() ?? const CloudsEntity(),
      weather: _weatherDescription,
      dt: date?.fromTimestampToDate(),
      name: cityName ?? '',
      sys: sunsetAndSunriseData?.mapToEntity() ?? const SunsetSunriseEntity(),
      timezone: timezone ?? 0,
      wind: windData?.mapToEntity() ?? const WindInfoEntity(),
      weatherTheme: weatherTypeEnum.toWeatherTheme(),
    );
  }
}

So, at the top of the file, we included the 'weather info response model.g.dart' part to provide the WeatherInfoResponseModel class access to the methods inside the file that will be generated later using the build_runner plugin. We also annotated our class with @JsonSerializable() to tell the build runner that this class is involved in the build. Finally, we added the fromJson factory constructor as well as the JsonKey() annotation in front of each field to indicate the API key.
Following our exploration of the model structure, we will begin work on the repository implementation and data source contracts.

Implementing repository the contract

The Repositories are the app's data layer's brain; they are in charge of:

1. Exposing data to the rest of the app.
2. Centralizing changes to the data.
3. Resolving conflicts between multiple data sources.
4. Abstracting sources of data from the rest of the app.

Besides this, the repository implements the logic for deciding whether to collect data from a remote data source or to use results cached in a local database. Each data source class, on the other hand, acts as a bridge between the application and the system for data operations; it is responsible for interacting with just one source of data.

In our case, we'll have two data sources: one for network data and another for local data to ensure that the user sees anything even when he's not connected to the internet. This indicates that we'll also require a method to determine the user's current network connection state.

To meet this requirement by creating the 'ConnectivityCheckerHelper' class, which allows for checking the connectivity whenever desired. This class can be found in the directory core/utils/helpers/connectivity_helper:

I used the 'Connectivity_plus' plugin to determine the user's connection status. It offers two functions: one to check the device's connection status, and another that triggers whenever the connectivity state changes:

@injectable
class ConnectivityCheckerHelper {
  Future<bool> checkConnectivity() async {
    final ConnectivityResult connectivityResult =
        await Connectivity().checkConnectivity();
    return _handleResult(connectivityResult);
  }

  static Stream<ConnectivityResult> listenToConnectivityChanged() {
    return Connectivity().onConnectivityChanged;
  }

  bool _handleResult(ConnectivityResult connectivityResult) {
    final bool connected;
    if (connectivityResult == ConnectivityResult.mobile ||
        connectivityResult == ConnectivityResult.wifi) {
      connected = true;
    } else {
      connected = false;
    }

    return connected;
  }
}

In the previous class, two functions were created: 'checkConnectivity()', which returns true if the user is connected and false otherwise, and 'listenToConnectivityChanged()', which listens to any changes in the connection status.

Implementing Data Sources

Now that the 'ConnectivityCheckerHelper' class has been created, it's time to implement our two data sources.

Remote Data Source

The data retrieved from the network source is represented by the 'Remote Data Source'. Its implementation can be found in the 'data/datasources/remote_datasource' directory, consisting of two files: the data source contract and its implementation:

The interface of the WeatherRemoteDataSource will be nearly identical to that of the Repository, with two methods: getWeatherDataByCoordinates and getWeatherDataByCity. As previously noted, the return type of these methods will be based on the response models rather than the entities, therefore each data source method will return the created WeatherInfoResponseModel (converted from JSON) using the shared ApiResultModel.


abstract class WeatherRemoteDataSource {
  Future<ApiResultModel<WeatherInfoResponseModel?>> getWeatherDataByCoordinates(
      {WeatherByCoordinatesRequestModel? weatherByCoordinatesRequestModel});

  Future<ApiResultModel<WeatherInfoResponseModel?>> getWeatherDataByCity(
      {String? cityName});
}

I implemented the new interface by creating a class called WeatherRemoteDataSourceImpl. This class will use HTTP requests to communicate with the server and obtain the needed data.

So, to maintain clean code and follow the DRY principle, I created a helper class that manages the creation of the HTTP client and provides generic HTTP request methods. The helper class can be found in the core/utils/helpers/api_call_helper directory:

And for the ApiCallHelper class will look like this:

@injectable
class ApiCallHelper {
  ApiCallHelper(this.connectivityCheckerHelper);

  final ConnectivityCheckerHelper connectivityCheckerHelper;
  final String? baseUrl = devBaseUrl;

  Map<String, String> _sharedDefaultHeader = <String, String>{};

  Future<void> initSharedDefaultHeader(
      [String contentValue = contentTypeValue]) async {
    _sharedDefaultHeader = <String, String>{};
    _sharedDefaultHeader.addAll(<String, String>{
      contentTypeKey: contentValue,
    });
  }

  Future<bool> _getConnectionState() async {
    final bool _result = await connectivityCheckerHelper.checkConnectivity();
    return _result;
  }

  ///@[params] should be added to the url as the api params
  Future<ApiResultModel<http.Response>> getWS({
    required String uri,
    Map<String, String> headers = const <String, String>{},
    Map<String, dynamic> params = const <String, dynamic>{},
  }) async {
    await initSharedDefaultHeader();
    _sharedDefaultHeader.addAll(headers);
    if (await _getConnectionState()) {
      try {
        final String _url = '$baseUrl$uri';
        final http.Response response = await http
            .get(_url.parseUri(params: params), headers: _sharedDefaultHeader)
            .timeout(timeOutDuration);
        if (response.statusCode >= 200 && response.statusCode < 300) {
          return ApiResultModel<http.Response>.success(data: response);
        } else {
          return ApiResultModel<http.Response>.failure(
            errorResultEntity: ErrorResultModel(
              message: response.reasonPhrase,
              statusCode: response.statusCode,
            ),
          );
        }
      } on TimeoutException catch (_) {
        return const ApiResultModel<http.Response>.failure(
          errorResultEntity: ErrorResultModel(
            message: commonErrorUnexpectedMessage,
            statusCode: timeoutRequestStatusCode,
          ),
        );
      } on IOException catch (_) {
        throw CustomConnectionException(
          exceptionMessage: commonConnectionFailedMessage,
          exceptionCode: ioExceptionStatusCode,
        );
      }
    } else {
      throw CustomConnectionException(
        exceptionMessage: commonConnectionFailedMessage,
        exceptionCode: ioExceptionStatusCode,
      );
    }
  }
}

1. The ApiCallHelper class will utilize the previously created ConnectivityCheckerHelper, which will be injected through the constructor.
2. The first method I wrote is initSharedDefaultHeader, which will set the default configuration for each request header. For example, I specified application/Json as the default header content type.
3. Second, using the connection helper, I wrote a private method called getConnectionState that returns whether or not the user is connected.
4. The getWS function, which represents the HTTP GET method, is the file's last function. Its usage requires the specification of the request URI, and it also allows for the inclusion of optional extra headers or request parameters. This function returns an HTTP response utilizing the ApiResultModel sealed class. When the response has a 2xx status code, the function returns a success state along with the received data. If the response returns a different status code, the function returns a failure state accompanied by error information. To handle exceptions, particularly network exceptions, the function throws a CustomConnectionException that holds the custom exception message.

We may use the same logic to create the other HTTP requests, but our application only needs the GET method. Now that all of the dependencies have been established, it is time to write the remote datasource implementation class:

@Injectable(as: WeatherRemoteDataSource)
class WeatherRemoteDataSourceImpl implements WeatherRemoteDataSource {
  WeatherRemoteDataSourceImpl(this._apiCallHelper);

  final ApiCallHelper _apiCallHelper;

  @override
  Future<ApiResultModel<WeatherInfoResponseModel?>> getWeatherDataByCity(
      {String? cityName}) async {
    try {
      final ApiResultModel<Response> _result = await _apiCallHelper.getWS(
          uri: getWeatherDetails,
          params: <String, dynamic>{
            cityNameKey: cityName,
            appIdKey: appIdValue
          });
      return _result.when(
        success: (Response response) {
          return ApiResultModel<WeatherInfoResponseModel?>.success(
            data: WeatherInfoResponseModel.fromJson(
              response.decodeJson(),
            ),
          );
        },
        failure: (ErrorResultModel errorModel) {
          return ApiResultModel<WeatherInfoResponseModel?>.failure(
              errorResultEntity: errorModel);
        },
      );
    } on CustomConnectionException catch (exception) {
      throw CustomConnectionException(
        exceptionMessage: exception.exceptionMessage,
        exceptionCode: exception.exceptionCode,
      );
    }
  }

  @override
  Future<ApiResultModel<WeatherInfoResponseModel?>> getWeatherDataByCoordinates(
      {WeatherByCoordinatesRequestModel?
          weatherByCoordinatesRequestModel}) async {
    try {
      final ApiResultModel<Response> _result = await _apiCallHelper
          .getWS(uri: getWeatherDetails, params: <String, dynamic>{
        latitudeKey: weatherByCoordinatesRequestModel?.lat,
        longitudeKey: weatherByCoordinatesRequestModel?.lon,
        appIdKey: appIdValue,
      });
      return _result.when(
        success: (Response response) {
          return ApiResultModel<WeatherInfoResponseModel?>.success(
            data: WeatherInfoResponseModel.fromJson(
              response.decodeJson(),
            ),
          );
        },
        failure: (ErrorResultModel errorModel) {
          return ApiResultModel<WeatherInfoResponseModel?>.failure(
              errorResultEntity: errorModel);
        },
      );
    } on CustomConnectionException catch (exception) {
      throw CustomConnectionException(
        exceptionMessage: exception.exceptionMessage,
        exceptionCode: exception.exceptionCode,
      );
    }
  }
}

The WeatherRemoteDataSourceImpl class implements the remote data source contract by overriding its methods. To obtain its response model, each method calls the getWS function given by the injected ApiCallHelper object. In addition, if the user is disconnected from the Internet, a CustomConnectionException is thrown.

Local Data Source

Until now, the methods we created were always concerned with retrieving data from the server. And now it's time to write the WeatherLocalDataSourceImpl class, which is in charge of caching weather data in a local database, retrieving all local weathers, and getting the most recently saved weather data. Additionally, this class will include an abstract class and other classe for implementation. But before that, we will start by creating our local database.

Local Database

In Flutter, we have numerous options for a local database, but in our situation, I chose the ObjectBox database, which is an excellent fit for our needs. This database consumes the least amount of CPU, memory, and battery power, ensuring that your program is not only effective but also long-lasting:

1. The objectbox plugin is a Flutter database that allows for super-fast NoSQL ACID (atomicity, consistency, isolation, and durability) object persistence.
2. The objectbox_flutter_libs plugin, which offers the platform's native ObjectBox library.
3. The objectbox_generator plugin is used to generate code for our database.

The following step involves adding the local database class, located in the 'datasources/local_datasource/local_database' directory:

class AppLocalDatabase {
  static Store? _store;

  /// Create an instance of ObjectBox to use throughout the app.
  static Future<AppLocalDatabase> create() async {
    final Directory docsDir = await getApplicationDocumentsDirectory();
    _store = await openStore(
      directory: p.join(docsDir.path, 'objectbox'),
    );
    return AppLocalDatabase();
  }

  int? insert<T>(T object) {
    final Box<T>? box = _store?.box<T>();
    return box?.put(object);
  }

  Future<List<T>?> getAll<T>() async {
    final Box<T>? box = _store?.box<T>();
    return box?.getAll();
  }
}

1. First, I created a static private object of type Store to serve as the starting point for implementing ObjectBox. It is the database's direct interface and also controls boxes. In reality, a Box instance provides access to items of a specific type, similar to a table in a standard database.
2. The second step is to open my database and keep it open while my app runs. To do this, I wrote a static create method that returns my AppLocalDatabase object, which will be injected, allowing my app to use just one instance.
3. Finally, I added two more functions: insert, which inserts a new object into the database, and getAll, which retrieves all of the stored weather data.

Local Data Source Implementation

Now we'll go on to the WeatherLocalDataSourceImpl class, which has the injected AppLocalDatabase object in its constructor. This class implements three functions: CacheWeatherInfo, that caches current weather data, getLastWeatherInfo, which returns the most recently saved WeatherInfoEntity object, and getAllLocalWeatherInfo, which retrieves all stored weather data:

@Injectable(as: WeatherLocalDataSource)
class WeatherRemoteDataSourceImpl implements WeatherLocalDataSource {
  WeatherRemoteDataSourceImpl(this.appLocalDatabase);

  final AppLocalDatabase appLocalDatabase;

  @override
  void cacheWeatherInfo(WeatherInfoResponseModel? weatherInfoResponseModel) {
    final WeatherInfoEntity? weatherData =
        weatherInfoResponseModel?.mapToEntity();
    final WeatherInfoLocalEntity _localEntity = WeatherInfoLocalEntity(
      timezone: weatherData?.timezone,
      name: weatherData?.name,
      dt: weatherData?.dt,
      visibility: weatherData?.visibility,
    );
    _localEntity.sys.target = SunsetSunriseLocalEntity(
      sunset: weatherData?.sys?.sunset,
      country: weatherData?.sys?.country,
      type: weatherData?.sys?.type,
      sunrise: weatherData?.sys?.sunrise,
    );
    _localEntity.weather.addAll(
      <WeatherDescriptionLocalEntity>[
        WeatherDescriptionLocalEntity(
          main: weatherData?.weather?[0]?.main,
          icon: weatherData?.weather?[0]?.icon,
          description: weatherData?.weather?[0]?.description,
        ),
      ],
    );
    _localEntity.main.target = MainWeatherInfoLocalEntity(
      tempMin: weatherData?.main?.tempMin,
      tempMax: weatherData?.main?.tempMax,
      pressure: weatherData?.main?.pressure,
      humidity: weatherData?.main?.humidity,
      feelsLike: weatherData?.main?.feelsLike,
      temp: weatherData?.main?.temp,
    );
    _localEntity.wind.target = WindInfoLocalEntity(
      speed: weatherData?.wind?.speed,
      deg: weatherData?.wind?.deg,
    );
    _localEntity.clouds.target = CloudsLocalEntity(
      all: weatherData?.clouds?.all,
    );
    _localEntity.weatherTheme.target = WeatherThemeLocalEntity(
      firstColorHex: weatherData?.weatherTheme?.firstColor?.value,
      secondColorHex: weatherData?.weatherTheme?.secondColor?.value,
    );
    appLocalDatabase.insert<WeatherInfoLocalEntity>(_localEntity);
  }

  @override
  Future<WeatherInfoEntity?> getLastWeatherInfo() async {
    final List<WeatherInfoLocalEntity>? weatherInfoLocalData =
        await appLocalDatabase.getAll<WeatherInfoLocalEntity>();
    if ((weatherInfoLocalData?.length ?? 0) > 0) {
      final WeatherInfoEntity? _lastInfoData =
          weatherInfoLocalData?.last.mapToEntity();
      return _lastInfoData;
    }
    return null;
  }

  @override
  Future<List<WeatherInfoEntity?>?> getAllLocalWeathers() async {
    final List<WeatherInfoLocalEntity>? weatherInfoLocalData =
        await appLocalDatabase.getAll<WeatherInfoLocalEntity>();
    if ((weatherInfoLocalData?.length ?? 0) > 0) {
      final List<WeatherInfoEntity?>? _localData = weatherInfoLocalData
          ?.map((WeatherInfoLocalEntity element) => element.mapToEntity())
          .toList();
      return _localData;
    }
    return null;
  }
}

Implementing the Repository

All of the contracts required for the repository's dependencies have been created.These dependencies include local and remote data sources.

The WeatherRepositoryImpl class will implement the functions specified in its contract, such as obtaining weather data for a specific city via the getWeatherDataByCity method, retrieving weather information based on coordinates via the getWeatherDataByCoordinates method, and accessing all local weather information via the getAllLocalWeathers method.

Moreover, it's important to remember that the primary function of the Repository is:

Retrieve up-to-date data from the API when an internet connection is available and to access cached data when the user is offline.

Additionally, this class is tasked with storing the data retrieved from the server in the ObjectBox database. To achieve this, I have created two private functions: getLastLocalWeatherInfo which is invoked when a CustomConnectionException is thrown, and cacheLocalData which is utilized when the getWeatherDataByCity and getWeatherDataByCoordinates functions successfully retrieve data:

@Injectable(as: WeatherRepository)
class WeatherRepositoryImpl implements WeatherRepository {
  WeatherRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
  });

  final WeatherRemoteDataSource remoteDataSource;

  final WeatherLocalDataSource localDataSource;

  @override
  Future<ApiResultModel<WeatherInfoEntity?>> getWeatherDataByCity(
      {String? cityName}) async {
    try {
      final ApiResultModel<WeatherInfoResponseModel?> _result =
          await remoteDataSource.getWeatherDataByCity(cityName: cityName);
      return _result.when(
        success: (WeatherInfoResponseModel? weatherInfoResponseModel) async {
          if (weatherInfoResponseModel != null) {
            _cacheLocalData(weatherInfoResponseModel);
          }
          return ApiResultModel<WeatherInfoEntity?>.success(
            data: weatherInfoResponseModel?.mapToEntity(),
          );
        },
        failure: (ErrorResultModel errorResultModel) {
          return ApiResultModel<WeatherInfoEntity>.failure(
            errorResultEntity: errorResultModel,
          );
        },
      );
    } on CustomConnectionException catch (_) {
      final ApiResultModel<WeatherInfoEntity?> _result =
          await _getLastLocalWeatherInfo();
      return _result;
    }
  }

  Future<ApiResultModel<WeatherInfoEntity?>> _getLastLocalWeatherInfo() async {
    final WeatherInfoEntity? _localResult =
        await localDataSource.getLastWeatherInfo();
    return ApiResultModel<WeatherInfoEntity?>.success(
      data: _localResult,
    );
  }

  @override
  Future<ApiResultModel<WeatherInfoEntity?>> getWeatherDataByCoordinates(
      {WeatherByCoordinatesRequestModel?
          weatherByCoordinatesRequestModel}) async {
    try {
      final ApiResultModel<WeatherInfoResponseModel?> _result =
          await remoteDataSource.getWeatherDataByCoordinates(
              weatherByCoordinatesRequestModel:
                  weatherByCoordinatesRequestModel);
      return _result.when(
        success: (WeatherInfoResponseModel? weatherInfoResponseModel) async {
          if (weatherInfoResponseModel != null) {
            _cacheLocalData(weatherInfoResponseModel);
          }
          return ApiResultModel<WeatherInfoEntity?>.success(
            data: weatherInfoResponseModel?.mapToEntity(),
          );
        },
        failure: (ErrorResultModel errorResultModel) {
          return ApiResultModel<WeatherInfoEntity>.failure(
            errorResultEntity: errorResultModel,
          );
        },
      );
    } on CustomConnectionException catch (_) {
      final ApiResultModel<WeatherInfoEntity?> _result =
          await _getLastLocalWeatherInfo();
      return _result;
    }
  }

  void _cacheLocalData(WeatherInfoResponseModel? weatherData) {
    localDataSource.cacheWeatherInfo(weatherData);
  }

  @override
  Future<ApiResultModel<List<WeatherInfoEntity?>?>>
      getAllLocalWeathers() async {
    final List<WeatherInfoEntity?>? _result =
        await localDataSource.getAllLocalWeathers();
    return ApiResultModel<List<WeatherInfoEntity?>?>.success(
      data: _result,
    );
  }
}

Next up

Our progress is remarkable, as we have successfully completed the entire data layer, and the domain layer is already implemented. Now, the final step is to focus on the presentation layer: Next

Flutter Clean Architecture [4]: An Overview & Project Structure

marwaMejri — Tue, 13 Jun 2023 15:13:31 +0000

This post is the final part of a tutorial series for Flutter App!.

You can find the completed project repository here

Presentation Layer

The presentation layer is in charge of managing the user interface and displaying information to the user. It serves as a bridge between the domain/business logic layer and the outside world. This layer is divided into three sections: the 'widgets' folder, the 'view' folder, and the 'presentation logic holder', which is implemented in our case using the Provider dependency.

Provider is a state management solution for Flutter applications that allows for simple and efficient management of application state. It is based on the InheritedWidget and ChangeNotifier APIs provided by the Flutter framework.
In fact, ChangeNotifier is a simple implementation of the Observer pattern, where the ChangeNotifier acts as the subject and notifies any registered observers (typically widgets) when there has been a change in state.
To read more about a provider, see its documentation.

Responsive UI

Since our application targets both iOS and Android platforms, and each platform has a multitude of screen sizes, it is essential to design responsive interfaces that can adapt to different screen sizes. By designing for responsiveness, we can ensure that our application will look and function properly on a wide range of devices.

Rather than designing separate interfaces for each screen size, we can use responsive design techniques to create flexible layouts that adjust to the available screen space. This can be achieved using widgets such as LayoutBuilder, AspectRatio, FittedBox, or FractionallySizedBox.

For our weather app, I have decided to use the MediaQuery.of() method to obtain the dimensions of the user's device. With this information, I can dynamically adjust the size of my app's widgets to ensure that they fit properly on the screen.

Applied to the Weather App

To implement the previous approach, I have created a new class called ResponsiveConfig. This class is located in the 'core/utils/helpers/responsive_ui_helper' directory:

@singleton
class ResponsiveUiConfig {
  late MediaQueryData _mediaQueryData;
  late double _screenWidth;
  late double _screenHeight;

  double get screenWidth => _screenWidth;

  double get screenHeight => _screenHeight;

  ///this method initialize all of our attributes
  void initialize(BuildContext context) {
    _mediaQueryData = MediaQuery.of(context);
    _screenWidth = _mediaQueryData.size.width;
    _screenHeight = _mediaQueryData.size.height;
  }

  double setWidth(num value) => _screenWidth * (value / 375);

  double setHeight(num value) => _screenHeight * (value / 812);
}

The ResponsiveConfig class includes an initialize method that uses the MediaQuery.of() function to determine the width and height of the user's device. With these numbers, I constructed the setWidth() function, which calculates the proper size of widgets based on the screen width. The setWidth() function takes two parameters: the screen width and the desired widget size. The algorithm for calculating widget size is screenWidth * (value / 375), where the reference value of 375 is based on the minimum screen width of an iOS device. As a result, for a device with a width of 375, the widget width will be the supplied value. For devices with wider screens, the widget width will increase proportionally.
Following the same approach, I added the setHeight() function to calculate the appropriate height value of widgets based on the screen height.
And to make the setWidth() and setHeight() functions easier to use, I added a new file named size_extension to the 'core/utils/helpers/extension_functions' folder:

extension ExtensionsOnNum on num {
  static final ResponsiveUiConfig _responsiveUiConfig = locator<ResponsiveUiConfig>();

  double get w => _responsiveUiConfig.setWidth(this);

  double get h => _responsiveUiConfig.setHeight(this);
}

There are two extension functions in this file: w() and h(). The w() function is a num data type extension function that refers to the setWidth() function. Similarly, the h() function is a num data type extension function that refers to the setHeight() function. We can simply set the width and height values of widgets within our app by using these extension functions. For example, we can adjust a widget's width to 13 by calling 13.w and its height to 20 by calling 20.h.

Additionally, I created a new base component called BaseResponsiveWidget:

class BaseResponsiveWidget extends StatelessWidget {
  const BaseResponsiveWidget({
    Key? key,
    required this.buildWidget,
    this.initializeConfig=false,
  }) : super(key: key);

  final Widget Function(
      BuildContext context, ResponsiveUiConfig responsiveUiConfig) buildWidget;
  final bool initializeConfig;

  @override
  Widget build(BuildContext context) {
    final ResponsiveUiConfig responsiveUiConfig = locator<ResponsiveUiConfig>();
    if (initializeConfig) {
      responsiveUiConfig.initialize(context);
    }
    return buildWidget(context, responsiveUiConfig);
  }
}

This widget takes two parameters: a buildWidget function that returns a widget and an initializeConfig parameter of boolean type. The BaseResponsiveWidget is intended to initialize the shared screen width and height by calling the initialize() function of the ResponsiveUiConfig class. The buildWidget function is responsible for returning the widget tree with a reference to the ResponsiveUiConfig class in case you need to set a widget size by percent based on the screen width or height or if your widget takes up all the available width or height.

Creating a base view model

It is time to implement the view model class using the provider dependency. Since the view model acts as a bridge between the domain and presentation layers, its implementation will depend on a specific use case. Also, the view model class extends the ChangeNotifier class provided by the Provider dependency, allowing for efficient state management.

To further improve the solution, it is a good idea to establish a basic view model class that can be extended by each individual view model. This approach promotes code reusability and consistency across different view models. The base view model class can define common methods and properties, such as loading state management, error handling, and data retrieval methods:

class BaseViewModel extends ChangeNotifier {
  final StreamController<bool> _toggleLoading = StreamController<bool>.broadcast();

  StreamController<bool> get toggleLoading => _toggleLoading;

  Future<ApiResultState<Type>?> executeParamsUseCase<Type, Params>(
      {required BaseParamsUseCase<Type, Params> useCase, Params? query}) async {
    showLoadingIndicator(true);
    final ApiResultModel<Type> _apiResult = await useCase(query);
    return _apiResult.when(
      success: (Type data) {
        showLoadingIndicator(false);
        return ApiResultState<Type>.data(data: data);
      },
      failure: (ErrorResultModel errorResultEntity) {
        showLoadingIndicator(false);
        return ApiResultState<Type>.error(
          errorResultModel: ErrorResultModel(
            message: errorResultEntity.message,
            statusCode: errorResultEntity.statusCode,
          ),
        );
      },
    );
  }

  void showLoadingIndicator(bool show) {
    _toggleLoading.add(show);
  }

  void onDispose() {}

  @override
  void dispose() {
    _toggleLoading.close();
    onDispose();
    super.dispose();
  }

}

The BaseViewModel class includes a StreamController attribute named toggleLoading, which is private and responsible for holding the loading state, as well as three other methods. To reduce code duplication, I created the executeParamsUseCase method. This method accepts a use case to execute as well as an optional query and uses the showLoadingIndicator function to switch the loading state depending on the success or failure of the API request.

StreamController: a StreamController allows you to create a Stream (a sequence of asynchronous events) and then add events to it over time. You can also listen to the stream to receive these events as they occur. This makes it a useful tool for managing state in a Flutter application, since you can use it to notify your widgets of changes as they happen.

The final method in the BaseViewModel class is onDispose(), which is responsible for closing any active StreamController streams. This is significant since ChangeNotifier is not lifecycle-aware, so we must manually close any active streams when the view model is disposed of.

Implementing the base view model

As an example, let's take the case of the weather details interface. In the presentation layer, a new folder named weather_details was created, which contains the view model class and two additional folders: one for the view and the other for the widgets used to build the view.

This interface is in charge of retrieving weather information based on coordinates. As a result, the corresponding view model class will be dependent on the previously developed GetWeatherDataByCoordinates use case:


@injectable
class WeatherDetailsViewModel extends BaseViewModel {
  WeatherDetailsViewModel(this.getWeatherDataByCoordinates);
  final GetWeatherDataByCoordinates getWeatherDataByCoordinates;

The WeatherDetailsViewModel class constructor includes the GetWeatherDataByCoordinates use case. To execute the use case, the class extends the BaseViewModel and calls the executeParamsUseCase function with a query of type WeatherByCoordinatesRequestModel. In addition, the class includes a new attribute named weatherResult of type StreamController to hold the received API response. Finally, the onDispose() method is overridden to close the stream listener:

@injectable
class WeatherDetailsViewModel extends BaseViewModel {
  WeatherDetailsViewModel(this.getWeatherDataByCoordinates);

  final GetWeatherDataByCoordinates getWeatherDataByCoordinates;

  final StreamController<ApiResultState<WeatherInfoEntity?>?> _weatherResult =
      StreamController<ApiResultState<WeatherInfoEntity?>?>.broadcast();

  StreamController<ApiResultState<WeatherInfoEntity?>?> get weatherResult =>
      _weatherResult;

  Future<void> getWeatherByCoordinates(
      {WeatherByCoordinatesRequestModel?
          weatherByCoordinatesRequestModel}) async {
    final ApiResultState<WeatherInfoEntity?>? _result =
        await executeParamsUseCase(
      useCase: getWeatherDataByCoordinates,
      query: weatherByCoordinatesRequestModel,
    );
    _weatherResult.add(_result);
  }

  @override
  void onDispose() {
    super.onDispose();
    _weatherResult.close();
  }
}

Creating the view

As of now, all that is left to do is use the WeatherDetailsViewModel that has previously been established to develop an interface for our weather details. In order to enhance our interfaces, I have developed a generic class named BaseViewModelView that manages view model initialization, connectivity state, and the loader widget switching when an API is called:

class BaseViewModelView<T> extends StatefulWidget {
  const BaseViewModelView({
    Key? key,
    this.onInitState,
    required this.buildWidget,
  }) : super(key: key);
  final void Function(T provider)? onInitState;
  final Widget Function(T provider) buildWidget;

  @override
  State<BaseViewModelView<T>> createState() => _BaseViewModelViewState<T>();
}

class _BaseViewModelViewState<T> extends State<BaseViewModelView<T>> {
  bool _showLoader = false;

  @override
  void initState() {
    super.initState();
    final T _provider = Provider.of<T>(context, listen: false);
    checkInternetAvailability();
    toggleLoadingWidget(_provider);
    if (widget.onInitState != null) {
      widget.onInitState!(_provider);
    }
  }

  void checkInternetAvailability() {
    ConnectivityCheckerHelper.listenToConnectivityChanged().listen(
      (ConnectivityResult connectivityResult) {
        if (connectivityResult == ConnectivityResult.none) {
          if (!mounted) {
            return;
          }
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(
              content: Text(commonConnectionFailedMessage),
            ),
          );
        }
      },
    );
  }

  void toggleLoadingWidget(T provider) {
    (provider as BaseViewModel).toggleLoading.stream.listen((bool show) {
      if (!mounted) {
        return;
      }
      setState(() {
        _showLoader = show;
      });
    });
  }

  @override
  Widget build(BuildContext context) {
    return Consumer<T>(
      builder: (BuildContext context, T provider, Widget? child) {
        return Stack(
          alignment: Alignment.center,
          children: <Widget>[
            widget.buildWidget(provider),
            if (_showLoader)
              BaseResponsiveWidget(
                buildWidget: (BuildContext context,
                    ResponsiveUiConfig responsiveUiConfig) {
                  return AnimatedOpacity(
                    opacity: 1,
                    duration: const Duration(milliseconds: 200),
                    child: Container(
                      width: responsiveUiConfig.screenWidth,
                      height: responsiveUiConfig.screenHeight,
                      color: Colors.transparent,
                      child: Center(
                        child: Container(
                          decoration: BoxDecoration(
                            shape: BoxShape.circle,
                            color: primaryColor,
                          ),
                          padding: EdgeInsets.all(
                            15.w,
                          ),
                          width: 70.w,
                          height: 70.w,
                          child: CircularProgressIndicator(
                            color: lightColor,
                          ),
                        ),
                      ),
                    ),
                  );
                },
              ),
          ],
        );
      },
    );
  }
}

The BaseViewModelView class is a generic class in which 'T' indicates the ViewModel type connected with the View. This class's arguments are two functions. One is named onInitState, and it accepts as an argument your view model instance. This function is called by the initState method, and it can be used to initialize the screen state or any other necessary initialization before producing the screen. The other function, buildWidget, is called in the build function and returns a widget.
Additionally, the initState() method invokes two additional methods: checkInternetAvailability() and toggleLoadingWidget():

The shared ConnectivityCheckerHelper class is used by the checkInternetAvailability() method to listen for changes in connectivity. If connectivity is lost, a snack bar with the text 'Please check your Internet connection' appears. This method avoids the need to manually check for connectivity on each screen.

The toggleLoadingWidget() function uses the BaseViewModel's toggleLoadingStream to determine whether the loader widget should be displayed or hidden.

Finally, in the build() function, I returned a Consumer widget, which listens to changes in the ViewModel object and rebuilds the widget tree accordingly. The Consumer widget returns a Stack widget, which contains the previously defined buildWidget() function to render the desired UI. On top of this, I added a loader widget, which is conditionally displayed based on changes in the ViewModel object's toggleLoading stream. By using this approach, the loader widget is displayed whenever an API call is performed, and it is hidden once the call is completed.

Consumer: a Consumer is a widget that rebuilds its child widget whenever the value passed into its builder function changes. It also allows obtaining a value from a provider when we don't have a BuildContext that is a descendant of provider, and therefore cannot use Provider.of.

And now the time to put all of our past work into effect has finally come!

The final step is to create the WeatherDetails interface, which will be a stateful widget due to the API call. To obtain weather information during initialization, we will use the onInitState method given by the BaseViewModelViewWeatherDetailsViewModel> widget. In addition, to ensure a responsive UI, we will use the BaseResponsiveWidget in the widget tree. The resultant interface will appear as follows:

class WeatherDetailsView extends StatefulWidget {
  const WeatherDetailsView({
    Key? key,
    this.weatherInfoEntity,
  }) : super(key: key);
  final WeatherInfoEntity? weatherInfoEntity;

  @override
  State<WeatherDetailsView> createState() => _WeatherDetailsViewState();
}

class _WeatherDetailsViewState extends State<WeatherDetailsView> {
  WeatherInfoEntity? _result;
  bool? _isSuccess;

  Future<void> _getWeatherData(WeatherDetailsViewModel provider) async {
    await provider.getWeatherByCoordinates(
      weatherByCoordinatesRequestModel: WeatherByCoordinatesRequestModel(
        lon: 10.634422,
        lat: 35.821430,
      ),
    );
  }

  Widget _getWidget(ResponsiveUiConfig responsiveUiConfig) {
    if (_isSuccess == false) {
      return ListView.builder(
        itemCount: 1,
        itemBuilder: (BuildContext context, int index) {
          return SizedBox(
            height: responsiveUiConfig.screenHeight,
            child: Center(
              child: Lottie.asset(
                'assets/lottie_animation.json',
              ),
            ),
          );
        },
      );
    } else {
      return Container();
    }
  }

  @override
  void initState() {
    super.initState();
    if (widget.weatherInfoEntity != null) {
      _result = widget.weatherInfoEntity;
    }
  }

  @override
  Widget build(BuildContext context) {
    final StackRouter appRouter = AutoRouter.of(context);
    return Scaffold(
      backgroundColor: lightColor,
      body: SafeArea(
        child: BaseViewModelView<WeatherDetailsViewModel>(
          onInitState: (WeatherDetailsViewModel provider) async {
            provider.weatherResult.stream.listen(
              (ApiResultState<WeatherInfoEntity?>? result) {
                result?.when(
                  data: (WeatherInfoEntity? data) {
                    if (!mounted) {
                      return;
                    }
                    setState(() {
                      _result = data;
                      _isSuccess = data != null;
                    });
                  },
                  error: (ErrorResultModel error) {
                    print(error);
                  },
                );
              },
            );
            if (widget.weatherInfoEntity == null) {
              await _getWeatherData(provider);
            }
          },
          buildWidget: (WeatherDetailsViewModel provider) {
            return BaseResponsiveWidget(
              initializeConfig: true,
              buildWidget: (BuildContext context,
                  ResponsiveUiConfig responsiveUiConfig) {
                return RefreshIndicator(
                  backgroundColor: lightColor,
                  color: primaryColor,
                  triggerMode: RefreshIndicatorTriggerMode.anywhere,
                  strokeWidth: 2.w,
                  onRefresh: () async {
                    _getWeatherData(provider);
                  },
                  child: Stack(
                    alignment: Alignment.bottomCenter,
                    children: <Widget>[
                      if (_result != null)
                        Container(
                          width: responsiveUiConfig.screenWidth,
                          decoration: BoxDecoration(
                            gradient: LinearGradient(
                              begin: Alignment.topCenter,
                              end: Alignment.bottomCenter,
                              colors: <Color>[
                                _result?.weatherTheme?.secondColor ?? lightBlue,
                                _result?.weatherTheme?.firstColor ?? blue,
                              ],
                            ),
                          ),
                          child: ListView.builder(
                            itemCount: 5,
                            primary: false,
                            physics: const BouncingScrollPhysics(),
                            itemBuilder: (BuildContext context, int index) {
                              switch (index) {
                                case 0:
                                  {
                                    return WeatherDetailsHeader(
                                      locationName: _result?.name,
                                      date: _result?.dt,
                                    );
                                  }
                                case 1:
                                  {
                                    return Align(
                                      alignment: Alignment.center,
                                      child: Container(
                                        padding: EdgeInsets.symmetric(
                                          vertical: 20.h,
                                        ),
                                        child: Image.asset(
                                          'assets/${_result?.weather?[0]?.icon}.png',
                                          height: 150.h,
                                          width: 150.w,
                                          alignment: Alignment.center,
                                        ),
                                      ),
                                    );
                                  }
                                case 2:
                                  {
                                    return WeatherDetailsDataWidget(
                                      weatherDescription:
                                          _result?.weather?[0]?.description,
                                      weatherVisibility: _result?.visibility,
                                      mainWeatherInfoEntity: _result?.main,
                                    );
                                  }
                                case 3:
                                  {
                                    return WeatherDetailsBoxList(
                                      sunsetSunriseEntity: _result?.sys,
                                      windInfoEntity: _result?.wind,
                                    );
                                  }
                                default:
                                  {
                                    return SizedBox(
                                      height: 90.h,
                                    );
                                  }
                              }
                            },
                          ),
                        )
                      else
                        _getWidget(responsiveUiConfig),
                      Positioned(
                        bottom: 0,
                        child: BottomNavigationBarWidget(
                          navigateToAddScreen: () {
                            appRouter.push(
                              const AddNewCityViewRoute(),
                            );
                          },
                        ),
                      ),
                    ],
                  ),
                );
              },
            );
          },
        ),
      ),
    );
  }
}

Conclusion

Throughout this article, we've taken an idea and turned it into a functioning weather app. While the app's functionality may be on the simpler side, what's important are the principles behind it. I've demonstrated the importance of breaking your architecture down into layers and how they communicate with one another. Additionally, I've created generic components that make it easier for developers to create their interfaces.

In addition to what we've covered, I've also utilized other important dependencies such as injectable, auto_route, and build_runner for building my app. While I won't delve into them in this article, I plan on writing about them in the future.
Thank you all for reading, and I hope you've learned something valuable.
Happy coding until next time!

Flutter Clean Architecture [1]: An Overview & Project Structure

marwaMejri — Tue, 13 Jun 2023 15:09:17 +0000

This post is the first part of a tutorial series for Flutter App!.

In their early stages, some software developers only struggle to pick up new skills quickly and create functional features; they don't worry about writing clean code or following the right architecture to improve application performance. When using a framework, some other developers often use the well-known MVC pattern, which enables us to separate our application into models, views, and controllers. This is not a problem when developing simple apps, but when we need to scale an application by adding new features, updating a library, or doing something similar, we encounter a number of problems because, as our code becomes more coupled, it becomes more challenging to make changes in our application without also making numerous changes throughout our code. As a result, before you begin developing your application, you must first design the appropriate architecture.

When designing your application architecture, it is essential that you respond to several principles, including:

SOLID: five object-oriented programming principles contribute to the readability, adaptability, and maintainability of OOP designs.
KISS: a design principle stating that designs and/or systems should be as simple as possible in order to maximize user acceptance and interaction.
DRY: a software development principle which stands for 'don't repeat yourself,' that aims to reduce code duplication in favor of abstractions and avoiding redundancy.

In latest years, we have seen a variety of architecture ideas that implement the preceding principles, such as:

Hexagonal Architecture: the Ports and Adapters architecture is based on the idea of separating the application into loosely coupled components in order to isolate the core business logic from outside concerns.
Onion Architecture: this architecture is made up of multiple concentric layers that connect to the core, which represents the domain. In fact, this architecture is based on the principle of control inversion.
The Clean architecture: Uncle Bob's architecture is based on the dependency inversion principle to define boundaries between high-level and low-level components. Furthermore, this architecture attempts to combine all previous architectures into a single actionable idea.

So, as we can see, the fundamental objective of all these architectures is to achieve a clear separation of concerns. This is accomplished by dividing the software into distinct layers, typically including a layer for business rules and another for interfaces. Furthermore, each architecture establishes a well-defined system that is:
1. Independent of Frameworks.
2. Testable.
3. Independent of UI.
4. Independent of Database.
5. Independent of any external agency.

After discussing the most popular architectures and their roles, I'll build an architecture for every Flutter application based on Uncle Bob's concept, which contains several architecture ideas.
The following diagram shows the proposed architecture, with separate layers represented by circles:

It should be noted that this architecture is not simply a folder structure that you can copy and paste into your project. It is the concept of separating your application into layers while adhering to Uncle Bob's Dependency Rule, which states that:

Nothing in an inner circle can know anything at all about something in an outer circle.

In other words, no variable, class or function declared in an outer circle can be mentioned in an inner circle.

Let's start by integrating this architecture into a Flutter project because theory can only take you so far, and practical interaction is where you learn the most.

The Project That We Will Create

We will create a weather application which aims to visualize the weather of a specific city. This application has two interfaces: one for displaying the details of the city's weather and another for adding a new city. This app will include the most basic functionalities, such as getting data from an API, storing data in a local database, handling errors, and so on:

Weather city details screen:

Add nes city item screen:

Flutter Clean Architecture and data flow

I have decided to use the Provider technique for state management in this project, as seen in the figure above. However, as clean architecture is not connected to any particular state management methodology, you are free to choose an alternative strategy that fits with your preferences and project objectives.

The above image also represents the data flow of each user-triggered event. In fact, when a user interacts with the Widget, we communicate their action to the Provider class, which then connects to the useCase to retrieve the action's result. Following that, the useCase communicates with the Repository class in order to obtain the solution from a remote or local DataSource.

So, to begin implementing these layers, let's divide our project into subfolders.

Project Organization

We create two subfolders in the lib folder. The first is called “core”, and it contains all of the shared and basic components, as well as the implementation of core features such as dependency injection. The second folder is titled "features," and it contains every "feature" of the app. For example, in our case, we only have one feature that represents weather information, and it contains two interfaces: one for details and another for adding new cities. Each feature will also be separated into three layers: data, domain, presentation, and utils.
The utils folder is not necessary for every feature; it is only required when you have individual feature utilities such as enums, classes, extension functions, and so on.

Explanation of feature layers

- Presentation

This layer, as its name implies, is in charge of presenting data to the user via widgets. This layer is also responsible for listening for states and connecting to the Provider class, which will delegate all work to the specific use case. In most cases, the presentation layer's primary task is to handle basic input validations, animations, and user interactions.

Applied to the Weather App

Every interface in our case will have two subfolders, one for the view file and the other for its widgets. We also include the provider file.

- Domain

This is the glue layer that connects the other two layers. It will use business objects (entities) and use cases to implement our application's business logic. In addition, every use case relies on the Repository to retrieve data.

Entity: Encapsulate the enterprise-wide high-level business rules. Only the fields that make sense from a "business standpoint" are held by an entity. Furthermore, the entity is the final result that the view will use, and it is the least likely to change when there are external changes. Moreover, it is not required that the entity have the same fields returned by the web service; you can customize your fields based on what your interface requires. For example, if the call model returns a timestamp date format, your entity must contain the converted date that will be parsed.

Use case: The use case, as Uncle Bob mentioned, “orchestrates the flow of data to and from the entity”. A use case, in its most basic form, represents a user action such as retrieving weather data by city, retrieving weather information by coordinates, and so on. To be compliant with the Single Responsibility SOLID principle, each use case must be independent of the others.

The domain layer should be completely independent of all other layers. But how can it be independent when any use case obtains data from a Repository that is shared with the data layer? Now comes the art of dependency inversion, one of the SOLID principles. In fact, in the domain layer, we create an abstract Repository class to define a contract for what the Repository must do, and then in the data layer, we write its actual implementation.

Repository: A repository class serves as a single source of truth, separating the logic that retrieves data and maps it to the entity model. In fact, this class collects data from various sources (REST APIs, local databases, cache, etc.) and provides it to the rest of the app. The other components have no idea where the data comes from; they simply consume it.

Applied to the Weather App

In our case, the domain layer will be divided into three distinct layers: entities, repository contracts, and use cases.

- Data

This layer is responsible for data retrieval from multiple sources. It consists of a repository class that implements the domain contract and determines whether to return fresh or cached data and when to cache it. Additionally, the data source class handles fetching data from a specific source, typically a remote API or local database.

Applied to the Weather App

Three layers will make up our data layer: datasources, implementations of repositories, and models. Due to the fact that every data source delivers it, we have the models folder rather than entities. In fact, each model is responsible for converting unstructured data (JSON, etc.) into Dart objects by using certain methods (fromJSON, toJSON, etc.).

Next up

After exploring the structure of the weather app, we'll start implementing the domain, which is the most independent layer: Next

Best Way to Become Flutter Developer – A Complete Roadmap

marwaMejri — Tue, 30 Aug 2022 13:12:53 +0000

Why Flutter?

This framework attracts the attention of many companies and development teams, its growth has taken place in a massive community of millions of people. In fact, Flutter is an open-source software development kit (SDK) created by Google and released in May 2017. It combines two important parts:

An SDK: a collection of software development tools in one installable package, that are going to facilitate the creation of your applications by having a compiler, debugger...
A Framework: a collection of reusable UI widgets that you can customize for your own needs.

What is more, Flutter is surrounded by extensive documentation provided by its owner which contains what every beginner needs to find like tutorials, examples etc. What can Flutter do? it allows to build an app for Android, iOS, Windows, Mac, Linux and Google Fuchsia using a single codebase with the quality of native apps, especially in Ui/Ux. What makes Flutter unique? compared to other cross-platform development applications like React Native that require bridges between their code and native elements, Flutter eliminates additional processing steps that decrease performance making it noticeably faster.

So, in this article, I want to recommend a multi-step roadmap for beginners to become a Flutter developer.

1. Pick a language:

The primary programming language of Flutter apps is Dart, which was founded by Google in 2011. It is a multi-platform asynchronous programming language that is typed, object-oriented, and client-optimized. So, what makes Dart stand out from other programming languages?

Optimized for UI: Dart is a programming language designed specifically for creating user interfaces, with features such as sound null safety, which protects you from null exceptions at runtime and increases productivity by removing all unnecessary testing.
Maximum productivity: the code is reloaded immediately thanks to hot reload, which is accomplished by a JIT compilation provided by the Dart virtual machine.
Fast on all platforms: Dart also uses an AOT compiler, which compiles your code into native ARM or x64 machine code for fast startup and consistent runtime performance.

Therefore, I advise a beginner to start studying Dart before diving into the fundamentals of Flutter.

Some useful learning resource links:

Practice, Practice !

Using an online DartPad code editor for beginners, you can practice your code and enhance your Dart language skills.

2. Flutter development environment

Before you start developing, you need know which IDE is the finest. So, in my opinion, and that of many other developers, I recommend utilizing Android Studio, IntelliJ, or VSCode. In reality, these IDEs assist you in developing sophisticated apps by providing code completion tools, syntax highlighting, widget editing assistance, runtime and debugging support, and other features.

3. Flutter fundamentals

After being familiar with Dart, it is now time to begin with Flutter Basics.

- Flutter Widgets:

Widgets are the primary building elements of every UI in a Flutter app, the entire screen is a widget, a button is a widget, text is a widget, and so on.

- Widget types:

Flutter widgets are classified into two types: stateless widgets and stateful widgets. Stateless widgets are immutable, so they cannot change their appearances or properties while the program is running or when an action is performed on the screen, such as an icon, text, etc. Stateful widgets, on the other hand, are a wonderful way to add interaction to your view. In fact, they can change their appearance in reaction to a user-triggered event or data update. To do so, you should override the createState() method, which returns the widget's state.
Check out the following sites for more information on the various types of Flutter widgets:

- InheritedWidget:

When you use the previous two widgets, you'll obtain a widget tree that you can inspect with the Flutter inspector. When you want to send data to the next widget in the tree, you must use the constructor of each widget to pass the data from one to the other, which is a time-consuming job, particularly for large apps.
The InheritedWidget solves the above problem by being able to persist data and communicate it to the widget tree without having to call each widget's constructor.
Please check out the following websites to learn more about how this widget works and how to implement it:

- Flutter's essential widgets:

Flutter has a set of strong basic widgets such as Text, Icon, Row, Stack, Container, and others. These are the widgets that you must know before developing your first application and that will assist you in creating your customized widgets.

When exploring different Flutter widgets, you will most likely come across two types of Google design guidelines.

- Flutter design guidelines:

Any Flutter app is either Material or Cupertino designed. Google built the Material design system to support any platform, not just Android, but also iOS, web, and desktop apps. Indeed, this design includes a number of components and technologies that support best standards in user interface design. However, if you want your app to look like a regular iOS app, you should use the Cupertino library. For each of these design principles, Flutter offers a variety of widgets, so you may check out the following links to become more familiar with Flutter design elements:

- Navigation and Routing:

The majority of Flutter apps have multiple screens, therefore you should transition between them to access a different one and pass data as needed. In this situation, Flutter gives us the Navigator class, whose primary function is to control the navigation of your application.

So far, what we've seen in navigation is suitable for small projects. However, as the project grows, we want to manage all routes in one location using a powerful solution. As a result, the Flutter community created the auto-route package, which uses code generation to simplify route setup.

- Use of Assets:

To make apps more enjoyable, we use custom assets like images, videos, fonts and audios. Each element is a static file that must be included in the application. Remember to only include the files that are required to keep the application size as little as possible.

4. Advanced UI:

Using the basic Flutter widgets or your own custom widgets, you can construct static user interfaces up to this point. However, most apps also include dynamic screens, such as a splash screen with a colorful loading animation, a dynamic list for data analysis, and others. So it's time to start learning how to design dynamic screens that conform to your specifications.

- Dynamic user interface:

As we've already mentioned, the primary principle of the Flutter Framework is the use of widgets. Almost everything is a widget, including elements that are hidden from view like Rows, Columns, GridViews, and ListViews that order your visible items. Several layouts are offered in Flutter, and which one you choose depends on how you want to constrain the visible widgets.
To practice creating layouts, see the following documentation:

- Add interactivity to your app:

So far, you can create a static widget-based screen to expose certain information or a dynamic layout to organize your elements. However, it is essential that your app interacts with user actions in various forms, such as gestures, taps, and so on.
Flutter creates several stateful widgets to accomplish this, such as Checkbox, Slider, GestureDetector, Text Field, and others. These widgets are capable of meeting your needs.

- Animations:

Developing dynamic user interfaces with user interactivity is an important step at this point, but if you want people to have fun while using your app, adding animation is the way to go. Using animation to attract users' attention to parts of an app is an excellent way to do it. Flutter provides various ready-to-integrate animation widgets to help with animation implementation, such as: AnimatedContainer, Hero widget, AnimatedOpacity, AnimatedSize, AnimatedPositioned, and so on. Furthermore, you can construct your own animation by combining several additional widgets provided by the framework.

Learning Resources:

- Responsive UI:

The Flutter framework's primary purpose is to construct applications for many operating systems from a single code base. This means that your program can be displayed on several screens of varying sizes, ranging from a watch to a huge device. In this case, you might think about designing a user interface that adjusts to different screen sizes smoothly.
As a solution, Flutter offers two fundamental ways of creating a responsive app:

Other useful widgets and classes for creating a responsive UI:

Here are a few resources for more information, including contributions from the Flutter community:

5. Networking:

Once you're comfortable with UI development, you should start learning about API call integration. Flutter API calls can be made using a variety of packages such as http, dio, retrofit, chopper, and so on. You can start with any of them, but it's always a good idea to start with http because it's the base package from which all other packages are built.

You need to learn:

Dart concepts for asynchronous programming
HTTP request methods (post,put,get,delete..)
How to use REST APIs with Flutter
How to convert JSON data to Dart objects

Learning Resources:

6. Data Persistence:

You may need to maintain data in local memory in order to directly access its value when needed. For this situation, the Flutter community provides you with several packages. However, for security reasons, you should always pay attention to the data to be saved.

Storage packages:

Shared-preferences: The shared preference package is used to store data locally on the device as a key-value pair. You should also be aware that this package does not save data in encrypted form.
Flutter-secure-storage: To solve the previous issue of saving values with better security, the Flutter community introduced the Flutter-secure-storage package, which is based on the IOS keychain and Android EncryptedSharedPreferences with V5.0.0 and more.

If your application must store a large amount of data while also querying it, It is suggested that you use a local database, and don't worry, you have various options:

7. The Art of State Management:

You can control the state of your screens at first by using the setState () function proposed by the Flutter team, but as your application grows in size and complexity, managing the state of your application becomes more difficult. Suppose you have an application with two screens and you want to pass data between them. It's easy. You can simply pass it through the constructors. However, if you have a huge application and need to transmit the value from page one to page five, the prior solution requires you to send the appropriate value to every screen constructor until you reach page five. State management comes in handy in this situation! Its primary role is to centralize all of the states of multiple UI components in order to handle data flow across the application.

Famous flutter state management libraries:

I appreciate you reading this article.

Conclusion

Through this blog, I covered all of the important topics that will help you become a Flutter developer .
Happy coding until next time.

What is Flutter and how it works? A brief introduction

marwaMejri — Tue, 05 Apr 2022 14:36:00 +0000

Flutter is an open-source software development kit (SDK) created by Google in 2015 with the name "Sky". Its alpha version was on May 2017 and it came to light on December 11, 2019 with its release version Flutter 1.12. It's used to build application for multiple operating systems like Android, iOS, Windows, Mac, Linux and Google Fuchsia by using a single codebase.
Besides, flutter is based on Google’s programming language called Dart. In fact, it is a typed and object-oriented programming language that can be compiled to machine code or transpiled to JavaScript. Moreover, Dart can be run as like an interpreted language on its own VM using JIT Compilation. In reality, JIT compilation holds both of the speed of compiled code and the flexibility of interpretation. In fact, the source code is compiled at runtime as bytecode, then it is interpreted (executed) using the Dart virtual machine.

What makes flutter a good choice?

•Open Source

Flutter is an open source framework surrounded with vast documentation provided by Google that contains what any beginner needs to find such as tutorials, samples, and more. Also, you can simply open the Flutter GitHub repo, view the source code, or look for existing issues. Besides, Flutter has a growing community that became increasingly active by developing helpful resources.

•Maximum productivity thanks to hot reload

Thanks to Flutter, you can change your code and see the results on emulators, simulators immediately using Hot reload feature. In fact, the changed code is reloaded in less than a second without restarting the app or wasting time.

•Better time-to-market speed

Generally, Flutter app needs almost fewer man-hours than building the same app separately for Android and iOS. In fact, it is rich with its own various components which can be used on several platforms. In this case, the developer doesn't need to create every platform specific code to attain the desired UI of the application which reduces the number of working hours.

•Single code base and native performance

With Flutter you only have to write a single code base to build cross-platform applications that perfectly perform like a Native app especially in UI/UX and functionality. This performance is due to the Dart's programming language compiler that builds the application directly into machine code, which eliminates any bugs of the interpretation process. In this case there’s no need for a JS bridge in the middle like other cross platform (React Native ...) for parsing and executing.

•Flutter Widgets catalog

Whether you are a client or an enterprise, your biggest concern is the performance of the application while investing in the mobile app development process. However, Flutter has all the fantastic widgets that look native to Android or iOS apps (following Material Design or Cupertino). Moreover, developers can create their own widgets as well.

How Does Flutter Work?

1. Flutter Framework Architecture

•Flutter Framework

Flutter framework is built based on Dart programming language, it holds a vast support of Material design and Cupertino style which help to create native UI for different platforms. Its main role consists of rendering widgets, state management, animations and many more.

•Flutter Engine

Flutter engine is written in C++. It implements Flutter core libraries which include text layout, file and network I/O, Dart runtime for compiling and executing applications. As well, it uses Google's graphics library Skia for rendering graphics.

•Flutter Platform Layer

The Platform layer is considered as the glue between the host OS and Flutter. In fact, it is responsible for the lifecycle of any app, including window sizing, thread manipulation and platform messages.

2. Flutter Base Component

What is a widget?

The major idea behind flutter framework is the use of widgets for building apps. In fact, it is regarded as the primary building blocks of every UI in Flutter app.

What are the different types of widgets?

a-Stateless Widget

Stateless widgets are immutable, so they don't require mutable state. In fact, those widgets cannot change their appearance and properties during the runtime of the app. In result, the build () method called only one time while the app is in activity.
Example of stateless Widget: Text, Icon, ...

b-Stateful Widget

Stateful widgets are dynamic. In fact, they can update their appearance based on a user triggered event or data change. To create a stateful widget, it is required to override the createState () method which returns the state of that widget.
Example of stateful Widget: Checkbox, Radio Button, ...

Flutter Widget Lifecycle

a-Stateful widget Lifecycle:

•CreateState():

The flutter framework calls this method immediately after creating a stateful widget. In fact, it's used to create a state object of the mentioned widget. Besides, once the state object was produced, a build Context is assigned to that widget. This build Context is used to specify the location of any widget inside the widget tree.
Moreover, this method can be called multiple times when we use the same widget in multiple places.

•initState():

This flutter method is called only once after creating the widget. In fact, this method is considered as the best place to initialize data or proprieties, even to subscribe to things that could change data like streams, changeNotifer and others.

•didChangeDependencies():

This method is called right away after initState (). Besides, it will be called when an object that this widget depends on changes.

•Build():

This method holds the tree of widgets. It's called every time when the UI needs to be rendered, for example, when we use a setState () method.

•didUpdateWidget(currentWidget oldWidget):

This method is called because of any changes within the parent widget. In fact, it has the currentWidget and the old one as a parameter so you can compare them to do some extra logic. Besides, in turn this method calls the build () method so no need to use setState () to rebuild the UI.

•setState():

The setState () method called by the framework and even from the developer itself. Its main role is to notify the framework that it should rebuild the widget.

•deactivate():

This Flutter method is rarely used. In fact, it's called when the state is removed from the widget tree, but it can be replaced before the current frame change is finished, which is the opposite of dispose () method.

•Dispose():

This method is called when the current object and its state are removed from the tree forever. Dispose method is the best place to unsubscribe to streams, cancel animations and more.

b-Stateless widget Lifecycle:

As mentioned above, stateless widgets only depend on their own configuration information. In other words, they don't care about any changes while the app is running. As a result, the stateless widget does not have the same lifecycle as the stateful widget, in fact it only calls the build () method once while the application is in action.

How does flutter render their widgets?

According to the documentation, "widget is an immutable description of part of a user interface". Then, a widget is an object whose state cannot be changed after its creation. However, UIs are not immutable and they can't be, therefore, how does Flutter represent change and handle the state of the UI?
In fact, Flutter framework composed of three trees: Widget tree, Element tree and Render Objects tree. The combination of those three trees allows Flutter to render UIs and display any state change.

a-What is an Element?

Refer to documentation Element is "An instantiation of a Widget at a particular location in the tree". In reality, the Element is considered as the changeable piece of the UI, which control the lifecycle of any widget. In fact, every element has a reference to a Widget.

b-What is a Render Object?

Render Object contains different protocols for painting and performing layout. In fact, it manages the tree of elements by rendering every single element.

Then, how does those three trees work together?

Example 1:

What happens here?

•Step one:

Flutter will create a widget tree which contains the center () and Text () widgets.

•Step two:

Every single widget called createElement method which generate an Element object in Element tree.

•Step three:

Each render object will be produced when an Element calls createRenderObject ().

Example 2:

In this example, we try to update the UI with the new text when we press the “change” Text widget.

What happens here?

The Render Object is considered as an expensive one, so instantiate it is a very sensible option. Therefore, how can we update the UI?

In reality, we will use the help of the Element tree which considered as the link between the two other trees and it hold the task of comparing the runtime type of both. If there is no difference, then, Render Object does not need to recreate it, just call updateRenderObject () method to update the value in question. If not, then new Element and Render Object trees will be produced.

This feature is one of several advantages of Flutter framework, indeed, every app contains various widgets, then rebuilding the whole tree for every modification is quite costly. For that reason, Flutter applies the concept of those three trees to minimize the processing which donates more optimal performance.

Reference:

https://docs.flutter.dev/

DEV Community: marwaMejri

Where Dart stops and Freezed starts

The short version

Introduction

1. Why Freezed had to exist

What a data class is, and why Dart makes it hard

What that cost in 2020

What Freezed did about it

2. What Dart shipped instead

Dart 3.0, May 2023

Macros, and why they matter here

The smaller pieces

The scoreboard

3. The same model, four ways

A — Freezed 4, the classic syntax

B — Equatable + copy_with_extension

C — Pure Dart 3.13

D — Freezed 4 with primary constructors

What the four have in common, and what they don't

4. What the numbers say

How this was measured

What the tests actually check

The one detail the whole suite rests on

The tests themselves

The results

What one more field costs you

Where the lines actually are

Finding 1 — the record trick breaks on collections, silently

Finding 2 — a hand-written union has no equality at all

Finding 3 — the obvious copyWith cannot clear a nullable field

Finding 4 — Equatable loses a field without telling you

Finding 5 — on freezed 4.0.1, a primary constructor and JSON don't mix

Finding 6 — build time is not an argument at this scale

Finding 7 — two things to check before you migrate

5. The arbitration

The default: keep Freezed

The exception: pure Dart, for models that stay simple

For your states: sealed classes, or Freezed?

Equatable: correct, and twice the size

And primary constructors?

So, do we still need Freezed?

Flutter Clean Architecture [2]: An Overview & Project Structure

Domain Layer

Entity

Repository & Error handling

Creating the sealed class

Creating the repository contract with the use of the sealed class

Use cases & callable classes

creating the base use case class

Extending the Base Class

Next up

Flutter Clean Architecture [3]: An Overview & Project Structure

Data Layer

Implementing the Models

Creating the model class with the use of the data mapper class

Implementing repository the contract

Implementing Data Sources

Remote Data Source

Local Data Source

Local Database

Local Data Source Implementation

Implementing the Repository

Next up

Flutter Clean Architecture [4]: An Overview & Project Structure

Presentation Layer

Responsive UI

Applied to the Weather App

Creating a base view model

Implementing the base view model

Creating the view

Conclusion

Flutter Clean Architecture [1]: An Overview & Project Structure

The Project That We Will Create

Flutter Clean Architecture and data flow

Project Organization

Explanation of feature layers

Applied to the Weather App

Applied to the Weather App

Applied to the Weather App

Next up

B — Equatable + `copy_with_extension`

Finding 3 — the obvious `copyWith` cannot clear a nullable field