Удивительный модуль сообщества

Простой и составной способ
проверить данные в 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?

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

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

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

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

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

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


Demo

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

Демо скриншот.


Examples

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


Documentation

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


License

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