Repository navigation
Releases
v0.1.0 — Литералы и дискриминированные объединения
zod-1c v0.1.0
Добавлены литералы и дискриминированные объединения - механизмы
для описания объектов с взаимоисключающими полями. Типичный кейс:
{
"method": "pickup",
"pickup": { "address": "...", "storeId": 42 }
}или
{
"method": "delivery",
"delivery": { "address": "...", "courierPhone": "..." }
}Раньше такое описывалось громоздким Zod.Объединение() с перебором всех
вариантов и «кашей» из ошибок. Теперь - одна декларативная конструкция,
аналог z.discriminatedUnion() из Zod 4.
Что нового
Zod.Литерал(Значение)
Схема точного значения. Пропускает только значение, полностью совпадающее
по типу и содержимому:
Zod.Литерал("pickup").Проверить("pickup"); // успешно
Zod.Литерал("pickup").Проверить("delivery"); // провал
Zod.Литерал("1").Проверить(1); // провал (тип разный)Zod.ДискриминированноеОбъединение(Дискриминатор, Варианты)
Выбирает ровно один вариант по значению дискриминатора. Валидация
идёт только по нему - отсюда строгая взаимосвязь полей, точные ошибки и
производительность O(1) вместо O(n).
СхемаЗаказа = Zod.ДискриминированноеОбъединение("method", Новый Массив(
Zod.СтрогийОбъект()
.Поле("method", Zod.Литерал("pickup"))
.Поле("pickup", Zod.Объект()
.Поле("address", Zod.Строки().Непустая())
.Поле("storeId", Zod.Числа().Целое())),
Zod.СтрогийОбъект()
.Поле("method", Zod.Литерал("delivery"))
.Поле("delivery", Zod.Объект()
.Поле("address", Zod.Строки().Непустая())
.Поле("courierPhone", Zod.Строки().Телефон()))
));
// pickup
СхемаЗаказа.Проверить(Новый Структура(
"method, pickup", "pickup",
Новый Структура("address, storeId", "ул. Ленина, 1", 42)));
// недопустимый method
СхемаЗаказа.Проверить(Новый Структура("method", "unknown"));Валидация конфигурации
Ошибки в конфигурации ловятся при построении схемы, а не в рантайме:
- дубликат значения дискриминатора;
- поле-дискриминатор не
Литерал(); - у варианта отсутствует поле-дискриминатор;
- вариант не является объектной схемой.
Новые публичные методы схемы
Для использования плагинами и составными схемами:
Схема.ПолучитьТип()- тип схемы.Схема.ПолучитьЛитерал()- значение литерала.Схема.НайтиСхемуПоля(Имя)- схема поля по имени.
Совместимость
- Обратная совместимость полная. Все изменения аддитивны: новые
фабрики, новые ветки в диспетчере типов. Существующий код не затронут. - Совместимость с
swagger-1c2.0.0+ сохраняется. - Совместимость с
.Необязательное(),.ДопускаетNull(),
.Трансформировать(),.Проверка()- работает как для обычных схем. - Покрытие тестами: 23 новых теста в YaxUnit
(Zod_Литерал_ДискриминированноеОбъединение_Тесты).
Полный список изменений
См. CHANGELOG.md.
0.0.3
[0.0.3] - 31.10.2026
Первый публичный релиз библиотеки. Включает накопленный функционал
предыдущих итераций и новое семейство модификаторов для работы с null.
Добавлено
Базовые типы и фабрики
- Фабрики примитивов:
Zod.Строки,Zod.Числа,Zod.Булевы,Zod.Даты,
Zod.Любое. - Фабрики объектов:
Zod.Объект,Zod.СтрогийОбъект,Zod.СвободныйОбъект,
Zod.Запись. - Фабрики коллекций:
Zod.Массивы,Zod.Перечисление,Zod.Объединение. - Фабрики приведения:
Zod.ПриведеннаяСтрока,Zod.ПриведенноеЧисло,
Zod.ПриведенноеБулево,Zod.ПриведеннаяДата. - Строковые форматы: Email, URL, UUID, IPv4, IPv6, ДатаISO, ХешMD5, ХешSHA256,
Телефон, ИНН, ИНН10, ИНН12, СНИЛС, ОГРН, ОГРНИП, КПП, БИК, РасчетныйСчет,
ОКТМО, ОКПО, Луна, EAN13, EAN8, ISBN10, ISBN13. - Ссылочные типы 1С:
Zod.Справочник,Zod.Документ,
Zod.ПеречислениеСсылка,Zod.ПланВидовХарактеристик,Zod.ПланСчетов,
Zod.ПланОбмена,Zod.БизнесПроцесс,Zod.Задача,Zod.ЛюбаяСсылка,
Zod.СоставнаяСсылка. - Объекты 1С:
Zod.ОбъектДокумента,Zod.ОбъектСправочника,
Zod.ОбъектПланаВидовХарактеристик,Zod.ОбъектПланаСчетов,
Zod.ОбъектПланаОбмена,Zod.ОбъектБизнесПроцесса,Zod.ОбъектЗадачи.
Модификаторы и утилиты схем
- Модификаторы строк:
.МинДлина,.МаксДлина,.Непустая,.Паттерн,
а также все строковые форматы как методы. - Модификаторы чисел:
.МинЗначение,.МаксЗначение,.Целое,
.Положительное. - Модификаторы объектов и массивов:
.Поле,.Элемент,.МинЭлементов,
.МаксЭлементов. - Модификатор ссылок:
.ТолькоСуществующая. - Модификатор объектов 1С:
.ЗаполнятьПоУмолчанию,.ТабличнаяЧасть. - Генерация шаблонов:
.СоздатьПустой,.СоздатьМинимальный.
Новое в этой версии: работа с null
- Модификатор
.ДопускаетNull(). Разрешает значениеНеопределено(в JSON -
null), но не разрешает отсутствие ключа в объекте. Используется для
OpenAPI-свойств, которые вrequiredиnullable: true. - Утилиты
.ДопускаетОтсутствие()и.ДопускаетНеопределено()для
программной проверки возможностей схемы. - Метод
.ЭтоНеобязательное()сохранён как алиас.ДопускаетОтсутствие()
для обратной совместимости. ПроверитьВнутреннийучитывает флагДопускаетNull: значение
Неопределенопроходит валидацию, если схема помечена.ДопускаетNull().ПроверитьОбъектиспользует.ДопускаетОтсутствие()для различения
«ключа нет» и «ключ есть, значение Неопределено».
Кастомные проверки и трансформеры
.Проверка(ОбъектПроверки)- добавление пользовательской проверки.
Проверка - объект с методомПроверить(Значение). Проверки применяются
только при успешной базовой валидации..Трансформировать(ОбъектТрансформера)- добавление трансформера.
Трансформер - объект с методомПреобразовать(Значение), применяется
до валидации.- Готовые трансформеры:
Zod_Трансформер_Телефон(нормализация телефона РФ),
Zod_Трансформер_ПустоеВНеопределено(пустая строка в Неопределено). - Фабрика
Zod.НормализованныйТелефондля быстрого подключения трансформера
телефона.
Утилиты и вспомогательные функции
Zod.СериализоватьСсылку- ссылка 1С в структуру{type, id}.Zod.СериализоватьОбъект- объект 1С в структуру с реквизитами и
табличными частями.Zod.ЭтоСсылка1С- предикат для проверки, является ли значение ссылкой.Zod.ПлоскиеОшибки- ошибки в формате{formErrors, fieldErrors}.Zod.ДеревоОшибок- ошибки в виде вложенной структуры.Zod.КрасивыйТекстОшибок- человекочитаемая строка ошибок.Zod.ПроверитьПараметрыЗапроса(Запрос, Схема)- адаптер для валидации
query-параметров HTTP-сервиса.
Изменено
- Внутренняя логика
Zod_Схема.ПроверитьВнутреннийтеперь учитывает
флагСостояние.ДопускаетNull. - Внутренняя логика
Zod_Схема.ПроверитьОбъектиспользует метод
.ДопускаетОтсутствие()вместо.ЭтоНеобязательное()для различения
отсутствия ключа и значения Неопределено.
Ограничения
- В общих модулях 1С нет переменных модуля, поэтому
Zod_Схема- это
обработка, и каждая схема является независимым объектом. Кэширование
схем в общем модуле невозможно. .Необязательное()ведёт себя как.nullish()в Zod (TypeScript):
пропускает и отсутствие ключа, иНеопределено. Для строгой семантики
.optional()используйте.ДопускаетNull()с явной проверкой..Паттерн()работает какRegExp.test(): ищет совпадение в любом месте
строки. Для полного совпадения используйте явные анкоры^...$.
Совместимость
Совместимость с swagger-1c 2.0.0 и выше:
Swag_ZodАдаптервswagger-1cиспользует функцииzod-1cдля
рантайм-валидации запросов и ответов HTTP-сервисов.Zod.ДопускаетNull()используется для корректного преобразования поля
nullable: trueиз OpenAPI-схем.- При отсутствии
zod-1cв конфигурацииswagger-1cработает без изменений
(генерация спецификации не требует валидации).