Choosing Local State Intentionally

In React, there are many state management libraries available for global state. However, it is surprisingly difficult to find a good solution for managing local state. You might ask why one would want, or even prefer, local state over global state. The answer is fairly simple: global state can become messy and may introduce unintended side effects, since many components can end up coupled to the same shared state.

With local state, changes are isolated to the component where the state is used. This isolation improves testability and makes components easier to reason about and debug.

For simple cases, the useState hook works well enough, and basic derived state can be handled with useMemo. However, as local state grows in size or complexity, useState becomes less appealing. You end up tracking multiple state values along with how and where each one is updated. React does provide a built-in solution for this in the form of useReducer, which handles more complex local state well. That said, useReducer requires some upfront boilerplate, and its action-based approach can feel clunky in practice.

Scaling Local State with useState

Lets take the simple example using a counter to represent the use of local state while exploring how useState scales over time.

The useState hook works well for simple local state and keeps components easy to reason about. This example starts small, but it provides a useful foundation for seeing how local state can become harder to manage as additional behavior and derived values are introduced.

import { useState, useMemo, useRef } from 'react'

const App = () => {
    const [count, setCount] = useState(0)
    const doubledCount = useMemo(() => count * 2, [count])

    const increase = () =>
        setCount(count => count + 1)

    const multiplyBy = (x: number) =>
        setCount(count => count * x)

    const multiplyRef = useRef<HTMLInputElement>(null)

    return (
        <div>
            <div>Count is: {count}</div>
            <div>Doubled count is: {doubledCount}</div>

            <button onClick={increase}>Increase count</button>

            <div>
                multiply by:
                <input ref={multiplyRef} type="number" />

                <button
                    onClick={() =>
                        multiplyRef.current &&
                        multiplyBy(Number(multiplyRef.current.value))
                    }
                >
                    Apply Multiplication
                </button>
            </div>
        </div>
    )
}

The above example is a simple one that represents a single state of count which has a derived state of doubledCount and two actions increase and multiplyBy. Even adding one more state variable we increase the complexity and thus the state, memos, and callbacks grow. One solution is to address this with a reducer.

Centralization With Reducers

import { useMemo, useReducer, useRef } from "react"

type State = {
    count: number
}

type Action =
    | { type: "increase" }
    | { type: "multiply"; factor: number }

const initialState: State = {
    count: 0
}

const reducer = (state: State, action: Action): State => {
    switch (action.type) {
        case "increase":
            return { count: state.count + 1 }

        case "multiply":
            return { count: state.count * action.factor }

        default:
            return state
    }
}

const App = () => {
    const [state, dispatch] = useReducer(reducer, initialState)
    const doubledCount = useMemo(() => state.count * 2, [state.count])
    const multiplyRef = useRef<HTMLInputElement>(null)

    const increase = () => {
        dispatch({ type: "increase" })
    }

    const multiplyBy = (factor: number) => {
        dispatch({ type: "multiply", factor })
    }

    return (
        <div>
            <div>Count is: {state.count}</div>
            <div>Doubled count is: {doubledCount}</div>

            <button onClick={increase}>
                Increase count
            </button>

            <div>
                multiply by:
                <input ref={multiplyRef} type="number" />

                <button
                    onClick={() =>
                        multiplyRef.current &&
                        multiplyBy(Number(multiplyRef.current.value))
                    }
                >
                    Apply Multiplication
                </button>
            </div>
        </div>
    )
}

The reducer here does not provide much value yet, because it requires a fair amount of setup. One pet peeve of mine is that reducer logic often ends up in a switch statement. It works, and it is a common pattern, but it has always felt a bit redundant to me.

Quiddity's Approach

Redux appears to be falling out of favor, with many developers gravitating toward libraries that offer simpler and more expressive state management APIs, such as Jotai and Zustand. Seeing these projects made me wonder why local state could not benefit from the same level of elegance. That line of thinking ultimately led to Quiddity a simple and lightweight local state management library designed specifically for React components.

Quiddity simplifies local state management by removing much of the ceremony around defining state and by providing helpers that improve TypeScript ergonomics. In this post we will focus on using Quiddity with TypeScript. When using JavaScript, the combine function is not required, since its primary purpose is to improve type inference.

import { useRef } from "react"
import { create, combine } from "@oneirosoft/quiddity"

const useCounter = create(
    combine({ count: 0 }, set => ({
        increment: () =>
            set(state => ({ count: state.count + 1 })),

        multiplyBy: (factor: number) =>
            set(state => ({ count: state.count * factor }))
    })),
    state => ({
        doubledCount: state.count * 2
    })
)

const App = () => {
    const { 
        count, 
        doubledCount, 
        increment, 
        multiplyBy 
    } = useCounter()

    const multiplyRef = useRef<HTMLInputElement>(null)

    return (
        <div>
            <div>Count is: {count}</div>
            <div>Doubled count is: {doubledCount}</div>

            <button onClick={increment}>
                Increase count
            </button>

            <div>
                multiply by:
                <input ref={multiplyRef} type="number" />

                <button
                    onClick={() =>
                        multiplyRef.current &&
                        multiplyBy(Number(multiplyRef.current.value))
                    }
                >
                    Apply Multiplication
                </button>
            </div>
        </div>
    )
}

The approach Quiddity takes strikes a balance between the simplicity of useState and the structure of useReducer. Like useState, it keeps state local and easy to reason about. Like useReducer, it centralizes state transitions and derived values in one place. The difference is that it does so without introducing action objects, switch statements, or a separate dispatch step.

Compared to useState, this pattern scales more naturally as state grows. Related state updates, derived values, and behaviors live together, rather than being spread across multiple hooks and callbacks. Compared to useReducer, it removes much of the boilerplate and ceremony, allowing state changes to be expressed directly as functions with clear intent.

The result is local state that remains explicit and predictable, while staying lightweight and approachable. For components with non-trivial state, this can make the code easier to read, easier to extend, and easier to reason about over time.

In this post, we will refer to these higher-order array methods as sequence operators, since they operate over sequences of values in a declarative way.

You can find the accompanying example code on GitHub: Declarative Sequence Transformations

A sequence operator is a higher-order function that takes a sequence, like an array or list, applies a function to each element, and returns a new value or sequence, enabling declarative, step-by-step data transformations. Many modern languages provide their own versions of these operators, such as LINQ in C# or the Stream API in Java. In this post, we will focus on several core sequence operators using TypeScript as our example.

Throughout this article, we will make use of a Note type. Assume we already have data coming from some data source, and we will refer to it simply as notes. The aim here is to keep the article abstract and focused on transformations rather than mock data, so you will often see a variable called notes in the examples.

Type Reference

note.types.ts

interface Note {
    id: string
    title: string
    tags: string[]
    sections: Section[]
}

interface Section {
    heading: string
    links: string[]
    references: string[]
}

map(T => R)

map transforms each element in a sequence using a function and returns a new sequence of the same length. Each element of the sequence is passed to the mapping function.

We can apply a transformation to each element in the notes sequence to produce cards by extracting data from each note and reshaping it into a new type.

interface Card {
    id: string
    title: string
    sectionCount: number
    tagCount: number
}

const cards: Card[] = 
    notes.map<Card>(note => ({
        id: note.id,
        title: note.title,
        sectionCount: note.sections.length,
        tagCount: note.tags.length
    }))

The result is a new sequence where each Note has been transformed into a Card. The original notes array is left untouched, and a new cards array is produced with the same number of elements, but a different data shape.

filter(T => boolean)

filter evaluates each element in a sequence using a predicate function, that is, a function that returns a boolean. filter does not transform items in the list. Instead, it pares down the sequence such that the resulting sequence only contains elements for which the predicate evaluates to true.

We can apply a predicate to each element in the notes sequence to produce a new sequence of only those notes whose tags include 'functional'.

const functionalNotes: Note[] = 
    notes.filter(note => note.tags.includes('functional'))

We can also select out any notes that have sections.

const isNotEmpty = <T>(arr: T[]) => arr.length > 0

const notesWithContent: Note[] = 
    notes.filter(note => isNotEmpty(note.sections))

In the examples above, we pare down the original notes sequence based on the provided predicates. In the first example, we only keep notes that include a tag equal to "functional". In the second example, we only keep notes whose sections sequence is not empty.

flatMap(T => R[])

flatMap is very similar to map in that it applies a transformation to a sequence. The difference is that the provided function returns another sequence, which is then flattened down into a single sequence of elements.

We can use flatMap to grab all of the tags within each note and flatten those tags into a single sequence, without touching the original array.

const allTags: string[] = 
    notes.flatMap<string>(note => note.tags)

We can use the same concept to extract all links across all notes. Feel free to jump to the Type Reference section as a refresher on the shape of the Note type.

const allSections: Section[] = 
    notes.flatMap<Section>(note => note.sections)

const allLinks: string[] =
    allSections.flatMap<string>(section => section.links)

Now, let’s extend the example beyond simple extraction of strings and indulge in transforming notes to provide us with an entirely new sequence of link artifacts.

interface LinkArtifact {
    noteId: string
    heading: string
    url: string
}

const allLinkArtifacts: LinkArtifact[] =
    notes.flatMap(note =>
        note.sections.flatMap(section =>
            section.links.map(link => ({
                noteId: note.id,
                heading: section.heading,
                url: link
            }))
        )
    )

In the examples above, we are transforming a sequence of notes into various data shapes by extracting nested sequences, flattening them, extracting additional values, and then flattening again. In other words, we are applying a transformation over a sequence of sequences and flattening that down into a single sequence, conceptually: [[]] -> [].

Conceptually, flatMap can be hard to grasp. If it helps, focus on the simple example of extracting all tags from a sequence of notes and ending up with just a single sequence of tags in the end.

reduce((TState, TValue) => TState, TState)

reduce is a sequence operator that applies a function to each value of a sequence and accumulates the result into a single state value. On each pass, the current element from the sequence and the previous accumulator value are provided to the reducer function. The value returned becomes the next accumulator. reduce requires a seed, or initial value, to kick things off.

The following example is for explanation, as we could more easily get the count of all tags by first applying flatMap and then accessing the resulting length. However, counting all items in a sequence is a simple example to grasp conceptually, and thus a good introduction to reduce.

const allTags: string[] = 
    notes.flatMap(note => note.tags)

const tagCount: number =
    allTags.reduce((count: number, _tag: string) => count + 1, 0)

In the example above, we omit the use of the tag itself because we only care about the total count. For each element in the sequence, we add 1 to the current count, which becomes the next accumulator value. This continues until the end of the sequence is reached. You can think of this process as recursive in nature, since each step depends on the result of the previous one.

Now, let’s imagine that our goal is to count all of the individual unique tags in our notes and end up with a data shape that uses a tag as a key and its count as the value.

type TagCounts = Record<string, number>

const allTags: string[] =
    notes.flatMap(note => note.tags)

const counts: TagCounts =
    allTags.reduce<TagCounts>((accumulator: TagCounts, tag: string) => {
        const currentCount = accumulator[tag] ?? 0
        accumulator[tag] = currentCount + 1
        return accumulator
    }, {})

In the example above, we first use flatMap to extract all tags from the notes sequence, producing a simple structure to work with, a single sequence of tags. We then reduce that sequence down into a single data structure, a record whose keys are tags and whose values represent how many times each tag appears in the sequence.

Finally, in the below example, we use reduce to accumulate multiple sequences into a single structured result. Rather than reducing to a number or a simple value, we are reducing the sequence of notes into a richer data shape that contains two sequences, one for links and one for references.

interface Artifacts {
    links: string[]
    references: string[]
}

const artifacts: Artifacts =
    notes.reduce<Artifacts>((acc, note) => {
        const links =
            note.sections.flatMap(section => section.links)

        const references =
            note.sections.flatMap(section => section.references)

        return {
            links: acc.links.concat(links),
            references: acc.references.concat(references)
        }
    }, { links: [], references: [] })

We start with a seed value that represents an empty result, an object with two empty sequences. On each pass, we take a single note and extract its links and references by flattening over its sections. Rather than mutating the accumulator, we return a new object that combines the previously accumulated values with the newly extracted ones using concat. Each step produces a new accumulator that becomes the input to the next pass. By the end of the sequence, reduce has produced a final Artifacts value containing every link and every reference across all notes, without ever pushing to an external list or mutating shared state. reduce really shines here because it lets us describe how to build up a complex result from a sequence in a declarative way. In this example, we construct two sequences in parallel through the composition of flatMap, concat, and reduce.

Building a sequence immutably

So far we have looked at map, filter, and flatMap as the building blocks for declarative transformations. We can combine those operators to build larger sequences without reaching for reduce, and without pushing into an external list.

Let’s say our goal is to build an artifacts sequence, but only for notes that include both the "functional" and "sequence" tags. From those notes, we want to extract all references and all links, then concatenate those results into a single list.

interface Artifact {
    kind: 'link' | 'reference'
    value: string
}

const hasTag = (tag: string) =>
    (note: Note) =>
        note.tags.includes(tag)

const isFunctional: (note: Note) => boolean =
    hasTag('functional')

const isSequence: (note: Note) => boolean =
    hasTag('sequence')

const isFunctionalSequenceNote = (note: Note): boolean =>
    isFunctional(note) && isSequence(note)

const functionalSequenceNotes: Note[] =
    notes.filter(isFunctionalSequenceNote)

const references: Artifact[] =
    functionalSequenceNotes
        .flatMap(note =>
            note.sections.flatMap(section =>
                section.references.map(reference => ({
                    kind: 'reference',
                    value: reference
                }))
            )
        )

const links: Artifact[] =
    functionalSequenceNotes
        .flatMap(note =>
            note.sections.flatMap(section =>
                section.links.map(link => ({
                    kind: 'link',
                    value: link
                }))
            )
        )

const artifacts: Artifact[] =
    references.concat(links)

The above approach keeps each step focused and readable. filter narrows the input sequence down to only the notes we care about, flatMap flattens nested sequences like sections and links, and map transforms each extracted value into a consistent artifact shape. Finally, concat combines independently-built sequences into one larger sequence, all without mutating state or manually pushing into a list.

Conclusion

In this post, we explored a small but powerful set of sequence operators and how they can be composed to transform data in a declarative and immutable way. Using map, filter, flatMap, and reduce, we shaped, narrowed, flattened, and accumulated sequences without mutating state or relying on external loops and push operations. Each operator focuses on a single concern, and when combined, they form a clear and expressive pipeline for working with data.

The examples built on the same notes sequence, showing how small, intentional transformations can grow into more meaningful results, from simple projections to richer artifact structures. Rather than describing how to perform each step imperatively, we described what each step should produce, letting the sequence operators handle the mechanics.

These operators only scratch the surface of what is available when working with sequences in JavaScript. Functions like some and every help answer questions about a sequence, find and findIndex locate specific elements, sort and slice help reshape and reorder data, and groupBy opens the door to building structured views of a sequence. When combined with chaining and composition, these operators provide a rich vocabulary for expressing data transformations clearly and concisely.

Once you start thinking in terms of sequences and transformations, you may find fewer reasons to reach for mutable loops and temporary collections. Instead, you can build results step by step, directly from the data, in a way that is easier to read, reason about, and extend.

Building a sequence is about the journey and not a mutable destination.

Null reference exceptions are the norm, they are not exceptional. For many developers, handling nothing (null) has become a mundane routine built into the mind's muscle memory. A few "if" statements there, a guard condition here, and yet many developers do not do enough to prevent their boring everyday code from becoming... well... exceptional.

"A billion-dollar mistake"(1), coined by its own designer, Tony Hoare and for good reason. Null has been responsible for a great number of bugs, vulnerabilities and system crashes. It has seeped into the nomenclature of systems despite the fact that null is insidious and unassumingly ambiguous.

What does "null" mean? Null typically means having no value or significance. However, in computer science, null is significant and represents the special value of having no value. How can something that, by definition, should not be significant, impact a great number of systems and software engineers? Despite its significance in computer science and its relatively clear layman's definition, null is ambiguous. Does null mean uninitialized, not applicable, not provided, not existent, not found, or simply forgotten?

Lets take a relatively trivial example of a simple user object and a variable. Lets say we have a User object with three fields, FirstName, MiddleInitial and LastName each a string value. While it might be expected of a person to not have a middle name and thus provide no middle initial to the system, a developer might simply forget to initialize the middle initial variable. If the latter is the case, then a middle initial may never be provided to the system, which can lead to bugs or guards that may never be required.

record User {
    public string FirstName { get; set; }
    public string MiddleInitial { get; set; }
    public string LastName { get; set; }
}

// did we mean to leave out middle initial?
// was the middle initial not provided for this user?
var author = new User {
    FirstName = "Mark",
    LastName = "Pro"
};

// what happened here? All fields are null
var uninitialized = new User {};

Such a simple example trivially represents how fields may be neglected during initialization of an object. But, we can take this a step further. What if FirstName and LastName are never set, presenting a larger issue with the expressiveness of the object itself? Before we dive a little deeper, we should explore the function aspect of nulls and something that is all too common in a great many codebases I have had the pleasure of working in.

record User {
    public string Id { get; set; }
    public string FirstName { get; set; }
    public string MiddleInitial { get; set; }
    public string LastName { get; set; }
}

// UserService Implementation
sealed class UserService {
    readonly IDbConnection _dbConnection;

    public UserService(IDbConnection dbConnection) =>
        _dbConnection = dbConnection;

    public User GetUser(string id) {
        if (id == null) return null; //<- These null guards pollute their way into our code 

        try {
            var user = _dbConnection.GetById(id); //<- used as an example here
            return user;
        }
        catch {
            return null;
        }
    }
}

//What the consumer sees without reference

var userService = new UserService(db);
var user = userService.GetUser("abc123");

Here we have access to the whole of the user context, which gives us some clues as to when the GetUser function may return null. However, we need to go looking for those clues, as the function is not "expressive" or rather it doesn't clearly state the intent and return of the function. Why is "null" potentially returned from GetUser? Is it because the ID was null when it was passed in, was there an exception when attempting to retrieve the information, or did the response back from the database return nothing?

While it might be tempting to return null as a default for when something goes awry, we have no good way of informing the consuming function that null needs to be accounted for. At least, not in how the GetUser function is currently implemented.

Null Pollution

Nulls are insidious, like plastics that make their way into the environment that we then later have to clean up or deal with, as ignoring the problem could lead to larger consequences. When we encounter code that is not expressive, we must account for possible permutations of that code.

var userService = new UserService();
var user = userService.GetUser("abc123");

var userName = 
    $"{user.FirstName} {user.MiddleInitial} {user.LastName}"; 
    //^ this will throw a NullReferenceException

//. do something with userName

The above code may throw a NullReferenceException because the GetUser function may return null. Since null is a possible return value for user we must account for its inevitable lack of value.

if (user is not null) {
    var userName = $"{user.FirstName} {user.MiddleInitial}. {user.LastName}";
    //. do something with userName
}

Despite the attempt to guard against nulls, there is still a potential bug in the code, and that is that the string may not contain the correct output, as either the first name, middle initial, or last name fields may also be null. Now we must account for all these nullable permutations of our code. In the modern .NET era, we have a variety of ways to deal with this permutation. For brevity I will use pattern matching to showcase the better handling of nulls.

var userName = 
    user switch {
        { FirstName: {}, MiddleInitial: {}, LastName: {} } u =>
            $"{u.FirstName} {u.MiddleInitial}. {u.LastName}",
        { FirstName: {}, LastName: {} } u =>
            $"{u.FirstName} {u.LastName}",
        _ => ""
    };

Using pattern matching, we have accounted for the permutations of the user object when constructing a name. Worse still is when a developer decides that an exception needs to be thrown exclusively when providing null, which most of the time is not required. In the case of modern DI, we will receive an exception stating that the object cannot be constructed if not enough information is provided, or the early construction of this object may throw exceptions on at runtime when the object is created, turning a null value passed into a constructor into a runtime error. Which, more than likely, would have still resulted in a runtime error later on, but with less explicit code. That is, either way the null reference would have to be resolved, but it could be done so without the explicit throwing of a null reference exception.

sealed class UserService {
    readonly IDbConnection _dbConnection;

    public UserService(IDbConnection dbConnection) =>
        _dbConnection = 
            (dbConnection ?? throw new ArgumentNullException(nameof(dbConnection)));
}

Microsoft has taken it upon themselves to combat the boilerplate pollution that nulls problematically propagate by creating a plethora of operators to help handle unwieldy nulls.

//What if a value is null and if so you want to reassign it?
user ??= new User();

//What if a field is null and you would like to propgate the null
var firstName1 = user?.FirstName;

//What if the field is null and you would like to provide an alternative
var firstName2 = user?.FirstName ?? "Mark";

//Upcomming in dotnet 10 to replace the following
user?.FirstName = "Mark";

Moving Towards Something Better

After a substantial number of versions of C#, Microsoft has generously provided developers with the means to enable and support Nullable Reference Types (NRTs). These are type markers that allow for a bit of expressiveness when defining code. To enable them, simply add <Nullable>enable</Nullable> to your project file under PropertyGroup. Upon doing so, the compiler takes on some of the work of null checking. However, the output from the compiler is simply a warning and can be ignored. There are other instances where nullable reference types can be overridden.

sealed class UserService {
    readonly IDbConnection _dbConnection;

    public UserService(IDbConnection dbConnection) =>
        _dbConnection = dbConnection;

    public User? GetUser(string id) {
        if (id == null) return null; //<- These null gaurds pollute their way into our code 

        try {
            var user = _dbConnection.GetById(id); //<- used as an example here
            return user;
        }
        catch {
            return null;
        }
    }
}

Given that NRTs are enabled, adding the ? operator to the GetUser function indicates the function returned result may be null, telling the compiler that a warning should be surfaced when it detects that not all potential permutations of null are accounted for. Nullable reference types move us a bit towards expressive code, but are still easy to ignore and shut off by providing using the ! or !. operator to silence any null warnings surfaced by the compiler.

var userName = $"{user!.FirstName} {user!.LastName}"; //<- silence compiler warning

Expressing Concerns

With all these built-in features for handling null, you’d think Microsoft would have provided a better way. They have with F#, but most mere mortal developers will never reach that far. Until we get fully baked discriminated unions(2) in .NET we have to make do with third-party libraries or build our own unions (for now). Wait… what is a discriminated union, you ask? A discriminated union is a way of saying that a value can be one of many possibilities, much like object inheritance “tags” an object or type to belong to a “family” of types.

To represent null, we can make our own simplistic discriminated union called Option. The idea is that Option<T> will either represent some value or none, allowing us to explicitly express that a function may or may not return a value to the caller.

public abstract record Option<T> {

    public sealed record Some : Option<T> {

        readonly T _value;

        public Some(T value) {
            ArgumentNullException.ThrowIfNull(value, nameof(value));
            _value = value;
        }

        public T Unwrap => _value;
    }

    public sealed record None : Option<T>;
}

public static class Option {

    public static Option<T>.Some Some<T>(T value) =>
        new Option<T>.Some(value);

    public static Option<T>.None None<T>() =>
        new Option<T>.None();

    public static Option<T> Optional<T>(T value) =>
        value switch {
            {} v => Some(v),
            _ => None<T>()
        };

    public static R Match<T, R>(this Option<T> option, Func<T, R> some, Func<R> none) =>
        option switch {
            Option<T>.Some v => some(v.Unwrap),
            _ => none()
        };
}

The above represents a simplistic, expressive Option type which can be reused and extended to support more features, or you can use the one provided in LanguageExt.Core. Let's bring this back to the user service class example and see how the GetById function can now be done a bit more expressively by returning Option<User> as opposed to returning a User which may or may not be null. By specifying Option<User> the consumer is informed that User may or may not exist.

sealed class UserService {
    readonly IDbConnection _dbConnection;

    public UserService(IDbConnection dbConnection) =>
        _dbConnection = dbConnection;

    public Option<User> GetUser(string id) {
        if (id == null) return Option.None<User>();
        try {
            var user = _dbConnection.GetById(id); //<- used as an example here
            return Option.Some(user);
        }
        catch {
            return Option.None<User>();
        }
    }
}

Now the consumer code must account for either some value or none (nothing).

var userService = new UserService();
var user = userService.GetUser("abc123");

var userName = 
    user.Match(
        user => $"{user.FirstName} {user.MiddleInitial} {user.LastName}",
        () => string.Empty
    );

That simple shift in design; from returning null to returning something expressive, highlights the larger point of this article.

Conclusion

Null has been with us for decades, and for just as long developers have been patching around it with guards, defaults, and boilerplate. The problem is not that null exists, but that it is ambiguous. A null can mean too many things at once, and that ambiguity leaks into our designs, our APIs, and eventually our runtime errors.

C# gives us tools to work with null: nullable reference types, pattern matching, and null-coalescing operators. These help, but they mostly treat null as an inevitability to be managed. What changes the story is when we design for absence directly. Modeling “something or nothing” with an Option<T> or another union type makes absence part of the type system instead of leaving it as a hidden runtime hazard.

This shift makes our code more expressive. A function that returns Option<User> communicates its intent far more clearly than one that returns User but sometimes null. Consumers of your code know what to expect, the compiler helps enforce it, and your intent stays visible.

Nulls should be exceptional, not routine. By adopting more expressive patterns like Option<T>, discriminated unions, or other evolving features of C#, we can write code that is safer, more predictable, and less haunted by the billion-dollar mistake.

References

1. Null References: The Billion Dollar Mistake by Tony Hoare

2. Discriminated Union Update

TL;DR

C# developers have better options than relying on null. Use value types for guaranteed validity, Option<T> in libraries like LanguageExt for explicit absence, required/init for complete object construction, and Nullable Reference Types for safer references. Together, these tools reduce ambiguity, improve safety, and make intent clear. With native discriminated unions on the horizon for C#, modeling data is becoming even more expressive.

Tony Hoare coined the term "Null is a Billion-Dollar Mistake" and for good reason. Null is ambiguous. Does it mean not found, not applicable, not initialized, or just a bug? Null leads to countless runtime errors, with NullReferenceException consistently topping .NET error logs. It also encourages defensive programming, cluttering code with checks like if (x is not null) or if (x == null). Fortunately, modern C# offers better alternatives, including those introduced through third-party libraries.

Value Types

Value types require that all data be provided at the time of construction. Either a default constructor must exist, or every field must be initialized before leaving the constructor. This allows the compiler to enforce validity up front. A properly defined value type like ZipCode can never be null. Instead, it can be safely defaulted, for instance using ZipCode.Default, and later validated using an IsDefault accessor.

The downside is the boilerplate involved. Nearly every such type must be defined manually. However, libraries like NewType and ValueOf help reduce this overhead. They make it easier to create expressive value types, with optional validation logic, without writing repetitive code.

Value types are essentially structs where their values are encapsulated and any information must be explicitly accessed. An example of such a value type is a ZipCode type, which can have either a five-digit or ZIP+4 (nine-digit) code.

using System.Text.RegularExpressions;

readonly record struct ZipCode {
    private readonly ReadOnlyMemory<char> _value;

    private ZipCode(string value) => _value = value.AsMemory();

    public static ZipCode Create(string value) =>
        ZipCodeRegex.Match(value) switch {
            { Groups: [_, { Success: true } fst, _, { Success: true } lst] } => 
                new ($"{fst.Value}-{lst.Value}"),
            { Groups: [_, { Success: true } fst, _, _] } => new (fst.Value),
            _ => default
        };

    public bool IsDefault => _value.IsEmpy

    public override string ToString() => _value.ToString();

    static readonly Regex ZipCodeRegex =
        new ("^([0-9]{5})(-([0-9]{4}))?$");
}

var zip = ZipCode.Create("33431");

The savvy .NET developer might point out that one could call new ZipCode() or have an array of codes that are not initialized, such as new ZipCode[5]. That developer is correct. However, the internal value is not null in these cases and is safe to act on.

Expressive Absence with Option<T>

The Option<T> type offers a safer and more expressive way to model values that may or may not be present. Rather than returning null, which forces guesswork and defensive checks, an API that returns Option<User> is making its contract explicit: a user may exist, or the result may be absent, and the caller is responsible for handling both.

This explicitness removes ambiguity and shifts absence from an implementation detail to a part of the type system. The result is more declarative, correct, and predictable code. Rather than defensively reacting to potential null, you proactively engage with known possibilities. Adopting Option<T> does introduce a small learning curve and usually a third-party library, but the clarity and safety it adds often outweigh those costs. Looking ahead, Microsoft’s plans to bring discriminated unions, and potentially a native Option<T> type, to C# may reduce those barriers.

We can represent that a field in a record might not be present and that a value returned from a function can also represent absence.

A compact, drop-in example (compiles with LanguageExt)

using LanguageExt;
using static LanguageExt.Prelude;

record Author(string FirstName, Option<string> MiddleInitial, string LastName);

Option<Author> GetAuthor(string lastName) {
    Author[] authors = [
        new("Ernest", None, "Hemingway"),
        new("Charles", None, "Dickens")
    ];

    foreach(var a in authors)
        if(author.LastName == lastName) return Some(a);

    return None;
};

Enforcing Presence with required and init

C# has introduced additional tools to help prevent uninitialized and partially initialized objects from entering the system. The required and init keywords are designed to encourage complete construction and immutable design. These keywords do not replace Option<T> or value types; instead, they complement them by guaranteeing required members are always set before use.

By default, all fields in C# record types must be initialized through the constructor. That is, all fields must be set during the type's construction. Fields in records can use explicit accessors without the need to specify the default constructor.

One could have an Author record in which the first name and last name need to be provided at construction, while the middle initial does not have to be set. However, due to the use of init, the value cannot be set once the type has been initialized. If a required field is not initialized during instantiation, the compiler produces an error and prevents the project from building.

record Author {
    public required string FirstName { get; init; }
    public string? MiddleInitial { get; init; }
    public required string LastName { get; init; }
}

var author1 = new Author {
    FirstName = "Charls",
    LastName = "Dickens"
};

var author2 = new Author {
    FirstName = "Ernest"
}; //. Will error as LastName is not set

Nullable Reference Types (NRTs)

C# 8 introduced nullable reference types, which allow developers to specify whether a given reference can hold null. When enabled, the compiler will warn you when you try to dereference a value that might be null, or fail to assign to a non-nullable property.

string name = "Mark";    // non-nullable
string? nickname = null; // nullable

These annotations provide a layer of static analysis that encourages safer handling of reference types. You can enable them per file with #nullable enable, or globally within a project:

<Nullable>enable</Nullable>

Once enabled, the compiler distinguishes between string and string?, making intent clearer and usage safer. You are prompted to consider where null might flow through your system and address it accordingly.

This model is a significant improvement over the historical default where all references could be null implicitly. It reduces accidents and helps signal the need for validation. However, it falls short of offering true modeling power. Nullable reference types do not prevent runtime nulls. They are enforced through warnings, not type errors, which can be ignored or suppressed. They do not compose. You cannot map, match, or bind nullable references in a fluent, predictable way. Their meaning is also less precise. A string? might mean “optional” or it might just mean “uninitialized.” The type system cannot differentiate.

As a result, NRTs are a useful baseline but not a replacement for union types like Option<T>. They can be used together, and in many codebases, enabling nullable annotations is a good first step. But when your domain logic demands clear expression of absence, when you want types that communicate and behavior that composes, Option<T> remains the better choice.

Enable NRTs to reduce accidental nulls, but use Option<T> when you want to express absence as part of your model.

Native Discriminated Unions (Coming to C#)

C# is moving closer to providing native support for discriminated unions. Discriminated unions are also known as “type unions," which will allow developers to define types that represent a value in one of several named cases, each potentially carrying its own data.

Although discriminated unions are not yet available in C# 14 or .NET 10, they are an active topic for the C# language design team. Proposals and working group notes outline how the feature might look in future versions of the language.

Below is a peek into Microsoft's proposal:

public union Option<T> {
    case Some(T Value);
    case None;
}

A union enables exhaustive pattern matching at compile time, so when you use a switch expression over a union, the compiler ensures all cases are handled. Such an approach is significantly safer and more expressive than traditional inheritance-based patterns.

var pet = Some(new Pet("Oliver", "cat"));

_ = pet switch {
    Some(value) => ...,
    None => ...
};

Feel free to learn more about unions by reading Microsoft's Union proposals overview.

Conclusion

Null has long been a source of ambiguity and runtime bugs in C#. With the combined use of value types, Option<T>, required/init, and nullable reference types, developers have a richer toolbox for designing safer, more expressive code. And with discriminated unions being developed for future C# versions, the language is taking another major step toward making absence and alternatives explicit in the type system rather than hidden in runtime behavior. Together, these features move C# closer to a future where intent is clear, bugs are reduced, and code is easier to reason about.