Fantastico modulo della community

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



UtilizzoPerchéPrincipiDemoEsempiDocumentazione



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

Ma Superstruct è progettato per la convalida dei dati in fase di runtime, quindi genera (o restituisce) errori di runtime dettagliati per te o per 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 struct factory per la creazione di 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 tutti i tipi JavaScript nativi immediatamente. Ma puoi anche definire i tuoi tipi di dati personalizzati, specifici per i requisiti dell'applicazione, utilizzando l'esportazione di 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 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 dentro l'altra, la restituzione di errori invece di lanciarli, ecc. Per maggiori informazioni leggere la Documentazione completa.


Why?

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

  • Non espongono errori dettagliati.Molti validatori restituiscono semplicemente errori di sola stringa o booleani senza alcun dettaglio sul perché, rendendo difficile personalizzare gli errori per essere utile per gli utenti finali.

  • Rendono i tipi personalizzati difficili. Molti validatori vengono forniti con tipi incorporati come e-mail, URL, UUID, ecc. Senza alcun modo per sapere cosa cercano e API complicate per la definizione di nuovi tipi.

  • Non incoraggiano singole fonti di verità. Molte API esistenti incoraggiano la ridefinizione dei tipi di dati personalizzati più e più volte, con la fonte della verità distribuita su tutta la tua base di codice.

  • Non generano errori. Molti in realtà non generano errori, costringendoti a eseguire il wrapping dappertutto. Sebbene sia utile ai tempi dei callback, non utilizzare il throw nel JavaScript moderno rende il codice molto più complesso.

  • Non pre-compilano 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 convalida, 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 tua base di codice.

  • Usano lo schema JSON. Non fraintendermi, lo schema JSON 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 .)

Ovviamente, non tutte le librerie di convalida soffrono di tutti questi problemi, ma la maggior parte ne mostra almeno uno. Se hai già riscontrato questo problema, Superstruct potrebbe piacerti.

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


Principles

  1. Tipi personalizzabili La potenza di Superstruct consiste nel semplificare la definizione di un intero set di tipi di dati personalizzati specifici per la tua applicazione e definiti in un unico punto, in modo da avere il pieno controllo sulle tue esigenze.

  2. Impostazioni predefinite non supportate 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, in modo da poter suddividere i dati comunemente ripetuti in componenti e comporli per creare gli oggetti più complessi.

  4. Schemi concisi Gli schemi in Superstruct sono progettati per essere estremamente concisi ed espressivi, il che 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 compilare i suoi schemi in anticipo, in modo da non perdere tempo a eseguire compiti costosi per ogni chiamata alle funzioni di convalida nei percorsi del codice a caldo.

  6. Errori utili Gli errori che Superstruct genera contengono tutte le informazioni necessarie per convertirli facilmente in errori specifici dell'applicazione, il che significa errori più utili per gli 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 ti sembrerà molto naturale da usare, quindi 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:

Screenshot demo.


Examples

L'API di Superstruct è molto flessibile, consentendo di utilizzarla per una varietà di casi d'uso sui tuoi server e nel browser. Ecco alcuni esempi di schemi comuni ...


Documentation

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


License

Questo pacchetto è MIT-licensed .