Module communautaire génial

Une manière simple et composable
pour valider les données en JavaScript.



UtilisationPourquoi?PrincipesDémoExemplesDocumentation



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

Mais Superstruct est conçu pour valider les données lors de l'exécution. Il génère (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 de saisie arbitraire 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 si nécessaire.


Usage

Les exportations Un Superstruct struct usine pour la création struct que la validation des données à une CAN spécifique du schéma:

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 de la boîte. Mais vous pouvez également définir vos propres types de données personnalisés - spécifiques aux exigences de votre application - en utilisant l'exportation de superstruct :

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 listes ou de structures 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 renvoyer, 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 difficile la maintenance de votre base de code ...

  • Ils n'exposent pas les erreurs détaillées. De nombreux validateurs renvoient simplement des erreurs de chaîne uniquement ou des booléens sans aucun détail expliquant pourquoi, ce qui rend difficile la personnalisation des erreurs pour être utile 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.

  • Ils n'encouragent pas des sources de vérité uniques. De nombreuses API existantes encouragent la redéfinition des types de données personnalisés, la source de vérité étant répartie sur l'ensemble de votre base de code.

  • Les erreurs de jet ne font - ils. Beaucoup ne le font pas fait le jeter aux erreurs, vous obligeant à envelopper partout. Bien est utile dans au Days des callbacks, pas en utilisant throw dans le code JavaScript MODERNE beaucoup complexifie.

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

  • Ils sont étroitement liés à d'autres préoccupations. De nombreux validateurs sont étroitement liés à Express ou à d'autres cadres, 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 - c'est généralement beaucoup plus complexe que ce dont vous avez besoin 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 est de faciliter 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 non appréciées. Superstruct est livré avec des types JavaScript natifs, et tout le reste est personnalisable, vous n'avez donc pas à vous battre pour écraser les décisions prises par le "cœur" 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 laconiques . Les schémas de Superstruct sont conçus pour être extrêmement laconiques et expressifs, ce qui 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, de sorte qu'il ne passe pas 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 que Superstruct lance contiennent toutes les informations dont vous avez besoin pour les convertir en vos propres erreurs spécifiques à l'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 êtes familier avec l'un d'entre eux, alors son API de définition de schéma sera très naturelle à utiliser, vous pouvez donc commencer 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:

Capture d'écran de démonstration.


Examples

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


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 ...


License

Ce package est MIT-licensed .