Validator

Validador que utilizamos dentro do Schema que operamos as validações de campos em formulários.

Classes

graph TB; schema[Schema] field[Field] validator[Validator] field_state[FieldState] context[Context]

API

Cada um das classes e de que maneira se relacionam com as otras serão explicados.

Validator

Os validadores da biblioteca são implementados de maneira padronizada. Para implementar um validador é necessário apenas criar um objeto que implemente o método validate. Este método recebe um objeto do tipo Context para validar.

Caso o contexto seja válido, o método validate deve retornar true, caso contrário false.

Além do método validate, é possível ter parâmetros. Esses parâmetros ficarão disponíveis no FieldState caso a validação falhe.

Por exemplo:

const validator = {
  $params: { extraInfo: 1 },
  validate(context) {
    if (context.value === "valid") {
      return true;
    }
    return false;
  },
};

Context

O Objeto Context é um objeto que é passado para todos os validadores(Validator), para que implementem a validação e verifiquem se o campo que estão validando está correto.

O contexto é composto pelos seguintes campos:

{
    value: '', // Valor a ser validado
    container: {}, // Objeto que o valor faz parte
    root: {}, // Raiz do objeto sendo validado
    lastValue: '', // Ultimo valor antes o valor atual
    lastStatus: false, // Ultimo state
}

Field

Field é a representação de um campo do Schema. O Schema é composto por N fields. Um Field pode ter uma condição associada com ele, e as validações só vão ser aplicadas caso a condição seja verdadeira.

A classe Field tem o seguinte formato:

{
  name: '', // Nome da propriedade do schema
  default: '', // Valor padrão para o objeto
  $fields: [], // Subcampos caso o campo for do tipo objeto
  $v: [], // Array com as validações que devem ser aplicadas
  $condition: '', // Condição para validar o campo
}

Schemas

O Schema é a representação do objeto que se está validando. É o ponto de entrada da lib de validação. Para a criação do Schema é necessário passar uma lista de Fields.

Internamente o Schema trabalha com outros tipos internamente(VObject, VList e VField). Porém, para o usuário da lib, é necessário apenas conhecer e utilizar objeto do tipo Field.

A criação de um Schema é feita através de uma lista de campos Field. A lista de fields não necessáriamente precisa estar no utilizando instâncias do tipo Field, podem ser utilizados objetos literais.

Nós criamos as validações a partir das restrições e das solicitações dos campos no backend.

Campo normal

Para cada campo deve ser definido pelo menos um Nome e um Valor Default

Se um campo não tem um valor default, que vem já pré estabelecido, ele pode ser apenas uma string vazia.

import vld from "@itflex/validations";

const fields = [
  { name: "quantity", value: "10", $v: [] },
  {
    name: "description",
    value: "",
    $v: [
      // Campo requerido
      { required: vld.required },
      // Ele tem um mínimo de caracteres (3) e um máximo (30)
      { length: vld.length({ lte: 3, gte: 30 }) },
    ],
  },
  {
    name: "campo",
    value: "",
    // Condição personalizada, o campo necessita do outroCampo para ser valido
    $condition: ({container}) => !container.outroCampo
    $v: [],
  },
];

Campo objeto

Os campos também podem ser do tipo objeto. Quando são do tipo objeto, eles não tem valor default. O valor default é composto pelos campos dentro dele

import vld from "@itflex/validations";

const fields = [
  {
    name: "campo",
    $obj: true,
    $v: [],
    fields: [{ name: "campoObjeto", value: "", $v: [] }],
  },
];

Campo Lista

Os campos podem ser lista quando indicado o campo $list como true. As validações colocadas em $v são aplicadas sobre a lista como um todo. Já as validações colocadas em $item são colocadas as validações que devem ser aplicadas a cada item.

import vld from "@itflex/validations";

{
  name: 'campo_que_é_lista',
  value: [],
  $list: true,
  $v: [
    {
      requiredList: vld.required,
      $condition: ({container}) => container.mimeTypes.length === 0,
    },
  ],
  $item: [{regex: vld.regex({expr: extensionRegex})}],
}

Campo Lista de Objetos

O campo lista de objetos é construído indicando o campo $list e o campo $objItem como true. As validações colocadas em $v são aplicadas à lista de objetos como um todo. A partir do $item os campos do objeto da lista são indicados

import vld from "@itflex/validations";

{
  name: 'campo_que_é_lista_de_objetos',
  $v: [{required: vld.required}],
  $list: true,
  $objItem: true,
  $item: [
    {
      name: 'campo_do_objeto',
      value: '',
      $v: [{required: vld.required}],
    },
  ],
}

Construção do Schema

// Deve ter em todos os Schemas
export const schema = new vld.Schema(fields);

FieldState

FieldState é o objeto que é composto para o retorno das validações. Nele é contido a informação de tudo que foi validado e seus resultados.

Caso o campo sendo validado seja um objeto, o FieldState terá um FieldState para cada campo do objeto. Caso for lista, terá um FieldState para cada item da lista.

Esse objeto é composto pelos seguintes campos:

{
    $error: false,
    $errors: [], // nome das validações que falharam
    $modified: false,
    $type: validationTypes.OBJECT
    $subfields: {
        subfield: {
            $error: false,
            $errors: [],
            $modified: false,
            $type: validationTypes.PLAIN,
            $subfields: {}
        },
        subfield: {
            $error: false,
            $errors: [], // nome das validações que falharam
            $modified: false,
            $type: validationTypes.OBJECT,
            $subfields: {
                subsubfield: {
                    $error: false,
                    $errors: [],
                    $modified: false,
                    $type: validationTypes.PLAIN,
                    $subfields: {}
                }
            }
        },
        subfieldList: {
            $error: false,
            $errors: [],
            $modified: true,
            $type: validationTypes.LIST
            $subfields: {
                '0': {
                    $error: false,
                    $errors: [],
                    $modified: false,
                    $type: validationTypes.PLAIN,
                    $subfields: {}
                }
            }
        }
    },
}

Validadores customizados

O validador construído pela itflex é bastante versátil e permite que se crie qualquer tipo de validação. Para criar uma validação customizada é necessário criar um objeto que contenha o método validate

Exemplo:

export const validadorCustomizado = {
  validate({ value, container }) {
    return true; // se válido
    return false; // se inválido
  },
};

export const fields = [
  { name: "campo", value: "", $v: { validadorCustomizado } },
];

value: O campo value contém o valor do campo que é para ser validado;
container: O campo container contém o objeto em que o valor está inserido

Mensagens de validação

Para colocar uma mensagem específica para esse valor customizado é necessário adicionar a mensagem no método buildMessage do Form

{
  ...
  computed: {
    ...
    validationMessages()  {
      return buildMessages({
        campo: {id: 'id_da_mensagem_de_validação'}
      })
    }
  }
}

Como criar um Schema

Vamos utilizar o exemplo do SDK e criar um Schema para os Products. Vamos relembrar os campos que criamos lá, e criaremos validações para eles.

id - campo obrigatório
name - campo obrigatório
description - não é obrigatório mas se for fornecido, terá um limite de caracteres entre 1 e 250
quantity - quantidade padrão é 100
price - campo obrigatório

Tendo isso em mente, teríamos:

import vld from "@itflex/validation";

export const fields = [
  { name: "id", value: "", $v: [{ required: vld.required }] },
  { name: "name": value: "", $v: [{ required: vld.required }] },
  {
    name: 'description',
    value: '',
    $v: [{maxLength: vld.length({lte: 1, gte: 250})}],
  },
  { name: "quantity", value: 100, $v: []}
  { name: "price", value: "", $v: [{ required: vld.required }]}
];

export const productSchema = new vld.Schema(fields);