# ADR 001: Use Result Type for Error Handling

## Status

Accepted. The repo is now **Rust-first**; error handling in Rust uses `Result` natively. This ADR still applies to any TypeScript (e.g. VS Code extension) code.

## Context

Traditional exception-based error handling in TypeScript/JavaScript has several issues:
- Exceptions are not part of the type system
- Control flow is implicit (hard to track)
- Error handling can be forgotten
- Stack traces can be expensive
- Async error handling is complex

We needed a more explicit, type-safe way to handle errors that:
- Makes errors explicit in the type system
- Encourages proper error handling
- Is composable and functional
- Works well with async code

## Decision

We will use a `Result<T, E>` type (similar to Rust's Result or Haskell's Either) for error handling in TypeScript code.

The Result type is defined as:
```typescript
type Result<T, E = Error> =
  | { readonly ok: true; readonly value: T }
  | { readonly ok: false; readonly error: E };
```

All validation functions and operations that can fail will return `Result<T, ValidationError>` instead of throwing exceptions.

## Consequences

### Positive

- **Type Safety**: Errors are explicit in function signatures
- **Composability**: Functions like `map`, `andThen`, `unwrapOr` enable functional composition
- **No Silent Failures**: Errors must be explicitly handled
- **Better Testing**: Error cases are easier to test
- **Performance**: No exception overhead for expected error cases

### Negative

- **Learning Curve**: Team members need to learn the Result pattern
- **More Verbose**: Error handling requires explicit checks
- **Migration Effort**: Existing code needs to be migrated

### Neutral

- **Library Compatibility**: Some libraries still throw exceptions (we wrap them with `tryCatch`)

## Alternatives Considered

1. **Traditional Exceptions**: Rejected - not type-safe, easy to forget error handling
2. **Option/Maybe Type**: Rejected - doesn't carry error information
3. **Go-style Error Returns**: Rejected - TypeScript doesn't support multiple return values elegantly

## References

- Rust Result type: https://doc.rust-lang.org/std/result/
- In this repo: Rust crates use `Result`; extension/TypeScript should follow the same principle where applicable.

