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

import {
  codigosResposta,
  gerarRespostas,
  respostaComuns,
  type tipoResposta,
  type tipoRespostaErro,
  type tipoRespostaSucesso,
  type tipoPrErroInterno,
} from "p-respostas"

CommonJS

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:

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

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:

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.

3.5 KiB Raw Permalink Blame History