Fantastisches Community-Modul

Ein einfacher und zusammensetzbarer Weg
um Daten in JavaScript zu validieren.



VerwendungWarum?PrinzipienDemoBeispieleDokumentation



Mit Superstruct ist es einfach, Schnittstellen zu definieren und anschließend JavaScript-Daten anhand dieser zu validieren. Die API für Typanmerkungen wurde von Typescript , Flow , Go und GraphQL inspiriert und bietet eine vertraute und leicht verständliche API.

Superstruct wurde jedoch für die Validierung von Daten zur Laufzeit entwickelt, sodass detaillierte Laufzeitfehler für Sie oder Ihre Endbenutzer ausgegeben (oder zurückgegeben) werden. Dies ist besonders nützlich in Situationen wie dem Akzeptieren beliebiger Eingaben in einer REST- oder GraphQL-API. Es kann jedoch sogar verwendet werden um interne Datenstrukturen bei Bedarf zur Laufzeit zu validieren.


Usage

Superstruct exportiert eine struct zum Erstellen von Strukturen, mit denen Daten anhand eines bestimmten Schemas überprüft werden können:

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()`.

Es erkennt sofort alle nativen JavaScript-Typen. Sie können jedoch auch Ihre eigenen benutzerdefinierten Datentypen definieren, die für die Anforderungen Ihrer Anwendung spezifisch sind, indem Sie den Export des 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 unterstützt auch komplexere Anwendungsfälle wie das Definieren von Listen- oder Skalarstrukturen, das Anwenden von Standardwerten, das Zusammenstellen von Strukturen ineinander, das Zurückgeben von Fehlern, anstatt sie zu werfen usw. Weitere Informationen finden Sie in der vollständigen Dokumentation .


Why?

Es gibt viele vorhandene Validierung Libraries joi , express-validator , validator.js , yup , ajv , is-my-json-valid ... Aber sie zeigen viele Probleme , die Führung zu Ihrer Code - Basis immer schwer zu pflegen ...

  • Sie legen keine detaillierten Fehler offen . Viele Prüfer geben einfach Nur-Zeichenfolgen-Fehler oder Boolesche Werte zurück, ohne Details darüber anzugeben, warum, was es schwierig macht, die Fehler so anzupassen, dass sie für Endbenutzer hilfreich sind.

  • Sie erschweren benutzerdefinierte Typen. Viele Validatoren werden mit integrierten Typen wie E-Mails, URLs, UUIDs usw. geliefert, ohne zu wissen, wonach sie suchen, und mit komplizierten APIs zum Definieren neuer Typen.

  • Sie fördern nicht einzelne Wahrheitsquellen. Viele vorhandene APIs empfehlen, benutzerdefinierte Datentypen immer wieder neu zu definieren, wobei die Wahrheitsquelle auf Ihre gesamte Codebasis verteilt ist.

  • Sie werfen keine Fehler. Viele haben nicht wirklich die Fehler werfen, Sie zwingen überall zu wickeln. Obwohl hilfreich in den Tagen der Rückrufe, nicht mit throw in modernen JavaScript - Code macht viel komplexer.

  • Sie kompilieren keine Schemas vor. Viele Validatoren definieren Schemas als einfache JavaScript-Objekte . Dies bedeutet, dass sie das Parsen der Schemalogik an die Validierungszeit delegieren, wodurch sie viel langsamer werden.

  • Sie sind eng mit anderen Anliegen verbunden. Viele Validatoren sind eng mit Express oder anderen Frameworks verbunden, was zu einmaligem, verwirrendem Code führt, der in Ihrer Codebasis nicht wiederverwendbar ist.

  • Sie verwenden das JSON-Schema. Verstehen Sie mich nicht falsch, das JSON-Schema kann nützlich sein. Aber es ähnelt HATEOAS - es ist normalerweise viel komplexer als Sie es benötigen und Sie nutzen keinen seiner Vorteile. (Entschuldigung, ich habe es gesagt .)

Natürlich leidet nicht jede Validierungsbibliothek unter all diesen Problemen, aber die meisten weisen mindestens eines auf. Wenn Sie zuvor auf dieses Problem gestoßen sind, könnte Ihnen Superstruct gefallen.

Was mich dazu bringt, wie Superstruct diese Probleme löst ...


Principles

  1. Anpassbare Typen: Superstruct macht es einfach, einen ganzen Satz benutzerdefinierter Datentypen zu definieren, die für Ihre Anwendung spezifisch und an einem einzigen Ort definiert sind, sodass Sie die volle Kontrolle über Ihre Anforderungen haben.

  2. Unoptionierte Standardeinstellungen: Superstruct wird mit nativen JavaScript-Typen geliefert , und alles andere ist anpassbar, sodass Sie nie kämpfen müssen, um Entscheidungen von "core" zu überschreiben, die von den Anforderungen Ihrer Anwendung abweichen.

  3. Zusammensetzbare Schnittstellen: Superstruct-Schnittstellen sind zusammensetzbar, sodass Sie häufig wiederholte Daten in Komponenten zerlegen und diese zusammensetzen können, um die komplexeren Objekte aufzubauen.

  4. Knappe Schemata: Die Schemata in Superstruct sind äußerst knapp und ausdrucksstark. Dadurch sind sie sehr einfach zu lesen und zu schreiben, sodass Sie eine vollständige Abdeckung der Datenvalidierung erhalten.

  5. Kompilierte Validatoren. Superstruct kompiliert seine Schemas im Voraus, damit es keine Zeit damit verbringt, teure Aufgaben für jeden Aufruf der Validierungsfunktionen in Ihren Hot-Code-Pfaden auszuführen.

  6. Nützliche Fehler: Die Fehler, die Superstruct auslöst, enthalten alle Informationen, die Sie benötigen, um sie einfach in Ihre eigenen anwendungsspezifischen Fehler umzuwandeln. Dies bedeutet hilfreichere Fehler für Ihre Endbenutzer!

  7. Vertraute API: Die Superstruct-API wurde stark von Typescript , Flow , Go und GraphQL inspiriert . Wenn Sie mit einer dieser APIs vertraut sind, fühlt sich die Verwendung der Schemadefinitions- API sehr natürlich an, sodass Sie schnell loslegen können.


Demo

Probieren Sie die Live-Demo auf JSFiddle aus , um eine Vorstellung von der Funktionsweise der API zu erhalten oder um Ihren Anwendungsfall schnell zu überprüfen:

Demo-Screenshot.


Examples

Die API von Superstruct ist sehr flexibel und kann für eine Vielzahl von Anwendungsfällen auf Ihren Servern und im Browser verwendet werden. Hier einige Beispiele für gängige Muster ...


Documentation

Lesen Sie die Kurzanleitung, um sich mit der Funktionsweise von Superstruct vertraut zu machen. Lesen Sie anschließend die vollständige API-Referenz, um detailliertere Informationen zu Strukturen, Typen und Fehlern zu erhalten.


License

Dieses Paket ist MIT-licensed .