Módulo comunitario incrible

Un xeito sinxelo e composíbel
de validar datos en JavaScript.



UsoPor que?PrincipiosDemostraciónExemplosDocumentación



Superestrutura facilita a definición de interfaces e despois validación de datos JavaScript contra elas. A súa API de anotación de tipo inspirouse en Typescript , Flow , Go e GraphQL , dándolle unha API familiar e fácil de entender.

Pero Superstruct está deseñado para validar datos en tempo de execución, polo que lanza (ou devolve) erros de tempo de execución detallados para vostede ou os seus usuarios finais. Isto é especialmente útil en situacións como a aceptación de entrada arbitraria nunha API REST ou GraphQL. Pero incluso pode usarse para validar as estruturas de datos internas en tempo de execución cando sexa necesario.


Usage

Superstruct exporta unha structfábrica para crear estruturas que poden validar datos contra un esquema específico:

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

Recoñece todos os tipos nativos de JavaScript fóra da caixa. Pero tamén podes definir os teus propios tipos de datos personalizados, específicos para os requisitos da túa aplicación, usando a superstructexportación:

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 tamén soporta casos de uso máis complexos como definir estruturas de lista ou escalares, aplicar valores predeterminados, compoñer estruturas entre si, devolver erros en vez de lanzalos, etc. Para obter máis información, lea a documentación completa .


Why?

Moitas existente Validación Hai libraries- joi, express-validator, validator.js, yup, ajv, is-my-json-valid... pero exhiben moitas e delincuencia que levan a súa base de código converténdose no difícil manter ...

  • Non expoñen erros detallados. Moitos validadores simplemente devolven erros de cadea ou booleanos sen detalles sobre o motivo, o que dificulta a personalización dos erros para que sexa útil para os usuarios finais.

  • Eles dificultan os tipos personalizados. Moitos validadores inclúense tipos incorporados como correos electrónicos, URL, UUID, etc. sen xeito de saber o que comproban e API complicadas para definir novos tipos.

  • Non fomentan fontes de verdade únicas. Moitas API existentes fomentan a redefinición de tipos de datos personalizados unha e outra vez, estendéndose a fonte de verdade en toda a súa base de código.

  • Non lanzan erros. Moitos non producen os erros, o que che obriga a envolverte por todas partes. Aínda que é útil nos tempos das devolucións de chamada, non usar throwo JavaScript moderno fai que o código sexa moito máis complexo.

  • Non precompilan esquemas. Moitos validadores definen os esquemas como obxectos JavaScript sinxelos, o que significa que delegan a análise da lóxica do esquema no tempo de validación, o que os fai moito máis lentos.

  • Están estreitamente combinados con outras preocupacións. Moitos validadores están estreitamente unidos a Express ou a outros frameworks, o que resulta nun código único e confuso que non se pode reutilizar na súa base de código.

  • Usan o esquema JSON. Non me malinterpretes, o esquema JSON pode ser útil. Pero é como HATEOAS; normalmente é moito máis complexo do que necesitas e non estás a usar ningún dos seus beneficios. (Sentímolo, xa o dixen) .)

Por suposto, non todas as bibliotecas de validación sofren todos estes problemas, pero a maioría delas presentan polo menos un. Se atopaches este problema antes, quizais che guste Superstruct.

O que me leva a como Superstruct resolve estes problemas ...


Principles

  1. Tipos personalizables. O poder de Superstruct consiste en facilitar a definición de todo un conxunto de tipos de datos personalizados que son específicos da súa aplicación e que se definen nun lugar para que poida controlar completamente as súas necesidades.

  2. Valores predeterminados non opinados. Superestrutúrase con tipos nativos de JavaScript e todo o demais é personalizable, polo que nunca terás que loitar por anular as decisións tomadas por "núcleo" que difiran das necesidades da túa aplicación.

  3. Interfaces composábeis . As interfaces de superestrutura son composíbeis, polo que pode dividir os datos que se repiten normalmente en compoñentes e compoñelos para acumular obxectos máis complexos.

  4. Esquemas concisos. Os esquemas de Superstruct están deseñados para ser extremadamente concisos e expresivos. Isto fai que sexan moi fáciles de ler e escribir, animándolle a ter unha cobertura completa de validación de datos.

  5. Validadores compilados. Superstruct fai a compilación dos seus esquemas de xeito anticipado, de xeito que non dedica tempo a realizar tarefas caras por cada chamada ás funcións de validación dos seus camiños de código quente.

  6. Erros útiles. Os erros que lanza Superstruct conteñen toda a información que precisa para convertelos en erros específicos da aplicación, o que significa erros máis útiles para os usuarios finais.

  7. API coñecida . A API de Superstruct inspirouse en Typescript , Flow , Go e GraphQL . Se está familiarizado con algún deles, entón a súa definición de esquema API será moi natural de usar, para que poida comezar rapidamente.


Demo

Proba a demostración en directo en JSFiddle para ter unha idea de como funciona a API ou para verificar rapidamente o seu caso de uso:

Captura de pantalla de demostración.


Examples

A API de Superstruct é moi flexible, o que permite que se utilice para unha variedade de casos de uso nos servidores e no navegador. Aquí tes algúns exemplos de patróns comúns ...


Documentation

Lea a guía inicial para familiarizarse co funcionamento de Superstruct. Despois diso, consulte a referencia completa da API para obter información máis detallada sobre estruturas, tipos e erros ...


License

Este paquete é MIT-licensed.