Eine einfache und zusammensetzbare Möglichkeit,
Daten in JavaScript zu validieren.

Verwendung • Warum? • Prinzipien • Demo • Beispiele • Dokumentation

Superstruct erleichtert die Definition von Schnittstellen und die anschließende Validierung von JavaScript-Daten anhand dieser. Die Typannotations-API wurde von Typescript , Flow , Go und GraphQL inspiriert und bietet eine vertraute und leicht verständliche API.

Aber Superstruct ist für die Validierung von Daten zur Laufzeit konzipiert, sodass es detaillierte Laufzeitfehler für Sie oder Ihre Endbenutzer auslöst (oder zurückgibt). Dies ist besonders nützlich in Situationen wie dem Akzeptieren willkürlicher Eingaben in einer REST- oder GraphQL-API. Es kann aber sogar verwendet werden um bei Bedarf interne Datenstrukturen zur Laufzeit zu validieren.

Usage

Superstruct exportiert eine structFactory zum Erstellen von Strukturen, die Daten anhand eines bestimmten Schemas validieren 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 standardmäßig alle nativen JavaScript-Typen. Sie können aber auch Ihre eigenen benutzerdefinierten Datentypen definieren – speziell für die Anforderungen Ihrer Anwendung –, indem Sie den superstructExport verwenden:

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 Zusammensetzen von Strukturen ineinander, das Zurückgeben von Fehlern statt sie auszulösen usw. Weitere Informationen finden Sie in der vollständigen Dokumentation .

Why?

Es gibt viele bestehende Validierungsbibliotheken – joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Aber sie weisen viele Probleme auf, die dazu führen, dass Ihre Codebasis schwer zu warten ist ...

• Sie legen keine detaillierten Fehler offen. Viele Validatoren geben einfach nur String-Fehler oder boolesche Werte ohne Angaben zum Grund zurück, 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. ausgeliefert, ohne dass man weiß, wonach sie suchen, und mit komplizierten APIs zum Definieren neuer Typen.

• Sie fördern keine Single Sources of Truth. Viele bestehende APIs ermutigen dazu, benutzerdefinierte Datentypen immer wieder neu zu definieren, wobei die Source of Truth über Ihre gesamte Codebasis verteilt ist.

• Sie werfen keine Fehler aus. Viele werfen die Fehler nicht wirklich aus, was Sie dazu zwingt, überall umzubrechen. Obwohl dies in Zeiten von Rückrufen hilfreich war, wird der Code durch die Nichtverwendung throwin modernem JavaScript viel komplexer.

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

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

• Sie verwenden JSON-Schema. Verstehen Sie mich nicht falsch, JSON-Schema kann nützlich sein. Aber es ist ein bisschen wie HATEOAS – es ist normalerweise viel komplexer, als Sie brauchen, und Sie nutzen keinen seiner Vorteile. (Entschuldigung, ich habe es gesagt .)

Natürlich leidet nicht jede Validierungsbibliothek unter allen diesen Problemen, aber die meisten weisen mindestens eines auf. Wenn Sie schon einmal 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. Die Stärke von Superstruct besteht darin, dass es einfach ist, einen ganzen Satz benutzerdefinierter Datentypen zu definieren, die spezifisch für Ihre Anwendung sind und an einem einzigen Ort definiert werden, sodass Sie die volle Kontrolle über Ihre Anforderungen haben.

2. Meinungslose Standardeinstellungen. Superstruct wird mit nativen JavaScript-Typen ausgeliefert und alles andere ist anpassbar, sodass Sie nie darum kämpfen müssen, vom „Kern“ getroffene Entscheidungen außer Kraft zu setzen, die von den Anforderungen Ihrer Anwendung abweichen.

3. Zusammensetzbare Schnittstellen. Superstruct-Schnittstellen sind zusammensetzbar, sodass Sie häufig wiederkehrende Datenelemente in Komponenten zerlegen und diese zusammensetzen können, um komplexere Objekte aufzubauen.

4. Prägnante Schemata. Die Schemata in Superstruct sind äußerst prägnant und ausdrucksstark gestaltet. Dadurch sind sie sehr einfach zu lesen und zu schreiben, sodass Sie eine vollständige Datenvalidierungsabdeckung erhalten.

5. Kompilierte Validatoren. Superstruct übernimmt die Arbeit des Kompilierens seiner Schemata im Voraus, sodass nicht für jeden Aufruf der Validierungsfunktionen in Ihren Hot-Code-Pfaden Zeit mit teuren Aufgaben verschwendet wird.

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

7. Vertraute API. Die Superstruct-API wurde stark von Typescript , Flow , Go und GraphQL inspiriert . Wenn Sie mit einer davon vertraut sind, wird sich die Verwendung der Schemadefinitions-API sehr natürlich anfühlen, sodass Sie schnell loslegen können.

Demo

Probieren Sie die Live-Demo auf JSFiddle aus , um eine Vorstellung davon zu bekommen, wie die API funktioniert, oder um Ihren Anwendungsfall schnell zu überprüfen:

Examples

Die API von Superstruct ist sehr flexibel und ermöglicht die Verwendung für eine Vielzahl von Anwendungsfällen auf Ihren Servern und im Browser. Hier sind einige Beispiele für gängige Muster...

• Grundlegende Validierung
• Benutzerdefinierte Typen
• Standardwerte
• Optionale Werte
• Strukturen komponieren
• Fehler werfen
• Zurückgeben von Fehlern
• Benutzerdefinierte Fehler

Documentation

Lesen Sie den Leitfaden „Erste Schritte“, um sich mit der Funktionsweise von Superstruct vertraut zu machen. Schauen Sie sich anschließend die vollständige API-Referenz an, um detailliertere Informationen zu Strukturen, Typen und Fehlern zu erhalten …

• Führung
  • Superstruct installieren
  • Strukturen erstellen
  • Definieren benutzerdefinierter Datentypen
  • Standardwerte festlegen
  • Benutzerdefinierte Fehler auslösen
  • Validierung komplexer Formen
  • Strukturen komponieren
• Referenz
  • API
  • Structs
  • Types
  • Errors
• Ressourcen

License

Dieses Paket istMIT-licensed.