Module communautaire génial

Un moyen simple et composable
de valider des 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 s'inspire de 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 renvoie (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 si nécessaire.


Usage

Superstruct exporte une structfabrique pour créer des structures pouvant 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 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, 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, tels que 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?

Existe-t-il BEAUCOUP de bibliothèques de validation existantes - joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Mais elles présentent BEAUCOUP DE DÉLINQUANCES 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 booléens sans aucun détail quant à 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.

  • Ils n'encouragent pas les sources de vérité uniques.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 renvoient pas d'erreurs. Beaucoup ne renvoient pas réellement d'erreurs, ce qui vous oblige à les encapsuler partout. Bien qu'utile à l'époque des rappels, la non-utilisation throwde 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 du schéma au moment de la validation, ce qui les rend beaucoup plus lents.

  • Ils sont étroitement liés à d'autres problèmes.De nombreux validateurs sont étroitement lié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 JSON Schema. Ne vous méprenez pas, JSON Schema peut être utile. Mais c'est un peu comme HATEOAS - c'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. 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 à 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'avez donc jamais à vous battre pour annuler 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 les objets les plus complexes.

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

  5. Validateurs compilés. Superstruct effectue le travail de compilation de ses schémas à l'avance, de sorte qu'il ne perde 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 génère 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 êtes familier avec l'un d'entre eux, alors son API de définition de schéma 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 API complète pour des informations plus détaillées sur les structures, les types et les erreurs...


License

Ce forfait est MIT-licensed.