@modulify/validator 0.1.0 → 0.2.0

package/docs/ru/04-json-schema-export.md

@@ -0,0 +1,264 @@
+# Экспорт JSON Schema
+
+[Оглавление документации](./00-index.md)  
+[English version](../en/04-json-schema-export.md)
+
+`@modulify/validator/json-schema` предоставляет тонкий слой экспорта в JSON Schema поверх публичного descriptor contract.
+
+Это именно derivation layer, а не вторая schema model. Exporter читает публичные descriptors и строит по ним представление в виде JSON Schema.
+
+## Быстрый старт
+
+```typescript
+import {
+  isNumber,
+  isString,
+  meta,
+  optional,
+  shape,
+} from '@modulify/validator'
+import { toJsonSchema } from '@modulify/validator/json-schema'
+
+const profile = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    format: 'email',
+  }),
+  age: optional(isNumber),
+}).strict(), {
+  title: 'Profile',
+})
+
+const jsonSchema = toJsonSchema(profile)
+```
+
+## Ментальная модель
+
+Поток экспорта специально устроен просто:
+
+1. validators публикуют публичные descriptors через `describe(...)`;
+2. `toJsonSchema(...)` строит JSON Schema поверх этих descriptors;
+3. unsupported или opaque nodes либо пропускаются в best-effort режиме, либо приводят к ошибке в strict режиме.
+
+Это разделение важно, потому что:
+
+- runtime validation остаётся runtime-first;
+- поведение exporter-а остаётся явным;
+- custom tooling может опираться на один публичный introspection contract.
+
+## Точка входа
+
+JSON Schema export импортируется из отдельного subpath:
+
+```typescript
+import {
+  JsonSchemaExportError,
+  toJsonSchema,
+} from '@modulify/validator/json-schema'
+```
+
+Root package намеренно не делает реэкспорт этого API.
+
+## Поддерживаемые built-in mappings
+
+Exporter покрывает built-in descriptor set, который уже участвует в публичной introspection.
+
+### Базовые assertions
+
+Практические mappings включают:
+
+- `isString` -> `type: 'string'`
+- `isNumber` -> `type: 'number'`
+- `isBoolean` -> `type: 'boolean'`
+- `isNull` -> `type: 'null'`
+- `isEmail` -> `type: 'string'` и `format: 'email'`
+- `exact(...)` -> `const`
+- `oneOf(...)` -> `enum`
+- `hasLength(...)` -> ограничения длины для строк и массивов
+
+### Обёртки
+
+Поддерживаются wrappers:
+
+- `optional(...)`
+- `nullable(...)`
+- `nullish(...)`
+
+`optional(...)` влияет на вычисление object `required`. `nullable(...)` и `nullish(...)` экспортируются как union с `null`.
+
+### Структурные combinators
+
+Поддерживаются structural mappings:
+
+- `shape(...)`
+- `each(...)`
+- `tuple(...)`
+- `record(...)`
+
+### Ветвящиеся combinators
+
+Поддерживаются branching mappings:
+
+- `union(...)`
+- `discriminatedUnion(...)`
+
+### Последовательные slots
+
+Массивы constraints в одном slot экспортируются как JSON Schema `allOf`.
+
+## Преобразование object schemas
+
+`shape(...)` экспортируется как JSON Schema object с:
+
+- `type: 'object'`
+- `properties`
+- `required`
+- `additionalProperties`
+
+Поведение unknown keys отображается так:
+
+- `.strict()` -> `additionalProperties: false`
+- default или `.passthrough()` -> `additionalProperties: true`
+
+## `required` и `undefined`
+
+Одна из важных границ касается наличия объектных полей.
+
+Runtime layer во многих практических сценариях рассматривает как один и тот же случай:
+
+- отсутствие ключа;
+- и ключ со значением `undefined`;
+
+особенно вокруг `optional(...)` и derived helpers вроде `partial()`.
+
+JSON Schema моделирует это не так. Поэтому exporter аппроксимирует наличие полей через JSON Schema `required`, а не обещает точную semantic parity.
+
+Это сделано намеренно: экспорт нужно воспринимать как interoperability layer, а не как обещание полной эквивалентности runtime semantics и JSON Schema.
+
+## Преобразование metadata
+
+Exporter не копирует всю metadata в JSON Schema автоматически.
+
+Вместо этого используется небольшой явный whitelist:
+
+- `title`
+- `description`
+- `format`
+- `default`
+- `examples`
+- `deprecated`
+- `readOnly`
+- `writeOnly`
+
+Остальная metadata остаётся библиотечно-специфичной и автоматически в экспорт не попадает.
+
+Так metadata layer остаётся явным и не превращается в implicit magic.
+
+## Best-Effort режим
+
+Best-effort режим используется по умолчанию:
+
+```typescript
+const schema = toJsonSchema(profile)
+```
+
+В этом режиме:
+
+- unsupported или opaque nodes превращаются в permissive `{}` schema nodes;
+- unsupported object-level shape rules отбрасываются;
+- отброшенные shape rules по возможности помечаются через `$comment`.
+
+Этот режим удобен, когда нужен максимально широкий внешний schema export, даже если часть runtime semantics нельзя выразить честно.
+
+## Strict режим
+
+Strict режим отклоняет unsupported nodes:
+
+```typescript
+const schema = toJsonSchema(profile, { mode: 'strict' })
+```
+
+Если export нельзя представить faithfully, exporter выбрасывает `JsonSchemaExportError`.
+
+Эта ошибка содержит:
+
+- descriptor, на котором произошёл сбой;
+- machine-readable причину;
+- путь внутри descriptor tree, где возникла ошибка.
+
+Strict режим полезен, когда silent fallback был бы вводящим в заблуждение.
+
+## Неподдерживаемые и opaque cases
+
+Не всё runtime behavior имеет faithful representation в JSON Schema.
+
+Важные примеры:
+
+- custom validators без поддерживаемого публичного descriptor;
+- неизвестные custom descriptor kinds;
+- object-level `refine(...)` rules;
+- descriptor nodes, чья семантика зависит от runtime-only behavior;
+- значения, которые нельзя практично представить как JSON Schema constants или enums.
+
+Exporter фиксирует эти границы явно и не пытается гадать.
+
+## Связь с `describe(...)`
+
+`toJsonSchema(...)` находится downstream от `describe(...)`.
+
+Это значит:
+
+- JSON Schema export должен опираться на публичные descriptors;
+- логика exporter-а не должна зависеть от приватных runtime internals;
+- custom validators участвуют в export сначала через публичный descriptor contract.
+
+Так архитектура остаётся тонкой и стабильной для внешнего tooling.
+
+## Пример metadata-aware экспорта shape
+
+```typescript
+const profile = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    format: 'email',
+  }),
+  age: optional(isNumber),
+}).strict(), {
+  title: 'Profile',
+})
+
+const schema = toJsonSchema(profile)
+```
+
+Практически это означает:
+
+- metadata shape может стать schema metadata;
+- metadata полей может стать metadata свойств;
+- strict object behavior становится `additionalProperties: false`.
+
+## Пример ошибки в strict режиме
+
+```typescript
+const schema = shape({
+  publishedAt: custom({
+    check(value: unknown): value is string {
+      return typeof value === 'string'
+    },
+    run() {
+      return []
+    },
+  }),
+})
+
+toJsonSchema(schema, { mode: 'strict' })
+```
+
+Здесь будет исключение, потому что custom validator остаётся opaque для exporter-а.
+
+## Практические замечания
+
+- воспринимайте JSON Schema export как interoperability layer;
+- используйте best-effort режим, когда partial export допустим;
+- используйте strict режим, когда unsupported semantics должны приводить к явной ошибке;
+- если custom descriptors должны участвовать в export, держите их компактными и публичными;
+- не считайте JSON Schema export заменой runtime validation semantics.

package/docs/ru/05-public-api.md

@@ -0,0 +1,123 @@
+# Публичный API
+
+[Оглавление документации](./00-index.md)  
+[English version](../en/05-public-api.md)
+
+Этот документ суммирует package surface `@modulify/validator` и поддерживаемые subpath exports.
+
+Это навигационный guide о том:
+
+- где находится каждый публичный entrypoint;
+- какие группы функций экспортируются вместе;
+- как выглядит результат валидации;
+- какие API вынесены в отдельные subpath вроде predicates и JSON Schema export.
+
+## Корневой пакет
+
+Root package экспортирует:
+
+- `validate`
+- `validate.sync`
+- `matches.sync`
+- `meta`
+- `describe`
+- `custom`
+- `collection`
+- `ViolationCollection`
+- все экспорты из `./assertions`
+- все экспорты из `./combinators`
+
+Используйте root package, когда нужен основной validation API, composed validators, metadata/introspection и violation utilities.
+
+## Assertions и combinators
+
+Root package включает:
+
+- низкоуровневое создание assertions через `assert(...)`
+- built-in assertions вроде `isString`, `isNumber`, `isBoolean`, `isNull`, `isEmail`, `hasLength(...)`, `oneOf(...)`
+- structural combinators вроде `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`
+- wrappers вроде `optional(...)`, `nullable(...)`, `nullish(...)`
+- branching combinators вроде `union(...)` и `discriminatedUnion(...)`
+- проверку точного значения через `exact(...)`
+
+Это основной runtime-facing API surface библиотеки.
+
+## Метаданные и интроспекция
+
+Тот же root package также включает:
+
+- `meta(...)`
+- `describe(...)`
+- `custom(...)`
+
+Вместе они дают публичный machine-readable descriptor contract и metadata layer поверх него.
+
+## Утилиты для нарушений
+
+Root package также содержит:
+
+- raw violation results, возвращаемые `validate(...)`
+- `collection(...)`
+- `ViolationCollection`
+
+Это основные утилиты для постобработки machine-readable validation failures.
+
+## Результат валидации
+
+`validate(...)` и `validate.sync(...)` возвращают:
+
+```typescript
+type ValidationTuple<T> =
+  | [ok: true, validated: T, violations: []]
+  | [ok: false, validated: unknown, violations: Violation[]]
+```
+
+Практически это значит:
+
+- `ok` показывает, прошла ли валидация;
+- `validated` становится строго типизированным только в успешной ветке;
+- `violations` пуст при успехе и содержит структурированные ошибки при неуспехе.
+
+## Subpath predicates
+
+Predicates доступны из:
+
+```typescript
+@modulify/validator/predicates
+```
+
+Этот subpath содержит переиспользуемые runtime/type-guard helpers и predicate combinators, например:
+
+- `isString`
+- `isNumber`
+- `isRecord`
+- `isArray`
+- `isShape`
+- `And`, `Or`, `Not`
+
+Используйте этот subpath, когда нужны guard-style runtime checks без более высокого validation layer.
+
+## Subpath экспорта JSON Schema
+
+JSON Schema export доступен из:
+
+```typescript
+@modulify/validator/json-schema
+```
+
+Этот subpath содержит:
+
+- `toJsonSchema(...)`
+- `JsonSchemaExportError`
+
+Он намеренно отделён от root package, чтобы export-specific concerns не смешивались с основным validation entrypoint.
+
+## Как читать package surface
+
+На верхнем уровне:
+
+- root package = validation, combinators, metadata, violations;
+- `./predicates` = standalone runtime/type-guard helpers;
+- `./json-schema` = производный слой JSON Schema export.
+
+Такое разделение сохраняет основной API понятным и в то же время позволяет держать специализированные subpath там, где это действительно нужно.

package/docs/ru/06-common-recipes.md

@@ -0,0 +1,273 @@
+# Практические рецепты
+
+[Оглавление документации](./00-index.md)  
+[Английская версия](../en/06-common-recipes.md)
+
+Это руководство отвечает на практический вопрос:
+
+> Какую часть `@modulify/validator` использовать для задачи `X`?
+
+Оно специально ориентировано на практические сценарии. Открывайте его, когда общее направление библиотеки уже понятно и нужен быстрый путь к конкретному решению.
+
+## Сначала выберите правильный слой
+
+Быстрое правило выбора:
+
+- используйте `@modulify/validator/predicates`, когда нужны только runtime checks и type guards;
+- используйте built-in assertions вроде `isString`, `isDefined`, `hasLength(...)`, `oneOf(...)`, когда нужны машиночитаемые ошибки;
+- используйте combinators вроде `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)`, `discriminatedUnion(...)`, когда валидация становится структурной;
+- используйте `meta(...)` и `describe(...)`, когда другой слой нуждается в стабильных машиночитаемых descriptors;
+- используйте `toJsonSchema(...)` только тогда, когда нужно представление для interoperability или экспорта, а не источник runtime truth.
+
+## Валидация API payload
+
+Используйте `shape(...)` вместе с leaf assertions.
+
+```typescript
+import {
+  hasLength,
+  isDefined,
+  isString,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+const createUser = shape({
+  email: [isDefined, isString],
+  password: [isString, hasLength({ min: 8 })],
+}).strict()
+
+const [ok, validated, violations] = validate.sync(input, createUser)
+```
+
+Практический шаблон:
+
+- используйте `.strict()` для request payload, если неизвестные ключи должны отклоняться;
+- держите leaf checks маленькими и хорошо сочетаемыми друг с другом;
+- используйте элемент кортежа `validated` внутри успешной ветки;
+- используйте `violations` как структурированные данные для ответов API, логов или сопоставления с UI.
+
+## Сужение уже существующей переменной в sync-коде
+
+Используйте `matches.sync(...)`.
+
+```typescript
+import {
+  isDefined,
+  isString,
+  matches,
+} from '@modulify/validator'
+
+const value: unknown = source()
+
+if (matches.sync(value, [isDefined, isString])) {
+  value.toUpperCase()
+}
+```
+
+Используйте этот API, когда нужно сузить саму исходную переменную.
+
+Не используйте для этого `validate.sync(...)`, если главная цель — сузить исходную переменную. `validate.sync(...)` сужает `validated` в кортеже, а не исходное входное значение.
+
+## Моделирование optional, nullable и nullish полей
+
+Используйте wrapper, который соответствует вашей runtime-семантике:
+
+- `optional(x)` принимает `undefined`
+- `nullable(x)` принимает `null`
+- `nullish(x)` принимает и `null`, и `undefined`
+
+```typescript
+const profile = shape({
+  nickname: optional(isString),
+  middleName: nullable(isString),
+  bio: nullish(isString),
+})
+```
+
+Практическое правило:
+
+- используйте `optional(...)` для отсутствующих или неустановленных полей;
+- используйте `nullable(...)`, когда `null` — это осмысленное явное значение;
+- используйте `nullish(...)` только тогда, когда оба случая действительно допустимы.
+
+## Переиспользование одной shape в нескольких представлениях
+
+Соберите одну базовую shape, а затем выводите производные варианты.
+
+```typescript
+import {
+  exact,
+  isString,
+  optional,
+  shape,
+} from '@modulify/validator'
+
+const account = shape({
+  id: isString,
+  nickname: optional(isString),
+  role: exact('admin'),
+}).strict()
+
+const publicAccount = account.pick(['id', 'nickname'])
+const editableAccount = account.partial()
+const adminAccount = account.extend({ team: isString })
+```
+
+Этот шаблон полезен, когда один доменный объект используется в:
+
+- API payload;
+- состоянии формы;
+- внутренних границах сервиса;
+- публичных представлениях с урезанным набором полей.
+
+Помните, что структурные derivations вроде `pick()`, `omit()`, `partial()`, `extend()` и `merge()` намеренно сбрасывают object-level rules.
+
+## Добавление metadata для UI без жёсткой связи UI со слоем валидации
+
+Используйте `meta(...)` поверх любого constraint.
+
+```typescript
+import {
+  isString,
+  meta,
+  shape,
+} from '@modulify/validator'
+
+const registration = shape({
+  email: meta(isString, {
+    title: 'Email',
+    description: 'Primary login address',
+  }),
+})
+```
+
+Это удобно, когда отдельному слою нужны:
+
+- названия полей;
+- placeholders или подсказки для отображения;
+- предметно-ориентированные метаданные для отображения;
+- инструменты, работающие через descriptors.
+
+Только часть метаданных позже отображается в JSON Schema. Остальные ключи остаются специфичными для библиотеки.
+
+## Построение состояния ошибок полей для форм
+
+Используйте `collection(...)` поверх `violations`.
+
+```typescript
+import {
+  collection,
+  isString,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+const schema = shape({
+  profile: shape({
+    email: isString,
+  }),
+})
+
+const [ok, validated, violations] = validate.sync(input, schema)
+const errors = collection(violations)
+
+const rootErrors = errors.at([])
+const emailErrors = errors.at(['profile', 'email'])
+```
+
+Это рекомендуемая форма, когда нужен точный поиск по path, а не разбор строк.
+
+## Добавление межполевых правил
+
+Используйте `fieldsMatch(...)` для частого случая подтверждения поля и `refine(...)` для всего остального.
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirmPassword: isString,
+}).fieldsMatch(['password', 'confirmPassword'])
+```
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirmPassword: isString,
+}).refine(value => {
+  return value.password === value.confirmPassword
+    ? []
+    : [{
+      path: ['confirmPassword'],
+      code: 'shape.fields.mismatch',
+      args: [['password', 'confirmPassword']],
+    }]
+})
+```
+
+Выбирайте `fieldsMatch(...)`, когда правило — это именно равенство двух selectors.
+
+Выбирайте `refine(...)`, когда:
+
+- участвуют больше двух полей;
+- правило доменно-специфично;
+- нужен явный контроль над выходным path;
+- нужен custom descriptor для introspection.
+
+## Написание custom validator, понятного инструментам
+
+Используйте `custom(...)` и добавляйте `describe()`, если validator должен участвовать в публичной introspection.
+
+```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' as const,
+      format: 'iso-date' as const,
+    }
+  },
+})
+```
+
+Без `describe()` validator намеренно остаётся непрозрачным для `describe(...)` и `toJsonSchema(...)`.
+
+## Безопасный экспорт JSON Schema
+
+Используйте `toJsonSchema(...)` в двух режимах в зависимости от потребителя.
+
+```typescript
+import { toJsonSchema } from '@modulify/validator/json-schema'
+
+const schema = toJsonSchema(profile)
+const strictSchema = toJsonSchema(profile, { mode: 'strict' })
+```
+
+Используйте best-effort режим, когда:
+
+- внешние потребители допускают permissive `{}` nodes;
+- частичный экспорт лучше, чем его отсутствие;
+- нужно максимально широкое представление schema.
+
+Используйте strict режим, когда:
+
+- экспорт с потерями был бы вводящим в заблуждение;
+- JSON Schema является частью контракта;
+- unsupported runtime semantics должны падать явно.
+
+## Рекомендуемый порядок чтения
+
+Если вы только входите в библиотеку, самый короткий полезный маршрут такой:
+
+1. `README.md`
+2. `01-shape-api.md`
+3. `03-violations.md`
+4. `02-metadata-and-introspection.md`
+5. `04-json-schema-export.md`
+6. `07-ai-reference.md`, если нужна компактная сводка по контракту