lib-payload

Biblioteca TypeScript para tratamento, validação, transformação, comparação e interpretação de payloads JSON no ecossistema Middleware Cargolift.

📌 Objetivo

Este repositório centraliza utilitários e componentes reutilizáveis para lidar com payloads de integração, reduzindo duplicação de lógica entre serviços e padronizando comportamentos críticos de validação e auditoria.

No contexto do Middleware, a lib apoia fluxos de integração com foco em resiliência, rastreabilidade, consistência de dados e facilidade de manutenção.

Público-alvo: Desenvolvedores de bibliotecas e serviços do monorepo middleware.

✨ Funcionalidades

• PayloadValidation: valida payloads por schema declarativo (tipos, obrigatoriedade, ranges, padrões e listas permitidas).
• PayloadTransformation: transforma estruturas JSON usando expressões JSONata.
• PayloadDiff: compara entidade x payload e retorna apenas mudanças efetivas, com changelog para auditoria.
• PayloadCondition: avalia árvores de condições lógicas (all/any) com suporte a variáveis dinâmicas.
• PayloadResponseInterpreter: interpreta respostas de APIs externas para padronizar sucesso/erro e mensagens.
• Utilitários de payload: navegação por path, comparação, JSON pointer, resolução de variáveis e hash.

Diferenciais técnicos:

• API agnóstica de framework.
• Cobertura por testes com Vitest.
• Foco em uso em pipelines de integração e processamento de mensagens.

🔍 Detalhamento

Validação de Payload

PayloadValidation executa validação declarativa e retorna relatório estruturado sem interromper o fluxo por exceções de negócio.

Exemplo de uso

import { PayloadValidation } from "@cargolift-cdi/lib-payload";

const validator = new PayloadValidation();

const schema = {
  "order/id": { required: true, type: "string" },
  "items": { type: "array", minItems: 1 },
  "items/qty": { type: "number", range: { min: 1 } },
};

const result = await validator.validate(
  { order: { id: "ORD-1" }, items: [{ qty: 2 }] },
  schema,
);

if (!result.success) {
  console.error(result.errorsList);
}

Parâmetros:

• rawPayload: objeto ou string JSON.
• schema: mapa de regras por caminho de campo.

Retorno:

• SchemaValidationResult com success, errors e errorsList.

Transformação de Payload

PayloadTransformation utiliza JSONata para projeções e enriquecimentos de payload.

Exemplo de uso

import { PayloadTransformation } from "@cargolift-cdi/lib-payload";

const expression = `{
  "orderId": order.id,
  "total": $sum(items.(qty * price))
}`;

const result = await PayloadTransformation.transform(expression, {
  order: { id: "ORD-10" },
  items: [{ qty: 2, price: 10 }, { qty: 1, price: 5 }],
});

console.log(result.result);

Parâmetros:

• expression: expressão JSONata.
• payload: entrada a ser transformada.

Retorno:

• PayloadTransformationResult com success, result e error?.

Diff para Auditoria

PayloadDiff compara entidade existente com payload recebido e retorna sanitizedPayload contendo somente alterações relevantes.

Exemplo de uso

import { PayloadDiff } from "@cargolift-cdi/lib-payload";

const entity = { name: "Cliente A", status: "active" };
const payload = { name: "Cliente A", status: "inactive" };

const diff = PayloadDiff.diff(entity, payload);

if (diff.hasChanges) {
  console.log(diff.sanitizedPayload); // { status: "inactive" }
  console.log(diff.changes);
}

Parâmetros:

• entity: estado atual persistido.
• payload: estado recebido para atualização.
• options?: campos ignorados e separador de path.

Retorno:

• ResultPayloadDiff<T> com hasChanges, changes e sanitizedPayload.

🛠 Tecnologias e Dependências

Dependências internas:

• @cargolift-cdi/lib-common
• @cargolift-cdi/types

🚀 Instalação

Pré-requisitos

• Node.js: >= 18
• pnpm: recomendado para o monorepo

Passos de instalação

1. Instalar dependências do workspace:

pnpm install

2. Build da biblioteca:

pnpm --filter @cargolift-cdi/lib-payload build

3. Rodar testes da biblioteca:

pnpm --filter @cargolift-cdi/lib-payload test

Variáveis de ambiente

Não há variáveis de ambiente obrigatórias para uso base da biblioteca.

💡 Como Usar

Quickstart

import {
  PayloadValidation,
  PayloadTransformation,
  PayloadDiff,
} from "@cargolift-cdi/lib-payload";

const validator = new PayloadValidation();
const validation = await validator.validate({ id: "1" }, { id: { required: true, type: "string" } });

const transformed = await PayloadTransformation.transform('{"id": id}', { id: "1" });

const diff = PayloadDiff.diff({ status: "A" }, { status: "I" });

Casos de uso avançados

• Pré-validação de payload canônico no ESB: aplicar PayloadValidation antes de regras de negócio.
• Detecção de alterações para update parcial: usar PayloadDiff para evitar writes desnecessários e registrar changelog.
• Projeções de integração entre sistemas: usar JSONata em PayloadTransformation para adaptar contratos.

📁 Estrutura do Projeto

.
├── src/
│   ├── index.ts
│   ├── payload-validation/
│   ├── payload-transformation/
│   ├── payload-diff/
│   ├── payload-condition/
│   ├── payload-response-interpreter/
│   ├── util/
│   └── __tests__/
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

• src/payload-validation/: validações declarativas por schema.
• src/payload-transformation/: transformações com JSONata.
• src/payload-diff/: comparação e sanitização de alterações.
• src/payload-condition/: avaliação de regras condicionais.
• src/payload-response-interpreter/: interpretação de respostas externas.
• src/util/: funções auxiliares reutilizáveis.

🧪 Testes

Como rodar os testes

pnpm --filter @cargolift-cdi/lib-payload test

Build e smoke de tipagem

pnpm --filter @cargolift-cdi/lib-payload build
pnpm --filter @cargolift-cdi/lib-payload build:smoke

🤝 Contribuindo

Padrão de branches:

• main: branch principal.
• feature/*: novas funcionalidades.
• bugfix/*: correções.

Padrão de commits:

• Conventional Commits.
• Exemplos:
  • feat(payload-validation): adiciona suporte a dateISO
  • fix(payload-diff): corrige comparação de arrays aninhados

Processo de PR:

1. Criar branch a partir de main.
2. Implementar alteração com testes.
3. Executar test e build da lib.
4. Abrir PR com descrição técnica e impacto.

📄 Licença

Este projeto é distribuído sob a licença MIT.