Download iodine - download do código-fonte iodine

iodine

Outro código-fonte

v8.5.0

Baixar

Iodo

Iodine.js é uma microbiblioteca de validação do lado do cliente. Não possui dependências e pode ser usado isoladamente ou como parte de um framework. O Iodine também oferece suporte a regras encadeadas, permitindo verificar se uma parte (ou partes) de dados atende a vários critérios.

Atualizando

A versão 8+ do Iodine envolveu uma grande reescrita com inúmeras alterações importantes. Recomenda-se, portanto, que os projetos existentes continuem a utilizar a versão 7 (ou inferior), enquanto a versão 8 (ou superior) deve ser reservada para projetos mais recentes.

Instalação

A maneira mais fácil de inserir Iodo em seu projeto é por meio de um CDN (certifique-se de atualizar o número da compilação):

 < script src =" https://cdn.jsdelivr.net/npm/@caneara/[email protected]/dist/iodine.min.umd.js " defer >  script >

Você também pode incluir Iodo em seu projeto via NPM:

 npm i @ caneara / iodine

Uso

O iodo é adicionado automaticamente ao namespace window , tornando-o disponível em qualquer lugar. Esta é a forma recomendada de usar Iodo se o seu projeto não envolver compilação ou importação. Mesmo que o seu projeto envolva compilação, geralmente é mais fácil usar apenas a instância adicionada ao namespace window .

Como alternativa, se você se sentir confortável em usar importações ou quiser criar sua própria instância, poderá importar Iodo da seguinte forma:

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ;

Validação Básica

O Iodine inclui várias regras de validação que você pode acessar por meio de seus métodos associados. Isso torna rápido e fácil verificar se um item é, por exemplo, um número inteiro ou uma data.

As regras do Iodo são prefixadas com assert . Então, para verificar se um item é um integer , você usaria o seguinte código:

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assertInteger ( item_1 ) ; // true
Iodine . assertInteger ( item_2 ) ; // false

Veja abaixo uma lista completa das regras de validação incluídas no Iodo.

Validação Avançada

Embora possa ser útil verificar se um item está em conformidade com uma regra de validação individual, muitas vezes você desejará verificar se um item está em conformidade com várias regras. Por exemplo, um endereço de e-mail pode ser obrigatório, deve ser uma string e deve satisfazer uma expressão regular de endereço de e-mail.

Para atender a essas necessidades, a Iodine oferece 'verificações de item único' e 'verificações de vários itens'...

Verificações de item único

Essa abordagem é preferida se você tiver um item que precisa testar em relação a diversas regras (como o exemplo de endereço de e-mail descrito acima). Para realizar uma 'verificação de item único', chame o método assert principal. O método leva dois parâmetros. O primeiro é o item a ser verificado. A segunda é uma array de regras de validação que devem ser executadas em sequência, por exemplo

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assert ( item_1 , [ 'required' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' ] ) ;

Como você pode ver no exemplo, as regras de validação são expressas usando strings . Para localizar a representação string de uma regra de validação, revise a lista existente.

Ao contrário das asserções individuais (que retornam um boolean ), o método assert retorna um object contendo um relatório. Quando o item passar em todas as regras, você obterá isto:

 {
    valid : true ,
    rule  : '' ,
    error : '' ,
} ;

Se o item não for validado, o relatório conterá a primeira regra que não satisfez, juntamente com a mensagem de erro associada:

 {
    valid : false ,
    rule  : 'integer' ,
    error : 'Value must be an integer' ,
} ;

Verificações de vários itens

Esta abordagem é preferida quando você precisa verificar vários itens em relação a diversas regras de validação diferentes, por exemplo, ao enviar um formulário contendo vários campos.

Tal como acontece com as 'verificações de item único', você deve chamar o método assert , no entanto, para ambos os parâmetros, você precisará fornecer um object . O primeiro objeto deve conter os itens a serem validados, enquanto o segundo deve consistir nas regras para cada item, por exemplo

 const items = {
    name     : 5 ,
    email    : '[email protected]' ,
    password : 'abcdefgh' ,
} ;

const rules = {
    name     : [ 'required' , 'string' ] ,
    email    : [ 'required' , 'email' ] ,
    password : [ 'required' ] ,
} ;

Iodine . assert ( items , rules ) ;

Ao contrário das “verificações de item único”, o relatório é ligeiramente diferente. Ele contém uma chave valid de nível superior que permite verificar facilmente se tudo passou ou algo falhou. Em seguida, contém uma chave fields , que contém sub-relatórios para cada item. O sub-relatório é o mesmo que você obteria para uma 'verificação de item único'. Aqui está o relatório para o exemplo de código mostrado acima:

 {
    valid  : false ,
    fields : {
        name : {
            valid : false ,
            rule  : 'string' ,
            error : 'Value must be a string' ,
        } ,
        email : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        } ,
        password : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        }
    } ,
} ;

Parâmetros adicionais

Algumas regras requerem parâmetros extras, por exemplo

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assertMin ( item_1 , 5 ) ; // true
Iodine . assertMin ( item_2 , 5 ) ; // false

Para validação avançada, você pode fornecer os parâmetros anexando-os à regra com um separador de ponto e vírgula, por exemplo

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assert ( item_1 , [ 'required' , 'integer' , 'min:5' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' , 'min:5' ] ) ;

Ou, se preferir, você pode fornecer a regra como um object em vez de uma string separada por ponto e vírgula:

 Iodine . assert ( 8 , [ 'required' , 'integer' , { rule : 'min' , param : 7 } , 'max:10' ] ) ;

Valores opcionais

Para validação avançada, você pode permitir valores opcionais. O iodo apoia isso com a regra optional :

 let item_1 = 7 ;
let item_2 = null ;
let item_3 = 'string' ;

Iodine . assert ( item_1 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_3 , [ 'optional' , 'integer' ] ) ;

IMPORTANTE : Se você deseja permitir valores opcionais, então esta deve ser a primeira regra do array.

Erros personalizados

O Iodine inclui um conjunto padrão de mensagens de erro para o idioma inglês. No entanto, você pode substituí-los facilmente por meio do método setErrorMessages . Este método requer um único parâmetro, que é um object que contém as mensagens. Veja o construtor do Iodine para ver um exemplo.

O Iodine substituirá automaticamente os espaços reservados [FIELD] e [PARAM] quando ocorrer um erro. Como tal, você deve inserir esses espaços reservados na posição apropriada em sua nova mensagem de erro, por exemplo

 Iodine . setErrorMessages ( { same : `[FIELD] must be '[PARAM]'` } ) ;   // English
Iodine . setErrorMessages ( { same : `[FIELD] doit être '[PARAM]'` } ) ; // French

Erros únicos

Em muitos casos, não será necessário substituir todas as mensagens de erro. Em vez disso, você desejará atualizar um ou adicionar um novo. Para fazer isso, você deve chamar setErrorMessage , por exemplo

 Iodine . setErrorMessage ( 'passwordConfirmation' , 'Does not match password' ) ;

Erros personalizados por campo

Às vezes, pode ser necessário definir uma mensagem de erro específica para um campo, ou pode ser necessário um rótulo para um campo diferente do nome da variável usada.

Para conseguir isso, passe um objeto para o método assert contendo a regra como propriedade e a mensagem de erro personalizada como um valor, por exemplo

 Iodine . assert ( value , [ 'required' ] , { 'required' : 'The "Label" must be present.' } ) ;

Você também pode usar a mesma abordagem para vários campos, por exemplo

 let items = {
    name : '' ,
} ;

let rules = {
    name : [ 'required' ]
} ;

let errors = {
    name : {
        required : 'The "Label" must be present.'
    }
} ;

Iodine . assert ( items , rules , errors ) ;

Nome do campo padrão

Como as 'verificações de item único' não suportam nomes de campos, o Iodine usa o padrão (que é 'Valor'). Se 'Value' não for adequado, então você pode chamar o método setDefaultFieldName e fornecer um valor string alternativo para usar, por exemplo

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

Observe que você deve chamar setDefaultFieldName antes de chamar assert .

Regras disponíveis

As seguintes regras de validação estão disponíveis:

Regra	Chave de string	Descrição
assertAfter(data/inteiro)	'depois'	Verifique se o item é uma `Date` posterior a uma determinada `Date` ou carimbo de data/hora
assertAfterOrEqual(data/inteiro)	'depoisOrEqual'	Verifique se o item é uma `Date` posterior ou igual a uma determinada `Date` ou carimbo de data/hora
assertArray	'variedade'	Verifique se o item é um `array`
assertBefore(data/inteiro)	'antes'	Verifique se o item é uma `Date` anterior a uma determinada `Date` ou carimbo de data/hora
assertBeforeOrEqual(data/inteiro)	'antesOuEqual'	Verifique se o item é uma `Date` anterior ou igual a uma determinada `Date` ou carimbo de data/hora
assertBoolean	'booleano'	Verifique se o item é `true` ou `false`
datadeafirmação	'data'	Verifique se o item é um objeto `Date`
assertDiferente(valor)	'diferente'	Verifique se o item é diferente do valor fornecido (usa comparação solta)
assertEnds(valor)	'termina'	Verifique se o item termina com o valor fornecido
assertE-mail	'e-mail'	Verifique se o item é um endereço de e-mail válido
assertFalsy	'falso'	Verifique se o item é `false` , `'false'` , `0` ou `'0'`
assertIn (matriz)	'em'	Verifique se o item está dentro da `array` fornecida
assertInteger	'inteiro'	Verifique se o item é um `integer`
assertJson	'json'	Verifique se o item é uma `string` de objeto JSON analisável
assertMaxLength(limite)	'maxComprimento'	Verifique se o comprimento de caracteres do item não excede o limite fornecido
assertMinLength(limite)	'minComprimento'	Verifique se o comprimento de caracteres do item não está abaixo do limite fornecido
assertMax(limite)	'máximo'	Verifique se o valor numérico do item não excede o limite determinado
assertMin(limite)	'min'	Verifique se o valor numérico do item não está abaixo do limite determinado
assertNotIn(matriz)	'não dentro'	Verifique se o item não está dentro da `array` fornecida
assertNumeric	'numérico'	Verifique se o item é `number` ou uma `string` numérica
assertOpcional	'opcional'	Permitir valores opcionais (apenas para uso com múltiplas verificações)
assertRegexMatch(exp)	'regexMatch'	Verifique se o item satisfaz a expressão regular fornecida
assertObrigatório	'obrigatório'	Verifique se o item não é `null` , `undefined` ou uma `string` vazia
assertSame(valor)	'mesmo'	Verifique se o item é igual ao valor fornecido (usa comparação solta)
assertStartsWith(valor)	'começa com'	Verifique se o item começa com o valor fornecido
assertString	'corda'	Verifique se o item é uma `string`
afirmarVerdade	'verdadeiro'	Verifique se o item é `true` , `'true'` , `1` ou `'1'`
assertUrl	'URL'	Verifique se o item é um URL válido
assertUuid	'uuuid'	Verifique se o item é um `UUID`

Examine os testes para obter exemplos de como usar cada regra.

Regras personalizadas

O Iodine permite que você adicione suas próprias regras de validação personalizadas por meio do método rule . Este método aceita dois parâmetros. O primeiro é o nome da regra. A segunda é o closure que o Iodine deve executar ao chamar a regra, por exemplo

 Iodine . rule ( 'lowerCase' , ( value ) => value === value . toLowerCase ( ) ) ;

IMPORTANTE : O Iodine irá automaticamente colocar a primeira letra do nome da regra em maiúscula e prefixá-la com 'assert'. Você deve, portanto, evitar adicionar o prefixo, por exemplo

 Iodine . rule ( 'lowerCase' ) ;       // right
Iodine . rule ( 'assertLowerCase' ) ; // wrong

Se a sua regra precisar aceitar um parâmetro, simplesmente inclua-o no seu closure como o segundo argumento, por exemplo

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;

Você também pode adicionar mensagens de erro para suas regras personalizadas, por exemplo

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;
Iodine . setErrorMessage ( 'equals' , "[FIELD] must be equal to '[PARAM]'" ) ;

Regras assíncronas

Versões anteriores do Iodine suportavam regras personalizadas assíncronas usando async / await . Desde então, isso foi removido para tornar a biblioteca mais fácil de manter. Se você estiver usando regras assíncronas, a estratégia preferida é executar primeiro sua lógica assíncrona, armazenar o resultado e depois fazer com que o Iodine o valide.

Contribuindo

Obrigado por considerar uma contribuição para o Iodo. Você pode enviar um PR contendo regras adicionais, porém, para serem aceitos, eles devem explicar o que fazem, ser úteis para outras pessoas e incluir um teste adequado para confirmar que funcionam corretamente.

Após puxar o projeto, para instalar as dependências: