iodine

Yodo

Iodine.js es una biblioteca de validación del lado del micro cliente. No tiene dependencias y se puede utilizar de forma aislada o como parte de un marco. Iodine también admite reglas encadenables, lo que le permite verificar que uno o varios datos satisfacen múltiples criterios.

Actualización

La versión 8+ de Iodine implicó una reescritura importante con numerosos cambios importantes. Por lo tanto, se recomienda que los proyectos existentes sigan usando la versión 7 (o inferior), mientras que la versión 8 (o superior) debería reservarse para proyectos más nuevos.

Instalación

La forma más sencilla de incorporar Iodine a su proyecto es a través de una CDN (asegúrese de actualizar el número de compilación):

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

También puedes incorporar yodo a tu proyecto a través de NPM:

 npm i @ caneara / iodine 

Uso

El yodo se agrega automáticamente al espacio de nombres window , haciéndolo disponible en cualquier lugar. Esta es la forma recomendada de utilizar Iodine si su proyecto no implica compilación ni importaciones. Incluso si su proyecto implica compilación, a menudo es más fácil usar simplemente la instancia agregada al espacio de nombres window .

Alternativamente, si se siente cómodo usando importaciones o desea crear su propia instancia, puede importar Iodine de esta manera:

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

Validación básica

Iodine incluye un montón de reglas de validación a las que puede acceder a través de sus métodos asociados. Esto hace que sea rápido y fácil comprobar si un elemento es, por ejemplo, un número entero o una fecha.

Las reglas de yodo tienen el prefijo assert . Entonces, para verificar si un elemento es un integer , usarías el siguiente código:

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

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

Consulte a continuación una lista completa de las reglas de validación incluidas en Iodine.

Validación avanzada

Si bien puede resultar útil comprobar si un elemento se ajusta a una regla de validación individual, a menudo querrás comprobar si un elemento se ajusta a varias reglas. Por ejemplo, es posible que se requiera una dirección de correo electrónico, que debe ser una cadena y debe satisfacer una expresión regular de dirección de correo electrónico.

Para abordar estas necesidades, Iodine ofrece 'verificaciones de artículos individuales' y 'verificaciones de artículos múltiples'...

Verificaciones de artículos individuales

Se prefiere este enfoque si tiene un elemento que necesita probar con varias reglas (como el ejemplo de dirección de correo electrónico descrito anteriormente). Para realizar una 'verificación de un solo elemento', llame al método assert principal. El método toma dos parámetros. El primero es el elemento a comprobar. El segundo es una array de reglas de validación que deben ejecutarse en secuencia, por ejemplo

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

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

Como puedes ver en el ejemplo, las reglas de validación se expresan mediante strings . Para encontrar la representación string para una regla de validación, revise la lista existente.

A diferencia de las afirmaciones individuales (que devuelven un boolean ), el método assert devuelve un object que contiene un informe. Cuando el artículo pase todas las reglas, obtendrás esto:

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

Si el elemento no se valida, el informe contendrá la primera regla que no cumplió, junto con el mensaje de error asociado:

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

Verificaciones de artículos múltiples

Se prefiere este enfoque cuando necesita comparar varios elementos con un conjunto de reglas de validación diferentes, por ejemplo, al enviar un formulario que contiene varios campos.

Al igual que con las 'verificaciones de un solo elemento', debe llamar al método assert ; sin embargo, para ambos parámetros, deberá proporcionar un object . El primer objeto debe contener los elementos que se van a validar, mientras que el segundo debe consistir en las reglas para cada elemento, por ejemplo.

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

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

Iodine . assert ( items , rules ) ;

A diferencia de los "controles de elementos individuales", el informe es ligeramente diferente. Contiene una clave valid de nivel superior que le permite verificar fácilmente si todo pasó o si algo falló. Luego contiene una clave fields , que contiene subinformes para cada elemento. El subinforme es el mismo que obtendría para una "verificación de un solo artículo". Aquí está el informe del ejemplo de código que se muestra arriba:

 {
    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 adicionales

Algunas reglas requieren parámetros adicionales, por ejemplo

 let item_1 = 7 ;
let item_2 = 4 ;

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

Para una validación avanzada, puede proporcionar los parámetros agregándolos a la regla con un separador de punto y coma, por ejemplo.

 let item_1 = 7 ;
let item_2 = 4 ;

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

O, si lo prefiere, puede proporcionar la regla como un object en lugar de una string separada por un punto y coma:

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

Valores opcionales

Para una validación avanzada, es posible que desee permitir valores opcionales. Yodo apoya esto con la regla 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 : si desea permitir valores opcionales, debe ser la primera regla de la matriz.

Errores personalizados

Yodo incluye un conjunto predeterminado de mensajes de error para el idioma inglés. Sin embargo, puede reemplazarlos fácilmente mediante el método setErrorMessages . Este método requiere un único parámetro, que es un object que contiene los mensajes. Vea el constructor de yodo para ver un ejemplo.

Yodo reemplazará automáticamente los marcadores de posición [FIELD] y [PARAM] cuando ocurra un error. Como tal, debe insertar estos marcadores de posición en la posición adecuada en su nuevo mensaje de error, por ejemplo

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

Errores únicos

En muchos casos, no será necesario reemplazar todos los mensajes de error. En su lugar, querrás actualizar uno o agregar uno nuevo. Para hacer eso, deberías llamar setErrorMessage por ejemplo

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

Errores personalizados por campo

A veces, puede ser necesario definir un mensaje de error específico para un campo, o necesitar una etiqueta para un campo que sea diferente al nombre de la variable utilizada.

Para lograr esto, pase un objeto al método assert que contenga la regla como propiedad y el mensaje de error personalizado como valor, por ejemplo.

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

También puede utilizar el mismo enfoque para varios campos, por ejemplo

 let items = {
    name : '' ,
} ;

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

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

Iodine . assert ( items , rules , errors ) ;

Nombre de campo predeterminado

Dado que las 'verificaciones de elementos individuales' no admiten nombres de campos, Iodine usa el valor predeterminado (que es 'Valor'). Si 'Valor' no es adecuado, puede llamar al método setDefaultFieldName y proporcionar un valor string alternativo para usar en su lugar, por ejemplo.

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

Tenga en cuenta que debe llamar setDefaultFieldName antes de llamar assert .

Reglas disponibles

Están disponibles las siguientes reglas de validación:

Regla	Clave de cadena	Descripción
afirmarDespués(fecha/entero)	'después'	Verifique que el artículo sea una Date posterior a una Date o marca de tiempo determinada
afirmarDespuésOrEqual(fecha/entero)	'despuésOrEqual'	Verifique que el artículo sea una Date posterior o igual a una Date o marca de tiempo determinada
afirmarmatriz	'formación'	Verifique que el elemento sea una array
afirmar antes (fecha/entero)	'antes'	Verifique que el elemento sea una Date anterior a una Date o marca de tiempo determinada
afirmarBeforeOrEqual(fecha/entero)	'antesOIgual'	Verifique que el elemento sea una Date anterior o igual a una Date o marca de tiempo determinada
afirmar booleano	'booleano'	Verifique que el elemento sea true o false
afirmar fecha	'fecha'	Verificar que el elemento sea un objeto Date
afirmarDiferente(valor)	'diferente'	Verifique que el artículo sea diferente al valor suministrado (usa comparación suelta)
afirmar termina (valor)	'termina'	Verificar que el artículo termine con el valor dado
afirmarCorreo electrónico	'correo electrónico'	Verifique que el artículo sea una dirección de correo electrónico válida
afirmarFalso	'falso'	Verifique que el elemento sea false , 'false' , 0 o '0'
afirmar en (matriz)	'en'	Verifique que el artículo esté dentro de la array dada
afirmarEntero	'entero'	Verificar que el elemento sea un integer
afirmarJson	'json'	Verifique que el elemento sea una string de objeto JSON analizable
afirmarMaxLength(límite)	'longitudmax'	Verifique que la longitud de caracteres del elemento no exceda el límite dado
afirmarMinLength(límite)	'minLongitud'	Verifique que la longitud de caracteres del elemento no esté por debajo del límite dado
afirmarMax(límite)	'máximo'	Verificar que el valor numérico del artículo no exceda el límite dado
afirmarMin(límite)	'mínimo'	Verifique que el valor numérico del artículo no esté por debajo del límite dado
afirmarNotIn (matriz)	'no estoy'	Verifique que el elemento no esté dentro de la array dada
afirmarNumérico	'numérico'	Verifique que el elemento sea number o una string numérica
afirmarOpcional	'opcional'	Permitir valores opcionales (solo para uso con cheques múltiples)
afirmarRegexMatch(exp)	'partido de expresiones regulares'	Verifique que el elemento satisfaga la expresión regular dada
afirmarRequerido	'requerido'	Verifique que el elemento no sea null , undefined o una string vacía
afirmarMismo(valor)	'mismo'	Verifique que el artículo sea el mismo que el valor suministrado (usa comparación suelta)
afirmarComienza con (valor)	'comienza con'	Verifique que el artículo comience con el valor dado
afirmar cadena	'cadena'	Verificar que el elemento sea una string
afirmar la verdad	'verdad'	Verifique que el elemento sea true , 'true' , 1 o '1'
afirmar URL	'URL'	Verifique que el elemento sea una URL válida
afirmarUuid	'uuido'	Verifique que el elemento sea un UUID

Examine las pruebas para ver ejemplos de cómo usar cada regla.

Reglas personalizadas

Iodine le permite agregar sus propias reglas de validación personalizadas a través del método rule . Este método acepta dos parámetros. El primero es el nombre de la regla. El segundo es el closure que Iodine debe ejecutar al llamar a la regla, por ejemplo.

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

IMPORTANTE : Iodine automáticamente pondrá en mayúscula la primera letra del nombre de la regla y le agregará el prefijo "asertar". Por lo tanto, deberías evitar añadir el prefijo tú mismo, por ejemplo

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

Si su regla necesita aceptar un parámetro, simplemente inclúyalo en su closure como segundo argumento, por ejemplo

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

También puede agregar mensajes de error para sus reglas personalizadas, por ejemplo

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

Reglas asincrónicas

Las versiones anteriores de Iodine admitían reglas personalizadas asincrónicas mediante async / await . Desde entonces, esto se ha eliminado para facilitar el mantenimiento de la biblioteca. Si estaba usando reglas asincrónicas, entonces la estrategia preferida es ejecutar primero la lógica asincrónica, almacenar el resultado y luego hacer que Iodine lo valide.

Contribuyendo

Gracias por considerar una contribución a Yodo. Le invitamos a enviar un PR que contenga reglas adicionales; sin embargo, para ser aceptado, deben explicar lo que hacen, ser útiles para los demás e incluir una prueba adecuada para confirmar que funcionan correctamente.

Después de tirar el proyecto, para instalar las dependencias:

npm install

Para ejecutar las pruebas

npm run test 

Licencia

La Licencia MIT (MIT). Consulte el archivo de licencia para obtener más información.