tryError Documentation

Getting Started

Introduction

Introduction to tryError

Lightweight, progressive, type-safe error handling for TypeScript that bridges the gap between traditional try/catch and heavy functional programming approaches.

Alpha Version: This library is currently in alpha and not ready for production use. APIs may change significantly before the stable release.

What is tryError?

tryError provides errors as values with zero-overhead success paths,progressive adoption, and a developer-first experience. It allows you to handle errors explicitly without the complexity of monads or the verbosity of traditional try/catch blocks.

Minimal Overhead

Success path: <3% overhead. Error path: configurable from 20% to 120% depending on configuration.

Progressive

Start simple, add complexity as needed. No need to rewrite existing code.

Type Safe

Full TypeScript support with discriminated unions and type inference.

The Problem

Current TypeScript error handling solutions have significant gaps:

❌

Traditional try/catch: Verbose, error-prone, poor composability, and makes it easy to forget error handling.

❌

Heavy FP libraries: Foreign feel for JavaScript developers, runtime overhead, steep learning curve.

❌

Existing Result libraries: Missing async support, poor developer experience, limited real-world patterns.

The Solution

tryError provides a middle ground that feels natural to JavaScript/TypeScript developers while providing the benefits of explicit error handling.

Before: Traditional try/catch

Traditional Error Handlingtypescript

try {
  const response = await fetch("/api/user");
  const user = await response.json();
  return user;
} catch (error) {
  console.error("Something failed:", error);
  return null;
}

Issues: Easy to forget, unclear error types, poor composability

After: tryError

tryError Approachtypescript

const result = await tryAsync(async () => {
  const response = await fetch("/api/user");
  return response.json();
});

if (isTryError(result)) {
  console.error("API failed:", result.message);
  return null;
}

return result; // Type-safe success value

Benefits: Explicit, type-safe, composable, rich error context

Performance Characteristics

Real-World Performance Impact

Success Path (Common Case)

<3% overhead

vs raw try/catch

• Direct value return, no wrapper objects
• No performance penalty for successful operations
• Ideal for hot paths and performance-critical code

Error Path (Exceptional Case)

20%-120% overhead

configurable

• Stack trace capture: ~65% of total overhead
• Context cloning: ~25% of total overhead
• Source location: ~10% of total overhead

Why the Error Overhead?

Error overhead is high because tryError captures rich debugging information:

• Stack traces: Essential for debugging but expensive to capture
• Source location: Shows exactly where errors occurred
• Context objects: Preserves state at error time
• Timestamps: Tracks when errors happened

This is usually fine because errors should be exceptional! If you have high error rates, use ConfigPresets.minimal() for <20% overhead.

Key Benefits

Errors as Values: No hidden control flow, explicit error handling

Minimal Overhead: Success path <3%, error path configurable (20%-120%)

Rich Error Context: Source location, timestamps, custom context

Composable: Chain operations, combine results, transform errors

TypeScript Native: Full type inference and safety

Progressive: Adopt incrementally, no big rewrites

Advanced Features

tryError goes beyond basic error handling with powerful performance optimizations and extensibility features.

🚀 Performance Optimizations

Object pooling, lazy evaluation, and configurable performance profiles for high-throughput applications.

🔌 Plugin System

Extend tryError with custom error types, middleware, and integrations without modifying core.

🎯 Middleware Pipeline

Intercept and transform errors with composable middleware for logging, retry, and monitoring.

Learn about Performance →Explore Middleware →Discover Plugins →

Next Steps

Installation

Get tryError installed in your project

Quick Start

5-minute tutorial with examples