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 à elles. 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 au moment de l'exécution, donc 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 comme l'acceptation d'une entrée 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

Superstruct exporte une struct usine pour créer struct qui peut valider les données sur 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 prêts à l'emploi. Mais vous pouvez également définir vos propres types de données personnalisés, spécifiques aux exigences de votre application, à l'aide de 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 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 d'erreurs détaillées. De nombreux validateurs renvoient simplement des erreurs de chaîne uniquement ou des valeurs booléennes sans aucun détail sur la raison, ce qui rend difficile la personnalisation des erreurs pour être 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 les e-mails, les URL, les UUID, etc. sans aucun moyen de savoir ce qu'ils recherchent, et des API compliquées pour définir de nouveaux types.

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

  • Ils ne lancent pas d'erreurs. Beaucoup ne lancent pas les erreurs, ce qui vous oblige à envelopper partout. Bien qu'utile à l'époque des rappels, ne pas utiliser throw dans le 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 des objets JavaScript simples, ce qui signifie qu'ils délèguent l'analyse de la logique de schéma au temps de validation, ce qui les ralentit beaucoup plus.

  • Ils sont étroitement liés à d'autres préoccupations. De nombreux validateurs sont étroitement associé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 beaucoup plus complexe que vous n'en 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 Le pouvoir 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 à un seul endroit, de sorte que vous ayez un contrôle total sur vos besoins.

  2. Valeurs par défaut sans opinion. Superstruct est fourni avec des types JavaScript natifs, et tout le reste est personnalisable, de sorte que vous n'aurez jamais à vous battre pour remplacer 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 les objets les 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, ce qui vous encourage à avoir une couverture complète de la 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 actif.

  6. Erreurs utiles Les erreurs générées par Superstruct contiennent toutes les informations dont vous avez besoin pour les convertir facilement 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, son API de définition de schéma vous semblera 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ée 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 obtenir des informations plus détaillées sur les structures, les types et les erreurs ...


License

Ce package est MIT-licensed .