74 lines
2 KiB
Markdown
74 lines
2 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
|
|
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(() => ({}))`.
|
|
|
|
## Compatibilidade
|
|
|
|
- Node: `>=20`
|
|
- Exporta ESM e CJS via `package.json#exports`
|