error-handling

Error handling

Assist with error handling design based on recoverability.

Basic Policy

Adopt Either/Result types in domain logic (business rules).

• Errors in the domain layer should be judged by the caller → make them explicit in the type
• Exceptions are not for control flow, but limited to truly exceptional situations
• A design where the possibility of an error can be known just by looking at the return type

Decision Flow

エラー発生
    ↓
回復可能か？
    ├─ YES → Either/Result型で表現
    └─ NO → 例外/panicで即座に停止

Recoverable	Unrecoverable
Business rule violation	Invalid argument (IllegalArgumentException)
External system error	State inconsistency (IllegalStateException)
Insufficient permissions / resource conflict	Unreachable code (unreachable)

Recoverable Errors

Express them with Either/Result types and leave the decision to the caller.

// TypeScript - neverthrow
function findUser(id: string): Result<User, UserError> {
  if (!isValidId(id)) return err({ type: 'VALIDATION_FAILED', field: 'id' });
  return repository.find(id)
    ? ok(user)
    : err({ type: 'NOT_FOUND', userId: id });
}

Unrecoverable Errors

Violations of a program's preconditions halt immediately.

// 引数の不正 → IllegalArgumentException 相当
if (order === null) throw new Error('order must not be null');

// 状態の矛盾 → IllegalStateException 相当
if (order.status === 'COMPLETED' && order.items.isEmpty())
  throw new Error('completed order must have items');

// 到達不可コード → unreachable
default: throw new Error(`unreachable: ${status}`);

Recommended Libraries

Language	Library	Selection Criteria
TypeScript	neverthrow	When Result alone is sufficient (lightweight and simple)
TypeScript	fp-ts	When using functional programming in general (Option, Task, IO, Reader, etc.)
JavaScript	neverthrow	Same as TypeScript
Rust	Standard Result<T, E>	Always use this. For error definitions, thiserror
Go	Standard (T, error)	When writing simple Go-like code
Go	samber/mo	When you want to chain processing with Result/Either
Scala	Standard Either[L, R]	The standard is sufficient. cats is for large-scale FP
Java	vavr.io Either	If you also use functional collections, vavr is the only choice
Python	returns (dry-python)	For production environments. Rich type annotations
Python	result	Lightweight. A simple Rust-like API

Detailed Guidelines

For implementation patterns in all languages and details of error type design, see references/guidelines.md .

Related Skills (Recommended for Concurrent Reading)

When using this skill, also refer to the following skills:

• error-classification: Selection of handling methods based on error classification (Error, Defect, Fault, Failure)
• domain-building-blocks: Application of Result/Either in domain operations
• repository-design: Repository error handling patterns (synchronous and asynchronous)