Een eenvoudige en configureerbare manier
om gegevens in JavaScript te valideren.

Gebruik • Waarom • Principes • Demo • Voorbeelden • Documentatie

Superstruct maakt het gemakkelijk om interfaces te definiëren en vervolgens JavaScript-gegevens daaraan te valideren. De type-annotatie-API is geïnspireerd op Typescript , Flow , Go en GraphQL , waardoor het een vertrouwde en gemakkelijk te begrijpen API is.

Maar Superstruct is ontworpen voor het valideren van gegevens tijdens runtime, dus het genereert (of retourneert) gedetailleerde runtime-fouten voor u of uw eindgebruikers. Dit is vooral handig in situaties zoals het accepteren van willekeurige invoer in een REST- of GraphQL-API. Maar het kan zelfs worden gebruikt om interne datastructuren tijdens runtime te valideren wanneer dat nodig is.

Usage

Superstruct exporteert een structfabriek voor het maken van structs die gegevens kunnen valideren tegen een specifiek schema:

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

Het herkent alle native JavaScript-typen, maar u kunt ook uw eigen aangepaste gegevenstypen definiëren, specifiek voor de vereisten van uw toepassing, door de superstructexport te gebruiken:

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 ondersteunt ook complexere gebruiksscenario's, zoals het definiëren van lijst- of scalaire structuren, het toepassen van standaardwaarden, het samenstellen van structuren in elkaar, het retourneren van fouten in plaats van ze te genereren, enz. Lees voor meer informatie de volledige Documentatie .

Why?

Er zijn veel bestaande validatiebibliotheken – joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Maar ze vertonen veel problemen die ertoe leiden dat uw codebase moeilijk te onderhouden wordt...

• Ze brengen geen gedetailleerde fouten aan het licht. Veel validators retourneren eenvoudigweg alleen maar string-fouten of booleans zonder enige details over waarom, waardoor het moeilijk wordt om de fouten aan te passen zodat ze nuttig zijn voor eindgebruikers.

• Ze maken aangepaste typen moeilijk. Veel validators worden geleverd met ingebouwde typen zoals e-mails, URL's, UUID's, enz. zonder dat ze weten waarop ze controleren, en ingewikkelde API's voor het definiëren van nieuwe typen.

• Ze moedigen geen enkele bron van waarheid aan. Veel bestaande API's moedigen het steeds opnieuw definiëren van aangepaste gegevenstypen aan, waarbij de bron van waarheid over je hele codebasis wordt verspreid.

• Ze genereren geen fouten. Velen genereren de fouten niet echt, waardoor je gedwongen wordt overal naar toe te gaan. Hoewel dit handig is in de tijd van callbacks, throwmaakt het niet gebruiken van moderne JavaScript de code veel complexer.

• Ze compileren schema's niet vooraf. Veel validators definiëren schema's als eenvoudige JavaScript-objecten, wat betekent dat ze het parseren van de schemalogica delegeren aan de validatietijd, waardoor ze veel langzamer worden.

• Ze zijn nauw verbonden met andere problemen.Veel validators zijn nauw gekoppeld aan Express of andere raamwerken, wat resulteert in eenmalige, verwarrende code die niet herbruikbaar is in uw codebasis.

• Ze gebruiken JSON Schema. Begrijp me niet verkeerd, JSON Schema kan nuttig zijn. Maar het lijkt een beetje op HATEOAS: het is meestal veel complexer dan je nodig hebt en je maakt geen gebruik van de voordelen ervan. (Sorry, ik zei het al .)

Natuurlijk heeft niet elke validatiebibliotheek last van al deze problemen, maar de meeste vertonen er minstens één. Als je dit probleem eerder bent tegengekomen, is Superstruct wellicht iets voor jou.

Dat brengt mij bij hoe Superstruct deze problemen oplost...

Principles

1. Aanpasbare typen De kracht van Superstruct ligt in het eenvoudig maken van een volledige set aangepaste gegevenstypen die specifiek zijn voor uw toepassing en op één plek worden gedefinieerd, zodat u volledige controle heeft over uw vereisten.

2. Geen mening. Superstruct wordt geleverd met native JavaScript-typen, en al het andere is aanpasbaar, zodat u nooit hoeft te vechten om beslissingen van de 'kern' die afwijken van de behoeften van uw applicatie, terzijde te schuiven.

3. Composeerbare interfaces Superstruct-interfaces zijn composeerbaar, zodat u vaak herhaalde stukjes gegevens in componenten kunt opsplitsen en deze kunt samenstellen om de meer complexe objecten op te bouwen.

4. Beknopte schema's. De schema's in Superstruct zijn ontworpen om extreem beknopt en expressief te zijn. Dit maakt ze zeer gemakkelijk te lezen en te schrijven, waardoor u wordt aangemoedigd om volledige gegevensvalidatiedekking te hebben.

5. Gecompileerde validators Superstruct doet het werk door zijn schema's vooraf te compileren, zodat het geen tijd hoeft te besteden aan het uitvoeren van dure taken voor elke aanroep van de validatiefuncties in uw hotcodepaden.

6. Nuttige fouten De fouten die Superstruct genereert bevatten alle informatie die u nodig heeft om ze eenvoudig om te zetten in uw eigen applicatiespecifieke fouten, wat meer nuttige fouten betekent voor uw eindgebruikers!

7. Bekende API. De Superstruct API is sterk geïnspireerd door Typescript , Flow , Go en GraphQL . Als u bekend bent met een van deze, voelt de API voor schemadefinitie heel natuurlijk aan, zodat u snel aan de slag kunt.

Demo

Probeer de live demo op JSFiddle om een ​​idee te krijgen van hoe de API werkt, of om snel uw gebruiksscenario te verifiëren:

Examples

De API van Superstruct is zeer flexibel, waardoor deze voor verschillende gebruiksscenario's op uw servers en in de browser kan worden gebruikt. Hier zijn een paar voorbeelden van veelvoorkomende patronen...

• Basisvalidatie
• Aangepaste typen
• Standaard waarden
• Optionele waarden
• Het samenstellen van structuren
• Fouten gooien
• Terugkerende fouten
• Aangepaste fouten

Documentation

Lees de 'Aan de slag'-gids om vertrouwd te raken met hoe Superstruct werkt. Bekijk daarna de volledige API-referentie voor meer gedetailleerde informatie over structs, typen en fouten...

• Gids
  • Superstruct installeren
  • Structuren creëren
  • Aangepaste gegevenstypen definiëren
  • Standaardwaarden instellen
  • Aangepaste fouten genereren
  • Valideren van complexe vormen
  • Het samenstellen van structuren
• Referentie
  • API
  • Structs
  • Types
  • Errors
• Bronnen

License

Dit pakket isMIT-licensed.