80 lines
2.1 KiB
Markdown
80 lines
2.1 KiB
Markdown
# AI / LLM usage notes (p-respostas)
|
|
|
|
Este pacote fornece um **contrato estável** de respostas para operações (principalmente APIs), representando:
|
|
|
|
- sucesso (`cod: 200`, `eCerto: true`, `eErro: false`, `mensagem: undefined`, `valor: T`)
|
|
- erro conhecido/permissão/não encontrado/timeout/erro interno (`cod` diferente de 200, `eErro: true`, `eCerto: false`, `valor: undefined`, `mensagem: string`)
|
|
|
|
## Imports
|
|
|
|
### TypeScript / ESM
|
|
|
|
```ts
|
|
import {
|
|
codigosResposta,
|
|
gerarRespostas,
|
|
respostaComuns,
|
|
type tipoResposta,
|
|
type tipoRespostaErro,
|
|
type tipoRespostaSucesso,
|
|
type tipoPrErroInterno,
|
|
} from "p-respostas"
|
|
```
|
|
|
|
### CommonJS
|
|
|
|
```js
|
|
const { respostaComuns, gerarRespostas, codigosResposta } = require("p-respostas")
|
|
```
|
|
|
|
## Como interpretar uma `tipoResposta<T>`
|
|
|
|
Regras úteis para checagem:
|
|
|
|
- Se `res.eCerto === true` então:
|
|
- `res.cod === codigosResposta.sucesso`
|
|
- `res.valor` existe (tipo `T`)
|
|
- `res.mensagem` é `undefined`
|
|
|
|
- Se `res.eErro === true` então:
|
|
- `res.valor` é sempre `undefined`
|
|
- `res.mensagem` é sempre `string`
|
|
- `res.cod` é um dos códigos de erro
|
|
|
|
Exemplo:
|
|
|
|
```ts
|
|
function handle<T>(res: tipoResposta<T>) {
|
|
if (res.eErro) {
|
|
// aqui o TS entende tipoRespostaErro
|
|
return { ok: false as const, status: res.cod, message: res.mensagem }
|
|
}
|
|
|
|
// aqui o TS entende tipoRespostaSucesso<T>
|
|
return { ok: true as const, value: res.valor }
|
|
}
|
|
```
|
|
|
|
## Como gerar respostas com log de erro interno
|
|
|
|
```ts
|
|
const respostas = gerarRespostas((op) => {
|
|
// op.erro: qualquer coisa lançada
|
|
// op.local: string (obrigatória)
|
|
// op.mensagem: string opcional
|
|
// op.__filename: opcional
|
|
console.error("Erro interno", op)
|
|
|
|
// Pode retornar complementos não-destrutivos
|
|
return { detalhes: ["id de rastreio: ..."] }
|
|
})
|
|
|
|
const r = respostas.erroInterno({ erro: new Error("boom"), local: "user.service" })
|
|
```
|
|
|
|
## Garantias / restrições
|
|
|
|
- Este pacote é amplamente importado por outros projetos.
|
|
- Os arquivos em `dist-*` são gerados automaticamente.
|
|
- Mudanças aqui devem focar em **melhorar o consumo (exports/tipos/docs)** sem alterar comportamento.
|
|
|