Functional Extensions for C#

This library helps write code in more functional way. To get to know more about the principles behind it, check out the Applying Functional Principles in C# Pluralsight course.

Installation

Available on NuGet

dotnet add package CSharpFunctionalExtensions

or

PM>Install-Package CSharpFunctionalExtensions

Core Concepts

Get rid of primitive obsession

Result<CustomerName>name=CustomerName.Create(model.Name);Result<Email>email=Email.Create(model.PrimaryEmail);Resultresult=Result.Combine(name,email);if(result.IsFailure)returnError(result.Error);varcustomer=newCustomer(name.Value,email.Value);

Make nulls explicit with the Maybe type

Maybe<Customer>customerOrNothing=_customerRepository.GetById(id);if(customerOrNothing.HasNoValue)returnError("Customer with such Id is not found: "+id);

Compose multiple operations in a single chain

return_customerRepository.GetById(id).ToResult("Customer with such Id is not found: "+id).Ensure(customer =>customer.CanBePromoted(),"The customer has the highest status possible").Tap(customer =>customer.Promote()).Tap(customer =>_emailGateway.SendPromotionNotification(customer.PrimaryEmail,customer.Status)).Finally(result =>result.IsSuccess?Ok():Error(result.Error));

Wrap multiple operations in a TransactionScope

return_customerRepository.GetById(id).ToResult("Customer with such Id is not found: "+id).Ensure(customer =>customer.CanBePromoted(),"The customer has the highest status possible").WithTransactionScope(customer =>Result.Success(customer).Tap(customer =>customer.Promote()).Tap(customer =>customer.ClearAppointments())).Tap(customer =>_emailGateway.SendPromotionNotification(customer.PrimaryEmail,customer.Status)).Finally(result =>result.IsSuccess?Ok():Error(result.Error));

API Examples

Maybe

Explicit Construction

Use case: Creating a new Maybe containing a value

Maybe<string>apple=Maybe<string>.From("apple");// orMaybe<string>apple=Maybe.From("apple");// type inference// orvarapple=Maybe.From("apple");

None/No Value

Use case: Replacing null or the Null Object Pattern for representing 'missing' data.

intstoreInventory= ...Maybe<string> fruit =storeInventory>0?Maybe<string>.From("apple"):Maybe<string>.None;// or where the generic type is a reference typeMaybe<string>fruit=null;// or where the generic type is a value typeMaybe<int>fruit=default;

Implicit Conversion

Use case: Easily creating a Maybe from a value

// Constructing a MaybeMaybe<string>apple="apple";// implicit conversion// Or as a method return valueMaybe<string>GetFruit(stringfruit){if(string.IsNullOrWhiteSpace(fruit)){returnMaybe<string>.None;}returnfruit;// implicit conversion}

Equality

Use case: Comparing Maybes or values without knowledge of the inner value of the Maybes

Maybe<string>apple="apple";Maybe<string>orange="orange";stringalsoOrange="orange";Maybe<string>noFruit=Maybe<string>.None;Console.WriteLine(apple==orange);// falseConsole.WriteLine(apple!=orange);// trueConsole.WriteLine(orange==alsoOrange);// trueConsole.WriteLine(alsoOrange==noFruit);// false

ToString

Maybe<string>apple="apple";Maybe<string>noFruit=Maybe<string>.None;Console.WriteLine(apple.ToString());// "apple"Console.WriteLine(noFruit.ToString());// "No value"

GetValueOrThrow

Use case: Procedurally accessing the inner value of the Maybe

Note: Calling this will throw a InvalidOperationException if there is no value

Maybe<string>apple="apple";Maybe<string>noFruit=Maybe<string>.None;Console.WriteLine(apple.GetValueOrThrow());// "apple";Console.WriteLine(noFruit.GetValueOrThrow());// throws InvalidOperationException !!Console.WriteLine(noFruit.GetValueOrThrow(newCustomException()));// throws CustomException !!

HasValue and HasNoValue

Use case: Procedurally checking if the Maybe has a value, usually before accessing the value directly

voidResponse(stringfruit){Console.WriteLine($"Yum, a {fruit} 😀");}Maybe<string>apple="apple";Maybe<string>noFruit=Maybe<string>.None;if(apple.HasValue){Response(apple.Value);// safe to access since we checked above}if(noFruit.HasNoValue){Response("We're all out of fruit 😢");}

GetValueOrDefault

Use case: Safely accessing the inner value, without checking if there is one, by providing a fallback if no value exists

voidResponse(stringfruit){Console.WriteLine($"It's a {fruit}");}Maybe<string>apple="apple";Maybe<string>unknownFruit=Maybe<string>.None;stringappleValue=apple.GetValueOrDefault("banana");stringunknownFruitValue=unknownFruit.GetValueOrDefault("banana");Response(appleValue);// It's a appleResponse(unknownFruitValue);// It's a banana

Where

Use case: Converting a Maybe with a value to a Maybe.None if a condition isn't met

Note: The predicate passed to Where (ex )

boolIsMyFavorite(stringfruit){returnfruit=="papaya";}Maybe<string>apple="apple";Maybe<string>favoriteFruit=apple.Where(IsMyFavorite);Console.WriteLine(favoriteFruit.ToString());// "No value"

Map

Use case: Transforming the value in the Maybe, if there is one, without needing to check if the value is there

Note: the delegate (ex CreateMessage) passed to Maybe.Map() is only executed if the Maybe has an inner value

stringCreateMessage(stringfruit){return$"The fruit is a {fruit}";}Maybe<string>apple="apple";Maybe<string>noFruit=Maybe<string>.None;Console.WriteLine(apple.Map(CreateMessage).Unwrap("No fruit"));// "The fruit is a apple"Console.WriteLine(noFruit.Map(CreateMessage).Unwrap("No fruit"));// "No fruit"

Select

Alias: Maybe.Select() is an alias of Maybe.Map()

Bind

Use case: Transforming from one Maybe into another Maybe (like Maybe.Map but it transforms the Maybe instead of the inner value)

Note: the delegate (ex MakeAppleSauce) passed to Maybe.Bind() is only executed if the Maybe has an inner value

Maybe<string>MakeAppleSauce(Maybe<string>fruit){if(fruit=="apple")// we can only make applesauce from apples 🍎{return"applesauce";}returnMaybe<string>.None;}Maybe<string>apple="apple";Maybe<string>banana="banana";Maybe<string>noFruit=Maybe<string>.None;Console.WriteLine(apple.Bind(MakeAppleSauce).ToString());// "applesauce"Console.WriteLine(banana.Bind(MakeAppleSauce).ToString());// "No value"Console.WriteLine(noFruit.Bind(MakeAppleSauce).ToString());// "No value"

SelectMany

Alias: Maybe.SelectMany() is an alias of Maybe.Bind()

Choose

Use case: Filter a collection of Maybes to only the ones that have a value, and then return the value for each, or map that value to a new one

Note: the delegate passed to Maybe.Choose() is only executed on the Maybes of the collection with an inner value

IEnumerable<Maybe<string>>unknownFruits=new[]{"apple",Maybe<string>.None,"banana"};IEnumerable<string>knownFruits=unknownFruits.Choose();IEnumerable<string>fruitResponses=unknownFruits.Choose(fruit =>$"Delicious {fruit}");Console.WriteLine(string.Join(", ",fruits))// "apple, banana"
Console.WriteLine(string.Join(", ",fruitResponses))// "Delicious apple, Delicious banana"

Execute

Use case: Safely executing a void (or Task) returning operation on the Maybe inner value without checking if there is one

Note: the Action (ex PrintFruit) passed to Maybe.Execute() is only executed if the Maybe has an inner value

voidPrintFruit(stringfruit){Console.WriteLine($"This is a {fruit}");}Maybe<string>apple="apple";Maybe<string>noFruit=Maybe<string>.None;apple.Execute(PrintFruit);// "This is a apple"noFruit.Execute(PrintFruit);// no output to the console

ExecuteNoValue

Use case: Executing a void (or Task) returning operation when the Maybe has no value

voidLogNoFruit(stringfruit){Console.WriteLine($"There are no {fruit}");}Maybe<string>apple="apple";Maybe<string>banana=Maybe<string>.None;apple.ExecuteNoValue(()=>LogNoFruit("apple"));// no output to consolebanana.ExecuteNoValue(()=>LogNoFruit("banana"));// "There are no banana"

Or

Use case: Supplying a fallback value Maybe or value in the case that the Maybe has no inner value

Note: The fallback Func<T> (ex () => "banana") will only be executed if the Maybe has no inner value

Maybe<string>apple="apple";Maybe<string>banana="banana";Maybe<string>noFruit=Maybe<string>.None;Console.WriteLine(apple.Or(banana).ToString());// "apple"Console.WriteLine(noFruit.Or(()=>banana)).ToString());// "banana"Console.WriteLine(noFruit.Or("banana").ToString());// "banana"Console.WriteLine(noFruit.Or(()=>"banana").ToString());// "banana"

Match

Use case: Defining two operations to perform on a Maybe. One to be executed if there is an inner value, and the other to executed if there is not

Maybe<string>apple="apple";Maybe<string>noFruit=Maybe<string>.None;// Void returning Matchapple.Match(
fruit =>Console.WriteLine($"It's a {fruit}"),()=>Console.WriteLine("There's no fruit"));// Mapping MatchstringfruitMessage=noFruit.Match(
fruit =>$"It's a {fruit}",()=>"There's no fruit"));Console.WriteLine(fruitMessage);// "There's no fruit"

TryFirst and TryLast

Use case: Replacing .FirstOrDefault() and .LastOrDefault() so that you can return a Maybe instead of a null or value type default value (like 0, false) when working with collections

IEnumerable<string>fruits=new[]{"apple","coconut","banana"};Maybe<string>firstFruit=fruits.TryFirst();Maybe<string>probablyABanana=fruits.TryFirst(fruit =>fruit.StartsWith("ba"));Maybe<string>aPeachOrAPear=fruits.TryFirst(fruit =>fruit.StartsWith("p"));Console.WriteLine(firstFruit.ToString());// "apple"Console.WriteLine(probablyABanana.ToString());// "banana"Console.WriteLine(aPeachOrAPear.ToString());// "No value"Maybe<string>lastFruit=fruits.TryLast();Maybe<string>anAppleOrApricot=fruits.TryLast(fruit =>fruit.StartsWith("a"));Console.WriteLine(lastFruit.ToString());// "banana"Console.WriteLine(anAppleOrApricot.ToString());// "apple"

TryFind

Use case: Safely getting a value out of a Dictionary

Dictionary<string,int>fruitInventory=new(){{"apple",10},{"banana",2}};Maybe<int>appleCount=fruitInventory.TryFind("apple");Maybe<int>kiwiCount=fruitInventory.TryFind("kiwi");Console.WriteLine(appleCount.ToString());// "10"Console.WriteLine(kiwiCount.ToString());// "No value"

ToResult

Use case: Representing the lack of an inner value in a Maybe as a failed operation

Note: See Result section below

Maybe<string>fruit="banana";Maybe<string>noFruit=Maybe<string>.None;stringerrorMessage="There was no fruit to give";Result<string>weGotAFruit=fruit.ToResult(errorMessage);Result<string>failedToGetAFruit=noFruit.ToResult(errorMessage);Console.WriteLine(weGotAFruit.Value);// "banana"Console.WriteLine(failedToGetAFruit.Error);// "There was no fruit to give"

Result

Explicit Construction: Success and Failure

Use case: Creating a new Result in a Success or Failure state

recordFruitInventory(stringName,intCount);Result<FruitInventory>appleInventory=Result.Success(newFruitInventory("apple",4));Result<FruitInventory>failedOperation=Result.Failure<FruitInventory>("Could not find inventory");ResultsuccessInventoryUpdate=Result.Success();

Conditional Construction: SuccessIf and FailureIf

Use case: Creating successful or failed Results based on expressions or delegates instead of if/else statements or ternary expressions

boolonTropicalIsland=true;ResultfoundCoconut=Result.SuccessIf(onTropicalIsland,"These trees seem bare 🥥");ResultfoundGrapes=Result.FailureIf(()=>onTropicalIsland,"No grapes 🍇 here");// orboolisNewShipmentDay=true;Result<FruitInventory>appleInventory=Result.SuccessIf(isNewShipmentDay,newFruitInventory("apple",4),"No 🍎 today");Result<FruitInventory>bananaInventory=Result.SuccessIf(()=>isNewShipmentDay,newFruitInventory("banana",2),"All out of 🍌");// orboolafterBreakfast=true;Result<FruitInventory>orangeInventory=Result.FailureIf(afterBreakfast,newFruitInventory("orange",10),"No 🍊 today");Result<FruitInventory>grapefruitInventory=Result.FailureIf(()=>afterBreakfast,newFruitInventory("grapefruit",5),"No grapefruit 😢");

Implicit Conversion

Use case: Easily creating a successful result from a value

Result<FruitInventory>appleInventory=newFruitInventory("apple",4);ResultfailedInventoryUpdate="Could not update inventory";

ToString

Use case: Printing out the state of a Result and its inner value or error

Result<FruitInventory>appleInventory=newFruitInventory("apple",4);Result<FruitInventory>bananaInventory=Result.Failure<FruitInventory>("Could not find any bananas");ResultfailedInventoryUpdate="Could not update inventory";ResultsuccessfulInventoryUpdate=Result.Success();Console.WriteLine(appleInventory.ToString());// "Success(FruitInventory { Name = apple, Count = 4 })"Console.WriteLine(bananaInventory.ToString());// "Failure(Could not find any bananas)"Console.WriteLine(failedInventoryUpdate.ToString());// "Failure(Could not update inventory)"Console.WriteLine(successfulInventoryUpdate.ToString());// "Success"

Map

Use case: Transforming the inner value of a successful Result, without needing to check on the success/failure state of the Result

Note: the delegate (ex CreateMessage) passed to Result.Map() is only executed if the Result was successful

stringCreateMessage(FruitInventoryinventory){return$"There are {inventory.Count}{inventory.Name}(s)";}Result<FruitInventory>appleInventory=newFruitInventory("apple",4);Result<FruitInventory>bananaInventory=Result.Failure<FruitInventory>("Could not find any bananas");Console.WriteLine(appleInventory.Map(CreateMessage).ToString());// "Success(There are 4 apple(s))"Console.WriteLine(bananaInventory.Map(CreateMessage).ToString());// "Failure(Could not find any bananas)"

MapError

Use case: Transforming the inner error of a failed Result, without needing to check on the success/failure state of the Result

Note: the delegate (ex ErrorEnhancer) passed to Result.MapError() is only executed if the Result failed

stringErrorEnhancer(stringerrorMessage){return$"Failed operation: {errorMessage}";}Console.WriteLine(appleInventory.MapError(ErrorEnhancer).ToString());// "Success(FruitInventory { Name = apple, Count = 4 })"Console.WriteLine(bananaInventory.MapError(ErrorEnhancer).ToString());// "Failed operation: Could not find any bananas"

Testing

CSharpFunctionalExtensions.FluentAssertions

A small set of extensions to make test assertions more fluent when using CSharpFunctionalExtensions! Check out the repo for this library more information!

Includes custom assertions for

• Maybe
• Result
• Result
• Result<T, E>
• UnitResult

Example

varresult=Result.Success(420);result.Should().Succeed();// passesresult.Should().SucceedWith(420);// passesresult.Should().SucceedWith(69);// throwsresult.Should().Fail();// throws

Read or Watch more about these ideas

• Functional C#: Primitive obsession
• Functional C#: Non-nullable reference types
• Functional C#: Handling failures, input errors
• Applying Functional Principles in C# Pluralsight course

Related Projects

• Typescript Functional Extensions
• UniTask extensions for Unity

Contributors

A big thanks to the project contributors!

• tinytownsoftware
• piotr121993
• Dmitry Korotin
• michalsznajder
• Xavier
• Julien Aspirot
• Kyle McMaster
• Vinícius Beloni Cubas
• rutkowskit
• Giovanni Costagliola
• Mark Wainwright
• ProphetLamb
• Paul Williams
• alexmurari
• ruud
• Tomasz Malinowski
• Staffan Wingren
• Tim Schneider
• Piotr Karasiński
• Marcel Roozekrans
• guythetechie
• Logan Kahler
• Ali Khalili
• Andrei Andreev
• YudApps
• dataphysix
• Laszlo Lueck
• Sean G. Wright
• Samuel Viesselman
• Stian Kroknes
• dataneo
• michaeldileo
• Renato Ramos Nascimento
• Patrick Drechsler
• Vadim Mingazhev
• Darick Carpenter
• Stéphane Mitermite
• Markus Nißl
• Adrian Frielinghaus
• svroonland
• JvSSD
• mnissl
• Vladimir Makaev
• Ben Smith
• pedromtcosta
• Michał Bator
• mukmyash
• azm102
• ThomasDC
• bopazyn
• Joris Goovaerts
• Ivan Deev
• Damian Płaza
• ergwun
• Michael DiLeo
• Jean-Claude
• Matt Jenkins
• Michael Altmann
• Steven Giesel
• Anton Hryshchanka
• Mikhail Bashurov
• kostekk88
• Carl Abrahams
• golavr
• Sviataslau Hankovich
• Chad Gilbert
• Robert Sęk
• Sergey Solomentsev
• Malcolm J Harwood
• Dragan Stepanovic
• Ivan Novikov
• Denis Molokanov
• Gerald Wiltse
• yakimovim
• Alex Erygin
• Omar Aloraini