_respostas/AI.md

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:

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

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.