@ivlev-dev/silent-validation 0.0.0-stage → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +573 -2
  3. package/dist/engine.d.ts +15 -0
  4. package/dist/engine.d.ts.map +1 -0
  5. package/dist/engine.js +967 -0
  6. package/dist/engine.js.map +1 -0
  7. package/dist/index.d.ts +15 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +13 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/messages.d.ts +17 -0
  12. package/dist/messages.d.ts.map +1 -0
  13. package/dist/messages.js +508 -0
  14. package/dist/messages.js.map +1 -0
  15. package/dist/model.d.ts +3 -0
  16. package/dist/model.d.ts.map +1 -0
  17. package/dist/model.js +3 -0
  18. package/dist/model.js.map +1 -0
  19. package/dist/modifiers.d.ts +7 -0
  20. package/dist/modifiers.d.ts.map +1 -0
  21. package/dist/modifiers.js +58 -0
  22. package/dist/modifiers.js.map +1 -0
  23. package/dist/property.d.ts +3 -0
  24. package/dist/property.d.ts.map +1 -0
  25. package/dist/property.js +42 -0
  26. package/dist/property.js.map +1 -0
  27. package/dist/registry.d.ts +11 -0
  28. package/dist/registry.d.ts.map +1 -0
  29. package/dist/registry.js +187 -0
  30. package/dist/registry.js.map +1 -0
  31. package/dist/rule.d.ts +7 -0
  32. package/dist/rule.d.ts.map +1 -0
  33. package/dist/rule.js +34 -0
  34. package/dist/rule.js.map +1 -0
  35. package/dist/rules/collections.d.ts +54 -0
  36. package/dist/rules/collections.d.ts.map +1 -0
  37. package/dist/rules/collections.js +116 -0
  38. package/dist/rules/collections.js.map +1 -0
  39. package/dist/rules/comparison.d.ts +36 -0
  40. package/dist/rules/comparison.d.ts.map +1 -0
  41. package/dist/rules/comparison.js +45 -0
  42. package/dist/rules/comparison.js.map +1 -0
  43. package/dist/rules/custom.d.ts +10 -0
  44. package/dist/rules/custom.d.ts.map +1 -0
  45. package/dist/rules/custom.js +12 -0
  46. package/dist/rules/custom.js.map +1 -0
  47. package/dist/rules/numbers.d.ts +61 -0
  48. package/dist/rules/numbers.d.ts.map +1 -0
  49. package/dist/rules/numbers.js +90 -0
  50. package/dist/rules/numbers.js.map +1 -0
  51. package/dist/rules/presence.d.ts +34 -0
  52. package/dist/rules/presence.d.ts.map +1 -0
  53. package/dist/rules/presence.js +66 -0
  54. package/dist/rules/presence.js.map +1 -0
  55. package/dist/rules/strings.d.ts +102 -0
  56. package/dist/rules/strings.d.ts.map +1 -0
  57. package/dist/rules/strings.js +234 -0
  58. package/dist/rules/strings.js.map +1 -0
  59. package/dist/rules/types.d.ts +76 -0
  60. package/dist/rules/types.d.ts.map +1 -0
  61. package/dist/rules/types.js +128 -0
  62. package/dist/rules/types.js.map +1 -0
  63. package/dist/schema.d.ts +11 -0
  64. package/dist/schema.d.ts.map +1 -0
  65. package/dist/schema.js +147 -0
  66. package/dist/schema.js.map +1 -0
  67. package/dist/thenable.d.ts +4 -0
  68. package/dist/thenable.d.ts.map +1 -0
  69. package/dist/thenable.js +16 -0
  70. package/dist/thenable.js.map +1 -0
  71. package/dist/type-validation.d.ts +44 -0
  72. package/dist/type-validation.d.ts.map +1 -0
  73. package/dist/type-validation.js +850 -0
  74. package/dist/type-validation.js.map +1 -0
  75. package/dist/types.d.ts +113 -0
  76. package/dist/types.d.ts.map +1 -0
  77. package/dist/types.js +22 -0
  78. package/dist/types.js.map +1 -0
  79. package/package.json +49 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ivlev-dev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,574 @@
1
- # Temporary Holding Version
1
+ # @ivlev-dev/silent-validation
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Валидация классов на stage 3 декораторах: синхронные и асинхронные проверки, вложенные объекты и коллекции, группы, условные правила и сообщения с поддержкой i18n. Типы полей можно не дублировать декораторами — их проверяет Vite-плагин по TS-аннотациям.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@ivlev-dev/silent-validation)](https://www.npmjs.com/package/@ivlev-dev/silent-validation)
6
+ [![license](https://img.shields.io/npm/l/@ivlev-dev/silent-validation)](https://github.com/ivlev-dev/silent-framework/blob/main/LICENSE)
7
+ [![node](https://img.shields.io/node/v/@ivlev-dev/silent-validation)](https://www.npmjs.com/package/@ivlev-dev/silent-validation)
8
+
9
+ ## Возможности
10
+
11
+ - Декларативные правила на полях класса: наличие, типы, числа, строки, коллекции, сравнения.
12
+ - Валидация из TS-типов без декораторов: Vite-плагин `@ivlev-dev/silent-validation-vite` читает аннотации `accessor`-полей и проверяет типы в рантайме.
13
+ - Имена декораторов в PascalCase: `@Required`, `@IsEmail`, `@Min`, `@Nested`.
14
+ - Синхронный `validate` и асинхронный `validateAsync` с одинаковым набором правил.
15
+ - Вложенная валидация объектов (`@Nested`) и элементов коллекций (`@Each`).
16
+ - Модификаторы: `@ValidateIf`, `@Optional`, `@Label`, `@Groups`, `@ValidateOnSet`.
17
+ - Сообщения: переопределение через `message`/`messageKey`, ярлыки полей, встроенные каталоги `ru`/`en`, глобальная настройка `configureValidation` и собственный резолвер (например, i18next).
18
+ - Пути ошибок вида `address.city` и `items[2].name`.
19
+ - Ошибки с машинно-читаемыми полями: `field`, `rule`, `params`, `value`, `path`, `label`, `index`.
20
+
21
+ ## Установка
22
+
23
+ ```bash
24
+ pnpm add @ivlev-dev/silent-validation
25
+ ```
26
+
27
+ ```bash
28
+ npm install @ivlev-dev/silent-validation
29
+ ```
30
+
31
+ ```bash
32
+ yarn add @ivlev-dev/silent-validation
33
+ ```
34
+
35
+ ## Требования
36
+
37
+ - Node.js >= 22.
38
+ - ESM-only (`type: "module"`), импорт только через `import`.
39
+ - Stage 3 декораторы TypeScript: `experimentalDecorators: false` (значение по умолчанию в современных конфигурациях).
40
+
41
+ ## Быстрый старт
42
+
43
+ ```ts
44
+ import { validate, Required, IsEmail, IsInt, Min, Max } from "@ivlev-dev/silent-validation";
45
+
46
+ class User {
47
+ @Required()
48
+ @IsEmail()
49
+ public accessor email!: string;
50
+
51
+ @IsInt()
52
+ @Min(0)
53
+ @Max(120)
54
+ public accessor age!: number;
55
+ }
56
+
57
+ const user = new User();
58
+ user.email = "user@example.com";
59
+ user.age = 30;
60
+
61
+ const result = validate(user);
62
+ // только stage-3 accessor-поля
63
+
64
+ if (!result.valid) {
65
+ for (const error of result.errors) {
66
+ console.log(error.path, error.rule, error.message);
67
+ }
68
+ }
69
+ ```
70
+
71
+ Валидация явная: декораторы только регистрируют правила, проверка запускается вызовом `validate`, `validateAsync`, `validateOrThrow`, `validateOrThrowAsync`, `validateProperty`/`validatePropertyAsync`, `validatePartial`/`validatePartialAsync` или `safeParse`/`safeParseAsync`. Исключение — opt-in `@ValidateOnSet`: он проверяет поле при каждом присваивании.
72
+
73
+ ## Валидация из типов
74
+
75
+ Типы полей уже описаны в TS-аннотациях, и дублировать их декораторами `@IsString()`/`@IsInt()` не нужно. Vite-плагин читает типы на этапе сборки через TypeScript API и вставляет в класс статическую схему. В рантайме `validate` проверяет по ней значения, а декораторы остаются для семантики: формат, диапазоны, сравнения.
76
+
77
+ Схему получают только классы-потомки `ValidationModel`. Импортируйте базовый класс из пакета и укажите его в `extends`:
78
+
79
+ ```ts
80
+ import { ValidationModel } from "@ivlev-dev/silent-validation";
81
+
82
+ class User extends ValidationModel {
83
+ public accessor email: string = "";
84
+ }
85
+ ```
86
+
87
+ Наследование может быть многоуровневым: промежуточные классы сохраняют признак, и потомок на любой глубине получает схему. Класс без `ValidationModel` в цепочке наследования метаданных не получает.
88
+
89
+ ### Подключение плагина
90
+
91
+ Плагин поставляется отдельным пакетом и устанавливается дополнительно:
92
+
93
+ ```bash
94
+ pnpm add -D @ivlev-dev/silent-validation-vite
95
+ ```
96
+
97
+ ```ts
98
+ import { defineConfig } from "vite";
99
+ import { silent } from "@ivlev-dev/silent-vite";
100
+ import { validation } from "@ivlev-dev/silent-validation-vite";
101
+
102
+ export default defineConfig({
103
+ plugins: [silent(), validation()],
104
+ });
105
+ ```
106
+
107
+ | Опция | Тип | По умолчанию | Назначение |
108
+ | --- | --- | --- | --- |
109
+ | `include` | `RegExp` | `/\.(?:[cm]?ts\|tsx)$/` | Файлы, которые обрабатывает плагин; заменяет набор по умолчанию |
110
+ | `exclude` | `RegExp` | `/node_modules/` | Файлы, которые плагин пропускает |
111
+ | `tsconfig` | `string` | ближайший `tsconfig.json` | Путь к конфигу относительно корня проекта |
112
+ | `base` | `string` | `"ValidationModel"` | Имя базового класса, потомки которого получают схему |
113
+ | `strict` | `boolean` | `false` | Бросать ошибку вместо предупреждения при неподдерживаемом типе |
114
+
115
+ TypeScript используется только на сборке: `typescript` — зависимость пакета `@ivlev-dev/silent-validation-vite`, рантайм от него не зависит. Плагин самостоятельный: `silent()` нужен только для JSX/VM-компиляции, в обычном Vite-конфиге достаточно `validation()`.
116
+
117
+ ### Пример
118
+
119
+ ```ts
120
+ import { validate, ValidationModel } from "@ivlev-dev/silent-validation";
121
+
122
+ class Address extends ValidationModel {
123
+ public accessor city: string = "";
124
+ }
125
+
126
+ class Item extends ValidationModel {
127
+ public accessor name: string = "";
128
+ public accessor quantity: number = 0;
129
+ }
130
+
131
+ class Order extends ValidationModel {
132
+ public accessor email: string = "";
133
+ public accessor age: number | undefined = undefined;
134
+ public accessor address: Address = new Address();
135
+ public accessor items: Item[] = [];
136
+ public accessor counts: Record<string, number> = {};
137
+ }
138
+
139
+ const order = new Order();
140
+ order.email = "user@example.com";
141
+ order.address.city = "Москва";
142
+ order.items = [new Item()];
143
+ order.counts = { apples: 3 };
144
+
145
+ const result = validate(order);
146
+ ```
147
+
148
+ Декораторов в классах нет, но `validate` проверяет типы: `email` — строка, `age` — число или `undefined`, `address` — экземпляр `Address` с корректным `city`, каждый элемент `items` — `Item`, значения `counts` — числа. Для этого плагин добавляет в класс статический блок вида:
149
+
150
+ ```js
151
+ static {
152
+ this[Symbol.for("silent.validation.schema")] = { version: 1, fields: { email: "string", age: ["optional", "number"] } };
153
+ }
154
+ ```
155
+
156
+ Схема без `version` (`{ fields: ... }`) поддерживается как legacy-формат; текущий плагин всегда генерирует `version: 1`.
157
+
158
+ Ошибка типа получает `rule: "type"`, `params.type` с именем ожидаемого типа, сообщение по ключу `validation.type` и обычный `path`:
159
+
160
+ ```ts
161
+ const broken = new Order();
162
+ Object.assign(broken, { email: 42 });
163
+
164
+ const { errors } = validate(broken);
165
+ // errors[0].rule === "type"
166
+ // errors[0].params.type === "string"
167
+ // errors[0].path === "email"
168
+ ```
169
+
170
+ ### Вложенность и пути
171
+
172
+ Вложенные классы, массивы, `Record` и index-signature дают те же пути, что и `@Nested`/`@Each`:
173
+
174
+ ```ts
175
+ class Order extends ValidationModel {
176
+ public accessor address: Address = new Address();
177
+ public accessor items: Item[] = [];
178
+ public accessor counts: Record<string, number> = {};
179
+ }
180
+ ```
181
+
182
+ Ошибки приходят как `address.city`, `items[0].quantity`; для прямых ошибок элемента массива заполняется `index`, а у ошибок внутри вложенного класса индекс есть только в `path`. Ключи объектов и `Record` идут через точку (`counts.apples`), ключи `Map` — в скобках (`map[userId]`).
183
+
184
+ ### Смешивание с декораторами
185
+
186
+ Тип проверяется первым. По умолчанию включён каскад (`cascade: true`): даже при неверном типе выполняются декораторы поля, поэтому `@Min(0)` на строке даст и `type`, и `min`. Чтобы остановиться на типовой ошибке, передайте `cascade: false`:
187
+
188
+ ```ts
189
+ import { IsEmail, Min, validate, ValidationModel } from "@ivlev-dev/silent-validation";
190
+
191
+ class User extends ValidationModel {
192
+ @IsEmail()
193
+ public accessor email: string = "";
194
+
195
+ @Min(18)
196
+ public accessor age: number = 0;
197
+ }
198
+
199
+ const user = new User();
200
+ user.email = "user@example.com";
201
+ user.age = 30;
202
+
203
+ validate(user);
204
+ ```
205
+
206
+ `@IsEmail` проверяет формат, `number` и `@Min(18)` — тип и диапазон. `@Required()`/`@Optional()` не нужны: `undefined` и `null` описываются в типе (`string | undefined`, `number | null`), а `@ValidateIf`, `@Label`, `@Groups` работают как раньше.
207
+
208
+ ### Отключение проверки типов
209
+
210
+ ```ts
211
+ validate(instance, { types: false });
212
+ ```
213
+
214
+ Флаг `types` в `ValidationOptions` по умолчанию `true`; глобально он не настраивается. С `types: false` остаются только правила декораторов — удобно, когда схема приходит извне или типы описывают данные шире, чем допустимо в конкретном вызове. Флаг `cascade` (по умолчанию `true`) управляет каскадом: `false` останавливает декораторы поля после ошибки типа. `cascade` можно задать глобально через `configureValidation` и переопределить на вызов; `types` задаётся только в `ValidationOptions`.
215
+
216
+ ### Поддерживаемые типы
217
+
218
+ | Группа | Типы |
219
+ | --- | --- |
220
+ | Примитивы | `string`, `number`, `boolean`, `bigint`, `symbol`, `object`, `function`, `undefined`, `null`, `void`, `never` |
221
+ | Литералы | `"admin"`, `42`, `true` — значение сверяется с литералом |
222
+ | Объединения и пересечения | `string \| number`, `A & B`, `T \| null`, `T \| undefined` |
223
+ | Массивы и кортежи | `T[]`, `ReadonlyArray<T>`, `ArrayLike<T>` (массивы и array-like объекты), `[string, number]`, `[string, number?]`, `[string, ...number[]]` |
224
+ | Объекты | `Record<K, V>`, `{ [key: string]: T }`, классы и интерфейсы, type alias’ы (структурно, включая рекурсивные), mapped-утилиты `Partial`/`Pick`/`Omit`/`Readonly`/`Required` |
225
+ | Коллекции | `Map`, `Set`, `ReadonlyMap`, `ReadonlySet`; `WeakMap`/`WeakSet` — только `instanceof`, без проверки ключей и значений |
226
+ | Встроенные | `Promise`, `Date`, `RegExp`, `Error` и подклассы, `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, typed arrays, `Buffer` (как `Uint8Array`), `URL`, `URLSearchParams` |
227
+ | Итераторы | `Iterable`, `Iterator`, `AsyncIterable`, `AsyncIterator` |
228
+ | Enum | значения `enum` — как у `@IsEnum` |
229
+
230
+ Валидируются только `accessor`-поля с явной аннотацией; обычные поля и поля без аннотации плагин пропускает.
231
+
232
+ ### Стоимость
233
+
234
+ - Рантайм: около **3 µs** на `validate` для модели из 6 полей с вложенным классом и массивом из трёх элементов (Intel i5-10400); с `types: false` — около **0.15 µs**. Схемы и планы полей кешируются по конструктору.
235
+ - Сборка: TypeScript Program создаётся один раз на проект (около **0.3–0.4 s** на холодную для проекта из 120 файлов); повторные сборки и HMR с тем же экземпляром плагина добавляют единицы миллисекунд. Файлы без `accessor`/`extends` плагин пропускает до создания Program.
236
+
237
+ ### Ограничения
238
+
239
+ - Метаданные получают только классы с `accessor`-полями и аннотациями; файл должен попадать под `include` и не попадать под `exclude`. Проверяются только `accessor`-поля с явной аннотацией и identifier-именем; вычисляемые и символьные имена пропускаются.
240
+ - Схема генерируется только для классов-потомков `ValidationModel`; класс без базового класса не валидируется по типу.
241
+ - Optional-поле описывается как `public accessor age: number | undefined = undefined;`. Синтаксис `accessor age?: number` в TypeScript запрещён.
242
+ - Mapped-утилиты (`Partial`, `Pick`, `Omit`, `Readonly`, `Required`) поддерживаются структурно. Глубина данных ограничена 256 уровнями (глубже — ошибка `validation.depth`). Числовая index-signature учитывается только у типов без именованных свойств. Условные, template и indexed-типы, а также generic-параметры без конкретизации пропускаются с диагностикой (в `strict` — ошибка).
243
+ - Символьные свойства структурных типов пропускаются с диагностикой (в `strict` — ошибка); ambient-классы (`declare class`) без рантайм-модуля пропускаются.
244
+ - Если класс импортирован только как тип (`import type { Item }`), плагин добавляет namespace-импорт при наличии рантайм-файла. Если рантайма нет, поле пропускается с диагностикой (в `strict` — ошибка).
245
+ - Плагин вставляет статический блок в бандл: без него `validate` увидит только правила декораторов.
246
+
247
+ ## API
248
+
249
+ | Символ | Назначение |
250
+ | --- | --- |
251
+ | `validate(instance, options?)` | Синхронная проверка, возвращает `ValidationResult` |
252
+ | `validateAsync(instance, options?)` | Асинхронная проверка, возвращает `Promise<ValidationResult>` |
253
+ | `validateProperty(instance, field, options?)` | Проверка одного поля |
254
+ | `validatePropertyAsync(instance, field, options?)` | Асинхронная проверка одного поля |
255
+ | `validatePartial(instance, fields, options?)` | Проверка выбранных полей |
256
+ | `validatePartialAsync(instance, fields, options?)` | Асинхронная проверка выбранных полей |
257
+ | `safeParse(instance, options?)` | Не бросает `ValidationException`; ошибки валидации в `{ success, data, errors }` |
258
+ | `safeParseAsync(instance, options?)` | Асинхронный вариант `safeParse` |
259
+ | `validateOrThrow(instance, options?)` | Синхронная проверка, при ошибках бросает `ValidationException` |
260
+ | `validateOrThrowAsync(instance, options?)` | Асинхронная проверка, при ошибках бросает `ValidationException` |
261
+ | `ValidationResult` | `{ valid: boolean; errors: readonly ValidationError[] }` |
262
+ | `ValidationError` | Ошибка правила: `field`, `rule`, `message`, `params`, `value`, `path`, `label`, `index?` |
263
+ | `ValidationException` | Исключение с полями `errors` и `result` |
264
+ | `AsyncRuleError` | Бросается `validate`, `validateProperty`, `validatePartial`, `safeParse`, `validateOrThrow`, если правило вернуло промис |
265
+ | `ValidationModel` | Базовый класс-маркер: схема из TS-типов генерируется только для его потомков |
266
+ | `ValidationOptions` | `groups`, `stopAtFirst`, `labels`, `types`, `cascade`, `locale`, `resolve`, `messages` |
267
+
268
+ ```ts
269
+ import {
270
+ validate,
271
+ validateAsync,
272
+ validateOrThrow,
273
+ validateOrThrowAsync,
274
+ ValidationException,
275
+ AsyncRuleError,
276
+ } from "@ivlev-dev/silent-validation";
277
+ ```
278
+
279
+ - `groups` — проверять только поля с указанными группами; поле без групп участвует всегда.
280
+ - `stopAtFirst` — остановиться на первой ошибке.
281
+ - `labels` — карта `имя поля или путь → человекочитаемый ярлык`; приоритет: `RuleOptions.label` → `@Label` → `labels[path]` → `labels[field]` → имя поля.
282
+ - `types` — проверка типов из TS-аннотаций (по умолчанию `true`, см. «Валидация из типов»).
283
+ - `locale`, `resolve`, `messages` — переопределяют глобальный конфиг сообщений для конкретного вызова.
284
+
285
+ Синхронные `validate`, `validateProperty`, `validatePartial`, `safeParse` и `validateOrThrow` бросают `AsyncRuleError`, если встретилось асинхронное правило (`Custom` с `async`-функцией). Они же бросают `TypeError`, если аргумент — не объект или обычный массив (подклассы `Array` валидируются), и `Error` при асинхронном резолвере сообщений. Для моделей с асинхронными правилами используйте `validateAsync`, `validatePropertyAsync`, `validatePartialAsync`, `safeParseAsync` или `validateOrThrowAsync`.
286
+
287
+ ## Правила
288
+
289
+ Все декораторы-правила принимают необязательный последний аргумент `RuleOptions` (`message`, `messageKey`, `label`, `groups`, `when`, `each`). Поведение каскада задаётся `ValidationOptions.cascade` (по умолчанию `true`). Имена декораторов — PascalCase.
290
+
291
+ ### Наличие
292
+
293
+ | Декоратор | Проверка |
294
+ | --- | --- |
295
+ | `@Required()` | Значение не `undefined`, не `null` и не пустая строка |
296
+ | `@NotNull()` | Значение не `null` и не `undefined` |
297
+ | `@NotUndefined()` | Значение не `undefined` |
298
+ | `@NotEmpty()` | Непустая строка без пробелов, непустые массив/`Map`/`Set`/объект |
299
+ | `@IsDefined()` | Значение не `undefined` |
300
+
301
+ ### Типы
302
+
303
+ | Декоратор | Проверка |
304
+ | --- | --- |
305
+ | `@IsString()` | Строка |
306
+ | `@IsBoolean()` | `boolean` |
307
+ | `@IsInt()` | Целое конечное число |
308
+ | `@IsFloat()` | Конечное нецелое число |
309
+ | `@IsNumber()` | Конечное число |
310
+ | `@IsArray()` | Массив |
311
+ | `@IsDate()` | Валидный объект `Date` |
312
+ | `@IsEnum(values)` | Значение входит в массив или enum-объект (без обратных ключей числовых enum) |
313
+ | `@IsInstanceOf(Ctor)` | Экземпляр указанного класса |
314
+ | `@IsObject()` | Объект, не `null` и не массив |
315
+ | `@IsFunction()` | Функция |
316
+
317
+ ### Числа
318
+
319
+ | Декоратор | Проверка |
320
+ | --- | --- |
321
+ | `@Min(limit)` | `value >= limit` |
322
+ | `@Max(limit)` | `value <= limit` |
323
+ | `@Between(min, max)` | `min <= value <= max` |
324
+ | `@Positive()` | `value > 0` |
325
+ | `@Negative()` | `value < 0` |
326
+ | `@NonNegative()` | `value >= 0` |
327
+ | `@NonPositive()` | `value <= 0` |
328
+ | `@MultipleOf(factor)` | Кратность `factor` с допуском `1e-9` |
329
+
330
+ Числовые правила принимают только конечные числа; `NaN`, `Infinity`, строки и `null` не проходят.
331
+
332
+ ### Строки
333
+
334
+ | Декоратор | Проверка |
335
+ | --- | --- |
336
+ | `@MinLength(min)` | Длина не меньше `min` |
337
+ | `@MaxLength(max)` | Длина не больше `max` |
338
+ | `@Length(length)` | Длина ровно `length` |
339
+ | `@Matches(pattern)` | Совпадение с `RegExp` или строковым шаблоном |
340
+ | `@IsEmail()` | Корректный email |
341
+ | `@IsUrl()` | URL с протоколом `http:` или `https:` |
342
+ | `@IsUUID()` | UUID |
343
+ | `@IsISO8601()` | Дата ISO 8601 |
344
+ | `@IsPhone()` | Телефон: `+`, цифры, пробелы, скобки, дефисы; 7–20 символов |
345
+ | `@IsAlpha()` | Только буквы (Unicode) |
346
+ | `@IsAlphanumeric()` | Только буквы и цифры (Unicode) |
347
+ | `@IsSlug()` | `kebab-case` из строчных латинских букв и цифр |
348
+ | `@IsHexColor()` | Цвет `#RGB`, `#RGBA`, `#RRGGBB` или `#RRGGBBAA` |
349
+ | `@IsBase64()` | Корректная Base64-строка |
350
+ | `@IsJSON()` | Строка с валидным JSON |
351
+
352
+ ### Коллекции
353
+
354
+ | Декоратор | Проверка |
355
+ | --- | --- |
356
+ | `@ArrayMinSize(min)` | Не меньше `min` элементов |
357
+ | `@ArrayMaxSize(max)` | Не больше `max` элементов |
358
+ | `@ArrayNotEmpty()` | Непустая коллекция |
359
+ | `@ArrayUnique()` | Элементы не повторяются |
360
+ | `@HasKey(key)` | Объект содержит ключ |
361
+ | `@Nested()` | Вложенный объект валидируется своими правилами |
362
+ | `@Each()` | Каждый элемент массива или `Set` валидируется как вложенный объект |
363
+
364
+ Для примитивных элементов используйте `each` в опциях правила:
365
+
366
+ ```ts
367
+ class Model {
368
+ @Min(0, { each: true })
369
+ public accessor scores!: number[];
370
+ }
371
+ ```
372
+
373
+ ### Сравнения
374
+
375
+ | Декоратор | Проверка |
376
+ | --- | --- |
377
+ | `@Equals(expected)` | Равенство `expected` |
378
+ | `@NotEquals(expected)` | Неравенство `expected` |
379
+ | `@IsIn(values)` | Значение входит в список |
380
+ | `@NotIn(values)` | Значение не входит в список |
381
+
382
+ ### Custom
383
+
384
+ ```ts
385
+ import { Custom, validate } from "@ivlev-dev/silent-validation";
386
+
387
+ class Order {
388
+ @Custom((value) => typeof value === "string" && value.startsWith("ORD-"))
389
+ public accessor number!: string;
390
+
391
+ @Custom(async (value) => value !== "blocked")
392
+ public accessor status!: string;
393
+ }
394
+ ```
395
+
396
+ `Custom` принимает функцию `(value, context) => boolean | Promise<boolean>`. Асинхронная функция требует одной из async-функций: `validateAsync`, `validatePropertyAsync`, `validatePartialAsync`, `safeParseAsync`, `validateOrThrowAsync`. Синхронные `validate`, `validateProperty`, `validatePartial`, `safeParse` и `validateOrThrow` бросят `AsyncRuleError`.
397
+
398
+ ## Модификаторы
399
+
400
+ | Декоратор | Назначение |
401
+ | --- | --- |
402
+ | `@ValidateIf(predicate)` | Проверять поле, только если `predicate(instance)` истинно |
403
+ | `@Optional()` | Пропустить все правила поля, если значение `null` или `undefined` |
404
+ | `@Label(text)` | Человекочитаемое имя поля для сообщений |
405
+ | `@Groups(...groups)` | Отнести поле к группам; проверяется при совпадении `options.groups` |
406
+ | `@ValidateOnSet()` | Проверять поле при каждом присваивании и бросать `ValidationException` |
407
+
408
+ ```ts
409
+ import { Groups, Label, Optional, ValidateIf, Min, validate } from "@ivlev-dev/silent-validation";
410
+
411
+ class Profile {
412
+ @Label("Возраст")
413
+ @Optional()
414
+ @Min(18)
415
+ public accessor age: number | undefined = undefined;
416
+
417
+ @ValidateIf((instance: Profile) => instance.age !== undefined)
418
+ @Label("Согласие")
419
+ public accessor consent: boolean | undefined = undefined;
420
+
421
+ @Groups("admin")
422
+ public accessor role: string | undefined = undefined;
423
+ }
424
+
425
+ const profile = new Profile();
426
+ profile.age = 30;
427
+ profile.consent = true;
428
+ profile.role = "admin";
429
+
430
+ validate(profile, { groups: ["admin"] });
431
+ ```
432
+
433
+ Поле без групп выполняется при любом `groups`; поле с группой выполняется, только если хотя бы одна его группа указана в вызове.
434
+
435
+ ## Сообщения
436
+
437
+ Каждое правило формирует ключ `validation.<rule>`, например `validation.min` или `validation.isEmail`. Встроенные каталоги — `ru` (по умолчанию, `DEFAULT_LOCALE`) и `en`.
438
+
439
+ Служебные ключи: `validation.type` — значение не совпало с типом из схемы, `validation.depth` — вложенность глубже 256 уровней, `validation.each` — элемент `@Each` не является объектом, `validation.eachValue` — значение `@Each` не является коллекцией (`each`/`eachValue` различают ошибку элемента и ошибку самой коллекции).
440
+
441
+ ```ts
442
+ import { validate, Required, Min, IsEmail } from "@ivlev-dev/silent-validation";
443
+
444
+ class User {
445
+ @Required({ message: "Укажите email" })
446
+ @IsEmail({ messageKey: "validation.required" })
447
+ public accessor email!: string;
448
+
449
+ @Min(18, { message: ({ label, params }) => `${label}: минимум ${params.min}` })
450
+ public accessor age!: number;
451
+ }
452
+ ```
453
+
454
+ - `message` — строка с плейсхолдерами `{label}`, `{value}`, `{field}`, `{index}` и параметрами правила, либо функция `(context) => string`. Имеет приоритет над резолвером и каталогом.
455
+ - `messageKey` — другой ключ каталога, например `validation.required`.
456
+ - `label` — ярлык поля в сообщении; приоритет: `options.label` → `@Label` → `options.labels[path]` → `options.labels[field]` → имя поля.
457
+
458
+ ### Глобальный конфиг
459
+
460
+ ```ts
461
+ import {
462
+ configureValidation,
463
+ getValidationConfig,
464
+ resetValidationConfig,
465
+ } from "@ivlev-dev/silent-validation";
466
+
467
+ configureValidation({
468
+ locale: "en",
469
+ messages: {
470
+ en: {
471
+ "validation.min": "{label} must be at least {min}",
472
+ },
473
+ },
474
+ });
475
+
476
+ const config = getValidationConfig();
477
+ resetValidationConfig();
478
+ ```
479
+
480
+ `configureValidation` мержит переданные поля с текущими настройками: `cascade`, `locale`, `resolve`, `messages`. Значения `messages` переопределяют встроенные каталоги. Если ключа нет в выбранной локали, используется `ru`, затем встроенный `en`.
481
+
482
+ ### Резолвер (i18next)
483
+
484
+ ```ts
485
+ import { configureValidation } from "@ivlev-dev/silent-validation";
486
+ import i18next from "i18next";
487
+
488
+ configureValidation({
489
+ locale: "en",
490
+ resolve: ({ key, params, locale }) => i18next.t(key, { ...params, lng: locale }),
491
+ });
492
+ ```
493
+
494
+ Резолвер `MessageResolver` получает `key`, `params`, `locale`, `label`, `field`, `value`, `path` и возвращает строку или `undefined`. При `undefined` используется каталог. Возвращённая строка интерполируется так же, как шаблон каталога.
495
+
496
+ Резолвер может быть асинхронным: `resolve` вправе вернуть `Promise<string | undefined>`, но такой режим работает только в async-функциях (`validateAsync`, `validatePropertyAsync`, `validatePartialAsync`, `safeParseAsync`, `validateOrThrowAsync`); синхронные `validate`, `validateProperty`, `validatePartial`, `safeParse` и `validateOrThrow` бросят `Error`.
497
+
498
+ Для i18next есть готовый адаптер `createI18nextResolver`:
499
+
500
+ ```ts
501
+ import { configureValidation, createI18nextResolver } from "@ivlev-dev/silent-validation";
502
+ import i18next from "i18next";
503
+
504
+ configureValidation({ resolve: createI18nextResolver(i18next) });
505
+ ```
506
+
507
+ `createI18nextResolver(i18n, { keyPrefix })` вызывает `i18n.t(prefix + key, { ...params, label, lng: locale, defaultValue, count })`. `lng` — текущая локаль, `label` — ярлык поля, `defaultValue` — встроенный шаблон (или сам ключ, если шаблона нет). `count` передаётся только для `arrayMinSize`, `arrayMaxSize`, `arrayNotEmpty`, `arrayUnique`, `length`, `minLength`, `maxLength`, `each`, `eachValue` и берётся из `params.count`/`min`/`max`/`length`, иначе из длины массива/строки или `Set.size`. Если `i18n.t` вернул не строку, пустую строку или сам ключ, используется встроенный каталог.
508
+
509
+ Для правил размера и длины (`arrayMinSize`, `arrayMaxSize`, `minLength`, `maxLength`) встроенные каталоги содержат плюральные формы: `_one`/`_few`/`_many`/`_other` в `ru`, `_one`/`_other` в `en`. Форма выбирается по числу из `params.count`/`min`/`max`/`length`, затем по числу значения, длине массива/строки или `Set.size`. Например, для `ru`: `1 символ`, `2 символа`, `5 символов`.
510
+
511
+ ## Вложенность
512
+
513
+ ```ts
514
+ import { Nested, Each, Required, IsInt, validate } from "@ivlev-dev/silent-validation";
515
+
516
+ class Address {
517
+ @Required()
518
+ public accessor city!: string;
519
+ }
520
+
521
+ class Item {
522
+ @Required()
523
+ public accessor name!: string;
524
+
525
+ @IsInt()
526
+ public accessor quantity!: number;
527
+ }
528
+
529
+ class Order {
530
+ @Nested()
531
+ public accessor address!: Address;
532
+
533
+ @Each()
534
+ public accessor items!: Item[];
535
+ }
536
+
537
+ const order = new Order();
538
+ order.address = new Address();
539
+ order.address.city = "Москва";
540
+ order.items = [new Item()];
541
+ order.items[0]!.name = "Чай";
542
+ order.items[0]!.quantity = 2;
543
+
544
+ const result = validate(order);
545
+ ```
546
+
547
+ Пути ошибок: `address.city`, `items[0].name`, `items[2].quantity`. `ValidationError.index` и плейсхолдер `{index}` заполняются у прямых ошибок элемента коллекции (неверный тип элемента или правило с `each: true`); у ошибок внутри вложенного класса индекс есть только в пути.
548
+
549
+ `@Nested()` проверяет вложенный объект правилами его класса. `@Each()` делает то же для каждого элемента массива или `Set`: неверная коллекция даёт `validation.eachValue`, неверный элемент — `validation.each`. Для примитивных элементов используйте `@Min(0, { each: true })`.
550
+
551
+ Элементы `@Each()` должны быть созданы конструктором класса с декораторами — правила регистрируются при инициализации экземпляра. Plain-объекты без декораторов считаются валидными (у них нет правил).
552
+
553
+ ## Ограничения и совместимость
554
+
555
+ - Поддерживаются только stage-3 `accessor`-поля (`public accessor email!: string`). Обычные поля, приватные (`#field`) и статические поля не поддерживаются — декоратор бросает `TypeError` (и типы не дадут применить его к обычному полю).
556
+ - Optional-поле описывается через `| undefined`: `public accessor age: number | undefined = undefined;`. Синтаксис `accessor age?: number` в TypeScript запрещён.
557
+ - Типы проверяются только из аннотаций `accessor`-полей и только при подключённом плагине `validation()` из `@ivlev-dev/silent-validation-vite`. Обычные поля и поля без аннотации остаются без проверки типов; условные/template/indexed-типы и generic-параметры без конкретизации пропускаются. Mapped-утилиты (`Partial`, `Pick`, `Omit`, `Readonly`, `Required`) поддерживаются структурно.
558
+ - Валидация явная: ни декораторы, ни типы из аннотаций не запускают проверку без вызова `validate`, `validateAsync`, `validateOrThrow`, `validateOrThrowAsync`, `validateProperty`/`validatePropertyAsync`, `validatePartial`/`validatePartialAsync` или `safeParse`/`safeParseAsync`. Исключение — opt-in `@ValidateOnSet`: он проверяет поле при каждом присваивании.
559
+ - Нужны stage 3 декораторы: `experimentalDecorators: false`. Legacy-декораторы (`experimentalDecorators: true`) не поддерживаются.
560
+ - ESM-only, Node.js >= 22.
561
+ - Синхронные функции (`validate`, `validateProperty`, `validatePartial`, `safeParse`, `validateOrThrow`) не поддерживают асинхронные правила — используйте `validateAsync`, `validatePropertyAsync`, `validatePartialAsync`, `safeParseAsync` или `validateOrThrowAsync`.
562
+ - Вложенный объект должен быть создан конструктором класса с декораторами: правила регистрируются при инициализации экземпляра. Plain-объекты без декораторов считаются валидными (у них нет правил). Кольцевые ссылки не приводят к бесконечной рекурсии.
563
+ - Пути и сообщения не зависят от фреймворка: пакет не требует `@ivlev-dev/silent-core`.
564
+
565
+ ## Ссылки
566
+
567
+ - Репозиторий: https://github.com/ivlev-dev/silent-framework
568
+ - Документация API: https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/validation.md
569
+ - CHANGELOG: https://github.com/ivlev-dev/silent-framework/blob/main/CHANGELOG.md
570
+ - Issues: https://github.com/ivlev-dev/silent-framework/issues
571
+
572
+ ---
573
+
574
+ MIT © ivlev-dev
@@ -0,0 +1,15 @@
1
+ import type { FieldKey, SafeParseResult, ValidationOptions, ValidationResult } from "./types.js";
2
+ /** @internal Диагностический счётчик построений плана полей (для тестов). */
3
+ export declare function validationPlanBuilds(): number;
4
+ export declare function validate(instance: object, options?: ValidationOptions): ValidationResult;
5
+ export declare function validateAsync(instance: object, options?: ValidationOptions): Promise<ValidationResult>;
6
+ export declare function validateProperty(instance: object, field: string, options?: ValidationOptions): ValidationResult;
7
+ export declare function validatePropertyAsync(instance: object, field: string, options?: ValidationOptions): Promise<ValidationResult>;
8
+ export declare function validateFieldKey(instance: object, key: FieldKey, options: ValidationOptions | undefined): ValidationResult;
9
+ export declare function validatePartial(instance: object, fields: readonly string[], options?: ValidationOptions): ValidationResult;
10
+ export declare function validatePartialAsync(instance: object, fields: readonly string[], options?: ValidationOptions): Promise<ValidationResult>;
11
+ export declare function safeParse<T extends object>(instance: T, options?: ValidationOptions): SafeParseResult<T>;
12
+ export declare function safeParseAsync<T extends object>(instance: T, options?: ValidationOptions): Promise<SafeParseResult<T>>;
13
+ export declare function validateOrThrow(instance: object, options?: ValidationOptions): void;
14
+ export declare function validateOrThrowAsync(instance: object, options?: ValidationOptions): Promise<void>;
15
+ //# sourceMappingURL=engine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,QAAQ,EAMR,eAAe,EAGf,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAmCpB,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AA2gCD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CAKxF;AAED,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAK3B;AA8CD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAElB;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,iBAAiB,GAAG,SAAS,GACrC,gBAAgB,CAalB;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAElB;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EACxC,QAAQ,EAAE,CAAC,EACX,OAAO,CAAC,EAAE,iBAAiB,GAC1B,eAAe,CAAC,CAAC,CAAC,CAMpB;AAED,wBAAsB,cAAc,CAAC,CAAC,SAAS,MAAM,EACnD,QAAQ,EAAE,CAAC,EACX,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAM7B;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAKnF;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAKf"}