Part 4: Functional Error Handling - Railway-Oriented Programming

Introduction

My first API service used try/catch everywhere. Nested error handling made code unreadable. Exceptions flew across module boundaries. Some errors got caught twice, others not at all. I couldn't tell which functions might throw just by looking at their signatures.

I refactored to functional error handling using Either and Option types. Errors became explicit in type signatures. Functions composed cleanly through success and failure paths. Error handling became predictable, composable, and type-safe. That's when I understood Railway-oriented programming.

This article teaches you to handle errors functionally using Either/Result types, Option/Maybe patterns, Railway-oriented programming, and composable error handling.

The Problem with Exceptions

// Exception-based approach - problems!
function parseUser(json: string): User {
    try {
        const data = JSON.parse(json);  // Might throw
        
        if (!data.username) {
            throw new Error('Missing username');
        }
        
        if (!data.email) {
            throw new Error('Missing email');
        }
        
        return {
            username: data.username,
            email: data.email
        };
    } catch (error) {
        // Lost type information
        throw new Error(`Parse error: ${error}`);
    }
}

function processUser(json: string): void {
    try {
        const user = parseUser(json);  // Might throw, but type doesn't say so!
        saveUser(user);  // Might throw too!
        sendEmail(user.email);  // And this!
    } catch (error) {
        // Which function threw? What error type?
        console.error('Something failed:', error);
    }
}

Problems:

• Errors not visible in type signatures

• Lost type information in catch blocks

• Breaks function composition

• Difficult to handle multiple error types

• Hard to track error flow

Either/Result Type

Either represents success (Right) or failure (Left).

type Either<E, A> = 
    | { type: 'left', value: E }
    | { type: 'right', value: A };

// Constructors
const left = <E, A>(value: E): Either<E, A> => ({
    type: 'left',
    value
});

const right = <E, A>(value: A): Either<E, A> => ({
    type: 'right',
    value
});

// Type guard
function isLeft<E, A>(either: Either<E, A>): either is { type: 'left', value: E } {
    return either.type === 'left';
}

function isRight<E, A>(either: Either<E, A>): either is { type: 'right', value: A } {
    return either.type === 'right';
}

// Usage
interface ValidationError {
    field: string;
    message: string;
}

function validateUsername(username: string): Either<ValidationError, string> {
    if (username.length < 3) {
        return left({ field: 'username', message: 'Too short' });
    }
    
    if (username.length > 20) {
        return left({ field: 'username', message: 'Too long' });
    }
    
    return right(username);
}

// Check result
const result = validateUsername('alice');

if (isRight(result)) {
    console.log('Valid username:', result.value);
} else {
    console.log('Error:', result.value.message);
}

Option/Maybe Type

Option represents presence (Some) or absence (None) of a value.

type Option<A> = 
    | { type: 'some', value: A }
    | { type: 'none' };

// Constructors
const some = <A>(value: A): Option<A> => ({
    type: 'some',
    value
});

const none = <A>(): Option<A> => ({
    type: 'none'
});

// Type guards
function isSome<A>(option: Option<A>): option is { type: 'some', value: A } {
    return option.type === 'some';
}

function isNone<A>(option: Option<A>): option is { type: 'none' } {
    return option.type === 'none';
}

// Usage
interface User {
    id: string;
    username: string;
    email: string;
}

function findUserById(users: User[], id: string): Option<User> {
    const user = users.find(u => u.id === id);
    return user ? some(user) : none();
}

// Check result
const users: User[] = [
    { id: '1', username: 'alice', email: '[email protected]' }
];

const result = findUserById(users, '1');

if (isSome(result)) {
    console.log('Found user:', result.value.username);
} else {
    console.log('User not found');
}

Mapping Over Either

// Map over Either - transforms success value
function map<E, A, B>(
    either: Either<E, A>,
    fn: (a: A) => B
): Either<E, B> {
    if (isRight(either)) {
        return right(fn(either.value));
    }
    return either;
}

// Usage
const result = validateUsername('alice');

const uppercased = map(result, username => username.toUpperCase());

if (isRight(uppercased)) {
    console.log(uppercased.value);  // "ALICE"
}

// Chain transformations
const processed = map(
    map(result, username => username.trim()),
    username => username.toUpperCase()
);

FlatMap/Chain for Either

// FlatMap - for functions that return Either
function flatMap<E, A, B>(
    either: Either<E, A>,
    fn: (a: A) => Either<E, B>
): Either<E, B> {
    if (isRight(either)) {
        return fn(either.value);
    }
    return either;
}

// Usage - chain validations
function validateEmail(email: string): Either<ValidationError, string> {
    if (!email.includes('@')) {
        return left({ field: 'email', message: 'Invalid format' });
    }
    return right(email);
}

function validateUser(username: string, email: string): Either<ValidationError, User> {
    return flatMap(
        validateUsername(username),
        validUsername => flatMap(
            validateEmail(email),
            validEmail => right({
                id: crypto.randomUUID(),
                username: validUsername,
                email: validEmail
            })
        )
    );
}

const userResult = validateUser('alice', '[email protected]');

if (isRight(userResult)) {
    console.log('Valid user:', userResult.value);
} else {
    console.log('Validation error:', userResult.value);
}

Real Example: User Registration

interface User {
    id: string;
    username: string;
    email: string;
    passwordHash: string;
}

interface ValidationError {
    field: string;
    message: string;
}

interface DatabaseError {
    code: string;
    message: string;
}

type RegistrationError = ValidationError | DatabaseError;

// Validation functions
function validateUsername(username: string): Either<ValidationError, string> {
    if (username.length < 3) {
        return left({ field: 'username', message: 'Too short (min 3)' });
    }
    
    if (username.length > 20) {
        return left({ field: 'username', message: 'Too long (max 20)' });
    }
    
    if (!/^[a-zA-Z0-9_]+$/.test(username)) {
        return left({ field: 'username', message: 'Invalid characters' });
    }
    
    return right(username);
}

function validateEmail(email: string): Either<ValidationError, string> {
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
        return left({ field: 'email', message: 'Invalid email format' });
    }
    return right(email);
}

function validatePassword(password: string): Either<ValidationError, string> {
    if (password.length < 8) {
        return left({ field: 'password', message: 'Too short (min 8)' });
    }
    
    if (!/[A-Z]/.test(password)) {
        return left({ field: 'password', message: 'Must contain uppercase' });
    }
    
    if (!/[0-9]/.test(password)) {
        return left({ field: 'password', message: 'Must contain number' });
    }
    
    return right(password);
}

// Hash password (simulated)
function hashPassword(password: string): string {
    return `hashed_${password}`;
}

// Check if user exists (simulated)
function userExists(username: string): Promise<boolean> {
    return Promise.resolve(false);
}

// Save user (simulated)
function saveUser(user: User): Promise<Either<DatabaseError, User>> {
    return Promise.resolve(right(user));
}

// Compose registration
async function registerUser(
    username: string,
    email: string,
    password: string
): Promise<Either<RegistrationError, User>> {
    // Validate username
    const usernameResult = validateUsername(username);
    if (isLeft(usernameResult)) {
        return usernameResult;
    }
    
    // Validate email
    const emailResult = validateEmail(email);
    if (isLeft(emailResult)) {
        return emailResult;
    }
    
    // Validate password
    const passwordResult = validatePassword(password);
    if (isLeft(passwordResult)) {
        return passwordResult;
    }
    
    // Check if user exists
    const exists = await userExists(usernameResult.value);
    if (exists) {
        return left({ field: 'username', message: 'Already taken' });
    }
    
    // Create user
    const user: User = {
        id: crypto.randomUUID(),
        username: usernameResult.value,
        email: emailResult.value,
        passwordHash: hashPassword(passwordResult.value)
    };
    
    // Save user
    return await saveUser(user);
}

// Usage
(async () => {
    const result = await registerUser('alice', '[email protected]', 'Secret123');
    
    if (isRight(result)) {
        console.log('User registered:', result.value.username);
    } else {
        console.log('Registration failed:', result.value);
    }
})();

Railway-Oriented Programming

Think of function composition as railway tracks. Success path on one track, failure path on another.

// Helper to build railway
function pipe<E, A, B, C>(
    f: (a: A) => Either<E, B>,
    g: (b: B) => Either<E, C>
): (a: A) => Either<E, C> {
    return (a: A) => flatMap(f(a), g);
}

// More composable registration
type ValidatedData = {
    username: string;
    email: string;
    password: string;
};

function validateAllFields(
    username: string,
    email: string,
    password: string
): Either<ValidationError, ValidatedData> {
    const usernameResult = validateUsername(username);
    if (isLeft(usernameResult)) return usernameResult;
    
    const emailResult = validateEmail(email);
    if (isLeft(emailResult)) return emailResult;
    
    const passwordResult = validatePassword(password);
    if (isLeft(passwordResult)) return passwordResult;
    
    return right({
        username: usernameResult.value,
        email: emailResult.value,
        password: passwordResult.value
    });
}

async function checkUserAvailability(
    data: ValidatedData
): Promise<Either<ValidationError, ValidatedData>> {
    const exists = await userExists(data.username);
    if (exists) {
        return left({ field: 'username', message: 'Already taken' });
    }
    return right(data);
}

function createUserFromData(data: ValidatedData): User {
    return {
        id: crypto.randomUUID(),
        username: data.username,
        email: data.email,
        passwordHash: hashPassword(data.password)
    };
}

// Compose the railway
async function registerUserRailway(
    username: string,
    email: string,
    password: string
): Promise<Either<RegistrationError, User>> {
    // Validate all fields
    const validationResult = validateAllFields(username, email, password);
    if (isLeft(validationResult)) {
        return validationResult;
    }
    
    // Check availability
    const availabilityResult = await checkUserAvailability(validationResult.value);
    if (isLeft(availabilityResult)) {
        return availabilityResult;
    }
    
    // Create and save user
    const user = createUserFromData(availabilityResult.value);
    return await saveUser(user);
}

Real Example: API Request Processing

interface ApiRequest {
    headers: Record<string, string>;
    body: any;
}

interface ApiResponse<T> {
    status: number;
    data: T;
}

type ApiError =
    | { type: 'auth', message: string }
    | { type: 'validation', field: string, message: string }
    | { type: 'notfound', message: string }
    | { type: 'server', message: string };

// Request processing pipeline
function validateAuth(req: ApiRequest): Either<ApiError, ApiRequest> {
    const token = req.headers['authorization'];
    
    if (!token) {
        return left({ type: 'auth', message: 'Missing authorization header' });
    }
    
    if (!token.startsWith('Bearer ')) {
        return left({ type: 'auth', message: 'Invalid authorization format' });
    }
    
    return right(req);
}

function parseBody<T>(req: ApiRequest): Either<ApiError, T> {
    try {
        const data = typeof req.body === 'string' 
            ? JSON.parse(req.body) 
            : req.body;
        return right(data as T);
    } catch {
        return left({ 
            type: 'validation', 
            field: 'body', 
            message: 'Invalid JSON' 
        });
    }
}

function validateRequestBody(body: any): Either<ApiError, { username: string, email: string }> {
    if (!body.username) {
        return left({ 
            type: 'validation', 
            field: 'username', 
            message: 'Missing username' 
        });
    }
    
    if (!body.email) {
        return left({ 
            type: 'validation', 
            field: 'email', 
            message: 'Missing email' 
        });
    }
    
    return right({
        username: body.username,
        email: body.email
    });
}

// Compose request processing
function processCreateUserRequest(
    req: ApiRequest
): Either<ApiError, { username: string, email: string }> {
    return flatMap(
        validateAuth(req),
        () => flatMap(
            parseBody(req),
            validateRequestBody
        )
    );
}

// Usage
const request: ApiRequest = {
    headers: {
        'authorization': 'Bearer token123',
        'content-type': 'application/json'
    },
    body: { username: 'alice', email: '[email protected]' }
};

const result = processCreateUserRequest(request);

if (isRight(result)) {
    console.log('Valid request:', result.value);
} else {
    console.log('Invalid request:', result.value);
}

Option Helpers

// Get value or default
function getOrElse<A>(option: Option<A>, defaultValue: A): A {
    return isSome(option) ? option.value : defaultValue;
}

// Map over Option
function mapOption<A, B>(option: Option<A>, fn: (a: A) => B): Option<B> {
    return isSome(option) ? some(fn(option.value)) : none();
}

// FlatMap for Option
function flatMapOption<A, B>(
    option: Option<A>,
    fn: (a: A) => Option<B>
): Option<B> {
    return isSome(option) ? fn(option.value) : none();
}

// Convert null/undefined to Option
function fromNullable<A>(value: A | null | undefined): Option<A> {
    return value != null ? some(value) : none();
}

// Usage
interface Config {
    apiUrl?: string;
    timeout?: number;
}

const config: Config = {
    apiUrl: 'https://api.example.com'
};

const apiUrl = getOrElse(fromNullable(config.apiUrl), 'https://default.com');
const timeout = getOrElse(fromNullable(config.timeout), 5000);

console.log(apiUrl);   // 'https://api.example.com'
console.log(timeout);  // 5000

Real Example: Database Query

interface QueryResult<T> {
    rows: T[];
}

async function queryDatabase<T>(sql: string): Promise<QueryResult<T>> {
    // Simulated database query
    console.log('Executing:', sql);
    return { rows: [] };
}

async function findUserByEmail(email: string): Promise<Option<User>> {
    const result = await queryDatabase<User>(
        `SELECT * FROM users WHERE email = '${email}'`
    );
    
    return result.rows.length > 0 
        ? some(result.rows[0]) 
        : none();
}

async function getUserProfile(email: string): Promise<Either<string, User>> {
    const userOption = await findUserByEmail(email);
    
    if (isNone(userOption)) {
        return left('User not found');
    }
    
    return right(userOption.value);
}

// Usage
(async () => {
    const profile = await getUserProfile('[email protected]');
    
    if (isRight(profile)) {
        console.log('User:', profile.value.username);
    } else {
        console.log('Error:', profile.value);
    }
})();

Combining Multiple Results

// Collect all errors or return success
function sequence<E, A>(eithers: Either<E, A>[]): Either<E[], A[]> {
    const errors: E[] = [];
    const values: A[] = [];
    
    for (const either of eithers) {
        if (isLeft(either)) {
            errors.push(either.value);
        } else {
            values.push(either.value);
        }
    }
    
    return errors.length > 0 ? left(errors) : right(values);
}

// Validate multiple fields
function validateUserData(data: {
    username: string;
    email: string;
    password: string;
}): Either<ValidationError[], ValidatedData> {
    const results = [
        validateUsername(data.username),
        validateEmail(data.email),
        validatePassword(data.password)
    ];
    
    return flatMap(
        sequence(results),
        ([username, email, password]) => right({
            username,
            email,
            password
        })
    );
}

// Usage - get all errors at once
const result = validateUserData({
    username: 'a',        // Too short
    email: 'invalid',     // Bad format
    password: 'weak'      // Too short
});

if (isLeft(result)) {
    console.log('All errors:', result.value);
    // [
    //   { field: 'username', message: 'Too short (min 3)' },
    //   { field: 'email', message: 'Invalid email format' },
    //   { field: 'password', message: 'Too short (min 8)' }
    // ]
}

Best Practices

1. Make Errors Explicit in Types

// Good - error in return type
function parseJson<T>(json: string): Either<Error, T> {
    try {
        return right(JSON.parse(json) as T);
    } catch (e) {
        return left(e as Error);
    }
}

// Bad - throws exception
function parseJsonBad<T>(json: string): T {
    return JSON.parse(json);  // Might throw!
}

2. Use Option for Nullable Values

// Good - explicit optionality
function findUser(id: string): Option<User> {
    // ...
    return none();
}

// Bad - null/undefined
function findUserBad(id: string): User | null {
    return null;  // Caller might forget to check
}

3. Compose Error Handling

// Good - composable
const pipeline = pipe(
    validateAuth,
    parseRequestBody,
    processRequest
);

// Bad - nested try/catch
function processBad(req: Request) {
    try {
        const auth = validateAuth(req);
        try {
            const body = parseBody(req);
            try {
                return processRequest(body);
            } catch (e) {
                // ...
            }
        } catch (e) {
            // ...
        }
    } catch (e) {
        // ...
    }
}

What's Next

You now understand:

• Either/Result types for explicit errors

• Option/Maybe for nullable values

• Railway-oriented programming

• Composing error handling

• Type-safe error flows

In Part 5: Advanced Functional Patterns, you'll learn about functors and monads, algebraic data types, functional reactive programming, and advanced patterns for production systems.

---

Based on building production TypeScript APIs with type-safe error handling, from user registration to complex request processing pipelines.