error-handling

Use the neverthrow library to return Result<T, E> from functions, wrapping success values in ok() and failures in err(). Define error cases as a union type so callers can exhaustively handle each failure mode.

Use Result types for recoverable errors like validation failures, not-found resources, and external system errors where the caller decides how to respond. Throw exceptions only for unrecoverable conditions like null arguments, inconsistent state, or unreachable code.

Choose neverthrow when you only need Result types, as it is lightweight and simple. Choose fp-ts when you also need broader functional programming utilities like Option, Task, IO, and Reader.

Use the standard (T, error) return pattern for idiomatic Go code. If you want Result/Either chaining with Map and FlatMap operations, use the samber/mo library instead.

Define errors as an enum with the thiserror crate, deriving Error and using #[error] attributes for display messages. Return them with the standard Result<T, E> type from functions.

Use panic or exceptions only for unrecoverable programmer errors: invalid arguments, contradictory object state, and logically unreachable branches. These indicate bugs that should stop execution immediately rather than be handled by callers.