Biblioteca neverthrow para TypeScript: Result type para tratamento de erros

1. O que é e por que usar

No desenvolvimento moderno com TypeScript, o tratamento de erros muitas vezes se transforma em uma bagunça de blocos try/catch espalhados por todo o código. A biblioteca neverthrow oferece uma solução elegante para esse problema, inspirada em linguagens de programação funcionais como Rust e Haskell. Ela fornece o tipo Result<T, E>, que representa explicitamente um resultado de sucesso (Ok) ou erro (Err), tornando o tratamento de erros parte do sistema de tipos, e não um efeito colateral.

O principal objetivo do neverthrow é substituir exceções implícitas por tipos explícitos. Em vez de escrever uma função que pode lançar uma exceção a qualquer momento, você retorna um Result que o compilador TypeScript o forçará a tratar. Isso torna o código mais previsível, seguro e autodocumentado. Você não precisa mais adivinhar quais funções podem lançar um erro — o tipo de retorno já informa isso diretamente.

A biblioteca é especialmente útil em projetos onde a confiabilidade é crucial: serviços backend, aplicações financeiras, sistemas de processamento de dados. Ela também se integra perfeitamente com outros conceitos funcionais, como tipos Option (Maybe), e pode ser combinada com bibliotecas como fp-ts. neverthrow não é apenas uma utilidade, é uma filosofia de escrita de código onde erros são dados, e não situações excepcionais.

2. Instalação

Instalação do neverthrow em um projeto TypeScript/NPM:

npm install neverthrow

Para projetos que usam yarn:

yarn add neverthrow

Para pnpm:

pnpm add neverthrow

A biblioteca é escrita em TypeScript e inclui tipos completos, portanto não é necessária a instalação adicional de @types. Após a instalação, você pode importar os tipos e funções principais:

import { ok, err, Result } from 'neverthrow';

3. Início rápido — exemplo mínimo funcional

Vamos criar uma função simples que divide dois números, mas retorna um Result em vez de lançar uma exceção ao dividir por zero:

import { ok, err, Result } from 'neverthrow';

// Define o tipo de erro
type DivisionError = { message: string; code: number };

// Função que retorna um Result
function safeDivide(a: number, b: number): Result<number, DivisionError> {
  if (b === 0) {
    return err({ message: 'Divisão por zero', code: 1001 });
  }
  return ok(a / b);
}

// Uso
const result = safeDivide(10, 2);

// Tratamento do resultado
if (result.isOk()) {
  console.log('Resultado:', result.value); // Resultado: 5
} else {
  console.error('Erro:', result.error.message); // Nunca será executado
}

const errorResult = safeDivide(10, 0);

if (errorResult.isErr()) {
  console.error('Erro:', errorResult.error.message); // Erro: Divisão por zero
}

Este exemplo demonstra a ideia principal: a função sempre retorna um Result, e o código chamador deve verificar se o resultado é bem-sucedido antes de usar o valor. O compilador TypeScript não permitirá que você acesse result.value sem essa verificação.

4. Métodos/funções/classes principais

4.1. ok(value) — Criando um resultado de sucesso

Assinatura:

function ok<T, E = never>(value: T): Ok<T, E>

O que faz: Cria uma instância de Ok representando um resultado bem-sucedido com o valor fornecido.

Exemplo:

import { ok } from 'neverthrow';

const success = ok(42);
console.log(success.isOk()); // true
console.log(success.value); // 42

4.2. err(e