@cargolift-cdi/lib-payload · PayloadValidation

Biblioteca utilizada pelos serviços do middleware para validar payloads antes de publicá-los ou processá-los. O PayloadValidation aplica regras declarativas, suporta objetos ou strings JSON e retorna um relatório padronizado com todos os erros encontrados.

Instalação

npm install @cargolift-cdi/lib-payload

Uso rápido

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

const schema: Schema = {
  validations: [
    { field: "order/id", required: true, type: "string", length: { min: 3, max: 36 } },
    { field: "items", type: "array", minItems: 1 },
    { field: "items/qty", type: "number", range: { min: 1 }, message: "Quantidade mínima por item é 1" },
  ],
};

const validator = new PayloadValidation();
const result = await validator.run(payloadOuJson, schema);

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

Campos disponíveis no schema

| Propriedade | Uso | | --- | --- | | field | Caminho do campo. Use / para navegar entre níveis (ex.: address/city). Arrays são percorridos automaticamente: items/qty valida cada qty dentro de items. | | required | Garante presença do campo. | | allowNull | Quando false, recusa valores null mesmo que o campo exista. | | type | Valida o tipo do conteúdo. Tipos suportados: string, number, boolean, date, dateISO, object, array, email. | | length | Restrições para strings (min, max). | | range | Faixas para números (min, max). | | minItems / maxItems | Controle de tamanho de arrays. | | allowedValues | Lista de valores aceitos. Combina com ignoreCase para strings. | | ignoreCase | Quando true, compara allowedValues sem diferenciar maiúsculas/minúsculas. | | pattern | Expressão regular aplicada ao valor (somente strings). | | message | Mensagem personalizada exibida quando a regra falhar. |

Como os caminhos são avaliados

• customer/name acessa propriedades aninhadas.
• contacts/type aplica a regra a cada item da coleção contacts.
• Valores inexistentes retornam undefined, permitindo diferenciar campos ausentes de campos nulos (allowNull).

Tipos especiais

• date: aceita objetos Date ou strings DD/MM/YYYY, DD-MM-YYYY e formatos reconhecidos por Date.parse.
• dateISO: exige ISO 8601 (2025-11-05T14:48:00.000Z).
• email: aplica regex simples user@domain.

Exemplos práticos

1. Validando um payload bruto (string JSON)

const rawPayload = '{"order":{"id":"ORD-9","value":0},"items":[]}';

const schema: Schema = {
  validations: [
    { field: "order/id", required: true, type: "string" },
    { field: "order/value", type: "number", range: { min: 1 }, message: "Valor mínimo do pedido é 1" },
    { field: "items", type: "array", minItems: 1 },
  ],
};

const validation = new PayloadValidation();
const result = await validation.run(rawPayload, schema);

/* result.errors => [
  { field: 'order/value', value: 0, error: 'Valor mínimo do pedido é 1' },
  { field: 'items', value: [], error: "Campo 'items' deve conter ao menos 1 itens" }
] */

2. AllowedValues com ignoreCase e campos opcionais

const payload = {
  status: "APPROVED",
  channel: null,
};

const schema: Schema = {
  validations: [
    {
      field: "status",
      type: "string",
      allowedValues: ["pending", "approved", "rejected"],
      ignoreCase: true,
    },
    {
      field: "channel",
      allowNull: false,
      required: false,
      type: "string",
      message: "Canal precisa ser informado quando enviado",
    },
  ],
};

const { success, errors } = await new PayloadValidation().run(payload, schema);
// success === false porque allowNull=false e channel veio como null

Estrutura do resultado

PayloadValidation.run() retorna ValidationResult:

{
  success: boolean;
  errors: Array<{
    field: string;
    value: any;       // valor que falhou
    error: string;    // mensagem final
    rule?: SchemaValidation; // regra original (útil para auditorias)
  }>;
  errorsList: string[]; // mensagens simples
}

• Em caso de payload malformado (JSON inválido), o erro é registrado com field = "_schema" e value contém o conteúdo bruto.
• Nenhuma exceção é propagada para regras inválidas; a execução continua e todos os erros são agregados.

Tratamento do payload

• Aceita objetos JavaScript ou strings JSON.
• Caso receba string, a biblioteca detecta o formato e tenta fazer JSON.parse (XML pode ser suportado futuramente, ver detectType).
• Falhas de parsing disparam BusinessError com código INVALID_PAYLOAD, permitindo padronizar a resposta HTTP ou o nack de mensagens.

Testes

A suíte usa Vitest e cobre cenários básicos de schema, tipos e parsing.

npm test

Execute os testes antes de publicar (npm prepublishOnly) para garantir que regressões sejam detectadas.