iodine

Iode

Iodine.js est une micro bibliothèque de validation côté client. Il n'a aucune dépendance et peut être utilisé isolément ou dans le cadre d'un framework. Iodine prend également en charge les règles chaînables, vous permettant de vérifier qu'un ou plusieurs éléments de données satisfont à plusieurs critères.

Mise à niveau

La version 8+ de Iodine impliquait une réécriture majeure avec de nombreuses modifications majeures. Il est donc recommandé que les projets existants continuent d'utiliser la version 7 (ou inférieure), tandis que la version 8 (ou supérieure) doit être réservée aux projets plus récents.

Installation

Le moyen le plus simple d'intégrer Iodine dans votre projet est via un CDN (assurez-vous de mettre à jour le numéro de build) :

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

Vous pouvez également intégrer Iodine dans votre projet via NPM :

 npm i @ caneara / iodine 

Usage

L'iode est automatiquement ajouté à l'espace de noms window , le rendant disponible n'importe où. C'est la manière recommandée d'utiliser Iodine si votre projet n'implique pas de compilation ou d'importation. Même si votre projet implique une compilation, il est souvent plus facile d'utiliser simplement l'instance ajoutée à l'espace de noms window .

Alternativement, si vous êtes à l'aise avec les importations ou si vous souhaitez créer votre propre instance, vous pouvez importer Iodine comme ceci :

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

Validation de base

Iodine comprend un ensemble de règles de validation auxquelles vous pouvez accéder via leurs méthodes associées. Cela permet de vérifier rapidement et facilement si un élément est, par exemple, un entier ou une date.

Les règles de l'iode sont préfixées par assert . Ainsi, pour vérifier si un élément est un integer , vous utiliserez le code suivant :

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

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

Voir ci-dessous pour une liste complète des règles de validation incluses par Iodine.

Validation avancée

Bien qu'il puisse être utile de vérifier si un élément est conforme à une règle de validation individuelle, vous souhaiterez souvent vérifier si un élément est conforme à plusieurs règles. Par exemple, une adresse e-mail peut être obligatoire, doit être une chaîne et doit satisfaire une expression régulière d'adresse e-mail.

Pour répondre à ces besoins, Iodine propose des « contrôles d'éléments uniques » et des « contrôles d'éléments multiples »...

Vérifications d'articles uniques

Cette approche est préférable si vous avez un élément que vous devez tester par rapport à plusieurs règles (comme l'exemple d'adresse e-mail décrit ci-dessus). Pour effectuer une « vérification d’un seul élément », appelez la méthode main assert . La méthode prend deux paramètres. Le premier est l’élément à vérifier. La seconde est un array de règles de validation qui doivent être exécutées en séquence, par exemple

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

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

Comme vous pouvez le voir dans l'exemple, les règles de validation sont exprimées à l'aide strings . Pour trouver la représentation string d'une règle de validation, examinez la liste existante.

Contrairement aux assertions individuelles (qui renvoient un boolean ), la méthode assert renvoie un object contenant un rapport. Lorsque l'élément satisfait à toutes les règles, vous obtiendrez ceci :

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

Si la validation de l'élément échoue, le rapport contiendra la première règle à laquelle il n'a pas satisfait, ainsi que le message d'erreur associé :

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

Vérifications d'articles multiples

Cette approche est préférable lorsque vous devez vérifier plusieurs éléments par rapport à un ensemble de règles de validation différentes, par exemple lors de la soumission d'un formulaire contenant plusieurs champs.

Comme pour les « vérifications d'éléments uniques », vous devez appeler la méthode assert , mais pour les deux paramètres, vous devrez fournir un object . Le premier objet doit contenir les éléments à valider, tandis que le second doit contenir les règles pour chaque élément, par exemple

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

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

Iodine . assert ( items , rules ) ;

Contrairement aux « vérifications d'éléments uniques », le rapport est légèrement différent. Il contient une clé valid de niveau supérieur qui vous permet de vérifier facilement si tout a réussi ou si quelque chose a échoué. Il contient ensuite une clé fields , qui contient des sous-rapports pour chaque élément. Le sous-rapport est le même que celui que vous obtiendriez pour une « vérification d'un seul élément ». Voici le rapport pour l'exemple de code présenté ci-dessus :

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

Paramètres supplémentaires

Certaines règles nécessitent des paramètres supplémentaires, par exemple

 let item_1 = 7 ;
let item_2 = 4 ;

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

Pour une validation avancée, vous pouvez fournir les paramètres en les ajoutant à la règle avec un séparateur point-virgule, par exemple

 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, si vous préférez, vous pouvez fournir la règle sous forme d' object au lieu d'une string séparée par un point-virgule :

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

Valeurs facultatives

Pour une validation avancée, vous souhaiterez peut-être autoriser des valeurs facultatives. Iodine prend en charge cela avec la règle 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' ] ) ;

IMPORTANT : Si vous souhaitez autoriser des valeurs facultatives, alors il doit s'agir de la première règle du tableau.

Erreurs personnalisées

Iodine comprend un ensemble par défaut de messages d'erreur pour la langue anglaise. Cependant, vous pouvez facilement les remplacer via la méthode setErrorMessages . Cette méthode nécessite un seul paramètre, qui est un object contenant les messages. Voir le constructeur d'Iodine pour un exemple.

Iodine remplacera automatiquement les espaces réservés [FIELD] et [PARAM] lorsqu'une erreur se produit. En tant que tel, vous devez insérer ces espaces réservés à la position appropriée dans votre nouveau message d'erreur, par exemple

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

Erreurs uniques

Dans de nombreux cas, vous n'aurez pas besoin de remplacer tous les messages d'erreur. Vous souhaiterez plutôt en mettre à jour un ou en ajouter un nouveau. Pour ce faire, vous devez plutôt appeler setErrorMessage par exemple

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

Erreurs personnalisées par champ

Parfois, il peut être nécessaire de définir un message d'erreur spécifique pour un champ, ou vous avez besoin d'un libellé pour un champ différent du nom de la variable utilisée.

Pour y parvenir, transmettez un objet à la méthode assert contenant la règle comme propriété et le message d'erreur personnalisé comme valeur, par exemple

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

Vous pouvez également utiliser la même approche pour plusieurs champs, par exemple

 let items = {
    name : '' ,
} ;

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

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

Iodine . assert ( items , rules , errors ) ;

Nom du champ par défaut

Étant donné que les « vérifications d'éléments uniques » ne prennent pas en charge les noms de champs, Iodine utilise à la place la valeur par défaut (qui est « Valeur »). Si « Valeur » ne convient pas, vous pouvez appeler la méthode setDefaultFieldName et fournir une valeur string alternative à utiliser à la place, par exemple

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

Notez que vous devez appeler setDefaultFieldName avant d'appeler assert .

Règles disponibles

Les règles de validation suivantes sont disponibles :

Règle	Clé de chaîne	Description
assertAfter (date/entier)	'après'	Vérifiez que l'élément est une Date après une Date ou un horodatage donné
assertAfterOrEqual (date/entier)	'aprèsOuÉgal'	Vérifiez que l'élément est une Date postérieure ou égale à une Date ou un horodatage donné.
assertArray	'tableau'	Vérifiez que l'élément est un array
assertBefore (date/entier)	'avant'	Vérifiez que l'élément est une Date antérieure à une Date ou un horodatage donné
assertBeforeOrEqual (date/entier)	'avantOuÉgal'	Vérifiez que l'élément est une Date antérieure ou égale à une Date ou un horodatage donné.
assertBooléen	'booléen'	Vérifiez que l'élément est true ou false
assertDate	'date'	Vérifiez que l'élément est un objet Date
assertDifférent(valeur)	'différent'	Vérifiez que l'élément est différent de la valeur fournie (utilise une comparaison lâche)
assertEnds (valeur)	'se termine'	Vérifiez que l'élément se termine par la valeur donnée
assertEmail	'e-mail'	Vérifiez que l'article est une adresse e-mail valide
assertFalsy	'faux'	Vérifiez que l'élément est soit false , 'false' , 0 ou '0'
assertIn (tableau)	'dans'	Vérifiez que l'élément se trouve dans le array donné
assertInteger	'entier'	Vérifiez que l'élément est un integer
assertJson	'json'	Vérifiez que l'élément est une string d'objet JSON analysable
assertMaxLength (limite)	'longueurmax'	Vérifiez que la longueur des caractères de l'élément ne dépasse pas la limite donnée.
assertMinLength (limite)	'minLongueur'	Vérifiez que la longueur des caractères de l'élément n'est pas inférieure à la limite donnée.
assertMax (limite)	'maximum'	Vérifiez que la valeur numérique de l'élément ne dépasse pas la limite donnée
assertMin (limite)	'min'	Vérifiez que la valeur numérique de l'élément n'est pas inférieure à la limite donnée
assertNotIn (tableau)	'pas dans'	Vérifiez que l'élément ne se trouve pas dans le array donné
assertNumérique	'numérique'	Vérifiez que l'élément est number ou une string numérique
assertFacultatif	'facultatif'	Autoriser les valeurs facultatives (uniquement pour une utilisation avec plusieurs contrôles)
assertRegexMatch(exp)	'regexMatch'	Vérifier que l'élément satisfait à l'expression régulière donnée
assertObligatoire	'requis'	Vérifiez que l'élément n'est pas null , undefined ou une string vide
assertSame (valeur)	'même'	Vérifiez que l'élément est identique à la valeur fournie (utilise une comparaison lâche)
assertStartsWith (valeur)	'commence par'	Vérifiez que l'élément commence par la valeur donnée
assertString	'chaîne'	Vérifiez que l'élément est une string
affirmerVérité	'véridique'	Vérifiez que l'élément est soit true , 'true' , 1 ou '1'
assertUrl	'url'	Vérifiez que l'élément est une URL valide
assertUuid	'uuide'	Vérifiez que l'élément est un UUID

Examinez les tests pour obtenir des exemples d’utilisation de chaque règle.

Règles personnalisées

Iodine vous permet d'ajouter vos propres règles de validation personnalisées via la méthode rule . Cette méthode accepte deux paramètres. Le premier est le nom de la règle. La seconde est la closure que Iodine doit exécuter lors de l'appel de la règle, par exemple

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

IMPORTANT : Iodine mettra automatiquement la première lettre du nom de la règle en majuscule et la préfixera par 'assert'. Vous devez donc éviter d'ajouter le préfixe vous-même, par exemple

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

Si votre règle doit accepter un paramètre, incluez-le simplement dans votre closure comme deuxième argument, par exemple

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

Vous pouvez également ajouter des messages d'erreur pour vos règles personnalisées, par exemple

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

Règles asynchrones

Les versions précédentes d'Iodine prenaient en charge les règles personnalisées asynchrones à l'aide de async / await . Cela a depuis été supprimé pour faciliter la maintenance de la bibliothèque. Si vous utilisiez des règles asynchrones, la stratégie préférée consiste à exécuter d'abord votre logique asynchrone, à stocker le résultat, puis à le faire valider par Iodine.

Contribuer

Merci d'avoir envisagé une contribution à Iodine. Vous êtes invités à soumettre un PR contenant des règles supplémentaires, mais pour être acceptés, ils doivent expliquer ce qu'ils font, être utiles aux autres et inclure un test approprié pour confirmer qu'ils fonctionnent correctement.

Après avoir extrait le projet, pour installer les dépendances :

npm install

Pour exécuter les tests

npm run test 

Licence

La licence MIT (MIT). Veuillez consulter le fichier de licence pour plus d'informations.