Maybe — Modeling Absence

When retrieving values from maps, database queries, or optional properties, standard TypeScript represents absence with T | null or T | undefined.

While familiar, handling nullable values across multi-step transformations requires repetitive if checks or optional chaining that breaks linear pipeline composition.

The problem with null

const rawValue = config.get("timeout");
let timeout = 1000;

if (rawValue !== undefined && rawValue !== null) {
  const parsed = parseInt(rawValue, 10);
  if (!isNaN(parsed) && parsed > 0) {
    timeout = parsed;
  }
}

In standard TypeScript, each transformation step requires guarding against missing intermediate values.

The Maybe Approach

Maybe<A> represents optionality as a discriminated union: Some<A> (value present) or None (empty).

flowchart TD
    Input([Raw Data]) --> Choice{Is it null or undefined?}
    Choice -->|No| Some[Some A]
    Choice -->|Yes| None[None]

    Some --> Transform[Apply Transformations]
    None --> Skip[Skip Transformations]

    Transform --> Edge[Extract with Default / Match]
    Skip --> Edge

By representing absence as a data structure rather than a language keyword, we can write our transformations as if the value is always there. The data structure itself manages the control flow. We decouple the what from the if.

import { pipe } from "@nlozgachev/pipelined/composition";
import { Maybe } from "@nlozgachev/pipelined/core";

export type Maybe<A> = Some<A> | None;

Creating Maybe

To work within this model, we must first lift our raw, potentially unsafe values into a Maybe context. This is the boundary where the messy real world meets our clean system.

// Wrapping an existing value
const five = Maybe.make.some(5); // Maybe<number>

// Representing explicit absence
const empty = Maybe.make.none(); // Maybe<never>

In practice, you will rarely write some or none manually. Instead, you will ingest values coming from external interfaces — such as third-party libraries, DOM elements, or API payloads — which use null or undefined. For this, we use from.nullable:

interface AppConfig {
  theme?: "light" | "dark";
}

const config: AppConfig = {};

const theme = Maybe.from.nullable(config.theme); // None

Transforming values

Once our data is wrapped inside a Maybe, we do not immediately unpack it. Instead, we describe how the value should change if it is present.

Pure transformations with `map`

If we have a Some, map applies a function to the value inside and returns a new Some with the result. If we have a None, map does nothing and returns the None unchanged.

const double = (n: number) => n * 2;

pipe(Maybe.make.some(5), Maybe.map(double)); // Some(10)
pipe(Maybe.make.none(), Maybe.map(double));  // None

Consider how this simplifies deep record navigation. Imagine parsing a user profile to extract their avatar’s filename:

interface User {
  profile?: {
    avatarUrl?: string;
  };
}

const getAvatarFilename = (user: User): Maybe<string> =>
  pipe(
    Maybe.from.nullable(user.profile),
    Maybe.map((p) => p.avatarUrl),
    Maybe.map((url) => url.split("/").pop()),
  );

We do not write a single if statement. If profile is missing, the first map is skipped. If avatarUrl is missing, the second map is skipped. The pipeline remains perfectly linear, and we are guaranteed never to encounter a TypeError: Cannot read properties of undefined.

Nested pipelines with `chain`

Sometimes, a transformation itself might return a Maybe. For example, we might want to take a string and parse it into an integer. The parsing operation is fallible — if the string is "abc", there is no valid number to return.

If we were to use map with a function that returns a Maybe, we would end up with a nested type: Maybe<Maybe<number>>. This is inconvenient to work with.

const parseInteger = (s: string): Maybe<number> => {
  const n = parseInt(s, 10);
  return isNaN(n) ? Maybe.make.none() : Maybe.make.some(n);
};

// Using map results in nesting:
const nested = pipe(Maybe.make.some("42"), Maybe.map(parseInteger)); // Some(Some(42))

To resolve this, we use chain. It applies the transformation and flattens the nested structure, leaving us with a clean Maybe<number>.

const flat = pipe(Maybe.make.some("42"), Maybe.chain(parseInteger)); // Some(42)
const failed = pipe(Maybe.make.some("abc"), Maybe.chain(parseInteger)); // None

Think of map as a tool for transformations that are guaranteed to succeed once a value is present, and chain as a tool for transformations that themselves introduce the possibility of failure.

Narrowing focus with `filter` and `from.Predicate`

Sometimes a value exists, but it does not meet our business criteria. We can use filter to turn a Some into a None if it fails to satisfy a predicate.

const isEven = (n: number) => n % 2 === 0;

pipe(Maybe.make.some(4), Maybe.filter(isEven)); // Some(4)
pipe(Maybe.make.some(5), Maybe.filter(isEven)); // None

If we are starting from a raw value rather than a Maybe, we can use from.Predicate to decide whether to wrap the value in Some or None right at the boundary:

const validateAge = (age: number): Maybe<number> =>
  pipe(
    age,
    Maybe.from.Predicate((n) => n >= 18),
  );

Extracting the value

Eventually, our pipeline must interface with the rest of our application — libraries that expect standard TypeScript primitives, UI frameworks, or database connectors. We must step out of our philosophical data structures and return a concrete value. We call this reaching the edge.

Safe fallbacks with `getOrElse`

The most common exit point is getOrElse. It extracts the value from a Some, or returns a fallback value if we have a None.

pipe(
  Maybe.make.some("admin"),
  Maybe.getOrElse(() => "guest"),
); // "admin"

pipe(
  Maybe.make.none(),
  Maybe.getOrElse(() => "guest"),
); // "guest"

Notice that getOrElse takes a function — a thunk — rather than a direct value. This is a deliberate design choice. If computing the fallback is expensive or triggers a side effect (such as writing to a log or generating a token), that computation is deferred. It is only executed if the value is actually absent.

Case analysis with `match` and `fold`

When you need to perform different logic for both the success and failure cases, you can use match for a named object syntax, or fold for a positional, error-first syntax.

// Using match with named handlers
const welcomeMessage = pipe(
  maybeUser,
  Maybe.match({
    some: (user) => `Welcome back, ${user.name}`,
    none: () => "Please log in to continue",
  }),
);

// Using fold with positional arguments (none handler first)
const statusString = pipe(
  maybeUser,
  Maybe.fold(
    () => "Inactive",
    (user) => `Active since ${user.createdAt}`,
  ),
);

Interoperability with standard TypeScript

If you are passing the result to an external library that expects standard null or undefined values, you can convert the Maybe back at the very end of your pipeline:

const nullable = Maybe.to.nullable(maybeValue);   // T | null
const undefinedVal = Maybe.to.undefined(maybeValue); // T | undefined

Side effects with tap

Occasionally, you need to perform a side effect — such as writing a message to a log or updating a metric — without altering the data or breaking the flow of your pipeline. For this, we use tap.

tap runs a side-effectful function on the value inside a Some and returns the original Maybe unchanged. If the Maybe is None, the function is ignored.

pipe(
  Maybe.make.some("Configuration parsed successfully"),
  Maybe.tap((msg) => console.log(msg)),
  Maybe.map((msg) => msg.toUpperCase()),
); // Logs message, then continues to produce Some("CONFIGURATION PARSED SUCCESSFULLY")

Recovering from None

When an operation fails to produce a value, we don’t always want to settle for a static fallback. Often, we want to try a secondary, fallible strategy. For instance, if a config is not in our memory cache, we might want to look for it in the database.

For this, we use recover. It takes a function that returns another Maybe when the current one is None.

const getTheme = (userId: string): Maybe<string> =>
  pipe(
    Maybe.from.nullable(cache.get(`theme:${userId}`)),
    Maybe.recover(() => Maybe.from.nullable(db.get(`theme:${userId}`))),
    Maybe.getOrElse(() => "light"),
  );

If the cache hit succeeds, the database lookup is never evaluated. If the cache misses, we attempt the database lookup. Only if both fail do we settle for the fallback value "light".

Converting to and from Result

A Maybe represents absence but does not tell you why the value is missing. Sometimes, absence is an error, and we need to attach a reason to it.

We can transition from a Maybe to a Result using to.Result. We provide a thunk that generates an error value if the Maybe is a None:

import { Result } from "@nlozgachev/pipelined/core";

const parseEmail = (email: string): Maybe<string> =>
  pipe(
    email,
    Maybe.from.Predicate((e) => e.includes("@")),
  );

const signup = (rawEmail: string) =>
  pipe(
    parseEmail(rawEmail),
    Maybe.to.Result(() => "Email address must contain an '@' symbol"),
  ); // Result<string, string>

Conversely, if we have a Result and want to discard the error context, we can downgrade it to a Maybe using from.Result:

const maybeValue = Maybe.from.Result(Result.make.err("An error occurred")); // None

Swapping container contexts: transposeResult

When working with optional operations that return fallible results (such as Maybe<Result<E, A>>), Maybe.transposeResult swaps the outer and inner contexts, producing Result<E, Maybe<A>>:

Maybe.transposeResult(Maybe.make.some(Result.make.ok(42)));  // Ok(Some(42))
Maybe.transposeResult(Maybe.make.some(Result.make.err("e"))); // Err("e")
Maybe.transposeResult(Maybe.make.none());                     // Ok(None)

Composition in practice

Let us look at how these elements fit together into a cohesive, structured pipeline. We will take a raw query parameter representing a page offset, validate it, apply pagination bounds, and return a clean offset index.

const getPageOffset = (rawOffset: string | undefined, pageSize: number): number =>
  pipe(
    Maybe.from.nullable(rawOffset),                     // Maybe<string>
    Maybe.chain(parseInteger),                         // Maybe<number>
    Maybe.filter((offset) => offset >= 0),             // Maybe<number>
    Maybe.map((offset) => offset * pageSize),          // Maybe<number>
    Maybe.getOrElse(() => 0),                          // number
  );

Observe the flow. Every step is insulated. The parsing logic, the validation criteria, and the mathematical mapping are written in a straight, readable line, fully detached from the defensive logic of verifying the presence of rawOffset.

Accumulating values: bind / bindTo

When you need to perform multiple sequential operations and gather their results into a single object, traditional pipelines can become deeply nested because each successive function needs access to previous results:

const userProfile = pipe(
  getUser(userId),
  Maybe.chain((user) =>
    pipe(
      getPreferences(user.id),
      Maybe.map((prefs) => ({ user, prefs }))
    )
  ),
  Maybe.chain(({ user, prefs }) =>
    pipe(
      getTheme(prefs.themeId),
      Maybe.map((theme) => ({ user, prefs, theme }))
    )
  )
);

To solve this, we can use bindTo and bind to cleanly accumulate values key-by-key in a flat, readable pipeline.

bindTo lifts a value into the pipeline’s accumulator object:

pipe(
  Maybe.make.some(42),
  Maybe.bindTo("value")
); // Some({ value: 42 })

bind runs a new operation using the accumulated object and attaches the result to a new key:

const userProfile = pipe(
  getUser(userId),
  Maybe.bindTo("user"),
  Maybe.bind("prefs", ({ user }) => getPreferences(user.id)),
  Maybe.bind("theme", ({ prefs }) => getTheme(prefs.themeId))
); // Some({ user: User, prefs: Preferences, theme: Theme })

If any step fails (yielding None), the entire pipeline short-circuits and propagates None immediately.

Combining records: struct

While bind is perfect for sequential steps where a latter step depends on the output of a prior step, sometimes you have a set of independent Maybe values that you want to combine into a single object. For this, you can use Maybe.struct.

It combines a record of Maybe values into a single Maybe holding a record of success values. If any individual field is None, the entire struct short-circuits to None immediately:

const user = Maybe.struct({
  name: Maybe.make.some("Alice"),
  age: Maybe.make.some(30),
  role: Maybe.from.Predicate((r: string) => r === "admin" || r === "user")("user"),
}); // Some({ name: "Alice", age: 30, role: "user" })

If multiple fields are None, Maybe.struct short-circuits immediately on the first None encountered in key order:

const failed = Maybe.struct({
  a: Maybe.make.some(1),
  b: Maybe.make.none(),
  c: Maybe.make.none(),
}); // None

Problems it solves

Deeply nested payload extraction: In client applications and API consumers, parsing responses often requires drilling through multiple layers of optional data (such as user?.profile?.preferences?.theme). When an intermediate property is absent, optional chaining yields an ambiguous undefined that easily leaks into downstream computations. Maybe turns optional paths into composable values that can be mapped, filtered, and transformed without manual null checks at each layer.
Multi-step lookup and filter pipelines: When querying in-memory caches, searching array elements by criteria, or looking up record keys, missing entries are standard domain occurrences. Wrapping lookups in Maybe allows subsequent processing steps (such as formatting display values, calculating tax rates, or applying discounts) to chain linearly, automatically bypassing downstream steps when an item is missing.
Combining multiple independent optional inputs (Maybe.struct): In search panels and report generators, an operation often requires multiple optional parameters (such as startDate, endDate, and regionId) to all be present before executing a query. Maybe.struct combines an object of individual Maybe fields into a single Maybe<Record>, resolving to Some only if every required field is present and short-circuiting on the first None.
Filtering missing entries from collection streams (Maybe.compact): When resolving an array of identifiers against a local cache or search index, some IDs match while others yield None. Arr.compact and Maybe combinators filter out all absent entries and unwrap the present values into a dense array in a single point-free step.
Explicit public module contracts: In shared domain services and library interfaces, returning null or undefined permits callers to inadvertently ignore missing values until a runtime error triggers downstream. Returning Maybe<A> makes absence an explicit type guarantee, ensuring callers handle both presence and absence at compile time.