DEV Community: Adriel Avila

Understanding Monads in TypeScript: A Practical Guide

Adriel Avila — Thu, 23 Jul 2026 15:37:29 +0000

You have read five blog posts about monads. Each one started with category theory, mentioned burritos, and left you more confused than before. Let's skip all of that.

Here is the short version: a monad is a container that supports three operations. You already use two monads every day in TypeScript — Promise and Array. Once you see the pattern, every monad in @oofp/core will feel familiar.

The Three Operations

Every monad has three things:

of(a) — Put a value into the container.
map(f) — Transform the value inside, keep the container shape.
chain(f) — Transform the value into a new container, then flatten.

That's it. If a type supports these three operations and follows a few simple laws, it's a monad. Let's see this with types you already know.

Promise — a monad you use daily

// of — wrap a value
const p = Promise.resolve(42);

// map — transform the inside (then with a plain return)
const doubled = p.then((x) => x * 2); // Promise<number>

// chain — transform into a new Promise (then with an async return)
const fetched = p.then((id) => fetch(`/api/users/${id}`)); // Promise<Response>

Promise.resolve is of. .then acts as both map and chain — JavaScript conflates them. When your callback returns a plain value, it's map. When it returns a Promise, it's chain. The runtime flattens the nested Promise<Promise<T>> into Promise<T> automatically.

Array — another monad hiding in plain sight

// of — wrap a value
const arr = [42];

// map — transform each element
const doubled = arr.map((x) => x * 2); // [84]

// chain — transform each element into an array, then flatten
const expanded = arr.flatMap((x) => [x, x * 10]); // [42, 420]

Array.of (or just [value]) is of. .map is map. .flatMap is chain. Same pattern, different container.

The insight is: chain is map followed by flatten. That's why it's also called flatMap or bind. You apply a function that returns a new container, then flatten the nested result.

Maybe: Eliminating null Checks

Now that you see the pattern, let's apply it to a real problem. Consider this code:

interface User {
  name: string;
  address?: {
    city?: string;
    zip?: string;
  };
}

function getCityUppercase(user: User | null): string {
  if (user === null) return "UNKNOWN";
  if (!user.address) return "UNKNOWN";
  if (!user.address.city) return "UNKNOWN";
  return user.address.city.toUpperCase();
}

Three null checks for one value. Optional chaining helps (user?.address?.city?.toUpperCase() ?? "UNKNOWN"), but it doesn't compose. You can't reuse pieces of this logic, and the fallback value is buried at the end.

Maybe is a monad that represents a value that might not exist. It has two states: Just(value) or Nothing. Here's the same logic:

import * as M from "@oofp/core/maybe";
import { pipe } from "@oofp/core/pipe";

const getCityUppercase = (user: User | null): string =>
  pipe(
    M.fromNullable(user),
    M.chain((u) => M.fromNullable(u.address)),
    M.chain((a) => M.fromNullable(a.city)),
    M.map((city) => city.toUpperCase()),
    M.getOrElse(() => "UNKNOWN"),
  );

Step by step:

M.fromNullable(user) — if user is null or undefined, return Nothing. Otherwise, Just(user).
M.chain(u => M.fromNullable(u.address)) — if we have a user, try to get the address. If it's missing, the whole chain becomes Nothing.
M.chain(a => M.fromNullable(a.city)) — same for city.
M.map(city => city.toUpperCase()) — if we still have a value, transform it.
M.getOrElse(() => "UNKNOWN") — extract the value, or use the fallback.

The key point: once any step produces Nothing, every subsequent map and chain is skipped. The Nothing propagates automatically. No null checks, no early returns, no exceptions.

Maybe API at a glance

import * as M from "@oofp/core/maybe";

M.just(42);              // Just(42)
M.nothing();             // Nothing
M.fromNullable(null);    // Nothing
M.fromNullable(42);      // Just(42)

// Transform
M.map((x) => x + 1);    // Just(42) -> Just(43), Nothing -> Nothing
M.chain((x) => M.just(x + 1)); // Just(42) -> Just(43)

// Extract
M.getOrElse(() => 0);   // Just(42) -> 42, Nothing -> 0
M.toNullable;            // Just(42) -> 42, Nothing -> null

Either: Errors as Values

Maybe tells you if something is missing, but not why. Either<E, A> fixes that. It has two states: Right(value) for success, Left(error) for failure. The error type E is explicit in the signature.

import * as E from "@oofp/core/either";
import { pipe } from "@oofp/core/pipe";

type ValidationError = { field: string; message: string };

const validateEmail = (input: string): E.Either<ValidationError, string> => {
  if (!input.includes("@"))
    return E.left({ field: "email", message: "Must contain @" });
  return E.right(input);
};

const validateAge = (input: number): E.Either<ValidationError, number> => {
  if (input < 0 || input > 150)
    return E.left({ field: "age", message: "Out of range" });
  return E.right(input);
};

const validateUser = (data: { email: string; age: number }) =>
  pipe(
    validateEmail(data.email),
    E.chain(() => validateAge(data.age)),
    E.map(() => data),
  );

Either is a monad where chain short-circuits on Left. If validateEmail fails, validateAge never runs. The error type is carried through the pipeline, and the compiler knows about it.

For a deeper look at Either-based error handling, including async operations and recovery patterns, see Functional Error Handling in TypeScript.

Task: Lazy Async

Promise has a problem: it's eager. The moment you create one, it starts executing:

// This fires immediately, whether you want it to or not
const result = fetch("/api/users");

You can't pass a Promise around without triggering its side effect. You can't compose Promises without running them. This breaks referential transparency — you can't substitute the expression with its value without changing program behavior.

Task<A> solves this. It's a lazy Promise:

type Task<A> = () => Promise<A>;

A Task is a function that, when called, produces a Promise. Nothing executes until you invoke it.

import * as T from "@oofp/core/task";
import { pipe } from "@oofp/core/pipe";

// Define computation — nothing runs yet
const fetchUsers = pipe(
  T.of("/api/users"),
  T.chain((url) => () => fetch(url)),
  T.chain((res) => () => res.json()),
  T.map((data) => data.users),
);

// Still nothing has happened.

// NOW it runs:
const users = await fetchUsers();

Because Task is just a function, you can:

Pass it around without triggering side effects.
Compose multiple Tasks into pipelines before executing any of them.
Retry, delay, or conditionally run Tasks based on other values.

Task API at a glance

import * as T from "@oofp/core/task";

T.of(42);                // Task that resolves to 42
T.map((x) => x + 1);    // Transform the resolved value
T.chain((x) => T.of(x + 1)); // Sequence into a new Task
T.delay(1000);           // Wait 1 second before resolving

TaskEither: The Workhorse

In real applications, most operations are both async and fallible. TaskEither<E, A> combines both:

type TaskEither<E, A> = () => Promise<Either<E, A>>;

It's a lazy function that returns a Promise which always resolves to an Either. No rejections, no unhandled promise errors — just typed success or typed failure.

import * as TE from "@oofp/core/task-either";
import { pipe } from "@oofp/core/pipe";

interface ApiError {
  status: number;
  message: string;
}

interface User {
  id: string;
  name: string;
}

interface Order {
  id: string;
  total: number;
}

const fetchUser = (id: string): TE.TaskEither<ApiError, User> =>
  TE.tryCatch(
    () =>
      fetch(`/api/users/${id}`).then(async (res) => {
        if (!res.ok) throw { status: res.status, message: res.statusText };
        return res.json() as Promise<User>;
      }),
    (err) => err as ApiError,
  );

const fetchOrders = (userId: string): TE.TaskEither<ApiError, Order[]> =>
  TE.tryCatch(
    () =>
      fetch(`/api/orders?user=${userId}`).then(async (res) => {
        if (!res.ok) throw { status: res.status, message: res.statusText };
        return res.json() as Promise<Order[]>;
      }),
    (err) => err as ApiError,
  );

// Compose a complete workflow
const getUserDashboard = (userId: string) =>
  pipe(
    fetchUser(userId),
    TE.chain((user) =>
      pipe(
        fetchOrders(user.id),
        TE.map((orders) => ({
          user,
          orders,
          totalSpent: orders.reduce((sum, o) => sum + o.total, 0),
        })),
      ),
    ),
  );

// Nothing has executed. Run it:
const result = await getUserDashboard("user-123")();

tryCatch takes a function that returns a Promise (which might reject) and wraps it into a TaskEither that never rejects. The second argument maps the caught error into your typed error.

This is the monad you will use most in production TypeScript. For retry strategies, error recovery with orElse, and concurrent execution with concurrencyObject, see the error handling guide.

The chain Pattern

Here is the key insight that ties everything together. chain is what makes monads powerful. It's sequential composition where each step can change the container's state:

Maybe.chain — a Just can become a Nothing. Once it's Nothing, the rest is skipped.
Either.chain — a Right can become a Left. The error propagates, the rest is skipped.
Task.chain — one async operation feeds its result into the next. Sequential by construction.
TaskEither.chain — sequences async operations that can fail. If one step produces a Left, subsequent steps are skipped.

Every monad follows this same structure. Learn chain once, and you can use any monad.

Here's a practical example that flows through multiple monads:

import * as M from "@oofp/core/maybe";
import * as E from "@oofp/core/either";
import * as TE from "@oofp/core/task-either";
import { pipe } from "@oofp/core/pipe";

// Parse config from environment (sync, might be missing)
const getConfig = (env: Record<string, string | undefined>) =>
  pipe(
    M.fromNullable(env.API_URL),
    M.chain((url) =>
      pipe(
        M.fromNullable(env.API_KEY),
        M.map((key) => ({ url, key })),
      ),
    ),
  );

// Validate the config (sync, might fail with reason)
const validateConfig = (config: { url: string; key: string }) =>
  pipe(
    config.url.startsWith("https")
      ? E.right(config)
      : E.left("API_URL must use HTTPS"),
    E.chain((c) =>
      c.key.length >= 32 ? E.right(c) : E.left("API_KEY too short"),
    ),
  );

// Fetch data using validated config (async, might fail)
const fetchData = (config: { url: string; key: string }) =>
  TE.tryCatch(
    () =>
      fetch(config.url, {
        headers: { Authorization: `Bearer ${config.key}` },
      }).then((r) => r.json()),
    (err) => `Fetch failed: ${String(err)}`,
  );

Three different monads, three different concerns (missing values, validation errors, async failures), but the same chain pattern throughout. Each function is small, testable, and composable.

pipe: Gluing It Together

You might have noticed that every example uses pipe. Without it, monadic code becomes deeply nested:

// Without pipe — nested and hard to read
const result = M.getOrElse(() => "UNKNOWN")(
  M.map((city: string) => city.toUpperCase())(
    M.chain((a: { city?: string }) => M.fromNullable(a.city))(
      M.chain((u: User) => M.fromNullable(u.address))(
        M.fromNullable(user)
      )
    )
  )
);

With pipe, the same logic reads top to bottom, left to right:

// With pipe — linear and clear
const result = pipe(
  M.fromNullable(user),
  M.chain((u) => M.fromNullable(u.address)),
  M.chain((a) => M.fromNullable(a.city)),
  M.map((city) => city.toUpperCase()),
  M.getOrElse(() => "UNKNOWN"),
);

pipe takes an initial value and passes it through a chain of functions. Each function receives the output of the previous one. It's the backbone of compositional code in @oofp/core.

import { pipe } from "@oofp/core/pipe";

// pipe(value, f1, f2, f3) === f3(f2(f1(value)))
const result = pipe(
  5,
  (x) => x * 2,    // 10
  (x) => x + 1,    // 11
  (x) => `${x}!`,  // "11!"
);

When to Use What

Situation	Monad	Why
Value might not exist	`Maybe`	Eliminates null checks, propagates absence
Operation can fail (sync)	`Either`	Typed errors in the function signature
Async operation	`Task`	Lazy, composable, referentially transparent
Async + can fail	`TaskEither`	Production workhorse for real-world apps
Needs runtime context	`Reader`	Dependency injection without globals
Async + fail + context	`ReaderTaskEither`	Full-stack application architecture

Start with Maybe and Either for synchronous code. Move to TaskEither when you need async operations with typed errors. Reach for ReaderTaskEither when you need to thread configuration, database connections, or other context through your application.

Getting Started

Install @oofp/core:

npm install @oofp/core

Import what you need:

import * as M from "@oofp/core/maybe";
import * as E from "@oofp/core/either";
import * as T from "@oofp/core/task";
import * as TE from "@oofp/core/task-either";
import { pipe } from "@oofp/core/pipe";

Explore each module in the documentation:

Maybe — optional values without null
Either — synchronous error handling
Task — lazy async computation
TaskEither — async error handling
Pipe, Flow & Compose — function composition

The pattern is always the same: wrap a value in a container, transform it with map, sequence operations with chain, and extract the result at the boundary. Once you internalize this, every monad is just a variation on the same theme.

TypeScript Pipe Function: Composing Functions Without the Nesting Hell

Adriel Avila — Thu, 23 Jul 2026 15:37:26 +0000

Look at this code and tell me the order of operations:

const result = uppercase(trim(removeSpaces(validate(input))));

You read it left-to-right, but it executes right-to-left. validate runs first, then removeSpaces, then trim, then uppercase. The reading order is the opposite of the execution order.

Now add one more step:

const result = format(uppercase(trim(removeSpaces(validate(input)))));

And another:

const result = encode(format(uppercase(trim(removeSpaces(validate(input))))));

This does not scale. Every new step wraps the entire expression in another function call. The nesting grows. The parentheses pile up. Inserting a step in the middle means counting parentheses. Removing one means the same. And if any of these functions return a wrapper type like Either or Task, the nesting becomes genuinely painful.

There is a better way to write this.

pipe: Left-to-Right Composition

pipe takes a value as its first argument and passes it through a sequence of functions, left-to-right. Each function receives the return value of the previous one.

import { pipe } from "@oofp/core/pipe";

const result = pipe(input, validate, removeSpaces, trim, uppercase);

Same operations. Same result. But now the code reads in execution order: start with input, validate it, remove spaces, trim it, uppercase it.

Adding a step is trivial:

const result = pipe(input, validate, removeSpaces, trim, uppercase, encode);

Removing one is just as easy — delete the line. No parenthesis counting. No restructuring.

Type inference through the chain

TypeScript infers every intermediate type. If validate returns string, then removeSpaces must accept string. If you pass a function that doesn't match, the compiler tells you immediately:

const double = (n: number) => n * 2;
const exclaim = (s: string) => s + "!";
const len = (s: string) => s.length;

// TypeScript infers each step:
const result = pipe(
  "hello",        // string
  exclaim,        // (string) => string
  len,            // (string) => number
  double,         // (number) => number
);
// result: number (10)

Swap double and len and the compiler catches it. The types flow through the pipeline and every mismatch surfaces at compile time.

Vertical pipelines

When pipelines get longer, write them vertically. This is the idiomatic style in functional TypeScript:

import { pipe } from "@oofp/core/pipe";
import * as E from "@oofp/core/either";

const processInput = (raw: string) =>
  pipe(
    raw,
    parseJSON,
    E.chain(validateSchema),
    E.map(normalize),
    E.map(enrichWithDefaults),
    E.map(serialize),
  );

Each line is one step. You can scan the pipeline top-to-bottom and understand the transformation at a glance.

flow: Creating Reusable Pipelines

pipe takes a value first and executes immediately. Sometimes you don't have the value yet — you want to define the pipeline and apply it later. That's flow.

flow takes functions only and returns a new function:

import { flow } from "@oofp/core/flow";

const process = flow(validate, removeSpaces, trim, uppercase);
// process is a function: (input: string) => string

const result = process(input);

flow composes left-to-right, same as pipe. The difference is when the computation happens: pipe runs now, flow builds a function for later.

Where flow shines

Use flow when you need to pass a transformation as an argument:

import { flow } from "@oofp/core/flow";
import * as E from "@oofp/core/either";

const parsePositiveNumber = flow(
  (s: string) => Number(s),
  (n) => (isNaN(n) ? E.left("Not a number") : E.right(n)),
  E.chain((n) => (n > 0 ? E.right(n) : E.left("Must be positive"))),
);

// Use it directly with Array.map
const results = ["10", "-3", "abc", "42"].map(parsePositiveNumber);
// [Right(10), Left("Must be positive"), Left("Not a number"), Right(42)]

Because flow returns a plain function, it integrates with any API that accepts callbacks: Array.map, Array.filter, event handlers, middleware chains, you name it.

Naming pipelines

flow encourages giving names to transformations. This is a readability win:

import { flow } from "@oofp/core/flow";
import * as M from "@oofp/core/maybe";

const parseAge = flow(
  M.fromNullable<string>,
  M.map((s) => parseInt(s, 10)),
  M.iif((n) => !isNaN(n) && n >= 0 && n <= 150),
);

const formatCurrency = flow(
  (cents: number) => cents / 100,
  (dollars) => dollars.toFixed(2),
  (s) => `$${s}`,
);

Now parseAge and formatCurrency are self-documenting, reusable, and testable in isolation.

compose: Right-to-Left (Mathematical Order)

compose does the same thing as flow, but in reverse order. Functions are listed outermost-first, matching mathematical notation where (f . g)(x) = f(g(x)).

import { compose } from "@oofp/core/compose";

const process = compose(uppercase, trim, removeSpaces, validate);
// Same result as flow(validate, removeSpaces, trim, uppercase)

Read it right-to-left: validate, then remove spaces, then trim, then uppercase.

import { flow } from "@oofp/core/flow";
import { compose } from "@oofp/core/compose";

const exclaim = (s: string) => s + "!";
const upper = (s: string) => s.toUpperCase();
const trim = (s: string) => s.trim();

// These produce identical functions:
const withFlow = flow(trim, upper, exclaim);
const withCompose = compose(exclaim, upper, trim);

withFlow("  hi  ");    // "HI!"
withCompose("  hi  "); // "HI!"

Most TypeScript developers prefer pipe and flow because left-to-right matches how we read code. compose exists for those coming from Haskell or category theory who think in terms of f . g. Use whichever reads better for your team.

Real-World Examples

Data validation pipeline

import { pipe } from "@oofp/core/pipe";
import * as E from "@oofp/core/either";

interface Order {
  items: Array<{ price: number; qty: number }>;
  discount: number;
}

const validateOrder = (data: unknown): E.Either<string, Order> =>
  typeof data === "object" && data !== null
    ? E.right(data as Order)
    : E.left("Invalid order data");

const calculateTotal = (order: Order): Order & { total: number } => ({
  ...order,
  total: order.items.reduce((sum, item) => sum + item.price * item.qty, 0),
});

const applyDiscount = (rate: number) => (order: Order & { total: number }) => ({
  ...order,
  total: order.total * (1 - rate),
});

const processOrder = (rawData: unknown) =>
  pipe(
    rawData,
    validateOrder,
    E.map(calculateTotal),
    E.map(applyDiscount(0.1)),
  );

Each step does one thing. The pipeline is the composition. Adding tax calculation is one line: E.map(applyTax(0.08)).

Async pipeline with TaskEither

import { pipe } from "@oofp/core/pipe";
import * as TE from "@oofp/core/task-either";

interface User {
  id: string;
  name: string;
}

interface Order {
  id: string;
  userId: string;
  total: number;
}

const fetchUser = (id: string): TE.TaskEither<Error, User> =>
  TE.tryCatch(
    () => fetch(`/api/users/${id}`).then((r) => r.json()),
    (err) => new Error(`Failed to fetch user: ${err}`),
  );

const fetchOrders = (userId: string): TE.TaskEither<Error, Order[]> =>
  TE.tryCatch(
    () => fetch(`/api/orders?userId=${userId}`).then((r) => r.json()),
    (err) => new Error(`Failed to fetch orders: ${err}`),
  );

const calculateTotals = (orders: Order[]) =>
  orders.reduce((sum, o) => sum + o.total, 0);

const formatReport = (total: number) => `Total revenue: $${total.toFixed(2)}`;

const fetchAndProcess = (id: string) =>
  pipe(
    fetchUser(id),
    TE.chain((user) => fetchOrders(user.id)),
    TE.map(calculateTotals),
    TE.map(formatReport),
  );

If fetchUser fails, fetchOrders never runs. The error propagates through the pipeline without any try-catch blocks.

Combining pipe and flow

A common pattern: define small pipelines with flow, orchestrate them with pipe:

import { pipe } from "@oofp/core/pipe";
import { flow } from "@oofp/core/flow";
import * as E from "@oofp/core/either";

const parseNumber = flow(
  (s: string) => Number(s),
  (n) => (isNaN(n) ? E.left("Invalid number" as const) : E.right(n)),
);

const ensureRange = (min: number, max: number) =>
  flow(
    E.iif((n: number) => n >= min && n <= max),
    E.mapLeft(() => `Must be between ${min} and ${max}` as const),
  );

const parsePercentage = (input: string) =>
  pipe(
    parseNumber(input),
    E.chain(ensureRange(0, 100)),
  );

parsePercentage("42");   // Right(42)
parsePercentage("-5");   // Left("Must be between 0 and 100")
parsePercentage("abc");  // Left("Invalid number")

flow creates the building blocks. pipe assembles them.

pipe vs Method Chaining

You might be thinking: "This looks like .then().then() or array.map().filter()." Method chaining and pipe solve a similar problem, but pipe is more general.

Method chaining only works with methods defined on a specific class:

// Method chaining — only works with Array's built-in methods
const result = [1, 2, 3, 4, 5]
  .filter((n) => n > 2)
  .map((n) => n * 2)
  .reduce((sum, n) => sum + n, 0);

What if you need to call a utility function from another module in the middle of the chain? You can't. You have to break the chain, assign to a variable, and start a new chain.

pipe works with any function, from any module:

import { pipe } from "@oofp/core/pipe";
import * as L from "@oofp/core/list";

const result = pipe(
  [1, 2, 3, 4, 5],
  L.filter((n) => n > 2),
  L.map((n) => n * 2),
  L.reduce(0, (sum, n) => sum + n),
  formatAsUSD,        // from your utils module
  addTaxDisclaimer,   // from another module
);

You can mix functions from any source. There's no class hierarchy. No prototype chain. Just functions in, values out.

This also makes testing simpler. Each function in the pipeline is a standalone unit that you can test independently. No need to instantiate a class or mock methods.

TC39 Pipeline Operator

JavaScript has a stage 2 proposal for a pipeline operator |>:

// Proposed syntax (not yet available)
const result = input
  |> validate(%)
  |> removeSpaces(%)
  |> trim(%)
  |> uppercase(%);

It solves the same problem pipe solves. But as of 2025, the proposal has been in stage 2 for years. It requires transpilation with experimental Babel plugins. It has gone through multiple syntax revisions. And it offers no type safety beyond what TypeScript already provides.

pipe from @oofp/core/pipe gives you the same ergonomics today:

Works in any TypeScript project with zero configuration.
Full type inference through the entire chain.
No experimental flags or transpiler plugins.
Available right now, not pending committee approval.

If the pipeline operator eventually lands in the language, migrating from pipe will be straightforward. Until then, pipe is the practical choice.

When to Use Each

Utility	Input	Returns	Use when
`pipe(value, f, g, h)`	A value + functions	The final result	You have a value and want to transform it now
`flow(f, g, h)`	Functions only	A new function	You want a reusable pipeline to apply later
`compose(h, g, f)`	Functions only (reversed)	A new function	You want right-to-left (mathematical) order

The decision tree is simple:

Have a value already? Use pipe.
Building a reusable transformation? Use flow.
Prefer mathematical notation? Use compose.

In practice, you'll use pipe about 80% of the time, flow about 19%, and compose rarely. That's fine. They all have full TypeScript inference, they all compose cleanly, and they all come from @oofp/core.

Getting Started

Install the core package:

npm install @oofp/core

Import what you need:

import { pipe } from "@oofp/core/pipe";
import { flow } from "@oofp/core/flow";
import { compose } from "@oofp/core/compose";

For a deeper look at each utility with more examples and API details, see the Pipe, Flow & Compose documentation.

Start with pipe. Replace one nested function call in your codebase. Once the reading order matches the execution order, you won't want to go back.

Functional Error Handling in TypeScript: Beyond try-catch

Adriel Avila — Thu, 23 Jul 2026 15:30:09 +0000

Every TypeScript developer has written something like this:

function getUser(id: string): User {
  const user = db.findUser(id);
  if (!user) throw new Error("User not found");
  return user;
}

The function signature says it returns a User. But that's a lie. It might throw, and nothing in the type system warns you about it. The caller has to remember to wrap it in try-catch, hope they handle the right error type, and accept that the compiler won't help if they forget.

This is the fundamental problem with exception-based error handling in TypeScript: errors are invisible in function signatures. They travel through a hidden channel that the type system cannot track.

There is a better way.

The Problem with try-catch

Consider a typical API call:

async function fetchUserOrders(userId: string) {
  try {
    const user = await fetchUser(userId);
    const orders = await fetchOrders(user.id);
    const enriched = orders.map((order) => ({
      ...order,
      userName: user.name,
    }));
    return enriched;
  } catch (error) {
    // What type is `error`? We don't know.
    // Did fetchUser throw? Or fetchOrders?
    // Is it a network error? A validation error? A parsing error?
    console.error("Something went wrong:", error);
    return [];
  }
}

Three problems stand out:

Lost type information. The catch block receives unknown. You have to guess or use instanceof chains to figure out what went wrong.
Invisible failure modes. Nothing in the function signature indicates it can fail. Callers see Promise<Order[]> and might not realize they need error handling.
Broken composition. You cannot chain operations cleanly. Every step might throw, so you either nest try-catch blocks or lump everything into one, losing granularity.

Either: Type-Safe Errors for Sync Operations

Either<E, A> is a type that explicitly represents a computation that can succeed with a value of type A or fail with an error of type E. The error type is right there in the signature — the compiler enforces it.

import * as E from "@oofp/core/either";

type ValidationError = { field: string; message: string };

const validateAge = (input: string): E.Either<ValidationError, number> => {
  const n = Number(input);
  if (isNaN(n)) return E.left({ field: "age", message: "Not a number" });
  if (n < 0 || n > 150) return E.left({ field: "age", message: "Out of range" });
  return E.right(n);
};

The return type Either<ValidationError, number> tells you everything: this function might fail with a ValidationError, or succeed with a number. No surprises. No hidden exceptions.

Composing with pipe

The real power of Either emerges when you compose operations using pipe:

import { pipe } from "@oofp/core/pipe";
import * as E from "@oofp/core/either";

type ParseError = string;

const parseNumber = (s: string): E.Either<ParseError, number> => {
  const n = Number(s);
  return isNaN(n) ? E.left(`"${s}" is not a number`) : E.right(n);
};

const ensurePositive = (n: number): E.Either<ParseError, number> =>
  n > 0 ? E.right(n) : E.left("Must be positive");

const ensureBelow = (max: number) => (n: number): E.Either<ParseError, number> =>
  n < max ? E.right(n) : E.left(`Must be below ${max}`);

const parsePercentage = (input: string) =>
  pipe(
    parseNumber(input),
    E.chain(ensurePositive),
    E.chain(ensureBelow(100)),
  );

parsePercentage("42");    // Right(42)
parsePercentage("-5");    // Left("Must be positive")
parsePercentage("abc");   // Left("\"abc\" is not a number")
parsePercentage("150");   // Left("Must be below 100")

Each step in the pipeline short-circuits on error. If parseNumber fails, ensurePositive never runs. The error propagates automatically, and its type is tracked at every step.

Validating structured data

Use sequenceObject to validate multiple fields at once:

import { pipe } from "@oofp/core/pipe";
import * as E from "@oofp/core/either";

interface UserForm {
  name: string;
  email: string;
  age: number;
}

const validateForm = (data: Record<string, string>): E.Either<string, UserForm> =>
  E.sequenceObject({
    name: pipe(
      data.name,
      E.fromNullable("Name is required"),
      E.chain((s) => s.length >= 2 ? E.right(s) : E.left("Name too short")),
    ),
    email: pipe(
      data.email,
      E.fromNullable("Email is required"),
      E.chain((s) => s.includes("@") ? E.right(s) : E.left("Invalid email")),
    ),
    age: pipe(
      data.age,
      E.fromNullable("Age is required"),
      E.chain(parseNumber),
      E.chain(ensurePositive),
    ),
  });

The result is either a fully validated UserForm or the first validation error. The compiler knows exactly what you'll get.

TaskEither: Async Error Handling

Most real applications involve async operations — API calls, database queries, file I/O. TaskEither<E, A> extends Either into the async world:

type TaskEither<E, A> = () => Promise<Either<E, A>>;

It's a lazy function that, when executed, returns a Promise that always resolves to an Either. No rejections, no unhandled promises — just typed success or failure.

import * as TE from "@oofp/core/task-either";
import { pipe } from "@oofp/core/pipe";

interface HttpError {
  status: number;
  message: string;
}

interface User {
  id: string;
  name: string;
  email: string;
}

const fetchUser = (id: string): TE.TaskEither<HttpError, User> =>
  pipe(
    () => fetch(`/api/users/${id}`).then(async (res) => {
      if (!res.ok) throw { status: res.status, message: res.statusText };
      return res.json() as Promise<User>;
    }),
    TE.tryCatch((err) => err as HttpError),
  );

tryCatch wraps the fallible async operation. If the promise rejects, the error is caught and mapped to your typed error via the callback. The resulting TaskEither never rejects.

Building async pipelines

Chain async operations the same way you chain sync ones:

interface Order {
  id: string;
  userId: string;
  total: number;
}

const fetchOrders = (userId: string): TE.TaskEither<HttpError, Order[]> =>
  pipe(
    () => fetch(`/api/orders?userId=${userId}`).then(async (res) => {
      if (!res.ok) throw { status: res.status, message: res.statusText };
      return res.json() as Promise<Order[]>;
    }),
    TE.tryCatch((err) => err as HttpError),
  );

const getUserWithOrders = (userId: string) =>
  pipe(
    fetchUser(userId),
    TE.chain((user) =>
      pipe(
        fetchOrders(user.id),
        TE.map((orders) => ({ user, orders })),
      ),
    ),
  );

If fetchUser fails, fetchOrders never executes. The error type flows through the entire pipeline.

Error recovery

Use orElse or chainLeft to recover from errors:

const fetchUserWithFallback = (id: string) =>
  pipe(
    fetchUser(id),
    TE.orElse((err) =>
      err.status === 404
        ? TE.of({ id, name: "Guest", email: "" })
        : TE.left(err),
    ),
  );

Collecting independent data

Use sequenceObject to combine multiple operations into a single result:

const getUserDashboard = (id: string) =>
  TE.sequenceObject({
    user: fetchUser(id),
    orders: fetchOrders(id),
    settings: fetchSettings(id),
  });
// TaskEither<HttpError, { user: User; orders: Order[]; settings: Settings }>

Each operation runs sequentially. If any fails, execution stops and you get the first error. Need parallelism? Use concurrencyObject instead:

const getUserDashboard = (id: string) =>
  TE.concurrencyObject()({
    user: fetchUser(id),
    orders: fetchOrders(id),
    settings: fetchSettings(id),
  });

Resilience with retry

const fetchUserReliable = (id: string) =>
  pipe(
    fetchUser(id),
    TE.retry({
      maxRetries: 3,
      delay: 1000,
      skipIf: (err) => err.status === 404, // don't retry "not found"
      onError: (err) => console.warn(`Retry: ${err.message}`),
    }),
  );

Bridging to the Outside World

At the boundaries of your application — HTTP handlers, React components, CLI entry points — you need to extract the Either and produce a concrete result:

import * as TE from "@oofp/core/task-either";
import { pipe } from "@oofp/core/pipe";

// Express handler
app.get("/users/:id", async (req, res) => {
  const result = await pipe(
    getUserWithOrders(req.params.id),
    TE.fold(
      (err) => ({ status: err.status, body: { error: err.message } }),
      (data) => ({ status: 200, body: data }),
    ),
    (task) => task(),
  );

  res.status(result.status).json(result.body);
});

fold collapses both branches into a single type. No try-catch anywhere. The error type is explicit, the happy path is clean, and the compiler ensures you handle both cases.

Why This Matters

Switching from try-catch to Either and TaskEither gives you three concrete advantages:

Type safety. Every function signature declares its failure modes. If a function returns TaskEither<HttpError | ValidationError, User>, you know exactly what can go wrong. The compiler enforces exhaustive handling.

Composability. Operations compose with pipe, chain, and map. You build complex pipelines from small, testable functions. Error propagation is automatic — no manual try-catch threading.

Testability. Functions that return Either are pure. They don't throw, they don't have hidden side effects, and they're trivial to test:

import { expect, test } from "vitest";
import * as E from "@oofp/core/either";

test("parsePercentage rejects negative numbers", () => {
  const result = parsePercentage("-5");
  expect(E.isLeft(result)).toBe(true);
  expect(result).toEqual(E.left("Must be positive"));
});

No mocking try-catch, no asserting that something throws — just straightforward input-output testing.

Getting Started

Install @oofp/core and start with the building blocks:

npm install @oofp/core

Either documentation — synchronous error handling
TaskEither documentation — async error handling
Pipe, Flow & Compose — function composition

The patterns scale from small validations to full application architectures. Start by replacing one try-catch block with Either, and the benefits will compound as you build on top of it.

Dependency Injection in TypeScript Without Classes or Decorators

Adriel Avila — Thu, 23 Jul 2026 15:30:05 +0000

You want dependency injection in TypeScript. So you reach for InversifyJS, tsyringe, or NestJS. You add reflect-metadata to your entry point. You slap @Injectable() on every class. You register bindings in a container. You configure modules. You emit decorator metadata. You lose tree-shaking. And after all that setup, the compiler still cannot tell you if you forgot to register a dependency — you find out at runtime.

There is a simpler way. One that uses the type system itself as the DI container.

The Class-Based DI Tax

Here is what dependency injection looks like in most TypeScript projects:

import { injectable, inject } from "tsyringe";

@injectable()
class UserRepository {
  constructor(@inject("Database") private db: Database) {}

  async findById(id: string): Promise<User | null> {
    return this.db.query("SELECT * FROM users WHERE id = ?", [id]);
  }
}

@injectable()
class UserService {
  constructor(
    @inject(UserRepository) private userRepo: UserRepository,
    @inject("Logger") private logger: Logger,
  ) {}

  async getUser(id: string): Promise<User> {
    this.logger.info(`Fetching user ${id}`);
    const user = await this.userRepo.findById(id);
    if (!user) throw new Error("User not found");
    return user;
  }
}

// Somewhere in bootstrap code...
container.register("Database", { useClass: PostgresDatabase });
container.register("Logger", { useClass: ConsoleLogger });
const service = container.resolve(UserService);

This works. But count the costs:

Runtime reflection. reflect-metadata must be imported before anything else. Decorator metadata is emitted into JavaScript output, adding bundle weight.
String tokens. @inject("Database") is a string. Rename it and nothing warns you. Forget to register it and you get a runtime error.
No tree-shaking. The container holds references to everything. Bundlers cannot eliminate unused code.
Class coupling. Every service must be a class. Every dependency must go through the constructor. You cannot use plain functions.
Testing ceremony. To test UserService, you create a testing module, override providers, resolve from a test container. That is a lot of machinery for calling a function with a mock.

What if the type system could do all of this at compile time, with zero runtime overhead?

The Reader Pattern

A Reader<R, A> is a function:

type Reader<R, A> = (context: R) => A;

R is what the function needs. A is what it produces. The dependency requirements are encoded in the type signature, not in decorators or a container registry.

import * as R from "@oofp/core/reader";
import { pipe } from "@oofp/core/pipe";

interface Config {
  apiUrl: string;
  timeout: number;
}

const getApiUrl: R.Reader<Config, string> = R.from((ctx) => ctx.apiUrl);

const buildHeaders = pipe(
  getApiUrl,
  R.map((url) => ({ "X-Api-Base": url })),
);

// Provide the context at the boundary
const headers = R.run({ apiUrl: "https://api.example.com", timeout: 5000 })(buildHeaders);
// { "X-Api-Base": "https://api.example.com" }

ask() gives you the entire context:

const program = pipe(
  R.ask<Config>(),
  R.map((ctx) => `Connecting to ${ctx.apiUrl} with timeout ${ctx.timeout}ms`),
);

chain lets you sequence computations that share the same context:

const getUser = (id: string): R.Reader<{ userRepo: UserRepo }, User | null> =>
  R.from(({ userRepo }) => userRepo.findById(id));

const logResult = (user: User | null): R.Reader<{ logger: Logger }, string> =>
  R.from(({ logger }) => {
    const msg = user ? `Found: ${user.name}` : "Not found";
    logger.info(msg);
    return msg;
  });

Use chainw to merge contexts from different modules:

const findAndLog = (id: string) =>
  pipe(
    getUser(id),
    R.chainw(logResult),
  );
// Reader<{ userRepo: UserRepo } & { logger: Logger }, string>

TypeScript infers the combined requirement. No registration step.

ReaderTaskEither for Real Applications

Reader handles dependency injection. But real application code is async and can fail. ReaderTaskEither<R, E, A> combines all three:

type ReaderTaskEither<R, E, A> = (r: R) => () => Promise<Either<E, A>>;

R — dependencies the computation requires
E — typed error on failure
A — success value

Nothing executes until you provide the context and call the resulting thunk. The entire pipeline is a description, not an execution.

import * as RTE from "@oofp/core/reader-task-either";
import * as TE from "@oofp/core/task-either";
import { pipe } from "@oofp/core/pipe";

// Define what your functions need via types
type Database = { db: { findUser: (id: string) => Promise<User | null> } };
type Logger = { logger: { info: (msg: string) => void } };

type AppError = { code: string; message: string };

// Each function declares its dependencies in the R type parameter
const findUser = (id: string): RTE.ReaderTaskEither<Database, AppError, User> =>
  pipe(
    RTE.ask<Database>(),
    RTE.chaint(({ db }) =>
      pipe(
        () => db.findUser(id),
        TE.tryCatch((err): AppError => ({ code: "DB_ERROR", message: String(err) })),
        TE.chain((user) =>
          user === null
            ? TE.left<AppError>({ code: "NOT_FOUND", message: "User not found" })
            : TE.of(user),
        ),
      ),
    ),
  );

const logAction = (msg: string): RTE.ReaderTaskEither<Logger, never, void> =>
  pipe(
    RTE.ask<Logger>(),
    RTE.map(({ logger }) => logger.info(msg)),
  );

Look at findUser. Its type signature says: "Give me a Database in the context, and I will asynchronously return either an AppError or a User." That is the entire dependency injection contract, enforced by the compiler.

Composing Services

The key insight is what happens when you chain functions that need different contexts. chainwc (chain with context widening) merges them automatically:

type OrderService = { orderRepo: { findByUserId: (id: string) => Promise<Order[]> } };

const getUserOrders = (userId: string): RTE.ReaderTaskEither<OrderService, AppError, Order[]> =>
  pipe(
    RTE.ask<OrderService>(),
    RTE.chaint(({ orderRepo }) =>
      pipe(
        () => orderRepo.findByUserId(userId),
        TE.tryCatch((err): AppError => ({ code: "DB_ERROR", message: String(err) })),
      ),
    ),
  );

// Compose operations from different modules
const getUserWithOrders = (id: string) =>
  pipe(
    findUser(id),                                // RTE<Database, AppError, User>
    RTE.chainwc((user) =>                        // merges Database & OrderService & Logger
      pipe(
        logAction(`Fetching orders for ${user.name}`),
        RTE.chainwc(() => getUserOrders(user.id)),
        RTE.map((orders) => ({ user, orders })),
      ),
    ),
  );
// Final type: RTE<Database & OrderService & Logger, AppError, { user: User; orders: Order[] }>

TypeScript computed the intersection Database & OrderService & Logger from the composition. You did not write it. You did not register it. The compiler inferred it from how you composed your functions.

This is compile-time dependency injection. If you forget to provide orderRepo when you run this pipeline, the compiler rejects it. Not at runtime — at build time.

Providing Dependencies

RTE.provide satisfies part of the context, removing those keys from the type:

const program = getUserWithOrders("123");
// RTE<Database & OrderService & Logger, AppError, { user: User; orders: Order[] }>

const withLogger = pipe(
  program,
  RTE.provide({ logger: { info: console.log } }),
);
// RTE<Database & OrderService, AppError, { user: User; orders: Order[] }>

const withDb = pipe(
  withLogger,
  RTE.provide({ db: createDb() }),
);
// RTE<OrderService, AppError, { user: User; orders: Order[] }>

const fullyProvided = pipe(
  withDb,
  RTE.provide({ orderRepo: createOrderRepo() }),
);
// RTE<{}, AppError, { user: User; orders: Order[] }>

Each provide call narrows the R type. When R reaches {}, all dependencies are satisfied and you can run the pipeline.

For async dependency creation, use provideTE:

const createDbPool = (): TE.TaskEither<AppError, Database> =>
  pipe(
    () => Pool.create({ host: "localhost", max: 10 }),
    TE.tryCatch((err): AppError => ({ code: "POOL_ERROR", message: String(err) })),
    TE.map((pool) => ({ db: { findUser: (id) => pool.query("SELECT ...") } })),
  );

const withDb = pipe(
  program,
  RTE.provideTE(createDbPool()),
);

When a dependency itself depends on another part of the context, use provideRTE:

type Config = { config: { dbConnectionString: string } };

const withDbFromConfig = pipe(
  program,
  RTE.provideRTE((ctx: Config) =>
    pipe(
      RTE.of(ctx),
      RTE.chaint((c) =>
        pipe(
          () => Pool.create(c.config.dbConnectionString),
          TE.tryCatch((err): AppError => ({ code: "POOL_ERROR", message: String(err) })),
        ),
      ),
      RTE.map((pool) => ({ db: pool })),
    ),
  ),
);
// Database is provided, but Config is now required

Running at the Boundary

At the edge of your application — an HTTP handler, a CLI command, a test — you provide the full context and execute:

import * as E from "@oofp/core/either";

app.get("/users/:id/orders", async (req, res) => {
  const result = await pipe(
    getUserWithOrders(req.params.id),
    RTE.run({
      db: appDb,
      orderRepo: appOrderRepo,
      logger: appLogger,
    }),
  )();

  pipe(
    result,
    E.fold(
      (err) => res.status(err.code === "NOT_FOUND" ? 404 : 500).json({ error: err.message }),
      (data) => res.status(200).json(data),
    ),
  );
});

Testing

This is where the Reader pattern delivers the biggest practical win. Testing a function that uses ReaderTaskEither means providing a plain object with mock implementations. That is it.

import { describe, it, expect, vi } from "vitest";
import * as E from "@oofp/core/either";

describe("findUser", () => {
  it("returns the user when found", async () => {
    const mockDb = {
      findUser: vi.fn().mockResolvedValue({ id: "1", name: "Alice", email: "alice@test.com" }),
    };

    const result = await pipe(
      findUser("1"),
      RTE.run({ db: mockDb }),
    )();

    expect(E.isRight(result)).toBe(true);
    expect(mockDb.findUser).toHaveBeenCalledWith("1");
  });

  it("returns NOT_FOUND when user is null", async () => {
    const mockDb = { findUser: vi.fn().mockResolvedValue(null) };

    const result = await pipe(
      findUser("999"),
      RTE.run({ db: mockDb }),
    )();

    expect(result).toEqual(E.left({ code: "NOT_FOUND", message: "User not found" }));
  });
});

describe("getUserWithOrders", () => {
  it("composes user and order lookups", async () => {
    const result = await pipe(
      getUserWithOrders("1"),
      RTE.run({
        db: { findUser: vi.fn().mockResolvedValue({ id: "1", name: "Alice" }) },
        orderRepo: { findByUserId: vi.fn().mockResolvedValue([{ id: "o1", total: 50 }]) },
        logger: { info: vi.fn() },
      }),
    )();

    expect(E.isRight(result)).toBe(true);
  });
});

Compare this with the NestJS testing equivalent:

// NestJS testing setup
const module = await Test.createTestingModule({
  providers: [
    UserService,
    { provide: UserRepository, useValue: mockUserRepo },
    { provide: "Logger", useValue: mockLogger },
    { provide: "Database", useValue: mockDb },
  ],
}).compile();

const service = module.get<UserService>(UserService);
const result = await service.getUser("1");

The NestJS version requires importing Test from @nestjs/testing, creating a module, registering providers, compiling the module, and resolving the service. The Reader version calls a function with an object.

Why This Beats IoC Containers

No runtime overhead. No container instantiation, no reflection, no metadata emission. ReaderTaskEither compiles down to plain function calls.
Tree-shakeable. Everything is functions and types. Bundlers eliminate unused code normally.
Type-safe at compile time. If you forget to provide a dependency, the compiler tells you. Not a runtime error — a red squiggle in your editor before you save the file.
No decorators or metadata. No emitDecoratorMetadata in your tsconfig. No reflect-metadata import. No experimental features.
Works everywhere. Browser, Node, Deno, Bun, Cloudflare Workers. No environment-specific runtime requirements.
Dependencies are explicit. Every function's signature declares exactly what it needs. Read the type, know the contract.
Testing is trivial. Provide a plain object with mocks. No container setup, no module configuration, no @Injectable().
Incremental adoption. You can use ReaderTaskEither in one module without converting your entire codebase. It composes with existing code.

Getting Started

Install the library:

npm install @oofp/core

Start with these resources:

ReaderTaskEither reference — full API documentation
Dependency injection guide — patterns for structuring applications
Reader reference — the synchronous building block

The pattern scales from a single function to an entire application architecture. Start by replacing one service class with a function that returns ReaderTaskEither. Chain it with another. Watch the compiler infer your dependency graph. You will not go back to decorators.