iodine

Йод

Iodine.js — это микробиблиотека проверки на стороне клиента. Он не имеет зависимостей и может использоваться изолированно или как часть фреймворка. Iodine также поддерживает цепочки правил, позволяющие проверить, что часть (или части) данных удовлетворяет множеству критериев.

Обновление

Версия Iodine 8+ включала в себя серьезную переработку с многочисленными критическими изменениями. Поэтому рекомендуется, чтобы существующие проекты продолжали использовать версию 7 (или ниже), а версию 8 (или выше) следует зарезервировать для новых проектов.

Установка

Самый простой способ подключить Iodine к вашему проекту — через CDN (обязательно обновите номер сборки):

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

Вы также можете добавить Iodine в свой проект через NPM:

 npm i @ caneara / iodine 

Использование

Iodine автоматически добавляется в пространство имен window , что делает его доступным где угодно. Это рекомендуемый способ использования Iodine, если ваш проект не требует компиляции или импорта. Даже если ваш проект требует компиляции, часто проще использовать экземпляр, добавленный в пространство имен window .

В качестве альтернативы, если вам удобно использовать импорт или вы хотите создать свой собственный экземпляр, вы можете импортировать Iodine следующим образом:

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

Базовая проверка

Iodine включает в себя набор правил проверки, к которым вы можете получить доступ через связанные с ними методы. Это позволяет быстро и легко проверить, является ли элемент, например, целым числом или датой.

Правила Iodine имеют префикс assert . Итак, чтобы проверить, является ли элемент integer , вы должны использовать следующий код:

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

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

Ниже приведен полный список включенных в Iodine правил проверки.

Расширенная проверка

Хотя проверка соответствия элемента отдельному правилу проверки может быть полезной, вам часто потребуется проверить, соответствует ли элемент нескольким правилам. Например, адрес электронной почты может быть обязательным, должен быть строкой и соответствовать регулярному выражению адреса электронной почты.

Чтобы удовлетворить эти потребности, Iodine предлагает «проверки одного элемента» и «проверки нескольких элементов»…

Проверка отдельных позиций

Этот подход предпочтителен, если у вас есть один элемент, который необходимо протестировать на соответствие нескольким правилам (как в примере с адресом электронной почты, описанном выше). Чтобы выполнить «проверку одного элемента», вызовите основной метод assert . Метод принимает два параметра. Во-первых, это элемент, который нужно проверить. Второй — это array правил проверки, которые следует выполнять последовательно, например

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

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

Как вы можете видеть в примере, правила проверки выражаются с помощью strings . Чтобы найти string представление правила проверки, просмотрите существующий список.

В отличие от отдельных утверждений (которые возвращают boolean ), метод assert возвращает object содержащий отчет. Когда предмет пройдет все правила, вы получите следующее:

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

Если элемент не прошел проверку, отчет будет содержать первое правило, которому он не соответствует, а также соответствующее сообщение об ошибке:

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

Множественные проверки товаров

Этот подход предпочтителен, когда вам нужно проверить несколько элементов на соответствие множеству различных правил проверки, например, при отправке формы, содержащей несколько полей.

Как и в случае с «проверкой одного элемента», вам следует вызвать метод assert , однако для обоих параметров вам необходимо будет предоставить object . Первый объект должен содержать элементы, подлежащие проверке, а второй должен состоять из правил для каждого элемента, например

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

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

Iodine . assert ( items , rules ) ;

В отличие от «проверок отдельных позиций», отчет немного отличается. Он содержит valid ключ верхнего уровня, который позволяет вам легко проверить, все ли прошло успешно или что-то не удалось. Затем он содержит ключ fields , который содержит вложенные отчеты для каждого элемента. Подотчет — это то же самое, что и при «проверке одного элемента». Вот отчет для примера кода, показанного выше:

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

Дополнительные параметры

Некоторые правила требуют дополнительных параметров, например

 let item_1 = 7 ;
let item_2 = 4 ;

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

Для расширенной проверки вы можете указать параметры, добавив их к правилу через точку с запятой, например

 let item_1 = 7 ;
let item_2 = 4 ;

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

Или, если хотите, вы можете указать правило в виде object а не string разделенной точкой с запятой:

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

Необязательные значения

Для расширенной проверки вы можете разрешить использование необязательных значений. Йод поддерживает это с помощью 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' ] ) ;

ВАЖНО : Если вы хотите разрешить необязательные значения, это должно быть первое правило в массиве.

Пользовательские ошибки

Iodine включает набор сообщений об ошибках по умолчанию для английского языка. Однако вы можете легко заменить их с помощью метода setErrorMessages . Для этого метода требуется один параметр, который представляет собой object содержащий сообщения. См. пример конструктора Iodine.

Йод автоматически заменит заполнители [FIELD] и [PARAM] при возникновении ошибки. Таким образом, вам следует вставить эти заполнители в соответствующую позицию в новом сообщении об ошибке, например

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

Одиночные ошибки

Во многих случаях вам не потребуется заменять все сообщения об ошибках. Вместо этого вы захотите обновить один или добавить новый. Для этого вам следует вместо этого вызвать setErrorMessage например

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

Пользовательские ошибки по полям

Иногда может потребоваться определить конкретное сообщение об ошибке для поля или вам нужна метка для поля, отличная от имени используемой переменной.

Для этого передайте объект методу assert , содержащему правило в качестве свойства и пользовательское сообщение об ошибке в качестве значения, например

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

Вы также можете использовать тот же подход для нескольких полей, например

 let items = {
    name : '' ,
} ;

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

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

Iodine . assert ( items , rules , errors ) ;

Имя поля по умолчанию

Поскольку «проверки отдельных элементов» не поддерживают имена полей, вместо этого Iodine использует значение по умолчанию (то есть «Значение»). Если «Значение» не подходит, вы можете вызвать метод setDefaultFieldName и указать альтернативное string значение для использования вместо него, например

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

Обратите внимание, что вы должны вызвать setDefaultFieldName перед вызовом assert .

Доступные правила

Доступны следующие правила проверки:

Правило	Струнный ключ	Описание
AssertAfter (дата/целое число)	'после'	Убедитесь, что элемент имеет Date после указанной Date или отметки времени.
AssertAfterOrEqual (дата/целое число)	'послеилиравный'	Убедитесь, что элемент имеет Date , следующую за заданной Date или меткой времени или равную ей.
AssertArray	'множество'	Убедитесь, что элемент является array
AssertBefore (дата/целое число)	'до'	Убедитесь, что элемент имеет Date до указанной Date или отметки времени.
AssertBeforeOrEqual (дата/целое число)	'beforeOrEqual'	Убедитесь, что элемент имеет Date предшествующую или равную заданной Date или метке времени.
AssertBoolean	'логическое'	Убедитесь, что элемент является либо true , либо false
утверждать дату	'дата'	Убедитесь, что элемент является объектом Date
AssertDifferent (значение)	'другой'	Убедитесь, что элемент отличается от предоставленного значения (используется свободное сравнение).
AssertEnds (значение)	'конец'	Убедитесь, что элемент заканчивается заданным значением
AssertEmail	'электронная почта'	Убедитесь, что элемент является действительным адресом электронной почты.
AssertFalsy	'ложный'	Убедитесь, что элемент имеет значение false , 'false' , 0 или '0'
утверждатьВ (массив)	'в'	Убедитесь, что элемент находится в данном array
AssertInteger	'целое'	Убедитесь, что элемент является integer
утверждатьJson	'json'	Убедитесь, что элемент представляет собой анализируемую string объекта JSON.
AssertMaxLength (ограничение)	'МаксДлина'	Убедитесь, что длина символов элемента не превышает заданный предел.
AssertMinLength (ограничение)	'минДлина'	Убедитесь, что длина символов элемента не превышает заданного предела.
утверждатьМакс (предел)	'макс'	Убедитесь, что числовое значение элемента не превышает заданный предел.
AssertMin (ограничение)	'мин'	Убедитесь, что числовое значение элемента не находится ниже заданного предела.
утверждатьNotIn (массив)	'не в'	Убедитесь, что элемент не находится в данном array
AssertNumeric	'числовой'	Убедитесь, что элемент является number или числовой string
утверждатьНеобязательно	'необязательный'	Разрешить необязательные значения (только для использования с несколькими проверками)
AssertRegexMatch(exp)	'regexMatch'	Убедитесь, что элемент удовлетворяет заданному регулярному выражению.
утверждатьтребуемый	'необходимый'	Убедитесь, что элемент не равен null , undefined или не является пустой string
AssertSame (значение)	'такой же'	Убедитесь, что элемент совпадает с предоставленным значением (используется свободное сравнение).
AssertStartsWith (значение)	'начинается с'	Убедитесь, что элемент начинается с заданного значения.
утверждатьстроку	'нить'	Убедитесь, что элемент является string
утверждатьИстинность	'правда'	Убедитесь, что элемент имеет значение true , 'true' , 1 или '1'
утверждать URL	'URL-адрес'	Убедитесь, что элемент является действительным URL-адресом.
утверждатьUuid	'uuid'	Убедитесь, что элемент имеет UUID

Изучите тесты на примерах использования каждого правила.

Пользовательские правила

Iodine позволяет вам добавлять свои собственные правила проверки с помощью метода rule . Этот метод принимает два параметра. Во-первых, это имя правила. Во-вторых, это closure , которое Iodine должен выполнить при вызове правила, например

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

ВАЖНО : Iodine автоматически преобразует первую букву названия правила в верхний регистр и добавляет к нему префикс «assert». Поэтому вам следует избегать самостоятельного добавления префикса, например

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

Если ваше правило должно принимать параметр, просто включите его в свое closure в качестве второго аргумента, например

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

Вы также можете добавить сообщения об ошибках для своих пользовательских правил, например

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

Асинхронные правила

Предыдущие версии Iodine поддерживали асинхронные пользовательские правила с использованием async / await . С тех пор это было удалено, чтобы упростить обслуживание библиотеки. Если вы использовали асинхронные правила, то предпочтительной стратегией будет сначала выполнить асинхронную логику, сохранить результат, а затем попросить Йода проверить его.

Содействие

Благодарим вас за рассмотрение вклада в Йод. Вы можете отправить заявку на участие, содержащую дополнительные правила, однако, чтобы ее приняли, она должна объяснять, что она делает, быть полезной для других и включать подходящий тест, подтверждающий ее правильную работу.

После извлечения проекта для установки зависимостей:

npm install

Чтобы запустить тесты

npm run test 

Лицензия

Лицензия MIT (MIT). Пожалуйста, смотрите файл лицензии для получения дополнительной информации.