Un modo semplice e componibile
per convalidare i dati in JavaScript.

Utilizzo • Perché? • Principi • Demo • Esempi • Documentazione

Superstruct semplifica la definizione delle interfacce e quindi la convalida dei dati JavaScript rispetto ad esse. La sua API di annotazione del tipo è stata ispirata da Typescript , Flow , Go e GraphQL , conferendole un'API familiare e di facile comprensione.

Ma Superstruct è progettato per convalidare i dati in fase di runtime, quindi genera (o restituisce) errori di runtime dettagliati per te o i tuoi utenti finali. Ciò è particolarmente utile in situazioni come l'accettazione di input arbitrari in un'API REST o GraphQL. Ma può anche essere utilizzato per convalidare le strutture dati interne in fase di esecuzione quando necessario.

Usage

Superstruct esporta una structfactory per creare strutture in grado di convalidare i dati rispetto a uno schema specifico:

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

Riconosce immediatamente tutti i tipi JavaScript nativi, ma puoi anche definire i tuoi tipi di dati personalizzati, specifici per i requisiti della tua applicazione, utilizzando l' superstructesportazione:

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 supporta anche casi d'uso più complessi come la definizione di liste o strutture scalari, l'applicazione di valori predefiniti, la composizione di strutture l'una all'interno dell'altra, la restituzione di errori invece di generarli, ecc. Per ulteriori informazioni leggere la documentazione completa .

Why?

Esistono molte librerie di convalida esistenti: joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Ma presentano molti problemi che rendono difficile la manutenzione della base di codice...

• Non espongono errori dettagliati. Molti validatori restituiscono semplicemente errori di sole stringhe o valori booleani senza dettagli sul motivo, rendendo difficile personalizzare gli errori per essere utili per gli utenti finali.

• Rendono difficili i tipi personalizzati: molti validatori vengono forniti con tipi incorporati come email, URL, UUID, ecc. senza alcun modo di sapere cosa controllare e API complicate per definire nuovi tipi.

• Non incoraggiano singole fonti di verità. Molte API esistenti incoraggiano a ridefinire ripetutamente i tipi di dati personalizzati, con la fonte di verità distribuita nell'intera base di codice.

• Non generano errori.Molti in realtà non generano errori, costringendoti a mandare a capo ovunque.Sebbene utile ai tempi dei callback, non utilizzarli thrownel moderno JavaScript rende il codice molto più complesso.

• Non precompilano gli schemi.Molti validatori definiscono gli schemi come semplici oggetti JavaScript, il che significa che delegano l'analisi della logica dello schema al tempo di validazione, rendendoli molto più lenti.

• Sono strettamente collegati ad altri problemi: molti validatori sono strettamente collegati a Express o ad altri framework, il che si traduce in un codice unico e confuso che non è riutilizzabile nella codebase.

• Usano JSON Schema. Non fraintendermi, JSON Schema può essere utile. Ma è un po' come HATEOAS: di solito è molto più complesso del necessario e non stai sfruttando nessuno dei suoi vantaggi. (Scusa, l'ho detto .)

Naturalmente, non tutte le librerie di validazione soffrono di tutti questi problemi, ma la maggior parte di esse ne presenta almeno uno. Se hai già riscontrato questo problema in precedenza, Superstruct potrebbe piacerti.

Il che mi porta a come Superstruct risolve questi problemi...

Principles

1. Tipi personalizzabili La potenza di Superstruct sta nel rendere semplice la definizione di un intero set di tipi di dati personalizzati specifici per la tua applicazione e definiti in un unico posto, in modo da avere il pieno controllo sui tuoi requisiti.

2. Impostazioni predefinite senza opinione. Superstruct viene fornito con tipi JavaScript nativi e tutto il resto è personalizzabile, quindi non dovrai mai lottare per ignorare le decisioni prese dal "core" che differiscono dalle esigenze della tua applicazione.

3. Interfacce componibili Le interfacce Superstruct sono componibili, quindi puoi suddividere pezzi di dati comunemente ripetuti in componenti e comporli per creare oggetti più complessi.

4. Schemi concisi. Gli schemi in Superstruct sono progettati per essere estremamente concisi ed espressivi. Ciò li rende molto facili da leggere e scrivere, incoraggiandoti ad avere una copertura completa della convalida dei dati.

5. Validatori compilati.Superstruct fa il lavoro di compilazione dei suoi schemi in anticipo, in modo da non perdere tempo eseguendo attività costose per ogni chiamata alle funzioni di convalida nei percorsi del codice attivo.

6. Errori utili Gli errori generati da Superstruct contengono tutte le informazioni necessarie per convertirli facilmente in errori specifici dell'applicazione, il che significa errori più utili per i tuoi utenti finali!

7. API familiare. L'API Superstruct è stata fortemente ispirata da Typescript , Flow , Go e GraphQL . Se hai familiarità con qualcuno di questi, la sua API di definizione dello schema sarà molto naturale da usare, così puoi iniziare rapidamente.

Demo

Prova la demo live su JSFiddle per avere un'idea di come funziona l'API o per verificare rapidamente il tuo caso d'uso:

Examples

L'API di Superstruct è molto flessibile e può essere utilizzata per una varietà di casi d'uso sui tuoi server e nel browser. Ecco alcuni esempi di modelli comuni...

• Convalida di base
• Tipi personalizzati
• Valori standard
• Valori facoltativi
• Composizione di strutture
• Errori di lancio
• Restituzione di errori
• Errori personalizzati

Documentation

Leggi la guida introduttiva per familiarizzare con il funzionamento di Superstruct. Successivamente, controlla il riferimento completo all'API per informazioni più dettagliate su strutture, tipi ed errori...

• Guida
  • Installazione di Superstruct
  • Creazione di strutture
  • Definizione dei tipi di dati personalizzati
  • Impostazione dei valori predefiniti
  • Generazione di errori personalizzati
  • Convalida di forme complesse
  • Composizione di strutture
• Riferimento
  • API
  • Structs
  • Types
  • Errors
• Risorse

License

Questo pacchetto èMIT-licensed.