README

validame

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.

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 at validameConfig.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.
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."

validame

Usage no npm install needed!

README

validame

Table of contents

Import ⬇️

Basic examples 🔮

Usage 🧭

Rules 📏

allow rule 🏳️

allowOr rule 🏳️

Symbols ✳️

Language 🌍

Editing symbols and rules 🧾

➡️ `symbols` property

➡️ `rules` property

Creating your own rules ⚗️

Creating your own symbols ⚗️

Advanced examples 🔮

⏫

Usage no npm install needed!

README

validame

Table of contents

Import ⬇️

Basic examples 🔮

Usage 🧭

Rules 📏

allow rule 🏳️

allowOr rule 🏳️

Symbols ✳️

Language 🌍

Editing symbols and rules 🧾

➡️ symbols property

➡️ rules property

Creating your own rules ⚗️

Creating your own symbols ⚗️

Advanced examples 🔮

⏫

➡️ `symbols` property

➡️ `rules` property