_respostas/README.md

p-respostas

Contrato simples e tipado de respostas para APIs e serviços (sucesso/erro), com suporte a:

• ESM (import) via dist-front/index.mjs
• CommonJS (require) via dist-back/index.js
• TypeScript com tipos publicados em dist-front/index.d.mts

Importante: os diretórios dist-* são gerados automaticamente no build. Este repositório deve manter compatibilidade e não alterar funcionalidades.

Instalação

pnpm add p-respostas
# ou
npm i p-respostas

Uso rápido

import { respostaComuns, gerarRespostas, codigosResposta, type tipoResposta } from "p-respostas"

const r1 = respostaComuns.valor({ ok: true })
// r1.cod === 200

const r2 = respostaComuns.erro("Falha ao processar")
// r2.eErro === true

// Exemplo com logger/observabilidade
const respostas = gerarRespostas(({ erro, mensagem, local }) => {
  console.error("erroInterno:", { erro, mensagem, local })
  // pode sobrescrever parcialmente a resposta final
  return { detalhes: ["contate o suporte" as const] }
})

const r3: tipoResposta<string> = respostas.valor("ok")
const r4: tipoResposta<string> = respostas.erroInterno({ erro: new Error("boom"), local: "serviceX" })

API

codigosResposta

Enum com os códigos HTTP usados pelo contrato:

• sucesso = 200
• erroConhecido = 400
• erroPermissao = 401
• erroNaoEncontrado = 404
• erroDesconhecido = 500
• tempoEsgotado = 504

Tipos

• tipoRespostaSucesso<T>
• tipoRespostaErro
• tipoResposta<T> = tipoRespostaSucesso<T> | tipoRespostaErro
• tipoPrErroInterno

gerarRespostas(registrarErroInterno)

Cria um conjunto de funções padronizadas para gerar respostas.

registrarErroInterno(op) recebe { erro, mensagem?, local, __filename? } e pode retornar um Partial<tipoRespostaErro> para complementar a resposta final.

respostaComuns

Instância default de gerarRespostas(() => ({})).

Compatibilidade

• Node: >=20
• Exporta ESM e CJS via package.json#exports