@modulify/validator 0.0.2 → 0.2.0

package/docs/ru/02-metadata-and-introspection.md

@@ -0,0 +1,276 @@
+# Метаданные и интроспекция
+
+[Оглавление документации](./00-index.md)  
+[English version](../en/02-metadata-and-introspection.md)
+
+`@modulify/validator` предоставляет публичный слой introspection, построенный вокруг двух небольших entrypoint-ов:
+
+- `meta(...)` для привязки machine-readable metadata к любому constraint;
+- `describe(...)` для чтения стабильного рекурсивного descriptor tree из built-in constraints и совместимых custom validators.
+
+Этот слой намеренно adapter-oriented. Он нужен для того, чтобы прикладной код и tooling могли исследовать структуру валидации без зависимости от приватных runtime internals.
+
+## Быстрый старт
+
+```typescript
+import {
+  describe,
+  isString,
+  meta,
+  optional,
+  shape,
+} from '@modulify/validator'
+
+const registration = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    format: 'email',
+  }),
+  nickname: optional(isString),
+}).strict(), {
+  title: 'Registration form',
+})
+
+const descriptor = describe(registration)
+```
+
+## Что делает `meta(...)`
+
+`meta(...)` добавляет read-only machine-readable metadata к constraint, не меняя validation semantics.
+
+Это значит:
+
+- исходный constraint не мутируется;
+- поведение валидации при успехе и ошибке остаётся тем же;
+- metadata становится видна через `describe(...)`;
+- вложенная metadata остаётся ровно там, где была применена.
+
+Пример:
+
+```typescript
+const email = meta(isString, {
+  title: 'Email',
+  widget: 'email',
+})
+```
+
+Тот же механизм работает для:
+
+- assertions;
+- wrappers вроде `optional(...)`;
+- object shapes;
+- structural validators вроде `each(...)` или `tuple(...)`;
+- custom validators.
+
+## Metadata явная, а не наследуемая
+
+Metadata не распространяется автоматически по descriptor tree.
+
+Если metadata повешена на parent shape, она остаётся на узле shape. Если metadata повешена на child field, она остаётся на узле этого поля.
+
+```typescript
+const profile = meta(shape({
+  email: meta(isString, { title: 'Email' }),
+  name: isString,
+}), {
+  title: 'Profile',
+})
+```
+
+В этом примере:
+
+- узел shape получает `title: 'Profile'`;
+- поле `email` получает `title: 'Email'`;
+- поле `name` не получает metadata, пока вы не добавите её явно.
+
+Это делает metadata предсказуемой и убирает скрытое tree-wide поведение.
+
+## Объединение metadata
+
+Если `meta(...)` применяется к одному и тому же constraint несколько раз, metadata merge-ится слева направо.
+
+```typescript
+const annotated = meta(
+  meta(isString, { title: 'Email' }),
+  { placeholder: 'name@example.com' }
+)
+```
+
+В результате получится один descriptor node, у которого `metadata` содержит оба ключа.
+
+## Что возвращает `describe(...)`
+
+`describe(...)` возвращает стабильный рекурсивный descriptor tree.
+
+Descriptor намеренно machine-readable, а не presentation-oriented. Он спроектирован для adapters и tooling, а не для встроенного рендеринга human-readable messages.
+
+Примеры built-in `kind`:
+
+- `'assertion'`;
+- `'allOf'`;
+- `'optional'`, `'nullable'`, `'nullish'`;
+- `'shape'`, `'each'`, `'tuple'`, `'record'`;
+- `'union'`, `'discriminatedUnion'`;
+- `'validator'` как generic fallback для custom validators без публичного structural descriptor.
+
+## Descriptor-ы assertions
+
+Leaf assertions создают descriptors с:
+
+- `kind: 'assertion'`;
+- `name`;
+- `bail`;
+- основными `code` и `args`;
+- `constraints` для дополнительного checker pipeline;
+- опциональной `metadata`.
+
+Пример:
+
+```typescript
+const descriptor = describe(meta(isString, { title: 'Display name' }))
+```
+
+Так assertion metadata становится доступной без изменения runtime-поведения самой assertion.
+
+## Descriptor-ы wrappers и structural validators
+
+Composed validators описывают себя рекурсивно.
+
+Примеры:
+
+- `optional(...)` раскрывает `child`;
+- `each(...)` раскрывает `item`;
+- `tuple(...)` раскрывает `items`;
+- `union(...)` раскрывает `branches`;
+- `record(...)` раскрывает `values`.
+
+Именно эта рекурсивная структура делает возможными adapter layers без доступа к runtime internals валидаторов.
+
+## Descriptor-ы shape
+
+У shape один из самых богатых built-in descriptor nodes.
+
+Shape descriptor включает:
+
+- `metadata`;
+- `unknownKeys` со значениями `'passthrough'` или `'strict'`;
+- `fields` с descriptor-ами полей;
+- `rules` с компактными summary object-level rules вроде `refine(...)` и `fieldsMatch(...)`.
+
+Пример:
+
+```typescript
+const descriptor = describe(shape({
+  email: meta(isString, { format: 'email' }),
+  password: isString,
+}).strict())
+```
+
+Это особенно полезно для:
+
+- form adapters;
+- contract adapters;
+- custom documentation generators;
+- JSON Schema export через отдельный derivation layer.
+
+## Правила уровня объекта в introspection
+
+Сами callbacks из `refine(...)` не сериализуются.
+
+Вместо этого shape хранит лёгкие rule descriptors в `rules`.
+
+Built-in примеры:
+
+- `fieldsMatch(...)` создаёт компактный `fieldsMatch` rule descriptor;
+- `refine(...)` может принимать собственный компактный rule descriptor object.
+
+Так публичное descriptor tree остаётся стабильным и достаточно сериализуемым для tooling, при этом библиотека не пытается сериализовать произвольные callbacks.
+
+## Пользовательские validators
+
+Custom validators могут участвовать в том же слое introspection через `custom(...)` и публичный метод `describe()`.
+
+```typescript
+import { custom } from '@modulify/validator'
+
+const isoDate = custom({
+  check(value: unknown): value is string {
+    return typeof value === 'string'
+  },
+  run() {
+    return []
+  },
+  describe() {
+    return {
+      kind: 'stringFormat',
+      format: 'iso-date',
+    } as const
+  },
+})
+```
+
+Тогда:
+
+- `describe(isoDate)` вернёт этот публичный descriptor;
+- `meta(...)` всё ещё сможет добавить metadata поверх него.
+
+Если custom validator не реализует `describe()`, `describe(...)` вернёт fallback:
+
+```typescript
+{ kind: 'validator' }
+```
+
+Этот fallback специально минимальный.
+
+## Пример adapter-а
+
+Небольшой adapter может пройти по shape descriptor и собрать widget hints:
+
+```typescript
+import type { ConstraintDescriptor } from '@modulify/validator'
+
+function collectFieldWidgets(node: ConstraintDescriptor) {
+  if (node.kind !== 'shape') {
+    return {}
+  }
+
+  return Object.fromEntries(
+    Object.entries(node.fields).map(([key, child]) => [key, child.metadata?.widget ?? 'text'])
+  )
+}
+```
+
+В этом и состоит основная цель слоя introspection: внешний код может построить своё представление, не зная, как именно внутри реализована runtime validation.
+
+## Связь с экспортом JSON Schema
+
+`toJsonSchema(...)` — это отдельный слой, производный от публичного descriptor contract.
+
+Это значит:
+
+- `describe(...)` — публичный источник истины для introspection;
+- JSON Schema export строится поверх него;
+- библиотека не поддерживает вторую скрытую schema model специально для exporter-ов.
+
+Такое разделение сделано намеренно:
+
+- runtime validation остаётся runtime-first;
+- metadata остаётся явной;
+- export behavior может развиваться как тонкий adapter layer.
+
+## Практические границы
+
+Текущие границы слоя metadata и introspection:
+
+- нет встроенного message rendering или i18n;
+- нет metadata inheritance по дереву;
+- нет отдельного schema DSL параллельно runtime constraints;
+- нет сериализации runtime callbacks из `refine(...)`;
+- custom validators без публичных descriptors намеренно остаются opaque.
+
+## Практические замечания
+
+- используйте `meta(...)`, когда нужны machine-readable annotations, а не скрытое поведение;
+- используйте `describe(...)`, когда нужен стабильный structural view дерева constraint-ов;
+- держите custom descriptors компактными и ecosystem-facing;
+- внешние форматы лучше получать derivation-слоями поверх descriptors, а не чтением приватных validator internals.

package/docs/ru/03-violations.md

@@ -0,0 +1,267 @@
+# Нарушения
+
+[Оглавление документации](./00-index.md)  
+[English version](../en/03-violations.md)
+
+`@modulify/validator` возвращает структурированные violations вместо встроенных human-readable сообщений.
+
+У этой части API два слоя:
+
+- сырой результат `Violation[]`, который возвращают `validate(...)` и `validate.sync(...)`;
+- `ViolationCollection` — тонкая utility-обёртка, создаваемая через `collection(...)`.
+
+## Быстрый старт
+
+```typescript
+import {
+  collection,
+  isString,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+const [ok, validated, violations] = validate.sync({
+  profile: {
+    email: 42,
+  },
+}, shape({
+  profile: shape({
+    email: isString,
+  }),
+}))
+
+const errors = collection(violations)
+const emailErrors = errors.at(['profile', 'email'])
+```
+
+## Почему нарушения структурированы
+
+Библиотека намеренно возвращает данные, а не presentation.
+
+Это позволяет переиспользовать один и тот же результат для:
+
+- локализованных UI-сообщений;
+- form error state;
+- API payloads;
+- аналитики и диагностики;
+- custom adapters и tooling.
+
+## Формат `Violation`
+
+Violation содержит:
+
+- `value` — значение, на котором произошла ошибка;
+- `path` — место ошибки внутри вложенного объекта или массива;
+- `violates` — machine-readable описание того, что именно нарушено.
+
+Пример:
+
+```typescript
+import type { Violation } from '@modulify/validator'
+
+const violation: Violation = {
+  value: '',
+  path: ['form', 'nickname'],
+  violates: {
+    kind: 'assertion',
+    name: 'hasLength',
+    code: 'length.min',
+    args: [4],
+  },
+}
+```
+
+## `violates`
+
+Поле `violates` содержит структурированную информацию о нарушении.
+
+Важные части:
+
+- `kind` — какой слой произвёл ошибку;
+- `name` — какая assertion или validator её создала;
+- `code` — семантический код ошибки;
+- `args` — структурированная нагрузка этой ошибки.
+
+Это позволяет потребителю самому решать, как позже рендерить и трансформировать ошибки.
+
+## `violates.kind`
+
+`violates.kind` показывает слой, который создал ошибку:
+
+- `'assertion'`
+- `'validator'`
+- `'runtime'`
+
+Примеры:
+
+- ошибки `isString` относятся к assertion-level;
+- `shape.unknown-key` относится к validator-level;
+- rejected async validations могут появиться как runtime-level ошибки.
+
+## Вложенные пути
+
+`path` — это обычный `PropertyKey[]`.
+
+Это значит:
+
+- свойства объекта остаются property keys;
+- позиции массивов остаются числовыми индексами;
+- вложенные ошибки сохраняют полный абсолютный путь от корня входного значения.
+
+Примеры:
+
+- `['profile', 'email']`
+- `['items', 0, 'title']`
+
+Именно поэтому библиотека остаётся adapter-friendly и не сериализует пути в строки.
+
+## Результаты валидации
+
+`validate(...)` и `validate.sync(...)` возвращают:
+
+```typescript
+type ValidationTuple<T> =
+  | [ok: true, validated: T, violations: []]
+  | [ok: false, validated: unknown, violations: Violation[]]
+```
+
+То есть:
+
+- при успехе список violations пуст;
+- при ошибке возвращается исходное значение и собранный список структурированных нарушений.
+
+## `ViolationCollection`
+
+`ViolationCollection` — это тонкая convenience-обёртка над `Violation[]`.
+
+Она сохраняет модель raw list, но добавляет несколько операций для постобработки:
+
+- `size`
+- итерацию через `for...of`
+- `.forEach(...)`
+- `.map(...)`
+- `.at(path)`
+- `.tree()`
+
+Её цель — удобство, а не вторая error model.
+
+## `collection(...)`
+
+Используйте `collection(...)`, чтобы обернуть сырой `Violation[]`:
+
+```typescript
+const errors = collection(violations)
+```
+
+Это особенно полезно, когда валидация уже произошла и дальше нужно:
+
+- посмотреть ошибки конкретного поля;
+- собрать вложенное UI-представление;
+- сгруппировать или преобразовать коды;
+- пользоваться helper-методами без изменения исходного формата данных.
+
+## Точный поиск по пути через `.at(path)`
+
+`.at(path)` делает точное совпадение по пути.
+
+```typescript
+const rootErrors = errors.at([])
+const emailErrors = errors.at(['profile', 'email'])
+```
+
+Важная семантика:
+
+- `at([])` означает root-level ошибки;
+- violations без `path` считаются root-level в collection utilities;
+- `at(['profile'])` не включает `['profile', 'email']`;
+- результатом снова будет `ViolationCollection`.
+
+Это делает path lookup предсказуемым и простым.
+
+## Древовидное представление через `.tree()`
+
+`.tree()` строит вложенное machine-readable дерево из текущей коллекции.
+
+```typescript
+const tree = errors.tree()
+```
+
+Это полезно, если потребителю нужны:
+
+- иерархический обход;
+- рендеринг вложенных ошибок;
+- path-aware UI state;
+- структурированное debugging view.
+
+Tree nodes содержат:
+
+- `path`
+- `self`
+- `subtree`
+- `children`
+- `.at(path)`
+
+## `ViolationTreeNode`
+
+Tree view имеет такой вид:
+
+```typescript
+type ViolationTreeNode = {
+  path: readonly PropertyKey[]
+  self: ViolationCollection
+  subtree: ViolationCollection
+  children: ReadonlyMap<PropertyKey, ViolationTreeNode>
+  at(path: readonly PropertyKey[]): ViolationTreeNode | undefined
+}
+```
+
+Важно различать:
+
+- `self` содержит только violations ровно на текущем пути;
+- `subtree` содержит нарушения на текущем пути и все нарушения потомков.
+
+## Семантика путей в дереве
+
+Tree nodes сохраняют абсолютные пути.
+
+Кроме того:
+
+- промежуточные узлы могут существовать, даже если у них нет собственных violations;
+- они всё равно полезны, потому что у потомков могут быть ошибки;
+- дерево строится из path arrays, а не из dot-separated строк.
+
+Так структура остаётся согласованной с raw violation format.
+
+## Практический пример
+
+```typescript
+const [ok, validated, violations] = validate.sync({
+  profile: {
+    email: '',
+  },
+}, shape({
+  profile: shape({
+    email: [isString],
+  }),
+}))
+
+const errors = collection(violations)
+const rootErrors = errors.at([])
+const emailErrors = errors.at(['profile', 'email'])
+const codes = emailErrors.map(violation => violation.violates.code)
+const tree = errors.tree()
+```
+
+Из одного raw списка violations можно получить:
+
+- collections по точному пути;
+- отображение кодов;
+- дерево для вложенного обхода.
+
+## Практические замечания
+
+- сохраняйте `Violation[]` как канонический transport format;
+- используйте `collection(...)` только когда helper API действительно упрощает работу;
+- считайте `code` и `args` главными точками интеграции;
+- оставляйте message rendering вне validation layer;
+- предпочитайте работу с path arrays вместо сериализации путей в строки.