Modulo community fantastico

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



UtilizzoPerché?PrincipiDemoEsempiDocumentazione



Superstruct semplifica la definizione delle interfacce e quindi la convalida dei dati JavaScript rispetto a esse: l'API di annotazione dei tipi è stata ispirata da Typescript , Flow , Go e GraphQL , offrendo 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 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 factory struct per la creazione di strutture in grado di convalidare i dati su 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 di JavaScript nativi, ma puoi anche definire i tuoi tipi di dati personalizzati, specifici per i requisiti della tua applicazione, usando l'esportazione 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 elenchi o strutture scalari, l'applicazione di valori predefiniti, la composizione di strutture l'una all'interno dell'altra, la restituzione di errori anziché il loro lancio, 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 portano a rendere la tua base di codice difficile da mantenere ...

  • Non espongono errori dettagliati: molti validatori restituiscono semplicemente errori solo stringa o booleani senza dettagli sul perché, rendendo difficile personalizzare gli errori per essere utili agli utenti finali.

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

  • Non incoraggiano singole fonti di verità e molte API esistenti incoraggiano a ridefinire continuamente tipi di dati personalizzati, con la fonte di verità diffusa su tutta la base di codice.

  • Non generano errori, molti in realtà non generano errori, costringendoti a finire dappertutto. Sebbene utile ai giorni dei callback, non usare il throw nel moderno JavaScript rende il codice molto più complesso.

  • Non pre-compilano 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 altre preoccupazioni e molti validatori sono strettamente associati a Express o ad altri framework, il che si traduce in codice unico e confuso che non è riutilizzabile nella tua base di codice.

  • Usano JSON Schema. Non fraintendetemi, JSON Schema può essere utile, ma è un po 'come gli HATEOAS: di solito è molto più complessa del necessario e non state usando nessuno dei suoi benefici. .)

Ovviamente, non tutte le librerie di convalida soffrono di tutti questi problemi, ma la maggior parte di essi ne presenta almeno uno.

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


Principles

  1. Tipi personalizzabili Il potere di Superstruct sta nel semplificare la definizione di un intero set di tipi di dati personalizzati specifici per la tua applicazione e definiti in un'unica posizione, in modo da avere il pieno controllo delle tue esigenze.

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

  3. Interfacce componibili Le interfacce Superstruct sono componibili, quindi è possibile scomporre 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, il che li rende molto facili da leggere e scrivere, incoraggiandoti ad avere una copertura completa della validazione dei dati.

  5. Validatori compilati Superstruct svolge il lavoro di compilazione anticipata dei suoi schemi, in modo da non perdere tempo a svolgere attività costose per ogni chiamata alle funzioni di convalida nei percorsi di hot code.

  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 gli utenti finali!

  7. API familiare L'API Superstruct è stata fortemente ispirata da Typescript , Flow , Go e GraphQL Se hai familiarità con una di queste, l'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 della demo.


Examples

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


Documentation

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


License

Questo pacchetto è MIT-licensed .