all_result 1.0.0

Typed success and failure for pure Dart, with predictable error contracts, sync/async composition, recovery, and zero runtime dependencies.

all_result

🇧🇷 Português | 🇺🇸 English

Result<F, S> em Dart puro para representar falha ou sucesso e compor operações sem esconder caminhos de erro. Assim, contratos de falha ficam visíveis no tipo sem impor framework ou I/O.

Por que usar

Métodos que retornam null escondem o motivo da falha. Exceções usadas em fluxos esperados espalham try/catch pela aplicação. Result<F, S> mantém os dois caminhos explícitos e permite compor validação, domínio, repositório e UI sem perder o tipo do erro.

• Contratos previsíveis entre pacotes e camadas.
• Menos condicionais aninhadas e tratamento duplicado.
• O mesmo modelo para operações síncronas e assíncronas.
• Erros de domínio separados de exceções inesperadas.
• Dart puro, sem dependências de runtime e sem vínculo com framework.
• Valores comparáveis, simples de testar e adequados para bibliotecas públicas.

Recursos

• Success e Failure com ordem genérica <F, S>.
• Criação com success, failure, cond, guard e tryAsync.
• Composição com map, mapFailure, flatMap, fold e recover.
• Extensões assíncronas para Future<Result<F, S>>.
• Helpers para efeitos, extração e nulabilidade.

Guia rápido da API

Necessidade	API
Criar sucesso ou falha	success, failure, cond, condLazy
Converter código que lança exceção	guard, guardTyped, tryAsync, tryAsyncTyped
Transformar um sucesso	map, mapAsync
Encadear outra operação que pode falhar	flatMap, flatMapAsync
Padronizar o erro entre camadas	mapFailure, mapFailureAsync
Produzir uma resposta final	fold, foldAsync
Aplicar fallback válido	recover, recoverAsync
Log, métrica ou auditoria	tap, tapFailure e variantes async
Extrair com fallback	getOrElse, getOrCall, toNullable

Instalação

dependencies:
  all_result: ^1.0.0

Exemplos de uso real

Regra de negócio sem exceções

import 'package:all_result/all_result.dart';

Result<String, int> parseQuantity(String raw) => Result.guard(
  () => int.parse(raw),
  onError: (_) => 'Quantidade inválida',
).flatMap(
  (quantity) => Result.cond(
    quantity > 0,
    quantity,
    'A quantidade deve ser positiva',
  ),
);

Result<String, int> checkStock(int quantity) =>
    Result.cond(quantity <= 10, quantity, 'Estoque insuficiente');

final total = parseQuantity('3')
    .flatMap(checkStock)
    .map((quantity) => quantity * 4990);

Se qualquer etapa falhar, as seguintes não executam e o primeiro Failure continua no fluxo.

Repositório ou API com erro tipado

Future<Result<RepositoryFailure, User>> findUser(String id) {
  return Result.tryAsync(
    () => api.fetchUser(id),
    onError: (error, stackTrace) => RepositoryFailure(
      message: 'Não foi possível carregar o usuário',
      cause: error,
      stackTrace: stackTrace,
    ),
  );
}

tryAsync entrega o erro e o StackTrace para que sua falha preserve contexto de diagnóstico. Use tryAsyncTyped quando somente uma exceção conhecida deve ser convertida e erros de programação precisam continuar propagando.

Fluxo assíncrono entre camadas

final result = await findUser(userId)
    .flatMapAsync(authorizeUser)
    .mapAsync(loadProfile)
    .mapFailureAsync(AppFailure.fromRepository)
    .tapFailureAsync(metrics.recordFailure);

O pipeline para na primeira falha. Não é necessário abrir um novo try/catch ou testar null em cada etapa.

Fallback para cache

final settings = await loadRemoteSettings()
    .recoverAsync((failure) => cache.readSettings());

Use recover apenas quando o fallback representar um sucesso válido. Se o erro precisar continuar visível, preserve o Failure.

Fechando o fluxo na UI ou API

final state = result.fold(
  (failure) => UserState.error(failure.message),
  (profile) => UserState.ready(profile),
);

Mantenha Result durante a composição e use fold na borda onde falha e sucesso viram um único tipo: estado de UI, resposta HTTP, mensagem de CLI ou código de saída.

Quando usar

Use Result para falhas esperadas que fazem parte do contrato: entrada inválida, regra de negócio, indisponibilidade externa, autorização ou item não encontrado. Continue usando exceções para violações de programação e estados que não podem ser recuperados. O pacote não substitui logging, telemetria ou uma hierarquia de erros da sua aplicação.

Ler o lado incorreto por successValue ou failureValue lança StateError. Prefira fold, checagem de estado ou getOrElse.

Documentação

Consulte a referência, o guia de composição, o guia de contribuição e a política de segurança. Licença MIT.