Ús: JavaScript a la fibra

Una manera senzilla i composable
de validar dades en JavaScript.

Ús • Per què • Principis • Demostració • Exemples • Documentació

Superstruct facilita la definició d'interfícies i després validar les dades de JavaScript amb elles. La seva API d'anotació de tipus s'ha inspirat en Typescript , Flow , Go i GraphQL , donant-li una API familiar i fàcil d'entendre.

Però Superstruct està dissenyat per validar dades en temps d'execució, de manera que genera (o retorna) errors d'execució detallats per a vostè o els usuaris finals. Això és especialment útil en situacions com acceptar entrades arbitràries en una API REST o GraphQL. Però fins i tot es pot utilitzar. per validar les estructures de dades internes en temps d'execució quan sigui necessari.

Usage

Superstruct exporta una structfàbrica per crear estructures que poden validar dades amb un esquema específic:

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()`.

Reconeix tots els tipus de JavaScript natius de manera immediata. Però també podeu definir els vostres propis tipus de dades personalitzades (específics per als requisits de la vostra aplicació) mitjançant l' superstructexportació:

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 també admet casos d'ús més complexos, com ara definir estructures de llista o escalar, aplicar valors predeterminats, compondre estructures una dins de l'altra, retornar errors en lloc de llançar-los, etc. Per obtenir més informació, llegiu la documentació completa .

Why?

Hi ha moltes biblioteques de validació existents: joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Però presenten molts problemes que fan que la vostra base de codi sigui difícil de mantenir...

No exposen errors detallats. Molts validadors simplement retornen errors només de cadena o booleans sense cap detall sobre el perquè, dificultant la personalització dels errors perquè siguin útils per als usuaris finals.
Dificulten els tipus personalitzats. Molts validadors s'envien amb tipus integrats, com ara correus electrònics, URL, UUID, etc., sense cap manera de saber què cerquen, i API complicades per definir nous tipus.
No fomenten fonts úniques de veritat. Moltes API existents fomenten la redefinició dels tipus de dades personalitzats una i altra vegada, amb la font de la veritat distribuïda per tota la base de codi.
No generen errors. Molts en realitat no els llancen, cosa que us obliguen a embolicar a tot arreu. Tot i que és útil en l'època de les devolucions de trucada, no utilitzar throwen JavaScript modern fa que el codi sigui molt més complex.
No compilen prèviament esquemes. Molts validadors defineixen els esquemes com a objectes JavaScript senzills, el que significa que deleguen l'anàlisi de la lògica de l'esquema al temps de validació, fent-los molt més lents.
Estan estretament vinculats a altres preocupacions. Molts validadors estan estretament vinculats a Express o a altres marcs, la qual cosa dóna lloc a un codi únic i confús que no es pot reutilitzar a tota la vostra base de codi.
Utilitzen l'esquema JSON. No m'equivoquis, l'esquema JSON pot ser útil. Però és una mica com HATEOAS: normalment és molt més complex del que necessites i no n'estàs utilitzant cap dels seus avantatges. (Ho sento, ho he dit). .)

Per descomptat, no totes les biblioteques de validació pateixen tots aquests problemes, però la majoria en presenten almenys un. Si us heu trobat amb aquest problema abans, potser us agrada Superstruct.

El que em porta a com Superstruct resol aquests problemes...

Principles

Tipus personalitzables. El poder de Superstruct està en facilitar la definició d'un conjunt complet de tipus de dades personalitzats específics per a la vostra aplicació i definits en un sol lloc, de manera que tingueu un control total sobre els vostres requisits.
Valors predeterminats sense opinions. Superstruct s'envia amb tipus de JavaScript natius i tota la resta es pot personalitzar, de manera que mai no haureu de lluitar per anul·lar les decisions preses pel "núcleament" que difereixen de les necessitats de la vostra aplicació.
Interfícies componibles. Les interfícies de Superstruct són componibles, de manera que podeu descompondre les dades que es repeteixen habitualment en components i compondre-les per crear els objectes més complexos.
Esquemes concisos. Els esquemes de Superstruct estan dissenyats per ser extremadament conciss i expressius. Això fa que siguin molt fàcils de llegir i escriure, la qual cosa us anima a tenir una cobertura completa de validació de dades.
Validadors compilats. Superstruct fa la feina de compilar els seus esquemes per endavant, de manera que no gasta temps realitzant tasques cares per a cada trucada a les funcions de validació a les rutes de codi d'activació.
Errors útils. Els errors que llança Superstruct contenen tota la informació que necessiteu per convertir-los fàcilment en errors específics de l'aplicació, la qual cosa significa errors més útils per als vostres usuaris finals!
API coneguda. L'API Superstruct es va inspirar molt en Typescript , Flow , Go i GraphQL . Si esteu familiaritzat amb algun d'ells, la seva API de definició d'esquemes us semblarà molt natural d'utilitzar, de manera que podreu començar ràpidament.

Demo

Proveu la demostració en directe a JSFiddle per fer-vos una idea de com funciona l'API o per verificar ràpidament el vostre cas d'ús:

Examples

L'API de Superstruct és molt flexible, la qual cosa permet utilitzar-la per a una varietat de casos d'ús als vostres servidors i al navegador. Aquí teniu alguns exemples de patrons comuns...

Documentation

Llegiu la guia inicial per familiaritzar-vos amb com funciona Superstruct. Després d'això, consulteu la referència completa de l'API per obtenir informació més detallada sobre estructures, tipus i errors...

License

Aquest paquet ésMIT-licensed.

Guia de desenvolupament

Mòdul bàsic

objectes incorporats

mòdul comunitari