tryError Documentation
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.
The Problem
Current TypeScript error handling solutions have significant gaps:
The Solution
tryError provides a middle ground that feels natural to JavaScript/TypeScript developers while providing the benefits of explicit error handling.
try {
const response = await fetch("/api/user");
const user = await response.json();
return user;
} catch (error) {
console.error("Something failed:", error);
return null;
}
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
Performance Characteristics
Real-World Performance Impact
- • Direct value return, no wrapper objects
- • No performance penalty for successful operations
- • Ideal for hot paths and performance-critical code
- • Stack trace capture: ~65% of total overhead
- • Context cloning: ~25% of total overhead
- • Source location: ~10% of total 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
Advanced Features
tryError goes beyond basic error handling with powerful performance optimizations and extensibility features.