iodine

Jod

Iodine.js ist eine mikroclientseitige Validierungsbibliothek. Es weist keine Abhängigkeiten auf und kann isoliert oder als Teil eines Frameworks verwendet werden. Iodine unterstützt auch verkettbare Regeln, sodass Sie überprüfen können, ob ein Datenteil (oder mehrere Datenteile) mehrere Kriterien erfüllen.

Upgrade

Version 8+ von Iodine erforderte eine umfassende Neufassung mit zahlreichen wichtigen Änderungen. Es wird daher empfohlen, bei bestehenden Projekten weiterhin Version 7 (oder niedriger) zu verwenden, während Version 8 (oder höher) neueren Projekten vorbehalten bleiben sollte.

Installation

Der einfachste Weg, Iodine in Ihr Projekt zu integrieren, ist über ein CDN (aktualisieren Sie unbedingt die Build-Nummer):

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

Sie können Jod auch über NPM in Ihr Projekt integrieren:

 npm i @ caneara / iodine 

Verwendung

Iodine wird automatisch zum window -Namespace hinzugefügt, sodass es überall verfügbar ist. Dies ist die empfohlene Methode zur Verwendung von Iodine, wenn Ihr Projekt keine Kompilierung oder Importe umfasst. Auch wenn Ihr Projekt eine Kompilierung beinhaltet, ist es oft einfacher, einfach die dem window -Namespace hinzugefügte Instanz zu verwenden.

Wenn Sie mit Importen vertraut sind oder Ihre eigene Instanz erstellen möchten, können Sie Iodine alternativ wie folgt importieren:

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

Grundlegende Validierung

Iodine enthält eine Reihe von Validierungsregeln, auf die Sie über die zugehörigen Methoden zugreifen können. Dadurch kann schnell und einfach überprüft werden, ob es sich bei einem Element beispielsweise um eine Ganzzahl oder ein Datum handelt.

Den Regeln von Iodine wird assert vorangestellt. Um also zu überprüfen, ob ein Element eine integer ist, verwenden Sie den folgenden Code:

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

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

Unten finden Sie eine vollständige Liste der in Iodine enthaltenen Validierungsregeln.

Erweiterte Validierung

Während es nützlich sein kann, zu prüfen, ob ein Artikel einer einzelnen Validierungsregel entspricht, möchten Sie häufig prüfen, ob ein Artikel mehreren Regeln entspricht. Beispielsweise kann eine E-Mail-Adresse erforderlich sein, eine Zeichenfolge sein und einen regulären Ausdruck für eine E-Mail-Adresse erfüllen.

Um diesen Anforderungen gerecht zu werden, bietet Iodine „Einzelartikelprüfungen“ und „Mehrfachartikelprüfungen“ an ...

Einzelpostenprüfungen

Dieser Ansatz wird bevorzugt, wenn Sie ein Element haben, das Sie anhand mehrerer Regeln testen müssen (wie das oben beschriebene Beispiel für eine E-Mail-Adresse). Um eine „Einzelelementprüfung“ durchzuführen, rufen Sie die assert -Methode auf. Die Methode benötigt zwei Parameter. Das erste ist das zu überprüfende Element. Das zweite ist eine array von Validierungsregeln, die nacheinander ausgeführt werden sollten, z

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

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

Wie Sie im Beispiel sehen können, werden die Validierungsregeln mithilfe von strings ausgedrückt. Um die string für eine Validierungsregel zu finden, überprüfen Sie die vorhandene Liste.

Im Gegensatz zu einzelnen Zusicherungen (die einen boolean zurückgeben) gibt die assert Methode ein object zurück, das einen Bericht enthält. Wenn der Artikel alle Regeln erfüllt, erhalten Sie Folgendes:

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

Wenn die Validierung des Elements fehlschlägt, enthält der Bericht die erste Regel, die nicht erfüllt wurde, sowie die zugehörige Fehlermeldung:

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

Mehrere Artikelprüfungen

Dieser Ansatz wird bevorzugt, wenn Sie mehrere Elemente anhand einer Reihe unterschiedlicher Validierungsregeln prüfen müssen, z. B. beim Absenden eines Formulars mit mehreren Feldern.

Wie bei „Einzelelementprüfungen“ sollten Sie die assert -Methode aufrufen, für beide Parameter müssen Sie jedoch ein object angeben. Das erste Objekt sollte die zu validierenden Elemente enthalten, während das zweite aus den Regeln für jedes Element bestehen sollte, z

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

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

Iodine . assert ( items , rules ) ;

Im Gegensatz zu „Einzelpostenprüfungen“ unterscheidet sich der Bericht geringfügig. Es enthält einen valid Schlüssel der obersten Ebene, mit dem Sie leicht überprüfen können, ob alles erfolgreich war oder etwas fehlgeschlagen ist. Es enthält dann einen fields , der Unterberichte für jedes Element enthält. Der Unterbericht ist derselbe, den Sie für eine „Einzelartikelprüfung“ erhalten würden. Hier ist der Bericht für das oben gezeigte Codebeispiel:

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

Zusätzliche Parameter

Einige Regeln erfordern zusätzliche Parameter, z

 let item_1 = 7 ;
let item_2 = 4 ;

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

Für eine erweiterte Validierung können Sie die Parameter bereitstellen, indem Sie sie mit einem Semikolon-Trennzeichen an die Regel anhängen, z. B

 let item_1 = 7 ;
let item_2 = 4 ;

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

Wenn Sie möchten, können Sie die Regel auch als object anstelle einer durch ein Semikolon getrennten string angeben:

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

Optionale Werte

Für eine erweiterte Validierung möchten Sie möglicherweise optionale Werte zulassen. Iodine unterstützt dies mit der optional Regel:

 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' ] ) ;

WICHTIG : Wenn Sie optionale Werte zulassen möchten, muss es sich um die erste Regel im Array handeln.

Benutzerdefinierte Fehler

Iodine enthält einen Standardsatz von Fehlermeldungen für die englische Sprache. Sie können sie jedoch problemlos über die Methode setErrorMessages ersetzen. Diese Methode erfordert einen einzelnen Parameter, bei dem es sich um ein object handelt, das die Nachrichten enthält. Ein Beispiel finden Sie im Konstruktor von Iodine.

Iodine ersetzt automatisch die Platzhalter [FIELD] und [PARAM] , wenn ein Fehler auftritt. Daher sollten Sie diese Platzhalter an der entsprechenden Stelle in Ihrer neuen Fehlermeldung einfügen, z

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

Einzelne Fehler

In vielen Fällen müssen Sie nicht alle Fehlermeldungen ersetzen. Stattdessen möchten Sie eines aktualisieren oder ein neues hinzufügen. Um dies zu tun, sollten Sie stattdessen z. B. setErrorMessage aufrufen

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

Benutzerdefinierte Fehler nach Feld

Manchmal kann es erforderlich sein, eine bestimmte Fehlermeldung für ein Feld zu definieren, oder Sie benötigen eine Bezeichnung für ein Feld, die sich vom Namen der verwendeten Variablen unterscheidet.

Um dies zu erreichen, übergeben Sie ein Objekt an die assert -Methode, das die Regel als Eigenschaft und die benutzerdefinierte Fehlermeldung als Wert enthält, z. B

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

Sie können den gleichen Ansatz auch für mehrere Felder verwenden, z

 let items = {
    name : '' ,
} ;

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

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

Iodine . assert ( items , rules , errors ) ;

Standardfeldname

Da „Einzelelementprüfungen“ keine Feldnamen unterstützen, verwendet Iodine stattdessen die Standardeinstellung (d. h. „Wert“). Wenn „Wert“ nicht geeignet ist, können Sie die Methode setDefaultFieldName aufrufen und stattdessen einen alternativen string angeben, z. B

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

Beachten Sie, dass Sie setDefaultFieldName aufrufen müssen, bevor Sie assert aufrufen.

Verfügbare Regeln

Folgende Validierungsregeln stehen zur Verfügung:

Regel	Zeichenfolgenschlüssel	Beschreibung
AssertAfter(Datum/Ganzzahl)	'nach'	Stellen Sie sicher, dass es sich bei dem Element um ein Date nach einem bestimmten Date oder Zeitstempel handelt
behauptenAfterOrEqual(Datum/Ganzzahl)	'afterOrEqual'	Stellen Sie sicher, dass es sich bei dem Element um ein Date nach oder gleich einem bestimmten Date oder Zeitstempel handelt
behauptenArray	'Array'	Stellen Sie sicher, dass das Element ein array ist
behauptenBefore(Datum/Ganzzahl)	'vor'	Stellen Sie sicher, dass es sich bei dem Element um ein Date vor einem bestimmten Date oder Zeitstempel handelt
behauptenBeforeOrEqual(Datum/Ganzzahl)	'beforeOrEqual'	Stellen Sie sicher, dass es sich bei dem Element um ein Date vor oder gleich einem bestimmten Date oder Zeitstempel handelt
behauptenBoolescher Wert	'boolean'	Stellen Sie sicher, dass das Element entweder true oder false ist
AssertDate	'Datum'	Stellen Sie sicher, dass es sich bei dem Element um ein Date -Objekt handelt
behauptenDifferent(Wert)	'anders'	Stellen Sie sicher, dass sich das Element vom angegebenen Wert unterscheidet (verwendet lose Vergleiche).
behauptenEnds(Wert)	'endet'	Stellen Sie sicher, dass das Element mit dem angegebenen Wert endet
behauptenEmail	'E-Mail'	Stellen Sie sicher, dass es sich bei dem Artikel um eine gültige E-Mail-Adresse handelt
behauptenFalsy	'falsch'	Stellen Sie sicher, dass das Element entweder false , 'false' , 0 “ oder '0' ist.
behauptenIn(array)	'In'	Stellen Sie sicher, dass sich das Element innerhalb des angegebenen array befindet
behauptenInteger	'ganze Zahl'	Stellen Sie sicher, dass das Element eine integer ist
behauptenJson	'json'	Stellen Sie sicher, dass es sich bei dem Element um eine analysierbare JSON- string handelt
affirmMaxLength(limit)	'maxLength'	Stellen Sie sicher, dass die Zeichenlänge des Elements den angegebenen Grenzwert nicht überschreitet
affirmMinLength(limit)	'minLength'	Stellen Sie sicher, dass die Zeichenlänge des Elements nicht unter dem angegebenen Grenzwert liegt
affirmMax(limit)	'max'	Stellen Sie sicher, dass der numerische Wert des Artikels den angegebenen Grenzwert nicht überschreitet
behauptenMin(Limit)	'min'	Stellen Sie sicher, dass der numerische Wert des Artikels nicht unter dem angegebenen Grenzwert liegt
behauptenNotIn(array)	'notIn'	Stellen Sie sicher, dass sich das Element nicht im angegebenen array befindet
behauptenNumerisch	'numerisch'	Stellen Sie sicher, dass es sich bei dem Element um number oder eine numerische string handelt
affirmOptional	'optional'	Optionale Werte zulassen (nur zur Verwendung mit mehreren Prüfungen)
behauptenRegexMatch(exp)	'regexMatch'	Stellen Sie sicher, dass das Element den angegebenen regulären Ausdruck erfüllt
AssertRequired	'erforderlich'	Stellen Sie sicher, dass das Element nicht null , undefined oder eine leere string ist
behauptenSame(Wert)	'Dasselbe'	Stellen Sie sicher, dass das Element mit dem angegebenen Wert übereinstimmt (verwendet lose Vergleiche).
affirmStartsWith(value)	'startsWith'	Stellen Sie sicher, dass das Element mit dem angegebenen Wert beginnt
behauptenString	'Zeichenfolge'	Stellen Sie sicher, dass es sich bei dem Element um eine string handelt
behauptenWahrheit	'Wahrheit'	Stellen Sie sicher, dass das Element entweder „ true , 'true' , 1 “ oder '1' ist.
behauptenUrl	'URL'	Stellen Sie sicher, dass es sich bei dem Element um eine gültige URL handelt
behauptenUuid	'uuid'	Stellen Sie sicher, dass es sich bei dem Element um eine UUID handelt

Sehen Sie sich die Tests an, um Beispiele für die Verwendung der einzelnen Regeln zu finden.

Benutzerdefinierte Regeln

Mit Iodine können Sie über die rule Ihre eigenen benutzerdefinierten Validierungsregeln hinzufügen. Diese Methode akzeptiert zwei Parameter. Der erste ist der Name der Regel. Der zweite ist der closure , den Iodine ausführen soll, wenn die Regel aufgerufen wird, z. B

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

WICHTIG : Iodine schreibt den ersten Buchstaben des Regelnamens automatisch in Großbuchstaben und stellt ihm „assert“ voran. Sie sollten daher vermeiden, das Präfix selbst hinzuzufügen, z

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

Wenn Ihre Regel einen Parameter akzeptieren muss, fügen Sie ihn einfach als zweites Argument in Ihren closure ein, z

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

Sie können auch Fehlermeldungen für Ihre benutzerdefinierten Regeln hinzufügen, z

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

Asynchrone Regeln

Frühere Versionen von Iodine unterstützten asynchrone benutzerdefinierte Regeln mit async / await . Dies wurde inzwischen entfernt, um die Wartung der Bibliothek zu vereinfachen. Wenn Sie asynchrone Regeln verwenden, besteht die bevorzugte Strategie darin, zuerst Ihre asynchrone Logik auszuführen, das Ergebnis zu speichern und es dann von Iodine validieren zu lassen.

Mitwirken

Vielen Dank, dass Sie einen Beitrag zu Jod in Betracht gezogen haben. Sie können gerne eine PR mit zusätzlichen Regeln einreichen. Um jedoch akzeptiert zu werden, müssen diese erklären, was sie tun, für andere nützlich sein und einen geeigneten Test enthalten, um zu bestätigen, dass sie korrekt funktionieren.

Nachdem Sie das Projekt abgerufen haben, installieren Sie die Abhängigkeiten:

npm install

Um die Tests durchzuführen

npm run test 

Lizenz

Die MIT-Lizenz (MIT). Weitere Informationen finden Sie in der Lizenzdatei.