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" })

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.

2.5 KiB Raw Blame History