96 lines
2.5 KiB
Markdown
96 lines
2.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
bun add p-respostas
|
|
# ou
|
|
pnpm add p-respostas
|
|
# ou
|
|
npm i p-respostas
|
|
```
|
|
|
|
## Uso rápido
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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`
|