@ivlev-dev/silent-validation 0.0.0-stage → 0.12.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.
- package/LICENSE +21 -0
- package/README.md +540 -2
- package/dist/engine.d.ts +13 -0
- package/dist/engine.d.ts.map +1 -0
- package/dist/engine.js +784 -0
- package/dist/engine.js.map +1 -0
- package/dist/index.d.ts +15 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +13 -0
- package/dist/index.js.map +1 -0
- package/dist/messages.d.ts +15 -0
- package/dist/messages.d.ts.map +1 -0
- package/dist/messages.js +393 -0
- package/dist/messages.js.map +1 -0
- package/dist/model.d.ts +3 -0
- package/dist/model.d.ts.map +1 -0
- package/dist/model.js +3 -0
- package/dist/model.js.map +1 -0
- package/dist/modifiers.d.ts +7 -0
- package/dist/modifiers.d.ts.map +1 -0
- package/dist/modifiers.js +64 -0
- package/dist/modifiers.js.map +1 -0
- package/dist/property.d.ts +3 -0
- package/dist/property.d.ts.map +1 -0
- package/dist/property.js +39 -0
- package/dist/property.js.map +1 -0
- package/dist/registry.d.ts +11 -0
- package/dist/registry.d.ts.map +1 -0
- package/dist/registry.js +84 -0
- package/dist/registry.js.map +1 -0
- package/dist/rule.d.ts +7 -0
- package/dist/rule.d.ts.map +1 -0
- package/dist/rule.js +34 -0
- package/dist/rule.js.map +1 -0
- package/dist/rules/collections.d.ts +54 -0
- package/dist/rules/collections.d.ts.map +1 -0
- package/dist/rules/collections.js +116 -0
- package/dist/rules/collections.js.map +1 -0
- package/dist/rules/comparison.d.ts +36 -0
- package/dist/rules/comparison.d.ts.map +1 -0
- package/dist/rules/comparison.js +45 -0
- package/dist/rules/comparison.js.map +1 -0
- package/dist/rules/custom.d.ts +10 -0
- package/dist/rules/custom.d.ts.map +1 -0
- package/dist/rules/custom.js +12 -0
- package/dist/rules/custom.js.map +1 -0
- package/dist/rules/numbers.d.ts +61 -0
- package/dist/rules/numbers.d.ts.map +1 -0
- package/dist/rules/numbers.js +90 -0
- package/dist/rules/numbers.js.map +1 -0
- package/dist/rules/presence.d.ts +34 -0
- package/dist/rules/presence.d.ts.map +1 -0
- package/dist/rules/presence.js +66 -0
- package/dist/rules/presence.js.map +1 -0
- package/dist/rules/strings.d.ts +102 -0
- package/dist/rules/strings.d.ts.map +1 -0
- package/dist/rules/strings.js +194 -0
- package/dist/rules/strings.js.map +1 -0
- package/dist/rules/types.d.ts +76 -0
- package/dist/rules/types.d.ts.map +1 -0
- package/dist/rules/types.js +128 -0
- package/dist/rules/types.js.map +1 -0
- package/dist/schema.d.ts +11 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +147 -0
- package/dist/schema.js.map +1 -0
- package/dist/thenable.d.ts +4 -0
- package/dist/thenable.d.ts.map +1 -0
- package/dist/thenable.js +16 -0
- package/dist/thenable.js.map +1 -0
- package/dist/type-validation.d.ts +33 -0
- package/dist/type-validation.d.ts.map +1 -0
- package/dist/type-validation.js +746 -0
- package/dist/type-validation.js.map +1 -0
- package/dist/types.d.ts +113 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +22 -0
- package/dist/types.js.map +1 -0
- 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,541 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @ivlev-dev/silent-validation
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Валидация классов на stage 3 декораторах: синхронные и асинхронные проверки, вложенные объекты и коллекции, группы, условные правила и сообщения с поддержкой i18n. Типы полей можно не дублировать декораторами — их проверяет Vite-плагин по TS-аннотациям.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@ivlev-dev/silent-validation)
|
|
6
|
+
[](https://github.com/ivlev-dev/silent-framework/blob/main/LICENSE)
|
|
7
|
+
[](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`.
|
|
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`).
|
|
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
|
+
|
|
114
|
+
TypeScript используется только на сборке: `typescript` — зависимость пакета `@ivlev-dev/silent-validation-vite`, рантайм от него не зависит. Плагин самостоятельный: `silent()` нужен только для JSX/VM-компиляции, в обычном Vite-конфиге достаточно `validation()`.
|
|
115
|
+
|
|
116
|
+
### Пример
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import { validate, ValidationModel } from "@ivlev-dev/silent-validation";
|
|
120
|
+
|
|
121
|
+
class Address extends ValidationModel {
|
|
122
|
+
public accessor city: string = "";
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
class Item extends ValidationModel {
|
|
126
|
+
public accessor name: string = "";
|
|
127
|
+
public accessor quantity: number = 0;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
class Order extends ValidationModel {
|
|
131
|
+
public accessor email: string = "";
|
|
132
|
+
public accessor age: number | undefined = undefined;
|
|
133
|
+
public accessor address: Address = new Address();
|
|
134
|
+
public accessor items: Item[] = [];
|
|
135
|
+
public accessor counts: Record<string, number> = {};
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const order = new Order();
|
|
139
|
+
order.email = "user@example.com";
|
|
140
|
+
order.address.city = "Москва";
|
|
141
|
+
order.items = [new Item()];
|
|
142
|
+
order.counts = { apples: 3 };
|
|
143
|
+
|
|
144
|
+
const result = validate(order);
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Декораторов в классах нет, но `validate` проверяет типы: `email` — строка, `age` — число или `undefined`, `address` — экземпляр `Address` с корректным `city`, каждый элемент `items` — `Item`, значения `counts` — числа. Для этого плагин добавляет в класс статический блок вида:
|
|
148
|
+
|
|
149
|
+
```js
|
|
150
|
+
static {
|
|
151
|
+
this[Symbol.for("silent.validation.schema")] = { fields: { email: "string", age: ["optional", "number"] } };
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Ошибка типа получает `rule: "type"`, `params.type` с именем ожидаемого типа, сообщение по ключу `validation.type` и обычный `path`:
|
|
156
|
+
|
|
157
|
+
```ts
|
|
158
|
+
const broken = new Order();
|
|
159
|
+
Object.assign(broken, { email: 42 });
|
|
160
|
+
|
|
161
|
+
const { errors } = validate(broken);
|
|
162
|
+
// errors[0].rule === "type"
|
|
163
|
+
// errors[0].params.type === "string"
|
|
164
|
+
// errors[0].path === "email"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Вложенность и пути
|
|
168
|
+
|
|
169
|
+
Вложенные классы, массивы, `Record` и index-signature дают те же пути, что и `@Nested`/`@Each`:
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
class Order extends ValidationModel {
|
|
173
|
+
public accessor address: Address = new Address();
|
|
174
|
+
public accessor items: Item[] = [];
|
|
175
|
+
public accessor counts: Record<string, number> = {};
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Ошибки приходят как `address.city`, `items[0].quantity`; для элементов массива заполняется `index`. Ключи объектов и `Record` идут через точку (`counts.apples`), ключи `Map` — в скобках (`map[userId]`).
|
|
180
|
+
|
|
181
|
+
### Смешивание с декораторами
|
|
182
|
+
|
|
183
|
+
Тип проверяется первым. По умолчанию включён каскад (`cascade: true`): даже при неверном типе выполняются декораторы поля, поэтому `@Min(0)` на строке даст и `type`, и `min`. Чтобы остановиться на типовой ошибке, передайте `cascade: false`:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
import { IsEmail, Min, validate, ValidationModel } from "@ivlev-dev/silent-validation";
|
|
187
|
+
|
|
188
|
+
class User extends ValidationModel {
|
|
189
|
+
@IsEmail()
|
|
190
|
+
public accessor email: string = "";
|
|
191
|
+
|
|
192
|
+
@Min(18)
|
|
193
|
+
public accessor age: number = 0;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
validate(user);
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`@IsEmail` проверяет формат, `number` и `@Min(18)` — тип и диапазон. `@Required()`/`@Optional()` не нужны: `undefined` и `null` описываются в типе (`string | undefined`, `number | null`), а `@ValidateIf`, `@Label`, `@Groups` работают как раньше.
|
|
200
|
+
|
|
201
|
+
### Отключение проверки типов
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
validate(instance, { types: false });
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Флаг `types` в `ValidationOptions` по умолчанию `true`. С `types: false` остаются только правила декораторов — удобно, когда схема приходит извне или типы описывают данные шире, чем допустимо в конкретном вызове. Флаг `cascade` (по умолчанию `true`) управляет каскадом: `false` останавливает декораторы поля после ошибки типа. Оба флага можно задать глобально через `configureValidation` и переопределить на вызов.
|
|
208
|
+
|
|
209
|
+
### Поддерживаемые типы
|
|
210
|
+
|
|
211
|
+
| Группа | Типы |
|
|
212
|
+
| --- | --- |
|
|
213
|
+
| Примитивы | `string`, `number`, `boolean`, `bigint`, `symbol`, `object`, `function`, `undefined`, `null`, `void`, `never` |
|
|
214
|
+
| Литералы | `"admin"`, `42`, `true` — значение сверяется с литералом |
|
|
215
|
+
| Объединения и пересечения | `string \| number`, `A & B`, `T \| null`, `T \| undefined` |
|
|
216
|
+
| Массивы и кортежи | `T[]`, `ReadonlyArray<T>`, `[string, number]`, `[string, number?]`, `[string, ...number[]]` |
|
|
217
|
+
| Объекты | `Record<K, V>`, `{ [key: string]: T }`, классы и интерфейсы, type alias’ы (структурно, включая рекурсивные) |
|
|
218
|
+
| Коллекции | `Map`, `Set`; `WeakMap`/`WeakSet` — только `instanceof`, без проверки ключей и значений |
|
|
219
|
+
| Встроенные | `Promise`, `Date`, `RegExp`, `Error` и подклассы, `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, typed arrays, `URL`, `URLSearchParams` |
|
|
220
|
+
| Итераторы | `Iterable`, `Iterator`, `AsyncIterable`, `AsyncIterator` |
|
|
221
|
+
| Enum | значения `enum` — как у `@IsEnum` |
|
|
222
|
+
|
|
223
|
+
Валидируются только `accessor`-поля с явной аннотацией; обычные поля и поля без аннотации плагин пропускает.
|
|
224
|
+
|
|
225
|
+
### Стоимость
|
|
226
|
+
|
|
227
|
+
- Рантайм: около **3 µs** на `validate` для модели из 6 полей с вложенным классом и массивом из трёх элементов (Intel i5-10400); с `types: false` — около **0.15 µs**. Схемы и планы полей кешируются по конструктору.
|
|
228
|
+
- Сборка: TypeScript Program создаётся один раз на проект (около **0.3–0.4 s** на холодную для проекта из 120 файлов); повторные сборки и HMR с тем же экземпляром плагина добавляют единицы миллисекунд. Файлы без `accessor`/`extends` плагин пропускает до создания Program.
|
|
229
|
+
|
|
230
|
+
### Ограничения
|
|
231
|
+
|
|
232
|
+
- Метаданные получают только классы с `accessor`-полями и аннотациями; файл должен попадать под `include` и не попадать под `exclude`.
|
|
233
|
+
- Схема генерируется только для классов-потомков `ValidationModel`; класс без базового класса не валидируется по типу.
|
|
234
|
+
- Optional-поле описывается как `public accessor age: number | undefined = undefined;`. Синтаксис `accessor age?: number` в TypeScript запрещён.
|
|
235
|
+
- Mapped-утилиты (`Partial`, `Pick`, `Omit`, `Readonly`, `Required`) поддерживаются структурно. Глубина данных ограничена 256 уровнями (глубже — ошибка `validation.depth`). Условные, template и indexed-типы, а также generic-параметры без конкретизации пропускаются с диагностикой.
|
|
236
|
+
- Если класс импортирован только как тип (`import type { Item }`), плагин добавляет namespace-импорт, чтобы проверять экземпляры в рантайме.
|
|
237
|
+
- Плагин вставляет статический блок в бандл: без него `validate` увидит только правила декораторов.
|
|
238
|
+
|
|
239
|
+
## API
|
|
240
|
+
|
|
241
|
+
| Символ | Назначение |
|
|
242
|
+
| --- | --- |
|
|
243
|
+
| `validate(instance, options?)` | Синхронная проверка, возвращает `ValidationResult` |
|
|
244
|
+
| `validateAsync(instance, options?)` | Асинхронная проверка, возвращает `Promise<ValidationResult>` |
|
|
245
|
+
| `validateProperty(instance, field, options?)` | Проверка одного поля |
|
|
246
|
+
| `validatePropertyAsync(instance, field, options?)` | Асинхронная проверка одного поля |
|
|
247
|
+
| `validatePartial(instance, fields, options?)` | Проверка выбранных полей |
|
|
248
|
+
| `validatePartialAsync(instance, fields, options?)` | Асинхронная проверка выбранных полей |
|
|
249
|
+
| `safeParse(instance, options?)` | Проверка без исключения: `{ success, data, errors }` |
|
|
250
|
+
| `safeParseAsync(instance, options?)` | Асинхронный вариант `safeParse` |
|
|
251
|
+
| `validateOrThrow(instance, options?)` | Синхронная проверка, при ошибках бросает `ValidationException` |
|
|
252
|
+
| `validateOrThrowAsync(instance, options?)` | Асинхронная проверка, при ошибках бросает `ValidationException` |
|
|
253
|
+
| `ValidationResult` | `{ valid: boolean; errors: readonly ValidationError[] }` |
|
|
254
|
+
| `ValidationError` | Ошибка правила: `field`, `rule`, `message`, `params`, `value`, `path`, `label`, `index?` |
|
|
255
|
+
| `ValidationException` | Исключение с полями `errors` и `result` |
|
|
256
|
+
| `AsyncRuleError` | Бросается синхронным `validate`, если правило вернуло промис |
|
|
257
|
+
| `ValidationModel` | Базовый класс-маркер: схема из TS-типов генерируется только для его потомков |
|
|
258
|
+
| `ValidationOptions` | `groups`, `stopAtFirst`, `labels`, `types`, `cascade`, `locale`, `resolve`, `messages` |
|
|
259
|
+
|
|
260
|
+
```ts
|
|
261
|
+
import {
|
|
262
|
+
validate,
|
|
263
|
+
validateAsync,
|
|
264
|
+
validateOrThrow,
|
|
265
|
+
validateOrThrowAsync,
|
|
266
|
+
ValidationException,
|
|
267
|
+
AsyncRuleError,
|
|
268
|
+
} from "@ivlev-dev/silent-validation";
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
- `groups` — проверять только поля с указанными группами; поле без групп участвует всегда.
|
|
272
|
+
- `stopAtFirst` — остановиться на первой ошибке.
|
|
273
|
+
- `labels` — карта `имя поля → человекочитаемый ярлык`, переопределяет `@Label`.
|
|
274
|
+
- `types` — проверка типов из TS-аннотаций (по умолчанию `true`, см. «Валидация из типов»).
|
|
275
|
+
- `locale`, `resolve`, `messages` — переопределяют глобальный конфиг сообщений для конкретного вызова.
|
|
276
|
+
|
|
277
|
+
`validate` бросает `AsyncRuleError`, если встретилось асинхронное правило (`Custom` с `async`-функцией). Для таких моделей используйте `validateAsync`.
|
|
278
|
+
|
|
279
|
+
## Правила
|
|
280
|
+
|
|
281
|
+
Все декораторы-правила принимают необязательный последний аргумент `RuleOptions` (`message`, `messageKey`, `label`, `groups`, `when`, `each`). Поведение каскада задаётся `ValidationOptions.cascade` (по умолчанию `true`). Имена декораторов — PascalCase.
|
|
282
|
+
|
|
283
|
+
### Наличие
|
|
284
|
+
|
|
285
|
+
| Декоратор | Проверка |
|
|
286
|
+
| --- | --- |
|
|
287
|
+
| `@Required()` | Значение не `undefined`, не `null` и не пустая строка |
|
|
288
|
+
| `@NotNull()` | Значение не `null` и не `undefined` |
|
|
289
|
+
| `@NotUndefined()` | Значение не `undefined` |
|
|
290
|
+
| `@NotEmpty()` | Непустая строка без пробелов, непустые массив/`Map`/`Set`/объект |
|
|
291
|
+
| `@IsDefined()` | Значение не `undefined` |
|
|
292
|
+
|
|
293
|
+
### Типы
|
|
294
|
+
|
|
295
|
+
| Декоратор | Проверка |
|
|
296
|
+
| --- | --- |
|
|
297
|
+
| `@IsString()` | Строка |
|
|
298
|
+
| `@IsBoolean()` | `boolean` |
|
|
299
|
+
| `@IsInt()` | Целое конечное число |
|
|
300
|
+
| `@IsFloat()` | Конечное нецелое число |
|
|
301
|
+
| `@IsNumber()` | Конечное число |
|
|
302
|
+
| `@IsArray()` | Массив |
|
|
303
|
+
| `@IsDate()` | Валидный объект `Date` |
|
|
304
|
+
| `@IsEnum(values)` | Значение входит в массив или enum-объект (без обратных ключей числовых enum) |
|
|
305
|
+
| `@IsInstanceOf(Ctor)` | Экземпляр указанного класса |
|
|
306
|
+
| `@IsObject()` | Объект, не `null` и не массив |
|
|
307
|
+
| `@IsFunction()` | Функция |
|
|
308
|
+
|
|
309
|
+
### Числа
|
|
310
|
+
|
|
311
|
+
| Декоратор | Проверка |
|
|
312
|
+
| --- | --- |
|
|
313
|
+
| `@Min(limit)` | `value >= limit` |
|
|
314
|
+
| `@Max(limit)` | `value <= limit` |
|
|
315
|
+
| `@Between(min, max)` | `min <= value <= max` |
|
|
316
|
+
| `@Positive()` | `value > 0` |
|
|
317
|
+
| `@Negative()` | `value < 0` |
|
|
318
|
+
| `@NonNegative()` | `value >= 0` |
|
|
319
|
+
| `@NonPositive()` | `value <= 0` |
|
|
320
|
+
| `@MultipleOf(factor)` | Кратность `factor` с допуском `1e-9` |
|
|
321
|
+
|
|
322
|
+
Числовые правила принимают только конечные числа; `NaN`, `Infinity`, строки и `null` не проходят.
|
|
323
|
+
|
|
324
|
+
### Строки
|
|
325
|
+
|
|
326
|
+
| Декоратор | Проверка |
|
|
327
|
+
| --- | --- |
|
|
328
|
+
| `@MinLength(min)` | Длина не меньше `min` |
|
|
329
|
+
| `@MaxLength(max)` | Длина не больше `max` |
|
|
330
|
+
| `@Length(length)` | Длина ровно `length` |
|
|
331
|
+
| `@Matches(pattern)` | Совпадение с `RegExp` или строковым шаблоном |
|
|
332
|
+
| `@IsEmail()` | Корректный email |
|
|
333
|
+
| `@IsUrl()` | URL с протоколом `http:` или `https:` |
|
|
334
|
+
| `@IsUUID()` | UUID |
|
|
335
|
+
| `@IsISO8601()` | Дата ISO 8601 |
|
|
336
|
+
| `@IsPhone()` | Телефон: `+`, цифры, пробелы, скобки, дефисы; 7–20 символов |
|
|
337
|
+
| `@IsAlpha()` | Только буквы (Unicode) |
|
|
338
|
+
| `@IsAlphanumeric()` | Только буквы и цифры (Unicode) |
|
|
339
|
+
| `@IsSlug()` | `kebab-case` из строчных латинских букв и цифр |
|
|
340
|
+
| `@IsHexColor()` | Цвет `#RGB`, `#RGBA`, `#RRGGBB` или `#RRGGBBAA` |
|
|
341
|
+
| `@IsBase64()` | Корректная Base64-строка |
|
|
342
|
+
| `@IsJSON()` | Строка с валидным JSON |
|
|
343
|
+
|
|
344
|
+
### Коллекции
|
|
345
|
+
|
|
346
|
+
| Декоратор | Проверка |
|
|
347
|
+
| --- | --- |
|
|
348
|
+
| `@ArrayMinSize(min)` | Не меньше `min` элементов |
|
|
349
|
+
| `@ArrayMaxSize(max)` | Не больше `max` элементов |
|
|
350
|
+
| `@ArrayNotEmpty()` | Непустая коллекция |
|
|
351
|
+
| `@ArrayUnique()` | Элементы не повторяются |
|
|
352
|
+
| `@HasKey(key)` | Объект содержит ключ |
|
|
353
|
+
| `@Nested()` | Вложенный объект валидируется своими правилами |
|
|
354
|
+
| `@Each()` | Каждый элемент массива или `Set` валидируется как вложенный объект |
|
|
355
|
+
|
|
356
|
+
Для примитивных элементов используйте `each` в опциях правила:
|
|
357
|
+
|
|
358
|
+
```ts
|
|
359
|
+
class Model {
|
|
360
|
+
@Min(0, { each: true })
|
|
361
|
+
public accessor scores!: number[];
|
|
362
|
+
}
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
### Сравнения
|
|
366
|
+
|
|
367
|
+
| Декоратор | Проверка |
|
|
368
|
+
| --- | --- |
|
|
369
|
+
| `@Equals(expected)` | Равенство `expected` |
|
|
370
|
+
| `@NotEquals(expected)` | Неравенство `expected` |
|
|
371
|
+
| `@IsIn(values)` | Значение входит в список |
|
|
372
|
+
| `@NotIn(values)` | Значение не входит в список |
|
|
373
|
+
|
|
374
|
+
### Custom
|
|
375
|
+
|
|
376
|
+
```ts
|
|
377
|
+
import { Custom, validate } from "@ivlev-dev/silent-validation";
|
|
378
|
+
|
|
379
|
+
class Order {
|
|
380
|
+
@Custom((value) => typeof value === "string" && value.startsWith("ORD-"))
|
|
381
|
+
public accessor number!: string;
|
|
382
|
+
|
|
383
|
+
@Custom(async (value) => value !== "blocked")
|
|
384
|
+
public accessor status!: string;
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
`Custom` принимает функцию `(value, context) => boolean | Promise<boolean>`. Асинхронная функция требует `validateAsync`, иначе синхронный `validate` бросит `AsyncRuleError`.
|
|
389
|
+
|
|
390
|
+
## Модификаторы
|
|
391
|
+
|
|
392
|
+
| Декоратор | Назначение |
|
|
393
|
+
| --- | --- |
|
|
394
|
+
| `@ValidateIf(predicate)` | Проверять поле, только если `predicate(instance)` истинно |
|
|
395
|
+
| `@Optional()` | Пропустить все правила поля, если значение `null` или `undefined` |
|
|
396
|
+
| `@Label(text)` | Человекочитаемое имя поля для сообщений |
|
|
397
|
+
| `@Groups(...groups)` | Отнести поле к группам; проверяется при совпадении `options.groups` |
|
|
398
|
+
| `@ValidateOnSet()` | Проверять поле при каждом присваивании и бросать `ValidationException` |
|
|
399
|
+
|
|
400
|
+
```ts
|
|
401
|
+
import { Groups, Label, Optional, ValidateIf, Min, validate } from "@ivlev-dev/silent-validation";
|
|
402
|
+
|
|
403
|
+
class Profile {
|
|
404
|
+
@Label("Возраст")
|
|
405
|
+
@Optional()
|
|
406
|
+
@Min(18)
|
|
407
|
+
public accessor age: number | undefined = undefined;
|
|
408
|
+
|
|
409
|
+
@ValidateIf((instance: Profile) => instance.age !== undefined)
|
|
410
|
+
@Label("Согласие")
|
|
411
|
+
public accessor consent: boolean | undefined = undefined;
|
|
412
|
+
|
|
413
|
+
@Groups("admin")
|
|
414
|
+
public accessor role: string | undefined = undefined;
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
validate(profile, { groups: ["admin"] });
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
Поле без групп выполняется при любом `groups`; поле с группой выполняется, только если хотя бы одна его группа указана в вызове.
|
|
421
|
+
|
|
422
|
+
## Сообщения
|
|
423
|
+
|
|
424
|
+
Каждое правило формирует ключ `validation.<rule>`, например `validation.min` или `validation.isEmail`. Встроенные каталоги — `ru` (по умолчанию, `DEFAULT_LOCALE`) и `en`.
|
|
425
|
+
|
|
426
|
+
```ts
|
|
427
|
+
import { validate, Required, Min, IsEmail } from "@ivlev-dev/silent-validation";
|
|
428
|
+
|
|
429
|
+
class User {
|
|
430
|
+
@Required({ message: "Укажите email" })
|
|
431
|
+
@IsEmail({ messageKey: "validation.required" })
|
|
432
|
+
public accessor email!: string;
|
|
433
|
+
|
|
434
|
+
@Min(18, { message: ({ label, params }) => `${label}: минимум ${params.min}` })
|
|
435
|
+
public accessor age!: number;
|
|
436
|
+
}
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
- `message` — строка с плейсхолдерами `{label}`, `{value}`, `{field}`, `{index}` и параметрами правила, либо функция `(context) => string`. Имеет приоритет над резолвером и каталогом.
|
|
440
|
+
- `messageKey` — другой ключ каталога, например `validation.required`.
|
|
441
|
+
- `label` — ярлык поля в сообщении; приоритет: `options.label` → `@Label` → `options.labels[field]` → имя поля.
|
|
442
|
+
|
|
443
|
+
### Глобальный конфиг
|
|
444
|
+
|
|
445
|
+
```ts
|
|
446
|
+
import {
|
|
447
|
+
configureValidation,
|
|
448
|
+
getValidationConfig,
|
|
449
|
+
resetValidationConfig,
|
|
450
|
+
} from "@ivlev-dev/silent-validation";
|
|
451
|
+
|
|
452
|
+
configureValidation({
|
|
453
|
+
locale: "en",
|
|
454
|
+
messages: {
|
|
455
|
+
en: {
|
|
456
|
+
"validation.min": "{label} must be at least {min}",
|
|
457
|
+
},
|
|
458
|
+
},
|
|
459
|
+
});
|
|
460
|
+
|
|
461
|
+
const config = getValidationConfig();
|
|
462
|
+
resetValidationConfig();
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
`configureValidation` мержит переданные поля с текущими настройками: `locale`, `resolve`, `messages`. Значения `messages` переопределяют встроенные каталоги. Если ключа нет в выбранной локали, используется `ru`, затем встроенный `en`.
|
|
466
|
+
|
|
467
|
+
### Резолвер (i18next)
|
|
468
|
+
|
|
469
|
+
```ts
|
|
470
|
+
import { configureValidation } from "@ivlev-dev/silent-validation";
|
|
471
|
+
import i18next from "i18next";
|
|
472
|
+
|
|
473
|
+
configureValidation({
|
|
474
|
+
locale: "en",
|
|
475
|
+
resolve: ({ key, params, locale }) => i18next.t(key, { ...params, lng: locale }),
|
|
476
|
+
});
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Резолвер `MessageResolver` получает `key`, `params`, `locale`, `label`, `field`, `value`, `path` и возвращает строку или `undefined`. При `undefined` используется каталог. Возвращённая строка интерполируется так же, как шаблон каталога.
|
|
480
|
+
|
|
481
|
+
Резолвер может быть асинхронным: `resolve` вправе вернуть `Promise<string | undefined>`, но такой режим работает только в `validateAsync` (и других async-функциях); синхронный `validate` бросит `Error`. Для i18next есть готовый адаптер `createI18nextResolver`.
|
|
482
|
+
|
|
483
|
+
Для правил размера и длины (`arrayMinSize`, `arrayMaxSize`, `minLength`, `maxLength`) встроенные каталоги содержат плюральные формы (`_one`/`_few`/`_many` в `ru`, `_one`/`_other` в `en`). Форма выбирается по числу из `params.count`/`min`/`max`/`length` или по значению.
|
|
484
|
+
|
|
485
|
+
## Вложенность
|
|
486
|
+
|
|
487
|
+
```ts
|
|
488
|
+
import { Nested, Each, Required, IsInt, validate } from "@ivlev-dev/silent-validation";
|
|
489
|
+
|
|
490
|
+
class Address {
|
|
491
|
+
@Required()
|
|
492
|
+
public accessor city!: string;
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
class Item {
|
|
496
|
+
@Required()
|
|
497
|
+
public accessor name!: string;
|
|
498
|
+
|
|
499
|
+
@IsInt()
|
|
500
|
+
public accessor quantity!: number;
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
class Order {
|
|
504
|
+
@Nested()
|
|
505
|
+
public accessor address!: Address;
|
|
506
|
+
|
|
507
|
+
@Each()
|
|
508
|
+
public accessor items!: Item[];
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
const result = validate(order);
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
Пути ошибок: `address.city`, `items[0].name`, `items[2].quantity`. Для ошибок элементов коллекций заполняется `ValidationError.index` и доступен плейсхолдер `{index}`; путь всегда содержит индекс элемента.
|
|
515
|
+
|
|
516
|
+
`@Nested()` проверяет вложенный объект правилами его класса. `@Each()` делает то же для каждого элемента массива или `Set` и сообщает ошибку, если коллекция или элемент имеют неверный тип. Для примитивных элементов используйте `@Min(0, { each: true })`.
|
|
517
|
+
|
|
518
|
+
Элементы `@Each()` должны быть созданы конструктором класса с декораторами — правила регистрируются при инициализации экземпляра. Plain-объекты без декораторов считаются валидными (у них нет правил).
|
|
519
|
+
|
|
520
|
+
## Ограничения и совместимость
|
|
521
|
+
|
|
522
|
+
- Поддерживаются только stage-3 `accessor`-поля (`public accessor email!: string`). Обычные поля, приватные (`#field`) и статические поля не поддерживаются — декоратор бросает `TypeError` (и типы не дадут применить его к обычному полю).
|
|
523
|
+
- Optional-поле описывается через `| undefined`: `public accessor age: number | undefined = undefined;`. Синтаксис `accessor age?: number` в TypeScript запрещён.
|
|
524
|
+
- Типы проверяются только из аннотаций `accessor`-полей и только при подключённом плагине `validation()` из `@ivlev-dev/silent-validation-vite`. Обычные поля и поля без аннотации остаются без проверки типов; условные/mapped/template/indexed-типы и generic-параметры пропускаются.
|
|
525
|
+
- Валидация явная: ни декораторы, ни типы из аннотаций не запускают проверку без вызова `validate`/`validateAsync`.
|
|
526
|
+
- Нужны stage 3 декораторы: `experimentalDecorators: false`. Legacy-декораторы (`experimentalDecorators: true`) не поддерживаются.
|
|
527
|
+
- ESM-only, Node.js >= 22.
|
|
528
|
+
- `validate` не поддерживает асинхронные правила — используйте `validateAsync`.
|
|
529
|
+
- Вложенный объект должен быть создан конструктором класса с декораторами: правила регистрируются при инициализации экземпляра. Plain-объекты без декораторов считаются валидными (у них нет правил). Кольцевые ссылки не приводят к бесконечной рекурсии.
|
|
530
|
+
- Пути и сообщения не зависят от фреймворка: пакет не требует `@ivlev-dev/silent-core`.
|
|
531
|
+
|
|
532
|
+
## Ссылки
|
|
533
|
+
|
|
534
|
+
- Репозиторий: https://github.com/ivlev-dev/silent-framework
|
|
535
|
+
- Документация API: https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/validation.md
|
|
536
|
+
- CHANGELOG: https://github.com/ivlev-dev/silent-framework/blob/main/CHANGELOG.md
|
|
537
|
+
- Issues: https://github.com/ivlev-dev/silent-framework/issues
|
|
538
|
+
|
|
539
|
+
---
|
|
540
|
+
|
|
541
|
+
MIT © ivlev-dev
|
package/dist/engine.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { FieldKey, SafeParseResult, ValidationOptions, ValidationResult } from "./types.js";
|
|
2
|
+
export declare function validate(instance: object, options?: ValidationOptions): ValidationResult;
|
|
3
|
+
export declare function validateAsync(instance: object, options?: ValidationOptions): Promise<ValidationResult>;
|
|
4
|
+
export declare function validateProperty(instance: object, field: string, options?: ValidationOptions): ValidationResult;
|
|
5
|
+
export declare function validatePropertyAsync(instance: object, field: string, options?: ValidationOptions): Promise<ValidationResult>;
|
|
6
|
+
export declare function validateFieldKey(instance: object, key: FieldKey, options: ValidationOptions | undefined): ValidationResult;
|
|
7
|
+
export declare function validatePartial(instance: object, fields: readonly string[], options?: ValidationOptions): ValidationResult;
|
|
8
|
+
export declare function validatePartialAsync(instance: object, fields: readonly string[], options?: ValidationOptions): Promise<ValidationResult>;
|
|
9
|
+
export declare function safeParse<T extends object>(instance: T, options?: ValidationOptions): SafeParseResult<T>;
|
|
10
|
+
export declare function safeParseAsync<T extends object>(instance: T, options?: ValidationOptions): Promise<SafeParseResult<T>>;
|
|
11
|
+
export declare function validateOrThrow(instance: object, options?: ValidationOptions): void;
|
|
12
|
+
export declare function validateOrThrowAsync(instance: object, options?: ValidationOptions): Promise<void>;
|
|
13
|
+
//# 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;AAs0BpB,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"}
|