PropertyDescriptors pour la validation de schémas TypeScript

Descripteurs de propriétés pour la validation de schémas : Gestion d'erreurs type-sûre en TypeScript

Les développeurs se heurtent souvent à la validation d'objets complexes imbriqués dans leurs projets JavaScript. Les approches traditionnelles utilisant des chemins sous forme de chaînes pour extraire les erreurs entraînent des bugs à l'exécution lors des refactorisations. La solution ? Les descripteurs de propriétés : un arbre structuré de descripteurs qui fournit des sélecteurs type-sûrs avec autocomplétion complète dans l'IDE.

L'idée centrale est que chaque schéma construit un arbre de nœuds, où chaque descripteur connaît son chemin de propriété, le schéma lié, le parent et les méthodes d'accès. Cela permet de compiler des sélecteurs via des lambdas au lieu de chaînes fragiles.

import { object, string, number, InferType } from '@cleverbrush/schema';

const OrderSchema = object({
    id: string(),
    customer: object({
        name: string().minLength(2),
        email: string().email(),
        address: object({
            city: string().required('La ville est obligatoire'),
            zip: number()
        })
    }),
    total: number().min(0)
});

const result = OrderSchema.validate({
    id: '123',
    customer: {
        name: 'A',
        email: 'not-an-email',
        address: {
            zip: -1
        }
    },
    total: -5
});

const nameErrors = result.getErrorsFor(t => t.customer.name);
const cityErrors = result.getErrorsFor(t => t.customer.address.city);

Renommez un champ, et TypeScript le détecte à la compilation. Votre IDE propose une autocomplétion complète.

API fluide immuable et constructeurs

Toutes les appels de méthodes de schéma retournent de nouvelles instances, évitant les mutations. Cela rend la composition et la réutilisation enfantines.

La bibliothèque propose 14 types de constructeurs :

• string() — minLength, maxLength, matches, email, url, uuid
• number() — min, max, positive, negative, finite, multipleOf
• boolean() — validation de base
• date() — minDate, maxDate
• object() — propriétés nommées
• array() — éléments typés, non vide
• union() — unions discriminées
• tuple() — longueur fixe
• record() — clés dynamiques
• func() — typage de fonctions
• any() — avec hasType
• nul() — null
• lazy() — schémas récursifs
• extern() — enveloppeur Standard Schema v1

Méthodes courantes sur le SchemaBuilder de base :

• .optional() — accepte undefined
• .required('msg') — champ obligatoire
• .nullable() — accepte null
• .default(value) — valeur par défaut
• .catch(value) — fallback en cas d'erreur
• .readonly() — Readonly<T>
• .brand<'T'>() — types marqués
• .describe('text') — préservation JSDoc
• .addValidator(fn) — logique personnalisée
• .addPreprocessor(fn) — prétraitement
• .introspect() — métadonnées

Introspection de schéma à l'exécution

La méthode .introspect() retourne une description complète du schéma : type, contraintes, flags, descriptions, extensions. Tout disponible à l'exécution pour les outils et intégrations.

const Name = string().minLength(2).maxLength(100).describe('Nom d\'utilisateur').optional();

const info = Name.introspect();
// info.type === 'string'
// info.minLength === 2
// info.description === 'Nom d\'utilisateur'

L'introspection est entièrement développée pour chaque constructeur. Idéal pour la conversion JSON Schema, la génération de formulaires ou les renderers personnalisés.

Système d'extensions typé

Les extensions sont des ajouts composables et introspectables au cœur. Exemple pour les couleurs HEX et les ports :

const hexColorExt = defineExtension({
    string: {
        hexColor(this: StringSchemaBuilder) {
            return this.addValidator((v) => {
                const valid = /^#[0-9a-f]{6}$/i.test(v as string);
                return {
                    valid,
                    errors: valid ? [] : [{ message: 'Doit être une couleur HEX valide' }]
                };
            });
        }
    }
});

const s = withExtensions(hexColorExt, portExt);
const colorSchema = s.string().hexColor();

Les extensions apparaissent dans .introspect().extensions. Les intégrées incluent email, url, uuid, positive, nonempty.

Compatibilité Standard Schema v1

Les schémas implémentent Standard Schema v1 pour une intégration fluide avec tRPC, TanStack Form, React Hook Form, Hono. extern() enveloppe Zod/Valibot dans des constructeurs.

const UserSchema = object({
    name: string().minLength(2),
    address: extern(zodAddress)
});

Les descripteurs de propriétés offrent un accès type-sûr aux erreurs même dans les schémas mixtes.

Points clés

• Sélecteurs type-sûrs via les descripteurs de propriétés : finis les chemins en chaînes et bugs à l'exécution.
• API fluide immuable : composition simplifiée sans effets de bord.
• Introspection à l'exécution : extraction de métadonnées pour n'importe quel outil.
• Extensions : ajouts typés et composables au cœur.
• Standard Schema v1 : compatibilité avec l'écosystème.

— Editorial Team