error-handling

Return errors as values with discriminated unions in TypeScript/Node.js applications.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/perimetre/ai-toolkit --skill error-handling-perimetre
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: error-handling
Source: https://github.com/perimetre/ai-toolkit/tree/main/plugins/perimetre-apps/skills/error-handling
Command: npx skills add https://github.com/perimetre/ai-toolkit --skill error-handling-perimetre

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

TypeScript projects often rely on exceptions, which can obscure error handling paths. This Skill demonstrates returning errors as values and using discriminated unions to clearly separate success from failure, enabling stronger type-safety and predictable behavior across layers.

Core Features & Use Cases

  • Custom error classes with contextual data and status codes.
  • Discriminated unions using an ok: true discriminator for success.
  • Application across service layers, data access, and API boundaries with robust recovery patterns.

Quick Start

Create a simple module that returns { ok: true, data } on success or an Error instance on failure and demonstrate usage with a sample getUser function.

Frequently Asked Questions about error-handling

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I handle errors as values instead of throwing exceptions in TypeScript?

To handle errors as values in TypeScript, return an Error instance on failure or an { ok: true, data } object on success. This pattern uses discriminated unions to separate success from failure, ensuring predictable behavior across application layers.

What is the best way to propagate type-safe errors across a Node.js service layer?

The best way to propagate type-safe errors across a Node.js service layer is using custom error classes with explicit context and status codes. Returning these instances as values ensures consistent error propagation and enables robust recovery patterns at API boundaries.

Why does TypeScript error handling with exceptions obscure logic paths?

TypeScript error handling with exceptions obscures logic paths because thrown errors bypass the normal control flow, making it difficult to track error propagation. Returning errors as values with an ok: true discriminator clearly separates success from failure for stronger type-safety.

Can I use discriminated unions for error handling in my data access layer?

Yes, you can use discriminated unions for error handling in your data access layer. By returning objects with an ok: true discriminator for success and custom error instances for failures, you achieve type narrowing and predictable behavior across data access boundaries.

Do I need custom error classes to return errors as values in TypeScript?

Yes, you need custom error classes to return errors as values in TypeScript. Defining these classes with explicit contextual data and status codes allows you to apply robust recovery patterns and ensures consistent, type-safe error propagation across layers.

When should I not use throw for error handling in Node.js applications?

You should not use throw for error handling in Node.js applications when you need predictable behavior across service and API boundaries. Returning errors as values using discriminated unions prevents obscured error paths and ensures stronger type-safety.