Toarnbeike.Optional 2.1.0

Toarnbeike.Optional

This package provides a lightweight and expressive Option (Maybe) monad for explicit handling of missing values in .NET.

It introduces Option<TValue> type, inspired by functional programming and discriminated unions, while remaining idiomatic to the .NET ecosystem.

An Option<TValue> represents a value that can either be there, or be absent, without reling on nulls. It improves code clarity and safety by making the absence of a value explicit, replacing null checks and exceptions with a functional approach.

Features

• Explicit missing value handling Avoid using nulls for missing values; make absent a meaningful feature.
• Fluent extension methods: Compose operations with Bind, Map, Match, Reduce, and more.
• Fluent collection extensions: Handle collections with missing values using WhereValues, SelectValues, FirstOrNone and more.

• Seamless async support: Works naturally with Task and async pipelines.

• Functional programming inspired: Inspired by FP principles for predictable, readable, and maintainable error handling.

Contents

1. Quick start
2. Core concepts
3. Extensions
4. Collections
5. Linq query syntax
6. Test extensions
7. Conclusion

Quick start

This example demonstrates the most common workflow when using Options: construction, transformation and consumption.

using Toarnbeike.Optional;			
using Toarnbeike.Optional.Extensions;

Option<string> message = "Hello World!";
Option<string> missing = Option.None;

// Transform the value
var messageLength = message.Map(value => value.Length); // Option<int> with value 12
var newMissing = missing.Map(_ => "Not executed");      // Option<string>, still None.

// Consume the value
Console.WriteLine($"Message had {messageLength.Reduce(0)} characters");    // Message had 12 characters
Console.WriteLine($"Missing was replaced by: {newMissing.Reduce("Hello")); // Missing was replaced by: Hello

Key properties of working with Unions:

• null values and nullable notation is replaced with Option.
• Values are never consumed directly, but always using Reduce() or Match() to provide an alternative for a missing value.
• Mapping, binding, etc. modifies the value in an Option state, but missing values remain Option.None.

Core Concepts

What is an Option<TValue>

An option can represent either a value (Some) with an attached value of type TValue, or no value (None). At any point, the option is either Some, with value, or None, without value.

Any TValue can implicitly be converted to Option<TValue>; the option is a container (monad) that contains the value, and supplies functional methods to transform it's value.

What is None

None is a state of the Option<TValue> that indicated that no value is present. If the option is in the None state, a value can be supplied using the Reduce function, with reduces the Option<TValue> to TValue by providing an alternative value.

Construction

An Option<TValue> can either be created through the static factory methods on Option<TValue>, or using implicit conversions. In the example below, some1 and some2 are equivalent, as are none1 and none2.

Option<int> some1 = 42;
var some2 = Option<int>.Some(42);

Option<int> none1 = Option.None;
var none2 = Option<int>.None();

Transformations

Options can be transformed on value using the many provided extension methods. For an overview of the available methods, see Extension methods. For a detailed description of each of the methods, see Extension docs.

Consumption

Options can be consumed either by

• using the Reduce method. This provides an alternative value when the option is None.
• using the Match method. This requires a delegate for both Some and None state.

string output = option.Reduce("fallback"); // if option whas None, the value fallback is used.
var match = option.Match(
    onSome: value => Console.WriteLine($"Some: {value}),
    onNone: () => Console.WriteLine("None));
)

Extensions

The Toarnbeike.Optional.Extensions namespace includes rich extensions for Option<T>:

Available Extensions

All methods support async variants and operate seamlessly with Task<Option<TValue>>.

For information per method, see the Extensions docs.

Collections

The Toarnbeike.Optional.Collections namespace contains extension methods to work with IEnumerable<Option<T>>:

Many of these methods come with predicate overloads to add additional filters, similar to their Linq equivalences.

For information per method, see the Collections docs.

Collections of T

In addition to extensions on IEnumerable<Option<T>>, the Toarnbeike.Optional.Collections namespace also contains extension methods that work on IEnumerable<T>:

All these methods also come with predicate overloads to add additional filters. These methods are also described in more detail in the Collections docs.

Linq query syntax

Toarnbeike.Results supports C# LINQ query syntax for composing Option<TValue> pipelines using from, select, let, and where.

This provides an alternative, declarative way to compose Bind, Map, and Check operations while preserving the same missing value propagation semantics.

None values are automatically propagated and short-circuit execution of the query.

See the LINQ extensions docs for details and examples.

Test extensions

The Toarnbeike.Optional.TestExtensions namespace provides simple test assertions for verifying Option<TValue> instances in unit tests.

The following assertions are included:

These methods are Test Framework Agnostic, as they throw a custom AssertionFailedException.

Conclusion

Nulls are dangerous and exceptions are control-flow. Options make illegal states unrepresentable.