fpdart

Description:

fpdart

Functional programming in Dart and Flutter


All the main functional programming types and patterns fully documented, tested, and with examples















Introduction #

fpdart is fully documented. You do not need to have any previous experience with functional programming to start using fpdart. Give it a try!

fpdart is inspired by fp-ts, cats, and dartz.

Follow my Twitter for updates, or subscribe to the newsletter



Introduction
📖 Learn functional programming and fpdart

✍️ Blog posts and tutorials
🧑‍🏫 Getting started with functional programming


💻 Installation
✨ Examples

fpdart + riverpod
Pokeapi
Open Meteo API
Read/Write local file
Manage imports
Option
Either
IO
Task
Utility types
Reader

ReaderTask
ReaderTaskEither


State
🔗 Do notation
📦 Immutable Collections
More


🎯 Types
💡 Motivation

Goal
Comparison with dartz


🤔 Roadmap
📃 Versioning
😀 Support
👀 License

📖 Learn functional programming and fpdart #
Would you like to know more about functional programming, fpdart, and how to use the package?
📚 Collection of tutorials on fpdart
Are you new to fpdart and functional programming?
👨‍💻 Getting started with fpdart complete guide
Interested in what fpdart is and how it came to be?
🚶 Full history of fpdart and functional programming in dart
✍️ Blog posts and tutorials #

Option type and Null Safety in dart
Either - Error Handling in Functional Programming
Future & Task: asynchronous Functional Programming
How to use TaskEither in fpdart
How to make API requests with validation in fpdart
How to map an Either to a Future in fpdart
Flutter Supabase Functional Programming with fpdart
fpdart, Functional Programming in Dart and Flutter
How to use fpdart Functional Programming in your Dart and Flutter app
Pure Functional app in Flutter – Pokemon app using fpdart and Functional Programming

🧑‍🏫 Getting started with functional programming #

Functional Programming Option type – Introduction
Chain functions using Option type – Functional Programming
Practical Functional Programming - Find repeated characters | Part 1
Pure Functions - Practical Functional Programming | Part 2
Immutability – Practical Functional Programming | Part 3
Loops using fold – Practical Functional Programming | Part 4
Maybe | Practical Functional Programming
5 Lessons from Functional Programming in Scala, By Paul Chiusano and Runar Bjarnason

💻 Installation #
# pubspec.yaml
dependencies:
fpdart: ^1.1.0
copied to clipboard
✨ Examples #
fpdart + riverpod #
Step by step course on how to build a safe, maintainable, and testable Flutter app using fpdart and riverpod.
Pokeapi #
Flutter app that lets you search and view your favorite Pokemon:

API request
Response validation
JSON conversion
State management (riverpod)

Open Meteo API #
Re-implementation using fpdart and functional programming of the Open Meteo API from the flutter_weather app example in the bloc package.
A 2 parts series explains step by step the Open Meteo API code:

Open Meteo API - Functional programming with fpdart (Part 1)
Open Meteo API - Functional programming with fpdart (Part 2)

Read/Write local file #
Example of how to read and write a local file using functional programming.
Manage imports #
Using fpdart with other libraries and noticing naming conflicts? Learn how to rename the classes that conflict with other SDK or third-party packages.
Option #
Used when a return value can be missing.

For example, when parsing a String to int, since not all String
can be converted to int

/// Create an instance of [Some]
final option = Option.of(10);

/// Create an instance of [None]
final none = Option<int>.none();

/// Map [int] to [String]
final map = option.map((a) => '$a');

/// Extract the value from [Option]
final value = option.getOrElse(() => -1);

/// Pattern matching
final match = option.match(
() => print('None'),
(a) => print('Some($a)'),
);

/// or use Dart's pattern matching as well 🤝
final dartMatch = switch (option) {
None() => 'None',
Some(value: final a) => 'Some($a)',
};

/// Convert to [Either]
final either = option.toEither(() => 'missing');

/// Chain computations
final flatMap = option.flatMap((a) => Option.of(a + 10));

/// Return [None] if the function throws an error
final tryCatch = Option.tryCatch(() => int.parse('invalid'));
copied to clipboard
Either #
Used to handle errors (instead of Exceptions).

Either<L, R>: L is the type of the error (for example a String explaining
the problem), R is the return type when the computation is successful

/// Create an instance of [Right]
final right = Either<String, int>.of(10);

/// Create an instance of [Left]
final left = Either<String, int>.left('none');

/// Map the right value to a [String]
final mapRight = right.map((a) => '$a');

/// Map the left value to a [int]
final mapLeft = right.mapLeft((a) => a.length);

/// Return [Left] if the function throws an error.
/// Otherwise return [Right].
final tryCatch = Either.tryCatch(
() => int.parse('invalid'),
(e, s) => 'Error: $e',
);

/// Extract the value from [Either]
final value = right.getOrElse((l) => -1);

/// Chain computations
final flatMap = right.flatMap((a) => Either.of(a + 10));

/// Pattern matching
final match = right.match(
(l) => print('Left($l)'),
(r) => print('Right($r)'),
);

/// or use Dart's pattern matching as well 🤝
final dartMatch = switch (right) {
Left(value: final l) => 'Left($l)',
Right(value: final r) => 'Right($r)',
};

/// Convert to [Option]
final option = right.toOption();
copied to clipboard
IO #
Wrapper around an sync function. Allows to compose synchronous functions that never fail.
/// Create instance of [IO] from a value
final IO<int> io = IO.of(10);

/// Create instance of [IO] from a sync function
final ioRun = IO(() => 10);

/// Map [int] to [String]
final IO<String> map = io.map((a) => '$a');

/// Extract the value inside [IO] by running its function
final int value = io.run();

/// Chain another [IO] based on the value of the current [IO]
final flatMap = io.flatMap((a) => IO.of(a + 10));
copied to clipboard
Task #
Wrapper around an async function (Future). Allows to compose asynchronous functions that never fail.

If you look closely, it's the same as IO but for async functions 💡

/// Create instance of [Task] from a value
final Task<int> task = Task.of(10);

/// Create instance of [Task] from an async function
final taskRun1 = Task(() async => 10);
final taskRun2 = Task(() => Future.value(10));

/// Map [int] to [String]
final Task<String> map = task.map((a) => '$a');

/// Extract the value inside [Task] by running its async function
final int value = await task.run();

/// Chain another [Task] based on the value of the current [Task]
final flatMap = task.flatMap((a) => Task.of(a + 10));
copied to clipboard
Utility types #
These types compose together the 4 above (Option, Either, IO, Task) to join together their functionalities:

IOOption: sync function (IO) that may may miss the return value (Option)
IOEither: sync function (IO) that may fail (Either)
TaskOption: async function (Task) that may miss the return value (Option)
TaskEither: async function (Task) that may fail (Either)

Reader #
Read values from a context without explicitly passing the dependency between multiple nested function calls. View the example folder for an explained usecase example.
ReaderTask
Combine the Reader type (dependecy) with Task (asynchronous).
ReaderTaskEither
Combine the Reader type (dependecy) with Task (asynchronous) and Either (error handling).
State #
Used to store, update, and extract state in a functional way. View the example folder for an explained usecase example.
🔗 Do notation #
Version v0.6.0 introduced the Do notation in fpdart. Using the Do notation makes chaining functions easier.
For example, a typical chain of methods in fpdart looks as follows:
/// Without the Do notation
String goShopping() => goToShoppingCenter()
.alt(goToLocalMarket)
.flatMap(
(market) => market.buyBanana().flatMap(
(banana) => market.buyApple().flatMap(
(apple) => market.buyPear().flatMap(
(pear) => Option.of('Shopping: $banana, $apple, $pear'),
),
),
),
)
.getOrElse(
() => 'I did not find 🍌 or 🍎 or 🍐, so I did not buy anything 🤷‍♂️',
);
copied to clipboard
Notice how you need to call flatMap multiple times to collect multiple variables and use them together (market, banana, apple, pear).
Everything looks more linear and simple by using the Do notation:
/// Using the Do notation
String goShoppingDo() => Option.Do(
(_) {
final market = _(goToShoppingCenter().alt(goToLocalMarket));
final amount = _(market.buyAmount());

final banana = _(market.buyBanana());
final apple = _(market.buyApple());
final pear = _(market.buyPear());

return 'Shopping: $banana, $apple, $pear';
},
).getOrElse(
() => 'I did not find 🍌 or 🍎 or 🍐, so I did not buy anything 🤷‍♂️',
);
copied to clipboard
You initialize the Do notation using the Do() constructor.
You have access to a _ function, that you can use to extract and use the value inside each Option, without using flatMap.

Note: We recommend using the Do notation whenever possible to improve the legibility of your code 🤝

📦 Immutable Collections #

If you are going to use fpdart in your project, make sure to use immutable collections as well ☝️

Immutability is at the core of functional programming (alongside pure functions 🤝).
fpdart does not provide immutable collections. Instead, we strongly suggest to use the fast_immutable_collections package.
fast_immutable_collections provides all the necessary immutable collections (List, Set, Map and more) with an extensive API and top-class performance.
fpdart instead provides some extension methods on Iterable, List, and Map. These are designed to extend the native Dart API with immutable methods, as well as providing many handy additional functions:
/// Dart: `1`
[1, 2, 3, 4].first;

/// fpdart: `Some(1)`
[1, 2, 3, 4].head;

/// Dart: Throws a [StateError] ⚠️
[].first;

/// fpdart: `None()`
[].head;

final map = {'a': 1, 'b': 2};

/// Dart: mutable ⚠️
map.updateAll((key, value) => value + 10);

/// fpdart: immutable equivalent 🤝
final newMap = map.mapValue((value) => value + 10);
copied to clipboard
You can use these extension methods on any native Dart collection and also in combination with fast_immutable_collections immutable collections.
More #
Many more examples are coming soon. Check out my website and my Twitter for daily updates.

🎯 Types #

Option
Either
Unit
IO
IORef
IOOption
IOEither
Task
TaskOption
TaskEither
Reader
ReaderTask
ReaderTaskEither
State
StateAsync
Iterable (List) extension
Map extension
Predicate
ReaderTaskOption
ReaderIO
ReaderIOEither
ReaderIOOption
ReaderEither
ReaderOption
StateReaderTaskEither
Lens
Writer

💡 Motivation #
📚 Read the full story of the origin and motivation for fpdart
Functional programming is becoming more and more popular, and for good reasons.
Many non-functional languages are slowly adopting patterns from functional languages, dart included. Dart already supports higher-order functions, generic types, type inference. Since Dart 3, the language supports also pattern matching, destructuring, multiple return values (Read more about these new features here).
Other functional programming features are coming to the language, like higher-order types.
Many packages are bringing functional patterns to dart, like the amazing freezed for unions/pattern matching.
fpdart aims to provide all the main types found in functional languages to dart. Types like Option (handle missing values without null), Either (handle errors and error messages), Task (composable async computations), and more.
Goal #
Differently from many other functional programming packages, fpdart aims to introduce functional programming to every developer. For this reason, every type and method is commented and documented directly in the code.

You do not need to have any previous experience with functional programming to start using fpdart.

fpdart also provides real-world examples of why a type is useful and how it can be used in your application. Check out my website for blog posts and articles.
Comparison with dartz #
One of the major pain points of dartz has always been is lack of documentation. This is a huge issue for people new to functional programming to attempt using the package.
dartz was released in 2016, initially targeting Dart 1.
dartz is also missing some features and types (Reader, TaskEither, and others).
fpdart is a rewrite based on fp-ts and cats. The main differences are:

fpdart is fully documented.
fpdart implements higher-kinded types using defunctionalization.
fpdart is based on Dart 3.
fpdart is completely null-safe from the beginning.
fpdart has a richer API.
fpdart implements some missing types in dartz.
fpdart does not provide implementation for immutable collections (ISet, IMap, IHashMap, AVLTree).

🤔 Roadmap #
Being documentation and stability important goals of the package, every type will go through an implementation-documentation-testing cycle before being considered as 'stable'.
The current work on fpdart aims to:

Expand the API to include more methods to work and convert between types easier (send an issue on the repository if you have a suggestion)
Simplify the current API to make it easier to use and learn
Expand the documentation with more articles and documentation comments


Note: There is also an experimental research in progress to implement ZIO in fpdart, stay tuned 🔜


The long-term goal is to provide all the main types and typeclasses available in other functional programming languages and packages. All the types should be completely documented and fully tested.
A well explained documentation is the key for the long-term success of the project. Any article, blog post, or contribution is welcome.
In general, any contribution or feedback is welcome (and encouraged!).
📃 Versioning #

v1.1.0 - 13 August 2023
v1.0.0 - 26 July 2023



v0.6.0 - 6 May 2023
v0.5.0 - 4 March 2023
v0.4.1 - 25 February 2023
v0.4.0 - 16 December 2022
v0.3.0 - 11 October 2022
v0.2.0 - 16 July 2022
v0.1.0 - 17 June 2022
v0.0.14 - 31 January 2022
v0.0.13 - 26 January 2022
v0.0.12 - 24 October 2021
v0.0.11 - 22 September 2021
v0.0.10 - 13 August 2021
v0.0.9 - 3 August 2021
v0.0.8 - 13 July 2021
v0.0.7 - 6 July 2021
v0.0.6 - 29 June 2021
v0.0.5 - 20 June 2021
v0.0.4 - 15 June 2021
v0.0.3 - 13 June 2021
v0.0.2 - 13 June 2021
v0.0.1 - 28 May 2021

😀 Support #
If you are interested in my work you can subscribe to my newsletter.
I share tutorials, guides, and code snippets about fpdart and functional programming: Subscribe to the Newsletter here 📧
For more frequent updates you can also follow me on my Twitter.
👀 License #
MIT License, see the LICENSE.md file for details.