alexandru/arrow-typed-errors

Arrow Typed Errors

Quick start

• Distinguish expected domain failures from exceptional faults before selecting an API.
• For new code, prefer context-parameter computations (context(_: Raise<E>)) and run them into a wrapper at a boundary with either { ... }, nullable { ... }, option { ... }, or ior(...) { ... }.
• Use Either operators for routine propagation and transformation; do not pattern match only to reconstruct Left or Right.
• Use when when the domain genuinely branches by case or when matching a multi-state wrapper directly communicates intent.

Workflow

1. Model domain failures as focused sealed types.
2. Choose fail-fast composition or independent validation accumulation.
3. Implement internal logic in a Raise<E> context and expose an appropriate wrapper at the public boundary.
4. Bind nested typed computations and translate their errors at the layer boundary.
5. Convert only expected, recoverable exceptions into typed failures.
6. Inspect the result with a combinator or intentional case analysis at the consumer boundary.
7. Type-check examples when introducing a less familiar Arrow API or upgrading Arrow/Kotlin.
8. When changing examples, update and run the bundled scripts/verify-examples.kt check.

References

• Load references/typed-errors.md for context-parameter API examples, imports, validation, wrapper usage, and the checked sample location.
• Load references/best-practices.md when designing or reviewing code, especially to simplify verbose Either handling without turning when into a blanket prohibition.