Impresionante módulo comunitario
  1. página delantera
  2. módulo comunitario
  3. Uso

Una forma sencilla y componible
de validar datos en JavaScript.



Uso • ¿ Por qué? • Principios • Demostración • Ejemplos • Documentación



Superstruct facilita la definición de interfaces y luego valida los datos de JavaScript con ellas. Su API de anotación de tipo se inspiró en Typescript , Flow , Go y GraphQL , lo que le brinda 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 puede usarse 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 con 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 desde el primer momento, pero también puedes definir tus propios tipos de datos personalizados (específicos para los requisitos de tu 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 unas dentro de otras, devolver errores en lugar de generarlos, etc. Para obtener más información, lea la documentación completa .


Why?

Existen muchas bibliotecas de validación: , , , , joi... express-validatorPero validator.jspresentan yupmuchos problemas que hacen que su código base se vuelva difícil de mantener...ajvis-my-json-valid

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

  • Hacen que los tipos personalizados sean difíciles. Muchos validadores vienen 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 alientan la redefinición de tipos de datos personalizados una y otra vez, con la fuente de verdad repartida por toda la base de código.

  • No arrojan errores. Muchos en realidad no arrojan los errores, lo que te obliga a ajustar en 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 precompilan esquemas. Muchos validadores definen 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 es reutilizable en toda su base de código.

  • Usan el esquema JSON. No me malinterpretes, el esquema JSON puede ser útil. Pero es algo así como HATEOAS: generalmente 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 sufren todos estos problemas, pero la mayoría 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 radica en facilitar la definición de un conjunto completo de tipos de datos personalizados que son específicos de su aplicación y definidos en un solo lugar, para que tenga control total sobre sus requisitos.

  2. Valores predeterminados sin opinión. Superstruct viene 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 Superstruct son componibles, por lo que puede dividir piezas de datos que se repiten comúnmente en componentes y componerlas para construir 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 errores específicos de su propia 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 Typecript , Flow , Go y GraphQL . Si está familiarizado con alguno de ellos, su API de definición de esquema le resultará muy natural de usar, por lo que podrá 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 utilizarla 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 cómo funciona Superstruct. Después de eso, consulte la referencia completa de API para obtener información más detallada sobre estructuras, tipos y errores...


License

Este paquete esMIT-licensed.

© Copyright 2012-2024 fibjs.org | Apóyanos