Impresionante módulo comunitario
  1. paxina principal
  2. módulo comunitario
  3. Uso

Unha forma sinxela e compoñeble
de validar datos en JavaScript.



Uso • Por que • Principios • Demostración • Exemplos • Documentación



Superstruct facilita a definición de interfaces e despois validar os datos de JavaScript contra elas. A súa API de anotación de tipos inspirouse en Typescript , Flow , Go e GraphQL , o que lle dá unha API familiar e fácil de entender.

Pero Superstruct está deseñado para validar datos en tempo de execución, polo que arroxa (ou devolve) erros de execución detallados para ti ou para os teus usuarios finais. Isto é especialmente útil en situacións como aceptar entradas arbitrarias nunha API REST ou GraphQL. Pero incluso pode usarse. para validar estruturas de datos internas en tempo de execución cando sexa necesario.


Usage

Superstruct exporta unha structfábrica para crear estruturas que poidan 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 de JavaScript nativos de forma inmediata. Pero tamén pode definir os seus propios tipos de datos personalizados, específicos para os requisitos da súa aplicación, mediante 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 admite casos de uso máis complexos, como definir estruturas de lista ou escalares, aplicar valores predeterminados, compoñer estruturas unhas dentro das outras, devolver erros en lugar de botalos, etc. Para obter máis información, lea a documentación completa .


Why?

Hai moitas bibliotecas de validación existentes: joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Pero presentan moitos problemas que fan que a súa base de código sexa difícil de manter...

  • Non expoñen erros detallados. Moitos validadores simplemente devolven erros de cadea ou booleanos sen ningún detalle sobre o porqué, polo que é difícil personalizar os erros para que sexan útiles para os usuarios finais.

  • Dificultan os tipos personalizados. Moitos validadores envían tipos integrados como correos electrónicos, URL, UUID, etc. sen xeito de saber o que buscan e API complicadas para definir novos tipos.

  • Non fomentan fontes únicas de verdade. Moitas API existentes animan a redefinir tipos de datos personalizados unha e outra vez, distribuíndo a fonte da verdade por toda a base de código.

  • Non xeran erros. Moitos non arroxan os erros, o que o obriga a envolver en todas partes. Aínda que é útil na época das devolucións de chamada, non usar throwJavaScript moderno fai que o código sexa moito máis complexo.

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

  • Están estreitamente vinculados a outras cuestións. Moitos validadores están estreitamente vinculados a Express ou a outros frameworks, o que dá como resultado un código único e confuso que non se pode reutilizar na base de código.

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

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

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


Principles

  1. Tipos personalizables. O poder de Superstruct está en facilitar a definición de todo un conxunto de tipos de datos personalizados específicos para a súa aplicación e definidos nun único lugar, para que teña control total sobre os seus requisitos.

  2. Valores predeterminados sen opinión. Superstruct envíase con tipos de JavaScript nativos e todo o demais é personalizable, polo que nunca terás que loitar para anular as decisións tomadas polo "núcleo" que difiren das necesidades da túa aplicación.

  3. Interfaces compoñentes. As interfaces de Superstruct son compoñentes, polo que podes descomponer os datos que se repiten habitualmente en compoñentes e compoñelos para construír os 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, o que che anima a ter unha cobertura completa de validación de datos.

  5. Validadores compilados. Superstruct fai o traballo de compilar os seus esquemas por adiantado, para que non dedique tempo a realizar tarefas caras por cada chamada ás funcións de validación nas rutas do código activo.

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

  7. API familiar. A API de Superstruct inspirouse en gran medida en Typescript , Flow , Go e GraphQL . Se estás familiarizado con algún destes, a súa API de definición de esquema parecerá moi natural de usar, para que poidas 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 teu caso de uso:

Captura de pantalla de demostración.


Examples

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


Documentation

Le a guía de inicio 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.

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