validame is a javascript string validator that returns the error message.
-
🚀 Lightweight (12 kB packed and 53 kB unpacked). -
⚪️ Zero dependencies. -
🔧 Totally customizable. -
🧩 Modular. -
🌍 Multilanguage.
Table of contents
- Import
⬇️ - Basic examples
🔮 - Usage
🧭 - Rules
📏 - allow rule
🏳️ - allowOr rule
🏳️ - Symbols
✳️ - Language
🌍 - Editing symbols and rules
🧾 - Creating your own rules
⚗️ - Creating your own symbols
⚗️ - Advanced examples
🔮
⬇️
Import
const {validame} = require("validame");
🔮
Basic examples
let error = validame("Dog", {
min: 4,
});
// error = "It should have 4 minimum characters but it has 3."
let error = validame("Dog", {
min: 2,
max: 4
});
// error = ""
let error = validame("My name is Mike", {
allow: "1"
});
// error = "It's only allowed: numbers."
let error = validame("My name is Mike", {
allow: "a 1"
});
// error = "It's only allowed: lowercase and numbers."
let error = validame("My name is Mike", {
allow: "aA"
});
// error = "It's only allowed: letters."
let error = validame("My name is Mike", {
min: 4,
max: 16,
allow: "a A _"
});
// error = ""
🧭
Usage
Returns an empty string if the validation is correct, otherwise it returns an string explaining the error.
validame (stringToValidate, rules);
-
stringToValidate
string
: The string you want to validate. -
rules
object
: One or more rules, they are defined atvalidameConfig.rules
.
📏
Rules
{
// Minimum number of characters
min: 1,
// Maximum number of characters
max: 10,
// Exact number of characters
minMax: 5,
// 0: Empty string or null will return "" (OK).
// 1: Empty string will return "" (OK) but null will return an error.
// 2: Empty string OR null will return an error.
req: 1,
// (Explained below) Contains a list of symbols separated with a space.
allow: "a A _ 1",
allowOr: "dni cif",
// Should have 3 uppercase, 2 lowercase and 1 numbers.
password: [3, 2, 1],
// Pass the validation and skips the next steps if the string matches any word.
passWith: ["goodWordOne", "goodWordTwo"],
}
The rules will be checked in the same order they are listed, example:
{
min: 5, // first check (if it fails, it stops here)
max: 10 // second check
}
🏳️
allow rule
-
The allow rule reads a list of symbols (explained below).
-
The symbol list must be separated with spaces.
Example:
a A _ !
. -
The validations are done from left to right.
-
If one symbol fails it will return the error and stops the validation, otherwise the next symbol will be read.
- Example:
"a 1"
(lowercase and numbers) will fail with "Mike123" but pass with "mike123". - Example:
"costlessPrefixEs phoneEs"
will fail with "807456789" because "807" is a paid prefix.
- Example:
-
If the symbol list is filled with regex symbols, they all will be read because they can't fail. They make an "allowlist" and will only fail if there is a character outside that allowlist.
🏳️
allowOr rule
- Same mechanics than
allow
rule, but this one needs all symbols failing to return an error. - The returned error it's from the first failed symbol.
❌ It only works with function symbols, not regex.
✳️
Symbols
Each symbol is unique and has a regex or function associated.
-
Regex symbols:
Allow rule with regex symbols describes an allowlist. Examples:
-
allow: "a"
with"mike123"
will fail because numbers are not in the allowlist. -
allow: "a 1"
with"mike123"
will pass because there are no characters outside the allowlist. -
allow: "a 1"
with"mike"
will pass because there are no characters outside the allowlist. -
allow: "1 a"
with"mike"
will pass because there are no characters outside the allowlist.
-
a
:a-z
-
A
:A-Z
-
aA
:a-zA-Z
-
1
:0-9 (only integers)
-
2
:0-9 (integers or decimals)
-
_
:spaces
-
!
:ºª\!|"@·#€\$%&¬/()=?'¿¡^``\[+]´,{}-_<>~
-
ñ
:áéíóúñ
-
Ñ
:ÑÁÉÍÓÚ
-
ñÑ
:áéíóúñÑÁÉÍÓÚ
-
-
Function symbols:
-
phoneEs
: Spanish telephone number. -
mobileEs
: Spanish mobile number. -
dni
: Valid DNI (spain). -
cif
: Valid CIF (spain). -
ibanEs
: Spanish IBAN. -
email
: Email address. -
postalCodeEs
: Spanish postal code.
-
✅ If the symbols are regex, the error string is built automatically. Example, with"a 1"
the error string will be:It's only allowed: lowercase and numbers
🌍
Language
const {validameConfig} = require("validame");
validameConfig.language = "en";
It specifies the language of the errors given, default "es"
.
At the moment the possible options are:
es
en
But you can add your own language and translations.
🧾
Editing symbols and rules
const {validameConfig} = require("validame");
valiadmeConfig.symbols = {...};
valiadmeConfig.rules = {...};
➡️ symbols
property
They are used inside allow
rule. Example: allow: "aA 1"
(letters and numbers).
-
regex
regex | function
: Used when the symbol is called. -
messages
object
: Messages displayed and his translations.
Examples:
"a": {
regex: /[a-z]/g,
messages: {
name: {
es: "minúsculas",
en: "lowercase",
xx: "here could be placed your own translation",
}
},
}
"phoneEs": {
regex: require("./validations/symbols/phone").phoneEs,
messages: {
invalid: {
es: "No es un teléfono español válido",
en: "It isn't a valid spanish phone",
xx: "here could be placed your own translation",
},
digits: {
es: "Debe tener 9 dígitos",
en: "It must have 9 digits",
xx: "here could be placed your own translation",
}
},
}
➡️ rules
property
-
fnc
function
: Used when the rule is called. - The next properties are an
object
with the name of the error message for the rule:
Examples:
allow: {
fnc: require("./validations/rules/allow"),
messages: {
itsOnlyAllowed: {
es: "Sólo se permite: ",
en: "It's only allowed: ",
},
and: {
es: " y ",
en: " and ",
}
},
}
min: {
fnc: require("./validations/rules/min"),
messages: {
error: {
es: "Debería tener _%1 caracteres como mínimo pero tiene _%2.",
en: "It should have _%1 minimum characters but it has _%2.",
}
},
}
🔴 The_%1
_%2
(and so on) are replacers.
⚗️
Creating your own rules
// Import
const {validame, validameConfig, validameUtils} = require("validame");
const multiReplace = validameUtils.multiReplace;
// Create the function
const myCustomRule = (stringToValidate, value, config) => {
let upper = new RegExp(`[A-Z]{${value[0]}}`).test(stringToValidate);
let lower = new RegExp(`[a-z]{${value[1]}}`).test(stringToValidate);
if (!upper || !lower) {
// Create message using replacers
let errorMessage = multiReplace(config.rules.upperAndLower.messages.must[config.language], {
"_%1": value[0],
"_%2": value[1],
});
return errorMessage;
// Without multilanguage
return `It must have at least ${value[0]} uppercase and ${value[1]} lowercase characters`;
};
// All OK
return "";
};
// Create your custom rule
validameConfig.rules.upperAndLower = {
fnc: myCustomRule,
messages: {
must: {
es: "Tiene que tener al menos _%1 mayúsculas y _%2 minúsculas.",
en: "It must have at least _%1 uppercase and _%2 lowercase characters",
}
},
};
// And you can use it now:
let error1 = validame("mike", {
upperAndLower: [1, 2],
});
// error1 = "It must have at least 1 uppercase and 2 lowercase characters"
let error2 = validame("Mike", {
upperAndLower: [1, 2],
});
// error2 = ""
⚗️
Creating your own symbols
// Import
const {validame, validameConfig} = require("validame");
// Create the function
const myCustomSymbol = (stringToValidate, config) => {
// Get the over18 symbol config
const symbolMessages = config.symbols.over18.messages;
// Check if it's a number
let age = parseInt(stringToValidate);
if (isNaN(age)) return symbolMessages.number[config.language];
// Check if it's over 18
if (age < 18) return symbolMessages.over[config.language];
// All OK
return "";
};
// Create your custom symbol
validameConfig.symbols.over18 = {
regex: myCustomSymbol,
messages: {
number: {
es: "Tiene que ser un número",
en: "It must be a number",
},
over: {
es: "Tiene que ser mayor que 18",
en: "It must be over 18",
}
},
};
let error1 = validame("35", {
allow: "over18",
});
// error1 = ""
let error2 = validame("17", {
allow: "over18",
});
// error2 = "It must be over 18"
🔮
Advanced examples
let error = validame("Name SurnameOne SurnameTwo", {
min: 4,
max: 64,
allow: "a A _"
});
// error = ""
let error = validame("600123456", {
req: 1,
allow: "phoneEs"
});
// error = ""
let error = validame("", {
req: 1,
min: 4,
max: 64,
allow: "a A"
});
// error = "It can't be empty."
let error = validame("", {
req: 2,
min: 4,
max: 64,
allow: "a A"
});
// error = "It can't be empty."
let error = validame(null, {
req: 1,
min: 4,
max: 64,
allow: "a A"
});
// error = "It should have 4 minimum characters but it has 0."
let error = validame(null, {
req: 2,
min: 4,
max: 64,
allow: "a A"
});
// error = "It can't be empty."