Módulo de comunidad impresionante

Una forma sencilla y componible
para validar datos en JavaScript.



Uso¿Por qué?PrincipiosDemostraciónEjemplosDocumentación



Superstruct facilita la definición de interfaces y luego la validación de datos de JavaScript contra ellas. Su API de anotación de tipos se inspiró en TypeScript , Flow , Go y GraphQL , lo que le proporciona una API familiar y fácil de entender.

Pero Superstruct está diseñado para validar datos en tiempo de ejecución, por lo que arroja (o devuelve) errores de tiempo de ejecución detallados para usted o sus usuarios finales. Esto es especialmente útil en situaciones como aceptar entradas arbitrarias en una API REST o GraphQL. Pero incluso se puede usar para validar estructuras de datos internas en tiempo de ejecución cuando sea necesario.


Usage

Superstruct exporta una fábrica de struct para crear estructuras que pueden 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()`.

Reconoce todos los tipos de JavaScript nativos listos para usar. Pero también puede definir sus propios tipos de datos personalizados, específicos para los requisitos de su aplicación, mediante la exportación de 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 también admite casos de uso más complejos, como definir listas o estructuras escalares, aplicar valores predeterminados, componer estructuras unas dentro de otras, devolver errores en lugar de arrojarlos, etc. Para obtener más información, lea la documentación completa.


Why?

Hay muchas bibliotecas de validación existentes: joi , express-validator , validator.js , yup , ajv , is-my-json-valid ... Pero presentan muchos problemas que hacen que su base de código sea difícil de mantener ...

  • No exponen errores detallados.Muchos validadores simplemente devuelven errores de cadena o valores booleanos sin ningún detalle del por qué, lo que dificulta la personalización de los errores para que sean útiles para los usuarios finales.

  • Hacen que los tipos personalizados sean difíciles. Muchos validadores se envían con tipos integrados como correos electrónicos, URL, UUID, etc., sin forma de saber qué buscan y API complicadas para definir nuevos tipos.

  • No fomentan fuentes únicas de la verdad. Muchas API existentes fomentan la redefinición de tipos de datos personalizados una y otra vez, con la fuente de la verdad esparcida por toda su base de código.

  • Ellos no generan errores. Muchos en realidad no arrojan los errores, lo que obligó a envolver todo el mundo. Aunque útil en los días de devoluciones de llamada, no usar throw en JavaScript moderna hace que el código mucho más compleja.

  • No compilan previamente los esquemas. Muchos validadores definen los esquemas como objetos simples de JavaScript, lo que significa que delegan el análisis de la lógica del esquema al tiempo de validación, lo que los hace mucho más lentos.

  • Están estrechamente vinculados a otras preocupaciones.Muchos validadores están estrechamente vinculados a Express u otros marcos, lo que da como resultado un código único y confuso que no se puede reutilizar en su base de código.

  • Usan JSON Schema. No me malinterpretes, JSON Schema puede ser útil. Pero es algo así como HATEOAS: por lo general, es mucho más complejo de lo que necesitas y no estás usando ninguno de sus beneficios. (Lo siento, lo dije .)

Por supuesto, no todas las bibliotecas de validación padecen todos estos problemas, pero la mayoría de ellos presenta al menos uno. Si se ha encontrado con este problema antes, es posible que le guste Superstruct.

Lo que me lleva a cómo Superstruct resuelve estos problemas ...


Principles

  1. Tipos personalizables: el poder de Superstruct consiste en facilitar la definición de un conjunto completo de tipos de datos personalizados que son específicos para su aplicación y se definen en un solo lugar, para que tenga control total sobre sus requisitos.

  2. Valores predeterminados sin control. Superstruct se envía con tipos de JavaScript nativos y todo lo demás es personalizable, por lo que nunca tendrá que luchar para anular las decisiones tomadas por el "núcleo" que difieren de las necesidades de su aplicación.

  3. Interfaces componibles. Las interfaces de superestructura se pueden componer, por lo que puede dividir los datos que se repiten comúnmente en componentes y componerlos para construir los objetos más complejos.

  4. Esquemas concisos. Los esquemas en Superstruct están diseñados para ser extremadamente concisos y expresivos, lo que los hace muy fáciles de leer y escribir, lo que lo alienta a tener una cobertura completa de validación de datos.

  5. Validadores compilados: Superstruct hace el trabajo de compilar sus esquemas por adelantado, de modo que no pierda tiempo realizando costosas tareas para cada llamada a las funciones de validación en sus rutas de código activo.

  6. Errores útiles Los errores que arroja Superstruct contienen toda la información que necesita para convertirlos fácilmente en sus propios errores específicos de la aplicación, lo que significa errores más útiles para sus usuarios finales.

  7. API familiar. La API de Superstruct se inspiró en gran medida en Typescript , Flow , Go y GraphQL . Si está familiarizado con alguno de ellos, su API de definición de esquema se sentirá muy natural de usar, por lo que puede comenzar rápidamente.


Demo

Pruebe la demostración en vivo en JSFiddle para tener una idea de cómo funciona la API o para verificar rápidamente su caso de uso:

Captura de pantalla de demostración.


Examples

La API de Superstruct es muy flexible, lo que permite que se utilice para una variedad de casos de uso en sus servidores y en el navegador. A continuación, se muestran algunos ejemplos de patrones comunes ...


Documentation

Lea la guía de introducción para familiarizarse con el funcionamiento de Superstruct. Después de eso, consulte la referencia completa de la API para obtener información más detallada sobre estructuras, tipos y errores ...


License

Este paquete tiene MIT-licensed .