Superstruct TypeScript : guide complet avec exemples

Introduction à Superstruct

Superstruct est une bibliothèque légère mais puissante pour la validation et l'analyse de structures de données en TypeScript et JavaScript. Elle vous permet de décrire la forme attendue des données (objets, tableaux, chaînes, nombres, etc.) à l'aide de "schémas" (structs) simples et expressifs, puis de vérifier si les données réelles correspondent à ces schémas.

Contrairement à d'autres bibliothèques de validation comme Zod ou Yup, Superstruct mise sur la simplicité, la performance et le minimalisme. Elle ne génère pas automatiquement des types TypeScript complexes (bien qu'elle s'intègre parfaitement avec eux), mais propose plutôt une API flexible et intuitive pour décrire les structures.

Pourquoi utiliser Superstruct ?

• Validation de données provenant de sources externes : Réponses API, données de formulaires, fichiers de configuration, localStorage — partout où les données peuvent arriver dans un format inattendu.
• Création de DTO (Data Transfer Objects) sécurisés : Garantit que les données échangées entre les couches de l'application respectent la structure attendue.
• Analyse et transformation : Superstruct peut non seulement valider, mais aussi transformer les données (par exemple, convertir des chaînes en nombres).
• Documentation lisible : Les schémas Superstruct constituent en eux-mêmes une excellente documentation de la structure des données.

Installation

Superstruct est un package npm, donc l'installation se fait via le gestionnaire de paquets Node.js :

npm install superstruct

Ou, si vous utilisez Yarn :

yarn add superstruct

Après l'installation, vous pouvez importer la bibliothèque dans votre fichier TypeScript :

import { struct, string, number, object, array, optional, union, literal, enums, size, refine, assert, is, validate } from 'superstruct';

Démarrage rapide

Créons un schéma simple pour un utilisateur et validons des données.

import { object, string, number, assert } from 'superstruct';

// 1. Définir le schéma (struct)
const User = object({
    id: number(),
    name: string(),
    email: string(),
});

// 2. Données à valider
const userData = {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
};

// 3. Validation
try {
    assert(userData, User);
    console.log('Données valides !');
} catch (e) {
    console.error('Erreur de validation :', e.message);
}

// 4. Si les données sont incorrectes, assert lève une exception
const badData = { id: 'pas un nombre', name: 'Bob' };
try {
    assert(badData, User);
} catch (e) {
    console.error('Erreur :', e.message);
    // Affiche : Expected a number for `id`, but received: "pas un nombre"
}

Méthodes et fonctions principales

Superstruct fournit un ensemble de fabriques pour créer des schémas. Voici les 10 principales :

1. string()

Description : Crée un schéma qui vérifie que la valeur est une chaîne de caractères.

Paramètres : Aucun.

import { string, assert } from 'superstruct';

const NameSchema = string();
assert('Bonjour', NameSchema); // OK
// assert(123, NameSchema); // Erreur : Expected a string, but received: 123

2. number()

Description : Vérifie que la valeur est un nombre (y compris NaN, sauf indication contraire).

Paramètres : Aucun.

import { number, assert } from 'superstruct';

const AgeSchema = number();
assert(30, AgeSchema); // OK
// assert('30', AgeSchema); // Erreur

3. boolean()

Description : Vérifie que la valeur est un booléen (true ou false).

Paramètres : Aucun.

import { boolean, assert } from 'superstruct';

const IsActiveSchema = boolean();
assert(true, IsActiveSchema); // OK

4. object(schem