124 lines
3.5 KiB
Markdown
124 lines
3.5 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 (narrowing recomendado)
|
|
|
|
Para o TypeScript, o narrowing mais robusto costuma ser usando `cod`:
|
|
|
|
```ts
|
|
import { codigosResposta, type tipoResposta } from "p-respostas"
|
|
|
|
function handle<T>(res: tipoResposta<T>) {
|
|
if (res.cod !== codigosResposta.sucesso) {
|
|
// aqui o TS entende tipoRespostaErro (na maioria dos setups)
|
|
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 }
|
|
}
|
|
```
|
|
|
|
> Nota: em alguns setups, checar somente `res.eErro` pode não eliminar completamente `undefined` em `res.valor`.
|
|
> Se isso acontecer, prefira checar `cod` como no exemplo acima.
|
|
|
|
## 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" })
|
|
```
|
|
|
|
## Validação com Zod (`zRespostas`)
|
|
|
|
Para validar payloads de resposta recebidos de APIs ou serviços com [Zod](https://zod.dev):
|
|
|
|
```ts
|
|
import z from "zod"
|
|
import { zRespostas, type tipoZResposta } from "p-respostas"
|
|
|
|
// 1. Validando payload com tipo específico de sucesso
|
|
const schemaUsuario = zRespostas(
|
|
z.object({
|
|
id: z.string(),
|
|
nome: z.string(),
|
|
})
|
|
)
|
|
|
|
const resposta = schemaUsuario.parse(jsonRecebidoDaApi)
|
|
|
|
if (resposta.eCerto) {
|
|
// TypeScript sabe que resposta.valor tem { id: string; nome: string }
|
|
console.log("Dados do usuário:", resposta.valor.nome)
|
|
} else {
|
|
// TypeScript sabe que resposta.mensagem é string e cod é um dos códigos de erro
|
|
console.error("Falha:", resposta.mensagem, "Código:", resposta.cod)
|
|
}
|
|
|
|
// 2. Aceitando qualquer valor no sucesso (default z.any())
|
|
const schemaGenerico = zRespostas()
|
|
|
|
// 3. Schemas e tipos auxiliares exportados:
|
|
// - zResposta (alias idêntico a zRespostas)
|
|
// - zRespostaSucesso(zValor?)
|
|
// - zRespostaErro
|
|
// - zCodigosRespostaErro
|
|
// - tipoZResposta<T>
|
|
```
|
|
|
|
## 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.
|
|
|