DEV Community: Adriel Avila

Harness Engineering through Functional Programming: Tools, Effects, and Verification

Adriel Avila — Mon, 03 Aug 2026 16:54:17 +0000

The phrase harness engineering is receiving attention because coding agents have made an old systems problem newly visible.

A capable model can propose a plausible change. That is not the same as navigating the right repository, selecting the right tools, respecting architectural boundaries, recovering from failure, and proving that the result is complete. Reliable software work emerges from the model and the system around it.

OpenAI describes this shift in Harness engineering: leveraging Codex in an agent-first world. The team found that progress depended on making capabilities legible to the agent, keeping repository knowledge structured, enforcing architectural invariants, and turning review and validation into feedback loops. Microsoft uses agent harness for the runtime that adds planning, memory, tool orchestration, approvals, context management, and telemetry around a model. Anthropic draws a related distinction between predefined workflows and agents that dynamically direct their own process and tool use.

Functional programming has spent decades asking how to represent computations, compose them, separate descriptions from execution, make dependencies explicit, and preserve meaning under transformation. Those ideas do not constitute a complete agent harness. They do, however, provide a mature technical foundation for one of its most important layers: the tools and effects through which an agent acts on the world.

This article develops that narrower claim:

Functional programming does not replace the agent harness. It gives us strong abstractions for typed tools, explicit effects, controlled execution, composable recovery, and verifiable outcomes.

Why harness engineering matters now

A language model produces output from context. A coding agent must also inspect a workspace, revise a plan, call tools, interpret observations, retain task state, operate within permissions, and decide when enough evidence exists to stop.

OpenAI's account is useful because it treats agent failures as system feedback. When Codex could not complete a task, the question was not only whether the model needed a better prompt. The team asked which capability, abstraction, constraint, or feedback signal was missing from the environment. Repository documentation became a navigable map. Application behavior, logs, metrics, tests, and browser state became observable. Architecture rules became mechanically enforceable.

This changes the unit we should evaluate. The relevant system is not merely the model:

model + harness + environment -> observable engineering behavior

A recent research proposal, AI Harness Engineering, formalizes this view with responsibilities including task specification, context selection, tool access, project memory, task state, observability, failure attribution, verification, permissions, and maintenance state. It is a useful vocabulary, although it is a recent preprint rather than an established industry standard.

A model can write correct local code and still fail the engineering task. It may open the wrong file, call an unsafe operation, misread a test failure, forget a constraint, or declare success without validating the requirement. Many such failures occur between reasoning and execution.

The harness is larger than its tools

Tools let the model read files, search code, run tests, query logs, drive a browser, or modify a repository. But a list of callable functions is not a complete runtime.

Microsoft Agent Framework's harness illustrates the difference. The developer provides a model, instructions, and tools; the harness adds facilities such as planning, history, compaction, approvals, memory, and telemetry. The tool answers what operation is available. The harness also decides:

what the model sees before choosing it;
whether the call is permitted;
how its input is validated;
what state is recorded before and after execution;
how errors and partial completion are represented;
whether another iteration is useful;
what evidence satisfies the definition of done.

Anthropic's Building effective agents makes another important separation. Workflows follow predefined paths, while agents dynamically control their process and tool use. Functional composition is naturally suited to defining reliable workflows, but that does not mean it supplies the policy that decides which workflow to construct next.

This is where the analogy needs discipline. A TaskEither is not memory. A Reader is not a sandbox. A Saga is not an agent loop. A Zod schema is not a permission system. These abstractions can make the corresponding runtime mechanisms clearer and safer, but they do not make those mechanisms appear automatically.

A functional model of a tool

Consider a minimal model for a tool:

type Tool<I, R, E, O> =
  (input: I) => ReaderTaskEither<R, E, O>

This is not an OOFP API. It is a compact design model built from ReaderTaskEither.

The four type parameters say more than a conventional asynchronous function usually does:

I is the explicit input supplied by the caller.
R is the environment of capabilities required to execute the operation.
E is the expected failure channel.
O is the successful output.

The returned value is lazy. Calling the tool with an input constructs a program; it does not have to execute the effect immediately. The runtime can validate the request, check permissions, select an environment, attach tracing, or reject the operation before interpretation.

Compare that with a common shape:

const inspectFile = async (path: string): Promise<string> => {
  return fs.readFile(path, "utf8")
}

The signature reveals the argument and eventual success value. It does not reveal which filesystem authority is used, which failures are expected, whether other effects occur, or whether calling the function starts work immediately.

A functional version makes the capability part of the program:

type FileError =
  | { tag: "not-found"; path: string }
  | { tag: "access-denied"; path: string }

type FileSystem = {
  readText: (path: string) => TaskEither<FileError, string>
}

const inspectFile = (
  path: string,
): ReaderTaskEither<FileSystem, FileError, string> =>
  pipe(
    RTE.ask<FileSystem>(),
    RTE.chaint(({ readText }) => readText(path)),
  )

This does not guarantee safety. A FileSystem implementation could still expose the entire machine. It provides a visible capability boundary: production can supply a workspace-scoped interpreter, tests an in-memory one, and read-only tasks an environment without write capability.

Input is a contract, not prompt prose

Agent tools normally require a machine-readable input schema. The functional model begins after that input has been decoded, so a fuller definition can carry both schema and program:

type ToolDefinition<I, R, E, O> = {
  name: string
  input: z.ZodType<I>
  execute: (input: I) => ReaderTaskEither<R, E, O>
}

The schema rejects malformed model output at the trust boundary. The program receives a typed value rather than repeatedly defending itself against unknown. This is particularly important for agents: model-generated arguments are untrusted input, even when they look structurally plausible.

Dependencies can approximate capabilities

Reader is usually introduced as dependency injection. In a harness, it is helpful to think in terms of capabilities. A read tool requires ReadWorkspace; a test tool requires TestRunner; a deployment tool requires a much stronger authority.

Narrow records make those differences inspectable:

type AnalyzeContext = {
  workspace: ReadWorkspace
  tests: TestRunner
  logger: StructuredLogger
}

The type checker can prevent accidental use of a capability that is absent from the context. Runtime permissions must still enforce filesystem, network, and credential boundaries. Types document and constrain the program; the sandbox constrains the process.

Errors become observations

An exception interrupts normal composition and often loses domain meaning as it travels through generic catch blocks. Either<E, O> turns expected failure into an observation the harness can classify.

That distinction affects recovery. not-found may mean the agent selected the wrong path and should search again. test-failed may be valuable feedback that should return to the reasoning loop. access-denied should not be retried with increasingly creative shell commands. timeout may permit a bounded retry. A typed error does not choose the policy, but it gives the policy something better than an arbitrary message to inspect.

Laziness creates an execution boundary

TaskEither<E, O> describes an asynchronous computation. It can be assembled, transformed, wrapped with telemetry, or replaced before it runs. With ReaderTaskEither<R, E, O>, the complete environment is supplied at a deliberate boundary:

const result = await pipe(
  inspectFile("src/config.ts"),
  RTE.run(workspaceCapabilities),
  TE.run,
)

That boundary is a natural place for the harness to record the request, enforce a timeout, attach a correlation ID, collect the result, and decide what the model should observe next.

Evidence from a production TypeScript codebase

These ideas were tested against an anonymized production backend rather than derived only from small examples. The audited snapshot contained roughly 1,500 TypeScript source files. About 650 imported OOFP packages, with approximately 1,500 pipe calls, 3,500 ReaderTaskEither operations, and 75 test files.

Those numbers measure adoption, not agent productivity. The audit did not compare models, completion rates, token usage, or defect rates. Its evidence is structural: which patterns survived at production scale, where they improved inspectability, and where hidden effects remained.

1. Capability records made use cases reconstructible

Application services were commonly expressed as records of functions assembled from an explicit context. A use case could declare repositories, external services, configuration, and logging in one type, then return a ReaderTaskEither without resolving a container or reaching into module globals.

For a coding agent, this creates semantic compression. The signature identifies the required environment, possible failure, and output before the agent explores every implementation. The real adapter and the test double share the same structural contract. When a new capability is introduced, TypeScript points to the execution boundaries that must supply it.

This is not proof that an agent will understand the business requirement. It is evidence that less of the execution contract is hidden in constructor history and runtime registration.

2. Pipelines and Sagas exposed recovery structure

One audited workflow coordinated several state-changing operations with compensations. Each step described an action and a rollback; the composed Saga executed compensations when a later step failed.

That structure matters for both humans and agents. A flat sequence of named steps communicates the business order. Explicit compensation communicates which partial effects are reversible. A failing test can identify the step and expected cleanup instead of leaving the reader to infer recovery from nested try/catch blocks.

The strongest version of the pattern kept each step small and named. The weakest version mixed logging, fallback policy, object construction, and external calls inside long chain callbacks. Functional syntax did not rescue an unclear program. Composition helped only when the units being composed had coherent contracts.

3. Test doubles turned context into executable evidence

Tests frequently supplied plain records of functions as repositories, clocks, loggers, or remote services. Running the program required no full framework container. A test could provide fixed capabilities, execute the returned task, and assert the resulting Either plus the calls recorded by the doubles.

That is relevant to a coding harness because tests become an interpretable feedback channel. The agent does not need to infer success from the absence of an exception or from a vague log. It can observe a deterministic value and a focused assertion failure. This aligns with OpenAI's broader observation that agent-friendly repositories make architecture, application behavior, and validation directly legible.

This is an architectural inference, not a benchmark result. The audit shows that feedback can be local and explicit, not how much that changes agent performance.

How functional architecture helps coding agents

A coding agent operates under a limited context budget. Hidden dependencies require more repository reconstruction, untyped failures permit more interpretations, and eager effects blur planning and action.

Functional architecture reduces these uncertainties in several ways:

Signatures carry operational facts. ReaderTaskEither<Context, Error, Result> exposes needs, failure, and success together.
Composition supplies a small grammar. map, chain, mapLeft, orElse, and provide constrain the valid transformations between steps.
Pure cores narrow the search space. Deterministic transformations can be inspected and tested without recreating runtime state.
Capabilities support substitution. Real interpreters, sandboxed interpreters, and test doubles can satisfy the same record contract.
Effects can be executed once. Controllers, workers, CLIs, and tests become visible interpretation boundaries.
Failures remain data. Verification and recovery logic can branch on meaning rather than parse exception text.

These properties complement repository-level harness work. AGENTS.md, architecture maps, skills, linters, and test commands tell the agent how the repository should be changed. Functional contracts make more of the repository itself agree with that description. Documentation can drift; a type error and a failing deterministic test provide immediate counterevidence.

For the related argument about local reasoning and hidden state, see Referential Transparency in TypeScript.

Where the analogy stops

Calling any functional application an agent harness would erase useful distinctions.

Functional programming does not decide which files enter the context window. It does not maintain project memory, compact a long conversation, allocate a tool budget, request human approval, isolate a process, or determine when the model should stop. It does not provide telemetry merely because a program is composable. It does not turn a business function into a model-facing tool without a schema, description, authorization policy, and observation format.

The audited backend was not a coding-agent harness. Its architecture made important behavior explicit; the harness remained the larger arrangement of agent loop, repository instructions, tools, permissions, tests, and review.

The accurate relationship is therefore:

functional tools are a substrate inside the harness,
not a synonym for the harness

This distinction also protects us from a common category error. Reader can express that a program requires DeployProduction; it cannot prove that the concrete interpreter protects credentials or requires approval. TaskEither can represent PermissionDenied; it cannot prevent an unrelated shell tool from bypassing the intended path. Static capability design and runtime enforcement must reinforce each other.

Failure modes found in the audit

The production audit was valuable because the system was not perfectly functional.

Implicit clocks and identifiers. Some parsers generated dates or IDs while validating data. The same input could produce different output, and the creation effect was hidden inside a boundary that appeared deterministic. Moving clocks and generators into explicit capabilities separated decoding from creation.

Global loggers and direct console calls. A pipeline can preserve its success value while still writing through a module-level logger. From the type signature, that effect is invisible. Important flows benefit from receiving structured logging as a capability, especially when the harness needs correlation and trace evidence.

Premature execution. Wrapping an already-running Promise does not recover laziness. The operation has begun before the harness can attach policy. Adapters should return thunks or lazy tasks and let the boundary execute them.

Unreadable pipelines. Deeply nested pipe calls, inline conditionals, broad contexts, and repeated widening combinators can become as opaque as a long imperative method. Agents learn local patterns, including poor ones. Named domain steps and small contracts matter more than maximizing functional syntax.

Types mistaken for security. A narrow context improves design-time visibility but is not a process boundary. Filesystem scopes, network policy, secrets, approvals, and timeouts require runtime enforcement outside the TypeScript type system.

These failures identify where the program's description and its real execution have drifted apart—the seam harness engineering must manage.

Practical principles

The following rules are a useful starting point for repositories that coding agents will read and change:

Treat model-produced arguments as untrusted data. Decode every tool input with a machine-readable schema.
Model tools as programs, not eager operations. Construct effects first and execute them at a deliberate boundary.
Use narrow capability records. Express the authority required by each operation instead of passing a universal application container.
Represent expected failures as data. Give the harness stable categories for retry, recovery, escalation, and reporting.
Keep runtime enforcement separate. Pair typed capabilities with sandboxes, approvals, credential scopes, timeouts, and audit logs.
Name orchestration steps. The main pipeline should read like a plan whose components can be inspected independently.
Make compensation explicit. For multi-step effects, state which operations can be reversed and verify rollback behavior.
Provide deterministic interpreters for tests. Make the cheapest verification path local, focused, and readable by an agent.
Run effects once. Supply context and interpret the program at controllers, workers, CLI commands, or tool executors.
Measure the complete system. Evaluate model, harness, and environment together; do not attribute every success or failure to the model.

A compact OOFP-shaped tool can then look like this:

type InspectInput = { path: string }

type InspectTool = ToolDefinition<
  InspectInput,
  ReadWorkspace,
  WorkspaceError,
  FileReport
>

const inspectTool: InspectTool = {
  name: "inspect_file",
  input: z.object({ path: z.string().min(1) }),
  execute: ({ path }) =>
    pipe(
      RTE.ask<ReadWorkspace>(),
      RTE.chaint((workspace) => workspace.read(path)),
      RTE.map(analyzeSource),
    ),
}

The surrounding harness still has work to do. It describes the tool to the model, validates the proposed call, decides whether the path is allowed, provides a scoped ReadWorkspace, records the execution, renders the Either as an observation, and determines what should happen next.

That is precisely the point. The model proposes. The functional program describes. The interpreter executes. The harness governs and verifies.

The useful connection

Harness engineering names the discipline of turning model capability into reliable system behavior. Context, state, tools, permissions, observability, recovery, and verification all participate.

Functional programming's contribution is more specific. It makes computations explicit before they run, carries dependencies and errors in types, composes smaller contracts, supports substitutable interpreters, and turns verification into program output.

Those properties were valuable before coding agents. Agents make their value easier to see.

When a probabilistic model is allowed to choose actions, the surrounding execution layer should contain as little accidental ambiguity as possible. Typed functional tools do not complete the harness, but they can make its boundary with the world narrower, more legible, and more accountable.

Understanding Monads in TypeScript: A Practical Guide

Adriel Avila — Mon, 03 Aug 2026 14:09:24 +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 — Sun, 02 Aug 2026 19:57:19 +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.

Referential Transparency in TypeScript: Software Humans and AI Can Reason About

Adriel Avila — Sun, 02 Aug 2026 19:57:16 +0000

The most valuable property of functional programming is not immutability, monads, or writing everything as an arrow function.

It is referential transparency.

An expression is referentially transparent when it can be replaced by its value without changing the behavior of the program. That sounds mathematical because it is. It is also one of the most practical constraints we can impose on production software.

Referential transparency reduces what a reader must know. It makes behavior local. It turns dependencies, errors, and effects into things that can be seen and composed instead of reconstructed from runtime state.

That helps a person reviewing a pull request. It helps the next person debugging an incident. It also helps an AI coding agent operating inside a finite context window. Humans and models have very different minds, but they share one limitation: both struggle when the meaning of a line depends on invisible history.

This is not a theoretical claim made from a toy project. The observations in this article come from auditing a mature TypeScript backend with roughly 1,500 source files, hundreds of pipe and ReaderTaskEither modules, Zod schemas, Prisma repositories, queues, external APIs, and 75 test suites. The application uses NestJS, so classes and decorators still exist at framework boundaries. Its business code, however, has deliberately moved toward typed functional programs.

The result is instructive precisely because it is not perfectly pure.

Substitution is the practical test

Consider a small transformation:

const normalizeEmail = (email: string): string =>
  email.trim().toLowerCase()

Every occurrence of:

normalizeEmail(" ADA@EXAMPLE.COM ")

can be replaced with:

"ada@example.com"

Nothing changes. The function does not read a global, inspect the clock, mutate its argument, write a log, or depend on how many times it has already been called.

This gives us a useful review question:

What information, beyond the arguments, must I know to predict this expression?

If the honest answer is “none,” the expression is locally understandable. If the answer includes object history, environment variables, container state, database contents, the current time, network availability, or an exception thrown three layers below, the expression is not referentially transparent.

The distinction is not about syntax:

const nextId = () => crypto.randomUUID()

This is an arrow function, but it is not referentially transparent. Replacing two calls with one previously computed value changes the program.

Likewise, a method can be pure:

class Price {
  static addTax(amount: number, rate: number): number {
    return amount + amount * rate
  }
}

The problem is not the class keyword. The problem is invisible input and invisible output.

Hidden context is the real coupling

Object-oriented dependency injection can make construction dependencies visible while leaving behavioral dependencies implicit:

class RegistrationService {
  async register(input: RegisterInput) {
    const existing = await this.repository.findByEmail(input.email)
    if (existing) throw new ConflictException()

    const user = {
      id: crypto.randomUUID(),
      createdAt: new Date(),
      ...input,
    }

    await this.repository.save(user)
    this.logger.info("User registered")
    return user
  }
}

To understand register, a reader needs more than input:

the repository implementation and its mutation history;
the system clock and random generator;
the exception behavior of every awaited call;
the logger's behavior;
the meaning of partial completion if saving or logging fails.

The constructor may list repository and logger, but the method's type still hides failure, time, identity generation, and execution policy.

A functional design does not make those concerns disappear. It promotes them into the program's vocabulary.

type RegistrationContext = {
  users: UserRepository
  clock: Clock
  ids: IdGenerator
  logger: Logger
}

const register = (
  dto: RegisterDto,
): RTE.ReaderTaskEither<RegistrationContext, RegistrationError, User> =>
  pipe(
    assertEmailAvailable(dto.email),
    RTE.chainwc(() => buildUser(dto)),
    RTE.chainwc(UserRepository.save),
    RTE.tapRTE(logRegistration),
  )

The signature is now a compact description:

RegistrationContext is required;
execution is asynchronous and lazy;
RegistrationError is an expected result;
success produces a User.

The function call constructs a program. It does not register anyone yet.

Describing an effect is different from performing it

A backend that never performs effects is not useful. It cannot store data, send a response, charge a card, or call an AI model.

The functional objective is therefore not “everything is pure.” It is:

Keep the description of effects referentially transparent, and execute those effects at explicit boundaries.

TaskEither<E, A> is a function:

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

The thunk matters. Compare these two repository adapters:

// Eager: the query starts now.
const result = prisma.user.findUnique({ where: { id } })

// Lazy: this value describes how to start the query later.
const result = () => prisma.user.findUnique({ where: { id } })

The second expression can be passed around, mapped, chained, retried, timed, or replaced in a test before anything happens.

A production-shaped repository can lift it into a typed pipeline:

const findById = (id: UserId) =>
  pipe(
    RTE.ask<{ prisma: PrismaClient }>(),
    RTE.map(({ prisma }) => () =>
      prisma.user.findUnique({ where: { id } }),
    ),
    RTE.chaint(TE.fromTask),
    RTE.map(M.fromNullable),
    RTE.mapLeft(mapDatabaseError("Unable to find user")),
  )

The database remains effectful. The important improvement is that its effect has a type, a construction point, an error translation, and an interpreter.

Four useful levels of transparency

Large applications are easier to discuss when we stop labeling whole files or layers simply “pure” or “impure.” The audited backend revealed four useful levels:

Level	Example	Property
Pure transformation	`calculateScore(profile, criteria)`	Same inputs always produce the same value
Program construction	`evaluateProfile(dto): RTE<Context, Error, Evaluation>`	Builds a lazy description without running effects
Effect interpreter	Prisma, HTTP, filesystem, queue adapters	Performs effects behind explicit functional contracts
Framework boundary	NestJS controller, worker processor, bootstrap	Supplies context, executes once, translates to the outside world

The dependency direction should move from the boundary toward programs and pure values. Execution moves in the opposite direction: the boundary supplies capabilities and runs the completed program.

This gradient is more honest than claiming a production backend is purely functional. It also gives reviewers a precise question: At which level is this code, and is an effect occurring too early?

Composition turns local reasoning into architecture

Referential transparency becomes architecturally powerful through composition.

One audited workflow accepted a public submission, built or merged a profile, parsed an attachment, created a review record, persisted it, and attempted a confirmation notification. Its main pipeline had the shape:

const processSubmission = (dto: SubmissionDto) =>
  pipe(
    buildProfile(dto),
    RTE.chainwc(saveProfile(dto)),
    RTE.chainwc(parseAttachment),
    RTE.map(createReview(dto)),
    RTE.chainwc(saveReview),
    RTE.tapRTE(() => sendConfirmationSoftFail(dto)),
  )

This reads as a business recipe because every named step preserves a common protocol. Each produces a value in an RTE context. chain connects dependent work. A left value short-circuits the remaining steps. tapRTE adds a policy-controlled effect without changing the successful result.

Composition gives us more than visual neatness:

dependencies combine in the Reader context;
error types combine in the left channel;
execution remains lazy;
the success value changes predictably from step to step;
a step can be replaced without rewriting the orchestration mechanism.

Without referential transparency, composition is fragile. A function that appears to transform A into B but secretly mutates shared state cannot be safely reordered, repeated, cached, tested, or substituted.

What humans gain

Local reasoning

A reviewer can understand a pure function from its signature, implementation, and tests. They do not need to search for constructor mutations, lifecycle hooks, or hidden singletons.

This does not eliminate the need to understand the system. It reduces the radius of understanding required for a specific change.

Tests that state behavior directly

Pure domain tests are ordinary input/output assertions:

expect(calculateRemainingCredits(account, purchase)).toEqual(
  E.right(expectedBalance),
)

Application programs need capabilities, but not a framework container:

const result = await pipe(
  updateProfile(dto),
  RTE.run({
    profiles: profileRepositoryDouble,
    embeddings: embeddingsServiceDouble,
    clock: fixedClock,
    logger: silentLogger,
  }),
  TE.run,
)

The test record is executable documentation of what the use-case needs. There is no Nest testing module, decorator metadata, database, or global clock to configure.

Failures stop being folklore

With exceptions, callers learn failure behavior through documentation, experience, or production incidents. TaskEither<DatabaseError | RecordConflict, Profile> makes expected failures part of the interface.

The type does not guarantee good error design, but it prevents expected failure from being completely invisible.

Safer change through substitution

If two functions implement the same total contract, one can replace the other. That is the foundation of refactoring. It is also why capabilities expressed as records of functions are powerful: a real adapter and a test double are values satisfying the same interface.

Debugging with fewer possible histories

Mutable objects accumulate history. When a result is wrong, the question becomes “which earlier operation changed this object?” Pure transformations narrow the question to “which input or rule produced this output?”

That difference is enormous during incidents.

What AI coding agents gain

An AI model does not understand software exactly as a human does. It predicts and reasons over the context it has been given. Referential transparency improves the quality of that context.

Semantic compression

This signature:

ReaderTaskEither<PaymentContext, PaymentError, Receipt>

compresses several facts into one place. An agent can infer that it must obtain PaymentContext, preserve the lazy computation, handle PaymentError, and produce Receipt. With an untyped async method, those facts may be distributed across constructors, thrown exceptions, mocks, and call sites.

A smaller search space

When a function depends only on its arguments, an agent can modify it using local evidence. Hidden global state forces repository-wide discovery and increases the number of plausible but incorrect changes.

This does not make repository exploration unnecessary. It makes the result of exploration more decisive.

Uniform transformation rules

map, chain, mapLeft, orElse, and provide form a small grammar. Once an agent identifies the current container and the next function's type, the set of valid transformations is constrained.

Regularity is valuable to humans; it is especially valuable to code-generation systems.

Verifiable output

Deterministic functions and plain capability records make it easier to generate focused tests. The agent can compare values instead of coordinating a large runtime environment.

Tests then become a feedback mechanism that rejects plausible-looking but semantically wrong code.

More reliable handoffs

Agents often operate in short sessions. Explicit pipelines preserve intent in code instead of requiring a previous agent's narrative. A named step such as assertProjectOwned communicates more durable information than an inline conditional embedded in a controller.

These are architectural inferences, not a productivity benchmark. Referential transparency does not make an agent correct. It removes classes of ambiguity that make both human and machine reasoning harder.

The audit also found broken transparency

The production system was not a functional utopia. Its deviations were some of the most useful findings.

Time and identity inside parsers

Several domain schemas supplied defaults such as:

createdAt: z.date().default(() => new Date())

Some constructors generated IDs when none were provided. Parsing the same input twice could therefore produce different values.

That breaks substitution and mixes two responsibilities: validating data and creating new identity.

A clearer design keeps parsing deterministic and moves creation into a program with explicit capabilities:

const parseProfile = (input: unknown): E.Either<ValidationError, ProfileDraft> =>
  pipe(profileSchema.safeParse(input), fromZodResult)

const createProfile = (draft: ProfileDraft) =>
  pipe(
    RTE.ask<{ clock: Clock; ids: IdGenerator }>(),
    RTE.map(({ clock, ids }): Profile => ({
      ...draft,
      id: ids.next(),
      createdAt: clock.now(),
    })),
  )

The clock and generator are still effectful. They are now visible, replaceable, and executed in the correct phase.

Imperative islands inside repositories

The audit found adapters containing try/catch, driver-specific branching, direct logging, and rethrowing inside an async block. Sometimes an external API makes a small imperative adapter unavoidable. The smell appears when the island also owns business policy and orchestration.

The remedy is not to ban try/catch cosmetically. It is to make the adapter small, convert its outcome immediately, and continue composition in TaskEither.

Pipelines can hide complexity too

A deeply nested pipe with several chain callbacks, inline conditions, and context construction is not automatically readable. Functional syntax can conceal control flow just as a large method can.

The successful pattern in the same codebase was a flat orchestration pipeline whose entries were named business steps. Referential transparency makes extraction safe; naming makes the result understandable.

Global loggers are hidden dependencies

Logging through tap may preserve the successful value, but it does not make the logger pure. A module-level logger is still hidden context. For important application flows, providing logging as a capability makes observability policy explicit and testable.

Referential transparency is not free

Functional architecture has costs.

Teams must learn the difference between map, chain, applicative composition, and execution.
Type errors involving nested contexts and error unions can be intimidating.
Excessive point-free style can remove useful names.
A generic effect stack can become ceremony around trivial code.
Poorly designed error unions can grow without a coherent recovery policy.
Laziness can surprise developers accustomed to eager Promises.

The answer is not maximum abstraction. It is the smallest abstraction that keeps important behavior explicit.

Use a plain function for a pure calculation. Use Either when synchronous validation can fail. Use TaskEither for lazy asynchronous failure. Add Reader when the computation genuinely needs capabilities. Keep framework classes where the framework requires them.

The goal is not to make every line look functional. The goal is to make business meaning substitutable and effects honest.

Working rules for human–AI codebases

The following rules survived contact with a large production system:

Ask what is hidden. Treat time, randomness, configuration, logging, and mutable caches as dependencies.
Separate parsing from creation. Validation should not silently generate identity or read the clock.
Return descriptions of effects. Do not start Promises while building the program.
Model expected failure as data. Reserve defects and truly unexpected failure for exceptions at the outer boundary.
Name business steps. The main pipeline should read as a recipe, not an implementation puzzle.
Decode at every trust boundary. HTTP bodies, database rows, queue messages, and AI responses are all untrusted values.
Execute once. Supply the complete context and run the program at the controller, worker, CLI, or test boundary.
Test substitution. Given fixed arguments and capabilities, repeated evaluation should produce the same observable value.
Audit escape hatches. Every new Date(), random ID, global read, throw, and direct Promise is a useful search target.
Optimize for the next reader. Humans and agents both benefit more from explicit names than clever combinator density.

The deeper payoff

Software maintenance is an exercise in prediction. Before changing a system, we try to predict what a piece of code means, what it can affect, and how the rest of the system will respond.

Referential transparency makes those predictions cheaper.

It does not eliminate effects. It gives them borders. It does not eliminate complexity. It lets complexity be composed from smaller contracts. It does not guarantee that humans or AI agents will write correct software. It gives both a codebase whose behavior is less dependent on invisible history.

That is why referential transparency is more than a functional-programming ideal. It is a collaboration protocol between the code, the person reading it today, and whatever intelligence must change it tomorrow.

For an end-to-end implementation, continue with Functional Clean Architecture and the runnable Opinionated Backend Architecture example.

Functional Error Handling in TypeScript: Beyond try-catch

Adriel Avila — Fri, 31 Jul 2026 11:47: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 — Fri, 31 Jul 2026 11:47:06 +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.

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.

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>

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();
}

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

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");

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

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

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))))));

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!"

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(%);

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.

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;
}

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

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:

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

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)),
  );

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[] }>

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");

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