Un moyen simple et composable
de valider des données en JavaScript.

Utilisation • Pourquoi ? • Principes • Démo • Exemples • Documentation

Superstruct facilite la définition d'interfaces, puis la validation des données JavaScript par rapport à elles. Son API d'annotation de type a été inspirée par Typescript , Flow , Go et GraphQL , ce qui lui confère une API familière et facile à comprendre.

Mais Superstruct est conçu pour valider les données au moment de l'exécution, il génère donc (ou renvoie) des erreurs d'exécution détaillées pour vous ou vos utilisateurs finaux. Ceci est particulièrement utile dans des situations telles que l'acceptation d'entrées arbitraires dans une API REST ou GraphQL. Mais il peut même être utilisé pour valider les structures de données internes au moment de l'exécution en cas de besoin.

Usage

Superstruct exporte une structusine pour créer des structures capables de valider les données par rapport à un schéma spécifique :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import { struct } from 'superstruct'

const Article = struct({
  id: 'number',
  title: 'string',
  is_published: 'boolean?',
  tags: ['string'],
  author: {
    id: 'number',
  },
})

const data = {
  id: 34,
  title: 'Hello World',
  tags: ['news', 'features'],
  author: {
    id: 1,
  },
}

const article = Article(data)

// This will throw when the data is invalid, and return the data otherwise.
// If you'd rather not throw, use `Struct.validate()` or `Struct.test()`.

Il reconnaît tous les types JavaScript natifs dès le départ. Mais vous pouvez également définir vos propres types de données personnalisés, spécifiques aux exigences de votre application, en utilisant l' superstructexportation :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import { superstruct } from 'superstruct'
import isUuid from 'is-uuid'
import isEmail from 'is-email'

const struct = superstruct({
  types: {
    uuid: value => isUuid.v4(value),
    email: value => isEmail(value) && value.length < 256,
  },
})

const User = struct({
  id: 'uuid',
  email: 'email',
  is_admin: 'boolean?',
})

const data = {
  id: 'c8d63140-a1f7-45e0-bfc6-df72973fea86',
  email: 'jane@example.com',
}

const user = User(data)

Superstruct prend également en charge des cas d'utilisation plus complexes, comme la définition de structures de liste ou scalaires, l'application de valeurs par défaut, la composition de structures les unes dans les autres, le renvoi d'erreurs au lieu de les lancer, etc. Pour plus d'informations, lisez la documentation complète .

Why?

Il existe de nombreuses bibliothèques de validation existantes : joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Mais elles présentent de nombreux problèmes qui rendent votre base de code difficile à maintenir...

• Ils n'exposent pas les erreurs détaillées. De nombreux validateurs renvoient simplement des erreurs de type chaîne ou des booléens sans aucun détail sur la raison, ce qui rend difficile la personnalisation des erreurs pour qu'elles soient utiles aux utilisateurs finaux.

• Ils rendent les types personnalisés difficiles. De nombreux validateurs sont livrés avec des types intégrés tels que des e-mails, des URL, des UUID, etc., sans aucun moyen de savoir ce qu'ils vérifient, et des API compliquées pour définir de nouveaux types.

• Elles n'encouragent pas les sources de vérité uniques. De nombreuses API existantes encouragent à redéfinir sans cesse les types de données personnalisés, la source de vérité étant répartie sur l'ensemble de votre base de code.

• Ils ne génèrent pas d'erreurs. Beaucoup ne génèrent pas réellement d'erreurs, ce qui vous oblige à retourner partout. Bien qu'utile à l'époque des rappels, ne pas utiliser throwle JavaScript moderne rend le code beaucoup plus complexe.

• Ils ne précompilent pas les schémas. De nombreux validateurs définissent les schémas comme de simples objets JavaScript, ce qui signifie qu'ils délèguent l'analyse de la logique du schéma au moment de la validation, ce qui les rend beaucoup plus lents.

• Ils sont étroitement liés à d'autres préoccupations. De nombreux validateurs sont étroitement couplés à Express ou à d'autres frameworks, ce qui entraîne un code unique et déroutant qui n'est pas réutilisable dans votre base de code.

• Ils utilisent le schéma JSON. Ne vous méprenez pas, le schéma JSON peut être utile. Mais c'est un peu comme HATEOAS : il est généralement bien plus complexe que nécessaire et vous n'utilisez aucun de ses avantages. (Désolé, je l'ai dit .)

Bien sûr, toutes les bibliothèques de validation ne souffrent pas de tous ces problèmes, mais la plupart d'entre elles en présentent au moins un. Si vous avez déjà rencontré ce problème, vous aimerez peut-être Superstruct.

Ce qui m'amène à la façon dont Superstruct résout ces problèmes...

Principles

1. Types personnalisables. La puissance de Superstruct réside dans le fait qu'il facilite la définition d'un ensemble complet de types de données personnalisés spécifiques à votre application et définis en un seul endroit, afin que vous ayez un contrôle total sur vos besoins.

2. Valeurs par défaut sans opinion. Superstruct est livré avec des types JavaScript natifs, et tout le reste est personnalisable, vous n'aurez donc jamais à vous battre pour ignorer les décisions prises par le « noyau » qui diffèrent des besoins de votre application.

3. Interfaces composables. Les interfaces Superstruct sont composables, vous pouvez donc décomposer des éléments de données fréquemment répétés en composants et les composer pour créer des objets plus complexes.

4. Schémas concis. Les schémas de Superstruct sont conçus pour être extrêmement concis et expressifs. Cela les rend très faciles à lire et à écrire, vous encourageant à avoir une couverture complète de validation des données.

5. Validateurs compilés. Superstruct fait le travail de compilation de ses schémas à l'avance, afin de ne pas perdre de temps à effectuer des tâches coûteuses pour chaque appel aux fonctions de validation dans vos chemins de code chaud.

6. Erreurs utiles. Les erreurs générées par Superstruct contiennent toutes les informations dont vous avez besoin pour les convertir facilement en erreurs spécifiques à votre application, ce qui signifie des erreurs plus utiles pour vos utilisateurs finaux !

7. API familière. L'API Superstruct a été fortement inspirée par Typescript , Flow , Go et GraphQL . Si vous connaissez l'un d'entre eux, son API de définition de schéma vous semblera très naturelle à utiliser, vous pourrez donc démarrer rapidement.

Demo

Essayez la démo en direct sur JSFiddle pour avoir une idée du fonctionnement de l'API ou pour vérifier rapidement votre cas d'utilisation :

Examples

L'API de Superstruct est très flexible, lui permettant d'être utilisée pour une variété de cas d'utilisation sur vos serveurs et dans le navigateur. Voici quelques exemples de modèles courants...

• Validation de base
• Types personnalisés
• Les valeurs par défaut
• Valeurs facultatives
• Composer des structures
• Erreurs de lancement
• Retour des erreurs
• Erreurs personnalisées

Documentation

Lisez le guide de démarrage pour vous familiariser avec le fonctionnement de Superstruct. Après cela, consultez la référence complète de l'API pour des informations plus détaillées sur les structures, les types et les erreurs...

• Guide
  • Installation de Superstruct
  • Création de structures
  • Définir des types de données personnalisés
  • Définition des valeurs par défaut
  • Lancer des erreurs personnalisées
  • Validation des formes complexes
  • Composer des structures
• Référence
  • API
  • Structs
  • Types
  • Errors
• Ressources

License

Ce paquet estMIT-licensed.