🔌 S’intègre naturellement à vos projets, qu’ils soient front-end ou back-end, et permet de définir des schémas de manière intuitive tout en favorisant leur réutilisation.
💡 Pensée pour allier simplicité et puissance, elle propose des fonctionnalités avancées comme l’inférence de types, ainsi que des validateurs standards tels que isEmail, isUuid ou isIp.
> npm install valia
import { Schema } from 'valia';
const userSchema = new Schema({
type: "object",
shape: {
name: { type: "string" },
role: {
type: "string",
literal: ["WORKER", "CUSTOMER"]
}
}
});
let data = {
name: "Alice",
role: "WORKER"
};
if (userSchema.validate(data)) {
console.log(data.name, data.role);
}
import type { SchemaInfer } from 'valia';
type User = SchemaInfer<typeof userSchema>;
-
criteria
Propriété représentant la racine des noeuds de critères. -
validate(data)
Methode qui valide les données fournies selon les critères et retourne un booléen.
Cette méthode utilise la prédiction de types ↗. -
evaluate(data)
Methode qui valide les données fournies selon les critères et retourne un objet avec les propriétés suivantes :- success: Un boolean qui indique si la validation a réussi.
- rejection: Instance de SchemaDataRejection si les données sont rejetées sinon null.
- admission: Instance de SchemaDataAdmission si les données sont admises sinon null.
-
message
Message décrivant le problème rencontré.
-
code
Code de l'exception. -
message
Message décrivant le problème rencontré. -
node
Noeud noeud lié à l'exception. -
nodePath
Chemin du noeud noeud lié à l'exception.
- explicit: Tableau représentant le chemin vers le noeud dans l'arbre des critères.
- implicit: Tableau représentant le chemin virtuel vers les données représentées par noeud.
-
rootData
Racine des données à valider. -
rootNode
Noeud racine utilisé pour la validation. -
rootLabel
Label du noeud racine utilisé pour la validation ou undefined si le label n'a pas été défini. -
data
Données rejetées. -
code
Code lié au rejet. -
node
Noeud lié au rejet. -
nodePath
Chemin du noeud noeud lié au rejet.- explicit: Tableau représentant le chemin vers le noeud dans l'arbre des critères.
- implicit: Tableau représentant le chemin virtuel vers les données représentées par noeud.
-
label
Label défini sur le noeud lié au rejet ou undefined si le label n'a pas été défini. -
message
Message défini sur le noeud lié au rejet ou undefined si le message n'a pas été défini.
-
data
Racine des données valider. -
node
Noeud racine utilisé pour la validation. -
label
Label du noeud racine utilisé pour la validation ou undefined si le label n'a pas été défini.
Number • String • Boolean • Object • Array • Function • Symbol • Union • Null • Undefined
Les formats représentent les noeuds de critères qui pourront être utilisés dans les schémas.
L'ordre des propriétés décrites pour chaque formats respecte l'ordre de validation.
-
label?
Une chaine de caratéres permetant d'idantifié le noeud, celle-ci vous sera retournée dans les instance de SchemaDataRejection et SchemaNodeException. -
message?
- string: Chaîne de caractères qui sera disponible dans l'instance de SchemaDataRejection.
- function: Fonction qui doit renvoyer une chaîne de caractères qui sera disponible dans l'instance de SchemaDataRejection.
- type: "number"
-
min?
Nombre minimale. -
max?
Nombre maximale. -
literal?
- string: Restreint la valeur à une seul nombre valide.
- array: Restreint la valeur avec un tableau dont les items représentent les nombres valides.
- object: Restreint la valeur avec un objet dont les valeurs représentent les nombres valides.
-
custom(value)?
Fonction de validation custom qui reçoit la valeur en paramètre et doit renvoyer un booléen indiquant si la celle-ci est valide.
Validé n'importe quel nombre
const schema = new Schema({
type: "number"
});
✅ schema.validate(0);
✅ schema.validate(10);
✅ schema.validate(-10);
Valide des nombres qui appartiennent à une plage spécifique
const schema = new Schema({
type: "number",
min: 0,
max: 10
});
✅ schema.validate(0);
✅ schema.validate(10);
❌ schema.validate(-1);
❌ schema.validate(-10);
Validé un nombre spécifique
const schema = new Schema({
type: "number",
literal: 141
});
✅ schema.validate(141);
❌ schema.validate(-1);
❌ schema.validate(-10);
Validé des nombres spécifique avec un tableau
const schema = new Schema({
type: "number",
literal: [141, 282]
});
✅ schema.validate(141);
✅ schema.validate(282);
❌ schema.validate(0);
❌ schema.validate(100);
❌ schema.validate(200);
- type: "string"
-
min?
Longueur minimale de la chaîne de caractères. -
max?
Longueur maximale de la chaîne de caractères. -
regex?
Une expression régulière fournie sous forme d'objet (RegExp). -
literal?
- string: Restreint la valeur à une seul chaîne de caractères valides.
- array: Restreint la valeur avec un tableau où les items représentent les chaîne de caractères valides.
- object: Restreint la valeur avec un objet où les valeurs représentent les chaîne de caractères valides.
-
constraint?
Un objet dont les clés correspondent à des noms de testeurs de chaîne et dont les valeurs possible sont :- boolean : active ou désactive le testeur.
- objet : le testeur est activé avec les options spécifiés dans l'objet.
-
custom(value)?
Fonction de validation custom qui reçoit la valeur en paramètre et doit renvoyer un booléen indiquant si la celle-ci est valide.
Validé n'importe quel chaîne de caractères
const schema = new Schema({
type: "string"
});
✅ schema.validate("");
✅ schema.validate("abc");
Validé des chaînes de caractères ayant une longueur spécifique
const schema = new Schema({
type: "string",
min: 3,
max: 3
});
✅ schema.validate("abc");
❌ schema.validate("");
❌ schema.validate("a");
❌ schema.validate("abcd");
Validé des chaînes de caractères avec une expression régulière
const schema = new Schema({
type: "string",
regex: /^#[a-fA-F0-9]{6}$/
});
✅ schema.validate("#000000");
✅ schema.validate("#FFFFFF");
❌ schema.validate("");
❌ schema.validate("#000");
❌ schema.validate("#FFF");
Validé une chaîne de caractères spécifique
const schema = new Schema({
type: "string",
literal: "ABC"
});
✅ schema.validate("ABC");
❌ schema.validate("");
❌ schema.validate("a");
❌ schema.validate("abc");
Validé des chaînes de caractères spécifique avec un tableau
const schema = new Schema({
type: "string",
literal: ["ABC", "XYZ"]
});
✅ schema.validate("ABC");
✅ schema.validate("XYZ");
❌ schema.validate("");
❌ schema.validate("a");
❌ schema.validate("abc");
Validé des chaînes de caractères avec un testeur de chaîne
const schema = new Schema({
type: "string",
constraint: {
idIp: { cidr: true }
}
});
✅ schema.validate("127.0.0.1/24");
❌ schema.validate("");
❌ schema.validate("127.0.0.1");
Validé des chaînes de caractères avec plusieurs testeurs de chaîne
const schema = new Schema({
type: "string",
constraint: {
isEmail: true,
idIp: { cidr: true }
}
});
✅ schema.validate("foo@bar");
✅ schema.validate("127.0.0.1/24");
❌ schema.validate("");
❌ schema.validate("foo@");
❌ schema.validate("127.0.0.1");
- type: "boolean"
-
literal?
Restreint la valeur à un seul état de booléen valide. -
custom(value)?
Fonction de validation custom qui reçoit la valeur en paramètre et doit renvoyer un booléen indiquant si la celle-ci est valide.
Validé n'importe quel booléen
const schema = new Schema({
type: "boolean"
});
✅ schema.validate(true);
✅ schema.validate(false);
❌ schema.validate("");
❌ schema.validate({});
Validé un booléen avec un état spécifique
const schema = new Schema({
type: "boolean",
literal: true
});
✅ schema.validate(true);
❌ schema.validate("");
❌ schema.validate({});
❌ schema.validate(false);
- type: "object"
-
nature? — (Default: "STANDARD")
- "STANDARD": Accepte toute valeur de type object, c’est-à-dire tout ce pour quoi typeof value === "object".
- "PLAIN": Accepte uniquement les objets dont le prototype est soit Object.prototype (comme les objets créés via {}), soit null (créés via Object.create(null)).
-
min?
Nombre de propriétés minimum. -
max?
Nombre de propriétés maximun. -
shape?
Un objet dont les clés sont de type string ou symbol et dont les valeurs sont des noeuds de critères. Représente des propriétés fixes que l'objet doit satisfaire. -
optional? — (Default: false | Utilisable seulement si shape est défini)
-
boolean
- true: Toutes les propriétés définies dans l'objet shape sont optionnelles.
- false: Toutes les propriétés définies dans l'objet shape sont obligatoires.
-
array
Un tableau dont les éléments sont des clés de l’objet shape qui sont optionnelles.
-
boolean
-
keys?
Noeud de critères que les clés de l'objet doivent satisfaire.
Les clés définies dans l'objet shape ne sont pas affectées. -
values?
Noeud de critères que les valeurs doivent satisfaire.
Les valeurs définies dans l'objet shape ne sont pas affectées.
Validé n'importe quel objet
const schema = new Schema({
type: "object"
});
✅ schema.validate({});
✅ schema.validate([]);
✅ schema.validate(new Date());
✅ schema.validate(Object.create(null));
❌ schema.validate("");
Validé un objet de nature simple
const schema = new Schema({
type: "object",
nature: "PLAIN"
});
✅ schema.validate({});
✅ schema.validate(Object.create(null));
❌ schema.validate("");
❌ schema.validate([]);
❌ schema.validate(new Date());
Validé un objet avec des propriétés fixes
const schema = new Schema({
type: "object",
shape: {
foo: { type: "string" },
bar: { type: "string" }
}
});
✅ schema.validate({ foo: "x", bar: "x" });
❌ schema.validate({});
❌ schema.validate({ foo: "x" });
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", a: "" });
Validé un objet et un sous-objet de propriétés fixes
const schema = new Schema({
type: "object",
shape: {
foo: { type: "string" },
bar: { type: "string" },
baz: {
foo: { type: "number" },
bar: { type: "number" }
}
}
});
✅ schema.validate({ foo: "x", bar: "x", baz: { foo: 0, bar: 0 } });
❌ schema.validate({});
❌ schema.validate({ foo: "x" });
❌ schema.validate({ foo: "x", bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", baz: {} });
❌ schema.validate({ foo: "x", bar: "x", baz: { foo: 0 } });
Validé un objet avec des propriétés facultatives
const schema = new Schema({
type: "object",
shape: {
foo: { type: "string" },
bar: { type: "string" }
},
optional: true
});
✅ schema.validate({});
✅ schema.validate({ foo: "x" });
✅ schema.validate({ bar: "x" });
✅ schema.validate({ foo: "x", bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", a: "x" });
Validé un objet avec une propriété fixe et une propriété facultative
const schema = new Schema({
type: "object",
shape: {
foo: { type: "string" },
bar: { type: "string" }
},
optional: ["bar"]
});
✅ schema.validate({ foo: "x" });
✅ schema.validate({ foo: "x", bar: "x" });
❌ schema.validate({});
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", a: "x" });
Validé un objet avec des propriétés fixes et des propriétés dynamiques libres
const schema = new Schema({
type: "object",
shape: {
foo: { type: "string" },
bar: { type: "string" }
},
values: { type: "unknown" }
});
✅ schema.validate({ foo: "x", bar: "x" });
✅ schema.validate({ foo: "x", bar: "x", a: "x", b: 0 });
❌ schema.validate({});
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x" });
Validé un objet avec des propriétés fixes et des propriétés dynamiques contraintes
const schema = new Schema({
type: "object",
shape: {
foo: { type: "string" },
bar: { type: "string" }
},
keys: { type: "string" },
values: { type: "number" }
});
✅ schema.validate({ foo: "x", bar: "x" });
✅ schema.validate({ foo: "x", bar: "x", a: 0 });
✅ schema.validate({ foo: "x", bar: "x", a: 0, b: 0 });
❌ schema.validate({});
❌ schema.validate({ foo: "x" });
❌ schema.validate({ bar: "x" });
❌ schema.validate({ foo: "x", bar: "x", a: "x", b: 0 });
Validé un objet avec des propriétés dynamiques contraintes
const schema = new Schema({
type: "object",
keys: { type: "string" },
values: { type: "string" }
});
✅ schema.validate({});
✅ schema.validate({ a: "x" });
✅ schema.validate({ a: "x", b: "x" });
❌ schema.validate({ a: 0 });
❌ schema.validate({ a: "x", b: 0 });
- type: "array"
-
min?
Nombre d'éléments minimum. -
max?
Nombre d'éléments maximum. -
tuple?
Un tableau dont les éléments sont des noeuds de critères. Représente les éléments fixes que le tableau doit satisfaire. -
items?
Noeud de critères que les éléments du tableau doivent satisfaire.
Les éléments définies dans le tableau tuple ne sont pas affectées.
Validé n'importe quel tableau
const schema = new Schema({
type: "array"
});
✅ schema.validate([]);
✅ schema.validate(["x"]);
❌ schema.validate({});
❌ schema.validate("x");
Validé un tableau d'éléments fixes
const schema = new Schema({
type: "array",
tuple: [
{ type: "string" },
{ type: "string" }
]
});
✅ schema.validate(["x", "x"]);
❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate(["x", "x", "x"]);
Validé un tableau et un sous-tableau d'éléments fixes
const schema = new Schema({
type: "array",
tuple: [
{ type: "string" },
{ type: "string" },
[
{ type: "number" },
{ type: "number" }
]
]
});
✅ schema.validate(["x", "x", [0, 0]]);
❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate(["x", "x", []]);
❌ schema.validate(["x", "x", [0]]);
Validé un tableau d'éléments fixes et des éléments dynamiques libres
const schema = new Schema({
type: "array",
tuple: [
{ type: "string" },
{ type: "string" }
],
items: { type: "unknown" }
});
✅ schema.validate(["x", "x"]);
✅ schema.validate(["x", "x", 0]);
✅ schema.validate(["x", "x", ""]);
✅ schema.validate(["x", "x", {}]);
❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate([0, "x"]);
Validé un tableau d'éléments fixes et des éléments dynamiques contraints
const schema = new Schema({
type: "array",
tuple: [
{ type: "string" },
{ type: "string" }
],
items: { type: "number" }
});
✅ schema.validate(["x"]);
✅ schema.validate(["x", "x"]);
✅ schema.validate(["x", "x", 0]);
✅ schema.validate(["x", "x", 0, 0]);
❌ schema.validate([]);
❌ schema.validate(["x"]);
❌ schema.validate(["x", "x", "x"]);
❌ schema.validate(["x", "x", "x", "x"]);
Validé un tableau avec éléments dynamiques contraints
const schema = new Schema({
type: "array",
items: { type: "string" }
});
✅ schema.validate([]);
✅ schema.validate(["x"]);
✅ schema.validate(["x", "x"]);
❌ schema.validate([0]);
❌ schema.validate(["x", 0]);
❌ schema.validate(["x", "x", 0]);
- type: "symbol"
-
literal?
- symbol: Restreint la valeur à un seul symbole valide.
- array: Restreint la valeur avec un tableau où les items représentent les symboles valides.
- object: Restreint la valeur avec un objet où les valeurs représentent les symboles valides.
-
custom(value)?
Fonction de validation custom qui reçoit la valeur en paramètre et doit renvoyer un booléen indiquant si la celle-ci est valide.
Validé n'importe quel symbole
const xSymbol = Symbol("x");
const ySymbol = Symbol("y");
const schema = new Schema({
type: "symbol"
});
✅ schema.validate(xSymbol);
✅ schema.validate(ySymbol);
Validé un symbole spécifique
const xSymbol = Symbol("x");
const ySymbol = Symbol("y");
const schema = new Schema({
type: "symbol",
literal: xSymbol
});
✅ schema.validate(xSymbol);
❌ schema.validate(ySymbol);
Validé des symboles spécifiques avec un tableau
const xSymbol = Symbol("x");
const ySymbol = Symbol("y");
const zSymbol = Symbol("z");
const schema = new Schema({
type: "symbol",
literal: [xSymbol, ySymbol]
});
✅ schema.validate(xSymbol);
✅ schema.validate(ySymbol);
❌ schema.validate(zSymbol);
Validé des symboles spécifiques avec un enum
enum mySymbol {
X = Symbol("x"),
Y = Symbol("y")
};
enum otherSymbol {
Z = Symbol("z")
};
const schema = new Schema({
type: "symbol",
literal: mySymbol
});
✅ schema.validate(mySymbol.X);
✅ schema.validate(mySymbol.Y);
❌ schema.validate(otherSymbol.Z);
-
union
Un tableau de noeuds de critères, où chaque noeud définit une valeur acceptable.
Une valeur est considérée comme valide si elle correspond à au moins un des noeuds de critères fournis.
const schema = new Schema({
type: "union",
union: [
{ type: "string" },
{ type: "number" }
]
});
✅ schema.validate(0);
✅ schema.validate("");
❌ schema.validate({});
- type: "null"
const schema = new Schema({
type: "null"
});
✅ schema.validate(null);
❌ schema.validate(0);
❌ schema.validate("");
❌ schema.validate({});
- type: "undefined"
const schema = new Schema({
type: "undefined"
});
✅ schema.validate(undefined);
❌ schema.validate(0);
❌ schema.validate("");
❌ schema.validate({});
const user = new Schema({
type: "object",
shape: {
name: {
type: "string",
min: 3,
max: 32
},
role: {
type: "string",
literal: ["WORKER", "CUSTOMER"]
}
}
});
✅ user.validate({
name: "Alice",
role: "WORKER"
});
❌ user.validate({
name: "Alice",
role: "MANAGER"
});
const name = new Schema({
type: "string",
min: 3,
max: 32
});
const role = new Schema({
type: "string",
literal: ["WORKER", "CUSTOMER"]
});
const user = new Schema({
type: "object",
shape: {
name: name.criteria,
role: role.criteria
}
});
✅ user.validate({
name: "Bob",
role: "CUSTOMER"
});
❌ user.validate({
name: "Bob",
role: "MANAGER"
});
const name = new Schema({
type: "string",
min: 3,
max: 32
});
const setting = new Schema({
type: "object",
shape: {
theme: {
type: "string",
literal: ["DARK", "LIGHT"]
},
notification: { type: "boolean" }
}
});
const user = new Schema({
type: "object",
object: {
name: name.criteria,
theme: setting.criteria.shape.theme
}
});
✅ user.validate({
name: "Alice",
theme: "DARK"
});
❌ user.validate({
name: "Alice",
theme: "DEFAULT"
});
Vérifie si la valeur fournie est de type object.
Vérifie si la valeur fournie est de type object et dont le prototype est soit Object.prototype, soit null.
Par exemple les valeurs créées via le littérale {} ou via Object.create(null) font partie des valeurs acceptées.
Vérifie si la valeur fournie est de type array.
Vérifie si la valeur fournie est de type array et si elle est une vue sur un ArrayBuffer, à l’exception des DataView.
Vérifie si la valeur fournie est de type function.
Vérifie si la valeur fournie est de type function et qu'elle n'est pas de nature async, generator ou async generator.
Vérifie si la valeur fournie est de type function et qu'elle n'est pas de nature basic, generator ou async generator.
Vérifie si la valeur fournie est de type function et qu'elle n'est pas de nature basic, async ou async generator.
Vérifie si la valeur fournie est de type function et qu'elle n'est pas de nature basic, async ou generator.
Vérifie si la chaîne fournie n'est composée que de caractères ASCII.
Vérifie si la chaîne fournie correspond à une IPV4.
Vérifie si la chaîne fournie correspond à une IPV6.
Vérifie si la chaîne fournie correspond à une IPV4 ou une IPV6.
Options:
-
cidr? — (Default: false)
Si true, rend obligatoire la présence d'un suffixe CIDR, sinon si false un suffixe n'est pas accepté.
Vérifie si la chaîne fournie correspond à une adresse email.
Options:
-
allowLocalQuotes?: boolean — (Default: false)
Spécifie si la première partie (partie locale) de l'adresse email peut être formée à l'aide de guillemets. Par exemple, "Jean Dupont"@exemple.com sera considéré comme valide. -
allowIpAddress?: boolean — (Default: false)
Spécifie si la deuxième partie (partie domain) de l'adresse email peut être une adresse IP. Par exemple, [email protected] sera considéré comme valide. -
allowGeneralAddress?: boolean — (Default: false)
Spécifie si la deuxième partie (partie domain) de l'adresse email peut être une adresse general. Par exemple, [email protected] sera considéré comme valide.
Standards: RFC 5321
Vérifie si la chaîne fournie correspond un nom de domain.
Standards: RFC 1035
Vérifie si la chaîne fournie correspond à une DataURL.
Options:
-
type?: string[]
Spécifie un ou plusieurs types MIME autorisés.
Liste des types MIME enregistrés par l'IANA ↗ -
subtype?: string[]
Spécifie un ou plusieurs sous-types MIME autorisés.
Liste des types MIME enregistrés par l'IANA ↗
Standards: RFC 2397
Vérifie si la chaîne fournie correspond à un UUID valide.
Options:
-
version?: number
Spécifie le numéro de version autorisé, compris entre 1 et 7.
Standards: RFC 9562
Vérifie si la chaîne fournie correspond à un encodage base16 valide.
Standards: RFC 4648
Vérifie si la chaîne fournie correspond à un encodage base32 valide.
Standards: RFC 4648
Vérifie si la chaîne fournie correspond à un encodage base32Hex valide.
Standards: RFC 4648
Vérifie si la chaîne fournie correspond à un encodage base64 valide.
Standards: RFC 4648
Vérifie si la chaîne fournie correspond à un encodage base64Url valide.
Standards: RFC 4648
Retourne le tag interne de la cible. Par exemple pour une cible async () => {} le tag retourné est "AsyncFunction".
Convertie une chaîne en base16 en une chaîne en base32 ou base32Hex.
Arguments:
-
to?: "B32" | "B32HEX" — (Default: "B32")
Spécifie dans quel encodage la chaîne doit être convertie. -
padding?: boolean — (Default: true)
Spécifie si la chaîne doit être complétée par un remplissage si nécessaire.
Standards: RFC 4648
Convertie une chaîne en base16 en une chaîne en base64 ou base64Url.
Arguments:
-
to?: "B64" | "B64URL" — (Default: "B64")
Spécifie dans quel encodage la chaîne doit être convertie. -
padding?: boolean — (Default: true)
Spécifie si la chaîne doit être complétée par un remplissage si nécessaire.
Standards: RFC 4648
Convertie une chaîne en base32 ou base32Hex en une chaîne en base16.
Arguments:
-
from?: "B32" | "B32HEX" — (Default: "B32")
Spécifie dans quel encodage la chaîne doit être fournie.
Standards: RFC 4648
Convertie une chaîne en base64 ou base64Url en une chaîne en base16.
Arguments:
-
from?: "B64" | "B64URL" — (Default: "B64")
Spécifie dans quel encodage la chaîne doit être fournie.