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.

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

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.

Next Steps