Простой и понятный способ
проверки данных в JavaScript.

Использование • Зачем? • Принципы • Демонстрация • Примеры • Документация

Superstruct позволяет легко определять интерфейсы, а затем проверять данные JavaScript на их основе.Его API аннотаций типов был вдохновлен Typescript , Flow , Go и GraphQL , что дает ему знакомый и простой для понимания API.

Но Superstruct предназначен для проверки данных во время выполнения, поэтому он выдает (или возвращает) подробные ошибки времени выполнения для вас или ваших конечных пользователей. Это особенно полезно в таких ситуациях, как принятие произвольных входных данных в REST или GraphQL API. Но его даже можно использовать. для проверки внутренних структур данных во время выполнения, когда это необходимо.

Usage

Superstruct экспортирует structфабрику для создания структур, которые могут проверять данные на соответствие определенной схеме:

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

Он распознает все собственные типы JavaScript по умолчанию. Но вы также можете определить свои собственные типы данных, соответствующие требованиям вашего приложения, с помощью экспорта 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 поддерживает и более сложные варианты использования, такие как определение списков или скалярных структур, применение значений по умолчанию, объединение структур друг в друга, возврат ошибок вместо их выдачи и т. д. Для получения дополнительной информации прочтите полную документацию .

Why?

Существует множество существующих библиотек проверки — joi, express-validator, validator.js, yup, ajv, is-my-json-valid... Но они обнаруживают множество проблем, которые приводят к тому, что вашу кодовую базу становится трудно поддерживать...

• Они не раскрывают подробные ошибки.Многие валидаторы просто возвращают ошибки в виде строк или логических значений без каких-либо подробностей о том, почему, что затрудняет настройку ошибок так, чтобы они были полезны конечным пользователям.

• Они усложняют пользовательские типы. Многие валидаторы поставляются со встроенными типами, такими как электронные письма, URL-адреса, UUID и т. д., без возможности узнать, что они проверяют, и сложными API для определения новых типов.

• Они не поощряют единый источник истины.Многие существующие API поощряют переопределение пользовательских типов данных снова и снова, при этом источник истины распространяется по всей вашей кодовой базе.

• Они не выдают ошибок. Многие на самом деле не выдают ошибок, вынуждая вас выполнять перенос повсюду. Хотя во времена обратных вызовов это полезно, отсутствие их использования throwв современном JavaScript делает код намного более сложным.

• Они не выполняют предварительную компиляцию схем.Многие валидаторы определяют схемы как простые объекты JavaScript, что означает, что они делегируют анализ логики схемы на время проверки, что делает их намного медленнее.

• Они тесно связаны с другими задачами.Многие валидаторы тесно связаны с Express или другими платформами, что приводит к созданию одноразового, запутанного кода, который невозможно повторно использовать в вашей кодовой базе.

• Они используют схему JSON. Не поймите меня неправильно, схема JSON может быть полезна. Но это что-то вроде HATEOAS — обычно она намного сложнее, чем вам нужно, и вы не используете ни одного из ее преимуществ. (Извините, я сказал это .)

Конечно, не каждая библиотека проверки страдает от всех этих проблем, но у большинства из них есть хотя бы одна. Если вы уже сталкивались с этой проблемой раньше, вам может понравиться Superstruct.

Это подводит меня к тому, как Superstruct решает эти проблемы...

Principles

1. Настраиваемые типы. Сила Superstruct заключается в том, что вы можете легко определить весь набор пользовательских типов данных, специфичных для вашего приложения, и определить их в одном месте , поэтому у вас есть полный контроль над вашими требованиями.

2. Самоуверенные значения по умолчанию. Superstruct поставляется с собственными типами JavaScript, а все остальное можно настраивать, поэтому вам никогда не придется бороться за отмену решений, принятых «ядром», которые отличаются от потребностей вашего приложения.

3. Составные интерфейсы.Интерфейсы надстроек являются составными, поэтому вы можете разбивать часто повторяющиеся фрагменты данных на компоненты и компоновать их для создания более сложных объектов.

4. Краткие схемы. Схемы в Superstruct разработаны так, чтобы быть чрезвычайно краткими и выразительными. Это делает их очень простыми для чтения и записи, что способствует полной проверке данных.

5. Скомпилированные валидаторы. Superstruct заранее выполняет работу по компиляции своих схем, чтобы не тратить время на выполнение дорогостоящих задач для каждого вызова функций проверки в ваших путях горячего кода.

6. Полезные ошибки Ошибки, которые выдает Superstruct, содержат всю информацию, необходимую для легкого преобразования их в ваши собственные ошибки, специфичные для вашего приложения, что означает больше полезных ошибок для ваших конечных пользователей!

7. Знакомый API. API Superstruct был во многом вдохновлен Typescript , Flow , Go и GraphQL . Если вы знакомы с любым из них, то его API определения схемы будет очень естественным в использовании, поэтому вы сможете быстро приступить к работе.

Demo

Попробуйте живую демонстрацию на JSFiddle, чтобы получить представление о том, как работает API, или быстро проверить свой вариант использования:

Examples

API Superstruct очень гибок, что позволяет использовать его для различных случаев использования на ваших серверах и в браузере. Вот несколько примеров распространенных шаблонов...

• Базовая проверка
• Пользовательские типы
• Значения по умолчанию
• Необязательные значения
• Составление структур
• Выдача ошибок
• Возврат ошибок
• Пользовательские ошибки

Documentation

Прочтите руководство по началу работы, чтобы ознакомиться с тем, как работает Superstruct. После этого ознакомьтесь с полным справочником по API для получения более подробной информации о структурах, типах и ошибках...

• Гид
  • Установка суперструктуры
  • Создание структур
  • Определение пользовательских типов данных
  • Установка значений по умолчанию
  • Выдача настраиваемых ошибок
  • Проверка сложных фигур
  • Составление структур
• Ссылка
  • API
  • Structs
  • Types
  • Errors
• Ресурсы

License

Этот пакетMIT-licensed.