diff --git a/AI.md b/AI.md deleted file mode 100644 index c001c62..0000000 --- a/AI.md +++ /dev/null @@ -1,86 +0,0 @@ -# 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` - -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(res: tipoResposta) { - 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 - 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" }) -``` - -## 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. diff --git a/README.md b/README.md index 2120d75..6896378 100644 --- a/README.md +++ b/README.md @@ -1,74 +1 @@ -# p-respostas - -Contrato simples e tipado de respostas para APIs e serviços (sucesso/erro), com suporte a: - -- **ESM** (`import`) via `dist-front/index.mjs` -- **CommonJS** (`require`) via `dist-back/index.js` -- **TypeScript** com tipos publicados em `dist-front/index.d.mts` - -> Importante: os diretórios `dist-*` são gerados automaticamente no build. Este repositório deve manter **compatibilidade** e **não alterar funcionalidades**. - -## Instalação - -```bash -pnpm add p-respostas -# ou -npm i p-respostas -``` - -## Uso rápido - -```ts -import { respostaComuns, gerarRespostas, codigosResposta, type tipoResposta } from "p-respostas" - -const r1 = respostaComuns.valor({ ok: true }) -// r1.cod === 200 - -const r2 = respostaComuns.erro("Falha ao processar") -// r2.eErro === true - -// Exemplo com logger/observabilidade -const respostas = gerarRespostas(({ erro, mensagem, local }) => { - console.error("erroInterno:", { erro, mensagem, local }) - // pode sobrescrever parcialmente a resposta final - return { detalhes: ["contate o suporte" as const] } -}) - -const r3: tipoResposta = respostas.valor("ok") -const r4: tipoResposta = respostas.erroInterno({ erro: new Error("boom"), local: "serviceX" }) -``` - -## API - -### `codigosResposta` - -Enum com os códigos HTTP usados pelo contrato: - -- `sucesso = 200` -- `erroConhecido = 400` -- `erroPermissao = 401` -- `erroNaoEncontrado = 404` -- `erroDesconhecido = 500` -- `tempoEsgotado = 504` - -### Tipos - -- `tipoRespostaSucesso` -- `tipoRespostaErro` -- `tipoResposta = tipoRespostaSucesso | tipoRespostaErro` -- `tipoPrErroInterno` - -### `gerarRespostas(registrarErroInterno)` - -Cria um conjunto de funções padronizadas para gerar respostas. - -`registrarErroInterno(op)` recebe `{ erro, mensagem?, local, __filename? }` e pode retornar um `Partial` para complementar a resposta final. - -### `respostaComuns` - -Instância default de `gerarRespostas(() => ({}))`. - -## Compatibilidade - -- Node: `>=20` -- Exporta ESM e CJS via `package.json#exports` +# drivers diff --git a/dist-front/index.d.mts b/dist-front/index.d.mts index 8f6d345..6251cb1 100644 --- a/dist-front/index.d.mts +++ b/dist-front/index.d.mts @@ -1,8 +1,3 @@ -/** - * Códigos padrão usados pelo contrato de respostas. - * - * Observação: este enum é parte da API pública do pacote. - */ declare enum codigosResposta { sucesso = 200, erroConhecido = 400, @@ -34,11 +29,6 @@ type tipoPrErroInterno = { local: string; __filename?: string; }; -/** - * Cria um conjunto de geradores de respostas. - * - * @param registrarErroInterno callback para registrar/normalizar erros internos. - */ declare const gerarRespostas: ( /** Faz um processamento quando erro interno * Recebe o erro gerado, mensagem personalizada e detalhes @@ -78,7 +68,7 @@ registrarErroInterno: (op: tipoPrErroInterno) => Partial) => { erroEspera: (mensagem?: string | undefined | null, detalhes?: string[]) => tipoRespostaErro; }; /** - * Instância default (sem handler de erro interno). + * Uso de respostas em comuns */ declare const respostaComuns: { /** diff --git a/package.json b/package.json index ec14b39..4a6b6ef 100644 --- a/package.json +++ b/package.json @@ -1,21 +1,16 @@ { "name": "p-respostas", - "version": "0.56.0", - "description": "Contrato simples de respostas (sucesso/erro) para APIs e serviços.", - "main": "./dist-back/index.js", - "module": "./dist-front/index.mjs", + "version": "0.54.0", + "description": "", + "main": "./src/index.ts", "exports": { ".": { - "types": "./dist-front/index.d.mts", + "types": "./src/index.ts", "import": "./dist-front/index.mjs", "require": "./dist-back/index.js" } }, - "types": "./dist-front/index.d.mts", - "engines": { - "node": ">=20" - }, - "sideEffects": false, + "types": "./src/index.ts", "scripts": { "biome": "npx @biomejs/biome check --write ./src", "build": "npm --no-git-tag-version version minor && pnpm run biome && tsup --config ./node_modules/p-comuns/tsup/tsup.config.ts && pnpm run pacote", diff --git a/pacote.tgz b/pacote.tgz index 8381adf..a108c65 100644 Binary files a/pacote.tgz and b/pacote.tgz differ diff --git a/src/index.ts b/src/index.ts index 9f14c03..565aacc 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,2 +1 @@ -// Re-export da API pública do pacote. export * from "./respostas" diff --git a/src/respostas.ts b/src/respostas.ts index 245b910..0f37f3c 100644 --- a/src/respostas.ts +++ b/src/respostas.ts @@ -1,8 +1,3 @@ -/** - * Códigos padrão usados pelo contrato de respostas. - * - * Observação: este enum é parte da API pública do pacote. - */ export enum codigosResposta { sucesso = 200, erroConhecido = 400, @@ -44,11 +39,6 @@ export type tipoPrErroInterno = { __filename?: string } -/** - * Cria um conjunto de geradores de respostas. - * - * @param registrarErroInterno callback para registrar/normalizar erros internos. - */ export const gerarRespostas = ( /** Faz um processamento quando erro interno * Recebe o erro gerado, mensagem personalizada e detalhes @@ -188,6 +178,6 @@ export const gerarRespostas = ( } /** - * Instância default (sem handler de erro interno). + * Uso de respostas em comuns */ export const respostaComuns = gerarRespostas(() => ({}))