Impresionante módulo de comunidad

Una manera simple y composable
para validar datos en JavaScript.



UsoPor quéPrincipiosDemostraciónEjemplosDocumentación



Superstruct hace que sea fácil definir interfaces y luego validar los datos de JavaScript contra ellas. Su API de anotación de tipo se inspiró en Typecript , Flow , Go y GraphQL , lo que le da 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 de 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 internos en tiempo de ejecución cuando sea necesario.


Usage

Superstruct exporta una fábrica de struct para crear estructuras que puedan 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 nativos de JavaScript listos para usar, pero también puede definir sus propios tipos de datos personalizados, específicos para los requisitos de su aplicación, utilizando 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 estructuras de lista o 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?

Hay muchas bibliotecas de validación existentes: joi , express-validator , validator.js , yup , ajv , is-my-json-valid ... Pero exhiben 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 booleanos sin ningún detalle de 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é verifican, y API complicadas para definir nuevos tipos.

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

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

  • No precompilan esquemas. Muchos validadores definen esquemas como objetos JavaScript simples, 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 acoplados a Express u otros marcos, lo que da como resultado un código único y confuso que no es reutilizable en su base de código.

  • Usan el esquema JSON. No me malinterpreten, el esquema JSON puede ser útil, pero es algo así como HATEOAS: por lo general, es mucho más complejo de lo que necesita y no está utilizando 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 exhiben al menos uno. Si ya se ha encontrado con este problema anteriormente, 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 es 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 un control total sobre sus requisitos.

  2. Valores predeterminados sin pines: 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 "core" que difieren de las necesidades de su aplicación.

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

  4. Esquemas breves: los esquemas de 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 Superstruct se inspiró en gran medida en Typescript , Flow , Go y GraphQL . Si está familiarizado con alguno de ellos, entonces 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 su uso 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 inicio 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 .