Iodine.js is a micro client-side validation library. It has no dependencies and can be used in isolation or as part of a framework. Iodine also supports chainable rules, allowing you to verify that a piece of data satisifies multiple criteria.

The easiest way to pull Iodine into your project is via a CDN:

<script src="https://cdn.jsdelivr.net/gh/mattkingshott/iodine/dist/iodine.min.js" defer></script>

You can also pull Iodine into your project via NPM:

npm i @kingshott/iodine

Iodine is automatically added to the window namespace, making it available anywhere. This is the recommended way to use Iodine if your project does not involve compilation or imports.

Alternatively, if you are comfortable using imports, or your project uses a build tool, then you can import Iodine like so:

import { Iodine } from '@kingshott/iodine';

const iodine = new Iodine();

Iodine's rules are prefixed with the is keyword. So, to check if an item is an integer, you'd use the following code:

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

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

Single checks return a true or false value, indicating whether the item passed validation.

If you want to verify whether an item passes a set of rules, you can use the main is method. This method accepts two parameters. The first, is the item you want to check. The second, is an array of rules that should be run in sequence e.g.

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

Iodine.is(item_1, ['required', 'integer']); // true
Iodine.is(item_2, ['required', 'integer']); // string - 'integer'

The is method will return true if the item passes every rule.

If the item fails to validate, the first rule that it failed to satisfy will be returned e.g. 'integer'.

Version 1 of Iodine only returned the rule name e.g. 'minimum'. Version 2+ returns the rule name and any supplied parameter e.g. 'minimum:7'.

If you want to know whether the value has passed the validation checks and don't care about which rule failed (if any), in other words you want the result purely as a boolean, then you can use the isValid helper method:

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

Iodine.isValid(item_1, ['required', 'integer']); // true
Iodine.isValid(item_2, ['required', 'integer']); // false

Some rules require extra parameters e.g.

let item_1 = 7;
let item_2 = 4;

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

For multiple checks, you can supply the parameters by appending them to the rule with a semicolon separator e.g.

let item_1 = 7;
let item_2 = 4;

Iodine.is(item_1, ['required', 'integer', 'min:5']); // true
Iodine.is(item_2, ['required', 'integer', 'min:5']); // string - 'min:5'

When performing multiple checks, you may wish to allow for optional values. Iodine supports this with the optional rule:

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

Iodine.is(item_1, ['optional', 'integer']); // true
Iodine.is(item_2, ['optional', 'integer']); // true
Iodine.is(item_3, ['optional', 'integer']); // string - 'integer'

IMPORTANT: If you wish to allow for optional values, then you must supply 'optional' as the first rule in the list.

Iodine includes a default set of error messages for the English language. To retrieve an error message for a rule, use the getErrorMessage method:

Iodine.getErrorMessage('array'); // string

When dealing with rules that have parameters, the getErrorMessage method allows you to supply the rule either as a combined string or as two arguments (the rule and parameter) e.g.

Iodine.getErrorMessage('min:7');  // string
Iodine.getErrorMessage('min', 7); // string

If you want the field name to appear within the error message, you can pass an object as the second parameter to the getErrorMessage method.

Iodine.getErrorMessage('min:7', { field: ''}); // string
Iodine.getErrorMessage('min', { field: '', param: 7}); // string

You can easily replace the default error messages with your own via the setErrorMessages method. This method requires a single parameter, which is an object containing the messages. See the _defaultMessages method for an example of this.

Iodine will automatically swap the [FIELD] and [PARAM] placeholders with the parameters supplied in the getErrorMessage method. As such, you should insert this placeholder at the appropriate position in your new error message e.g.

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

If no field name is provided when calling getErrorMessage, by default it will be replaced with "Value". You can change this by calling setDefaultFieldName

Iodine.setDefaultFieldName('Valeur');

You can also add or update a single error

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

The following validation rules are available:

Examine the tests for examples of how to use each rule.

The following rules are deprecated and should not be used:

Iodine allows you to add your own custom validation rules through the addRule method. This method excepts two parameters. The first, is the name of the rule. The second, is the closure that Iodine should execute when calling the rule e.g.

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

IMPORTANT: Iodine will automatically make the first letter of the rule's name uppercase and prefix it with 'is'. You should therefore avoid adding the prefix yourself e.g.

Iodine.addRule('lowerCase');   // correct
Iodine.addRule('isLowerCase'); // wrong

If your rule needs to accept a parameter, simply include it in your closure as the second argument e.g.

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

You can also add error messages for your custom rules e.g.

Iodine.addRule('equals', (value, param) => value == param);
Iodine.setErrorMessages({ equals : `[FIELD] must be equal to '[PARAM]'` });

Thank you for considering a contribution to Iodine. You are welcome to submit a PR containing additional rules, however to be accepted, they must explain what they do, be useful to others, and include a suitable test to confirm they work correctly.

After pulling the project, to install the dependencies:

npm install

To run the tests

npm run test

If you'd like to support the development of Iodine, then please consider sponsoring me. Thanks so much!

The MIT License (MIT). Please see License File for more information.