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

bun add p-respostas
# ou
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(() => ({})).

Validação Zod (zRespostas)

Permite validar e inferir tipos de payloads recebidos via HTTP/APIs:

import z from "zod"
import { zRespostas } from "p-respostas"

const schema = zRespostas(z.string())
const resultado = schema.parse(payload)

if (resultado.eCerto) {
  console.log("Sucesso:", resultado.valor)
} else {
  console.log("Erro:", resultado.mensagem, resultado.cod)
}

Também exporta zResposta, zRespostaSucesso, zRespostaErro, zCodigosRespostaErro e type tipoZResposta<T>.

Compatibilidade

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