CSharpEssentials.Maybe 8.0.0

dotnet add package CSharpEssentials.Maybe --version 8.0.0
                    
NuGet\Install-Package CSharpEssentials.Maybe -Version 8.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CSharpEssentials.Maybe" Version="8.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CSharpEssentials.Maybe" Version="8.0.0" />
                    
Directory.Packages.props
<PackageReference Include="CSharpEssentials.Maybe" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CSharpEssentials.Maybe --version 8.0.0
                    
#r "nuget: CSharpEssentials.Maybe, 8.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CSharpEssentials.Maybe@8.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CSharpEssentials.Maybe&version=8.0.0
                    
Install as a Cake Addin
#tool nuget:?package=CSharpEssentials.Maybe&version=8.0.0
                    
Install as a Cake Tool

CSharpEssentials.Maybe

Maybe<T> (an Option type) makes a missing value explicit. It has Map, Bind, Where, Match, Or and Tap, LINQ query syntax, async overloads, conversion to and from Result<T>, and sequence helpers (TryFirst, TryLast, TryFind, Choose, Sequence, Traverse, Partition).

Targets net11.0, net10.0, net9.0 and netstandard2.1. Depends on CSharpEssentials.Results and CSharpEssentials.Errors. Maybe<T> and the non-generic Maybe (for Maybe.None, Maybe.From, Maybe.FromAsync and Maybe.FromTry) live in the CSharpEssentials.Maybe namespace.

Benchmarks of TryFirst, TryLast, TryFind and Choose against CSharpFunctionalExtensions and hand-written loops are in BENCHMARKS.md.

Installation

dotnet add package CSharpEssentials.Maybe

Usage

Creating a Maybe

using CSharpEssentials.Maybe;

public Maybe<User> FindUser(int id)
{
    User? user = _repo.Find(id);
    return user; // implicit from T? to Maybe<T>
}

Maybe<string> none = Maybe.None;
Maybe<int> value = 42;

Maybe<string> name = Maybe.From("Ann");                       // the non-generic Maybe infers T
Maybe<int> five = 5.AsMaybe();
Maybe<int> parsed = Maybe.FromTry(() => int.Parse("42"));
Maybe<string> lazy = Maybe.From(() => Environment.GetEnvironmentVariable("HOME"));

From gives None for null. Maybe<T> serializes with System.Text.Json as {"HasValue":true,"value":5} and deserializes back from that shape.

Functional chaining

string city = FindUser(1)
    .Where(u => u.IsActive)
    .Map(u => u.Address)
    .Map(a => a.City)
    .GetValueOrDefault("Unknown");

LINQ queries

Maybe<string> tracking =
    from user in FindUser(1)
    from order in FindOrder(user.Id)
    where order.Amount > 100
    select order.TrackingNumber;

Matching

FindUser(1).Match(
    some: user => Console.WriteLine($"Found: {user.Name}"),
    none: () => Console.WriteLine("Not found"));

string label = FindUser(1).Match(some: u => u.Name, none: () => "stranger");

string loaded = await FindUser(1).MatchAsync(
    some: async (u, ct) => await LoadProfileAsync(u, ct),   // async handlers receive a CancellationToken
    none: async ct => await LoadAnonymousAsync(ct),
    cancellationToken: token);

Reading the value

Maybe<int> maybe = 5;

if (maybe.HasValue) { int v = maybe.Value; }          // Value throws InvalidOperationException on None
bool found = maybe.TryGetValue(out int value);
var (hasValue, inner) = maybe;                          // Deconstruct

int a = maybe.GetValueOrDefault(0);                    // fallback value
int b = maybe.GetValueOrDefault(() => 0);              // lazy fallback
int c = maybe.GetValueOrDefault(v => v * 2, -1);       // map when Some, else the fallback
int d = maybe.GetValueOrThrow("missing");              // or GetValueOrThrow(new MyException())
int? e = maybe.AsNullable();                           // T? for reference types; default(T) for value types
List<int> list = maybe.ToList();                       // one element, or empty

Filtering, fallbacks and side effects

Maybe<int> big = maybe.Where(v => v > 3);               // None when the predicate fails
Maybe<int> alt = Maybe<int>.None.Or(7);                 // Or(Maybe<T>) (a plain T converts), Or(Func<T>), Or(Func<Maybe<T>>)

maybe.Tap(v => Console.WriteLine(v));                   // only when Some; returns the same Maybe
maybe.TapIf(v => v > 3, v => Console.WriteLine(v));     // predicate-gated tap
maybe.Execute(v => Console.WriteLine(v));               // Action<T> on Some
maybe.ExecuteNoValue(() => Console.WriteLine("none"));  // Action on None

Maybe<int> doubled = maybe.MapIf(v => v > 3, v => v * 2);
Maybe<int> kept = maybe.BindIf(v => v > 3, v => Maybe<int>.From(v + 1));

MapIf, BindIf and TapIf also take a bool or a Func<bool> condition. MapIfAsync and BindIfAsync exist on Maybe<T>, Task<Maybe<T>> and ValueTask<Maybe<T>>; TapIfAsync exists on the Task and ValueTask sources.

Converting to Result

Maybe<Order> order = FindOrder(1);
Result<Order> result = order.ToResult(Error.NotFound("Order.Missing", "Order not found."));

// Result -> Maybe
Result<Order> result2 = new Order();
Maybe<Order> maybe = result2.AsMaybe();

ToResult and ToUnitResult are aliases of ToMaybeResult and ToMaybeUnitResult. Without an error argument a None becomes the Maybe.Result NotFound error. Always pass the error to ToResult(error), or call ToMaybeResult(): maybe.ToResult() with no argument binds the generic ToResult<TValue>(this TValue value) of CSharpEssentials.Results and returns a successful Result<Maybe<T>>. AsMaybe on a failed Result<T> gives None and drops the errors. The async forms are ToResultAsync, ToUnitResultAsync, ToMaybeResultAsync, ToMaybeUnitResultAsync and AsMaybeAsync.

Async

Maybe<User> user = await FindUserAsync(1);
Maybe<Order> order = await user
    .BindAsync(u => GetOrderAsync(u.Id))
    .MapAsync(o => EnrichAsync(o));

Every Maybe member that returns Task or ValueTask ends in Async: WhereAsync, ExecuteAsync, ExecuteNoValueAsync, OrAsync, MatchAsync, ToMaybeResultAsync, ToMaybeUnitResultAsync and Maybe.FromAsync (maybe.ExecuteAsync(async v => ...), task.OrAsync(() => ...)). The old unsuffixed overloads still compile as [Obsolete] forwarders. OrElseAsync keeps its name. An untyped async lambda on an instance ExecuteAsync, ExecuteNoValueAsync, OrAsync, WhereAsync or MatchAsync, or on a key/value MatchAsync, binds to the Task overload through OverloadResolutionPriority, which needs C# 13 or later; on C# 12, type the lambda or pass a typed local such as Func<T, Task>. The instance MapAsync has a Task and a ValueTask twin without that priority, so maybe.MapAsync(async v => ...) is ambiguous (CS0121) on every language version; pass a lambda that returns a Task instead (maybe.MapAsync(v => LoadAsync(v))) or type the delegate.

Collection extensions

// None if any lookup is missing
Maybe<User[]> allUsers = userIds.Traverse(id => FindUser(id));

// Collect present values and count absences
var (values, missingCount) = maybes.Partition();

// Sequence: None if any element is None
Maybe<Config[]> configs = configMaybes.Sequence();
Method Returns Behavior
Sequence() Maybe<T[]> None if any element is None
Traverse(selector) Maybe<TOut[]> Applies selector then sequences
Partition() (T[] Values, int NoneCount) Never returns None; always splits
Choose() IEnumerable<T> Keeps the present values; Choose(selector) maps them too, ChooseAsync streams a sequence of Task<Maybe<T>>
TryFirst(), TryFirst(predicate), TryLast(), TryLast(predicate) Maybe<T> First or last element, None when there is none
dictionary.TryFind(key) Maybe<TValue> Lookup on an IReadOnlyDictionary

TryFirst and TryLast return None for an empty sequence or a predicate without a match, for value types too. A null element gives None. On an IList<T> or IReadOnlyList<T>, TryLast reads the last element by index, and TryLast(predicate) walks from the end and stops at the first match.

Choosing between T?, Maybe<T> and Result<T>

Use When Example
T? At boundaries: DTOs, entity columns, JSON public string? MiddleName { get; set; }
Maybe<T> Inside the domain, when absence is an expected state composed with Map/Bind Maybe<User> user = _cache.TryFind(id);
Result<T> When the failure carries a reason the caller acts on Result<User> user = FindUser(id);
Exceptions Only for bugs and invariant violations ArgumentNullException, broken invariants
// Boundary: a nullable column converts implicitly into the domain
Maybe<string> middleName = entity.MiddleName;

// Domain: absence is expected, compose it
string display = middleName.Map(n => n.ToUpperInvariant()).GetValueOrDefault("-");

// The caller needs to know why it is missing: upgrade to Result
Result<User> found = _cache.TryFind(id).ToMaybeResult(Error.NotFound("User.NotFound", "User does not exist"));
Equality

Maybe<T>.None never equals a non-null plain T: Maybe<int>.None == 0 is false, while Maybe<int>.From(0) == 0 is true. A typed null compares as absence: Maybe<string>.None == null is true and Maybe<string>.From("a") == null is false, in either operand order. Equals(object?) and maybe == (object?)null follow the BCL rule that x.Equals(null) is false, so Maybe<string>.None.Equals((object?)null) and Maybe<string>.None == (object?)null are both false. Use HasNoValue to test for absence. For a value type T, maybe == default means default(T) (so Maybe<int>.None == default is false), and Maybe<int> == null does not compile cleanly (CS9342, a known overload ambiguity), so use HasNoValue. ToString() returns Some(value) or None; IFormattable values are formatted with the invariant culture.

Exception-safe creation

using System.Text.Json;

// Returns None if the factory throws; OperationCanceledException is rethrown
Maybe<int> result = Maybe<int>.FromTry(() => int.Parse(userInput));
Maybe<User> user  = Maybe<User>.FromTry(() => JsonSerializer.Deserialize<User>(json));

TapNone: side effect on absence

Maybe<int> maybe = Maybe.None;

maybe.TapNone(() => logger.LogWarning("Value missing"));

// Async
await maybe.TapNoneAsync(async () => await NotifyAsync("Missing"));

// Via Task<Maybe<T>> / ValueTask<Maybe<T>>
await GetMaybeAsync().TapNoneAsync(() => logger.LogWarning("Value missing"));

GetValueOrElse: lazy fallback

// Factory called only on None; same as GetValueOrDefault(Func<T>)
int value = maybe.GetValueOrElse(() => ComputeExpensiveDefault());

Flatten

Maybe<int> inner = Maybe<Maybe<int>>.From(Maybe<int>.From(5)).Flatten(); // Some(5)

Maybe<int>? stored = null;              // e.g. a Maybe<int>? property mapped to a nullable column
Maybe<int> points = stored.Flatten();   // None

OrElse: lazy Maybe chain

// Alias of Or(Func<Maybe<T>>): the factory runs only on None
Maybe<Config> config = GetFromCache().OrElse(() => GetFromDatabase());

// Async
Maybe<Config> loaded = await GetFromCache().OrElseAsync(() => Task.FromResult(GetFromDatabase()));

Upgrading to 8.0

TryFirst on value-type sequences

TryFirst() and TryFirst(predicate) used to return Some(default) for a value-type sequence such as int[] when the sequence was empty or nothing matched. They now return None, like TryLast. Code that read Value from that Some(0) should check HasValue or use GetValueOrDefault.

TryLast(predicate) on lists

TryLast(predicate) on an IList<T> or IReadOnlyList<T> now calls the predicate from the last element backwards and stops at the first match, the way Enumerable.LastOrDefault does. The result is the same, but a predicate with side effects sees fewer calls in a different order. Other sequences are still enumerated from the start.

Cancellation in async operations

Async operations that take a CancellationToken and wait on a task source (Maybe.FromAsync, AsMaybeAsync, MapAsync, BindAsync, TapAsync, WhereAsync, OrAsync, ToResultAsync and the rest) wait through Core WithCancellation, which is Task.WaitAsync on the .NET 9, 10 and 11 targets. When the token is cancelled while they wait, they throw TaskCanceledException, a subclass of OperationCanceledException, instead of OperationCanceledException itself. A catch (OperationCanceledException) still catches it; an exact type check no longer matches. The netstandard2.1 asset is unchanged.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on CSharpEssentials.Maybe:

Package Downloads
CSharpEssentials

A comprehensive C# library enhancing functional programming capabilities with type-safe monads (Maybe, Result), discriminated unions (Any), and robust error handling. Features include: domain-driven design support, enhanced Entity Framework integration, testable time management, JSON utilities, and LINQ extensions. Built for modern C# development with focus on maintainability, testability, and functional programming principles.

CSharpEssentials.EntityFrameworkCore

Enhances Entity Framework Core with functional programming patterns and DDD-friendly features. Includes base entity classes, soft delete support, audit trails, query filters, optimistic concurrency, PostgreSQL integration, query performance monitoring, and domain event handling. Perfect for building maintainable and scalable data access layers in modern .NET applications.

CSharpEssentials.Mediator

High-performance CQRS and pipeline behaviors built on the Mediator source-generator library. Provides Result-integrated commands, queries, validation, logging, caching, transaction, lock and idempotency behaviors with a Result-first pipeline.

CSharpEssentials.These

These<E, A> is a third result type that can carry Left (error), Right (value), or Both. Ideal for partial success scenarios, batch validation, and warning systems.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
8.0.0 242 11/9/2026
7.0.0 247 10/20/2026
6.5.2 207 10/10/2026
6.5.1 205 10/10/2026
6.5.0 206 10/9/2026
6.4.0 215 10/9/2026
6.3.0 212 10/8/2026
6.2.0 204 10/8/2026
6.1.0 233 10/7/2026
6.0.0 219 10/7/2026
5.2.1 214 10/7/2026
5.2.0 219 10/7/2026
5.1.0 208 10/7/2026
5.0.0 214 10/6/2026
4.1.0 214 10/6/2026
4.0.0 221 10/5/2026
3.2.3 482 5/31/2026
3.2.2 262 5/31/2026
3.2.1 237 5/31/2026
3.2.0 232 5/30/2026
Loading failed