Módulo de comunidad impresionante

Una forma simple y componible
de validar datos en JavaScript.



Uso¿Por qué?PrincipiosDemostraciónEjemplosDocumentación



Superstruct facilita la definición de interfaces y luego validar los datos de JavaScript contra ellas. Su API de anotación de tipo 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 detallados en tiempo de ejecución 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 structfábrica 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 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 también admite casos de uso más complejos, como definir listas o estructuras escalares, aplicar valores predeterminados, componer estructuras entre sí, devolver errores en lugar de arrojarlos, etc. Para obtener más información, lea la documentación completa .


Why?

Un montón de validación existente Existen bibliotecas- joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Pero Ellos exhiben muchas y delincuencia que conducen a su base de código Ser difícil de mantener ...

  • No exponen errores detallados.Muchos validadores simplemente devuelven errores de cadena o valores booleanos sin ningún detalle sobre el motivo, 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.

  • No arrojan errores. Muchos en realidad no arrojan los errores, lo que lo obliga a ajustarse a todas partes. Aunque es útil en los días de las devoluciones de llamada, no usarlo throwen JavaScript moderno hace que el código sea mucho más complejo.

  • 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 toda 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 presenta al menos uno. Si ya 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 usted tenga un 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 las piezas de datos que se repiten comúnmente en componentes y componerlas 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 tareas costosas 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. Aquí hay 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 es MIT-licensed.