@modulify/validator 0.0.2 → 0.2.0

package/docs/en/08-violation-code-types.md

@@ -0,0 +1,241 @@
+# Violation Code Types
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/08-violation-code-types.md)
+
+`@modulify/validator` exposes two related layers around machine-readable codes:
+
+- exact literal codes in assertion descriptors and structured violations;
+- an extensible global registry that can be used to derive a project-wide union of known codes.
+
+This guide explains when each layer is useful, how they work together, and how to extend them safely.
+
+## Quick Start
+
+The public entrypoints are:
+
+- `ViolationCodeEntry` - a compact contract record for a known code;
+- `ViolationCodeRegistry` - an interface that collects known codes;
+- `ViolationCode` - a union extracted from `keyof ViolationCodeRegistry`;
+- `ViolationArgs<C>`, `ViolationKindOf<C>`, and `ViolationNameOf<C>` - code-driven utility types.
+
+The package ships built-in keys for its own built-in violations, for example:
+
+- `'type.string'`
+- `'length.min'`
+- `'shape.unknown-key'`
+- `'runtime.rejection'`
+
+So the following works out of the box:
+
+```typescript
+import type { ViolationCode } from '@modulify/validator'
+
+const code: ViolationCode = 'type.string'
+```
+
+## Exact Codes From `describe(...)`
+
+Built-in assertions now preserve their exact code literals in introspection.
+
+```typescript
+import {
+  describe,
+  hasLength,
+  isString,
+} from '@modulify/validator'
+
+const stringDescriptor = describe(isString)
+const lengthDescriptor = describe(hasLength({ min: 3 }))
+```
+
+In TypeScript this means:
+
+- `stringDescriptor.code` is typed as `'type.string'`;
+- `stringDescriptor.args` is typed as `[]`;
+- `lengthDescriptor.code` is typed as `'length.unsupported-type'`;
+- `lengthDescriptor.constraints[number].code` is typed as a concrete length-code union instead of plain `string`.
+
+This is useful when adapters inspect descriptors and want code-aware branching without hand-written casts.
+
+## What The Global Registry Solves
+
+Exact literals on individual values are good for local introspection.
+
+The global registry solves a different problem: extracting one reusable union for the whole app.
+
+```typescript
+import type { ViolationCode } from '@modulify/validator'
+
+type AppViolationCode = ViolationCode
+```
+
+That union can be reused in:
+
+- message dictionaries;
+- analytics payload contracts;
+- API error envelopes;
+- UI error-state mappers;
+- shared helper utilities.
+
+## Extending `ViolationCodeRegistry`
+
+The registry is designed for module augmentation and now stores small code contracts.
+
+```typescript
+import type { ViolationCodeEntry } from '@modulify/validator'
+import '@modulify/validator'
+
+declare module '@modulify/validator' {
+  interface ViolationCodeRegistry {
+    'user.email.taken': ViolationCodeEntry<'validator', 'user', readonly []>;
+    'profile.password.mismatch': ViolationCodeEntry<'validator', 'shape', readonly []>;
+  }
+}
+```
+
+After that:
+
+```typescript
+import type { ViolationCode } from '@modulify/validator'
+
+const codeA: ViolationCode = 'user.email.taken'
+const codeB: ViolationCode = 'profile.password.mismatch'
+```
+
+This lets you define project-specific codes once and reuse the extracted union everywhere else.
+
+If you still have older augmentations that use `never`, they continue to contribute to `ViolationCode`, but they fall back to generic `kind` / `name` / `args` typing until you migrate them to `ViolationCodeEntry`.
+
+## Deriving Related Types From A Code
+
+Once a code is registered with a contract entry, it becomes a key into the related type information.
+
+```typescript
+import type {
+  ViolationArgs,
+  ViolationKindOf,
+  ViolationNameOf,
+  ViolationSubject,
+} from '@modulify/validator'
+
+type PasswordArgs = ViolationArgs<'profile.password.mismatch'>
+type PasswordKind = ViolationKindOf<'profile.password.mismatch'>
+type PasswordName = ViolationNameOf<'profile.password.mismatch'>
+type PasswordSubject = ViolationSubject<'profile.password.mismatch'>
+```
+
+That means:
+
+- `PasswordArgs` becomes `readonly []`;
+- `PasswordKind` becomes `'validator'`;
+- `PasswordName` becomes `'shape'`;
+- `PasswordSubject` gets the matching `kind`, `name`, `code`, and `args`.
+
+## Using Augmented Codes In Custom Assertions
+
+Custom assertions can keep their own explicit code literals.
+
+```typescript
+import { assert } from '@modulify/validator/assertions'
+
+const isAvailableEmail = assert(
+  (value: unknown): value is string => typeof value === 'string' && value.includes('@'),
+  {
+    name: 'isAvailableEmail',
+    bail: true,
+    code: 'user.email.taken',
+  }
+)
+```
+
+Then `describe(isAvailableEmail).code` is typed as `'user.email.taken'`.
+
+This part does not depend on the global union extraction. The literal is preserved directly from the assertion definition.
+
+## Using Augmented Codes In Shape Refinements
+
+The same idea applies to object-level refinement issues.
+
+```typescript
+import type { ObjectShapeRefinementIssue } from '@modulify/validator'
+import {
+  isEmail,
+  isString,
+  shape,
+} from '@modulify/validator'
+
+const signUpForm = shape({
+  email: [isString, isEmail],
+  password: isString,
+  confirmation: shape({
+    password: isString,
+  }),
+}).refine(value => {
+  if (value.password === value.confirmation.password) {
+    return []
+  }
+
+  return [{
+    path: ['confirmation', 'password'],
+    code: 'profile.password.mismatch',
+    args: [],
+  }] satisfies ObjectShapeRefinementIssue<'profile.password.mismatch'>
+})
+```
+
+That keeps the refinement code aligned with the same registry-backed union used elsewhere.
+
+## A Practical Pattern For App-Level Mappers
+
+Many consumers want a small helper layer that maps codes into rendering or transport concerns.
+
+```typescript
+import type {
+  Violation,
+  ViolationCode,
+} from '@modulify/validator'
+
+const labels: Partial<Record<ViolationCode, string>> = {
+  'type.string': 'Expected a string',
+  'length.min': 'Value is too short',
+  'user.email.taken': 'Email is already taken',
+}
+
+function toLabel(violation: Violation) {
+  return labels[violation.violates.code as ViolationCode] ?? violation.violates.code
+}
+```
+
+You do not need to force every possible code into one giant exhaustive map. `Partial<Record<ViolationCode, ...>>` is often the most practical option.
+
+## Built-In Union vs Explicit Literal Preservation
+
+These two behaviors are complementary:
+
+- built-in and augmented codes appear in the reusable `ViolationCode` union;
+- explicit custom literals are preserved directly where values are created, such as `assert(...)` or typed refinement issues.
+
+That distinction is important.
+
+If you define a custom literal but do not augment `ViolationCodeRegistry`:
+
+- local descriptor and violation values can still carry that exact literal;
+- the global `ViolationCode` union will not include it yet.
+
+If you augment `ViolationCodeRegistry` with `never` instead of `ViolationCodeEntry`:
+
+- the global `ViolationCode` union will include the code;
+- the code still falls back to generic `kind`, `name`, and `args` typing.
+
+So the usual recommendation is:
+
+1. define the custom code where the violation is produced;
+2. add it to `ViolationCodeRegistry`;
+3. reuse `ViolationCode` in adapters and app-level helper types.
+
+## Related APIs
+
+- [Metadata And Introspection](./02-metadata-and-introspection.md)
+- [Violations](./03-violations.md)
+- [Public API](./05-public-api.md)

package/docs/ru/00-index.md

@@ -0,0 +1,15 @@
+# Документация
+
+- [README на русском](./README.md) - Перевод основного README с обзором библиотеки и ссылками на подробные руководства.
+- [API объектных схем](./01-shape-api.md) - Подробное описание `shape(...)`, производных вспомогательных методов, режимов unknown keys и правил уровня объекта.
+- [Метаданные и интроспекция](./02-metadata-and-introspection.md) - Подробное описание слоя метаданных, introspection и пользовательских descriptors.
+- [Нарушения](./03-violations.md) - Подробное описание формата violation, `collection(...)` и дерева ошибок.
+- [Экспорт JSON Schema](./04-json-schema-export.md) - Подробное описание слоя экспорта, поддерживаемых преобразований и режимов strict и best-effort.
+- [Публичный API](./05-public-api.md) - Обзор публичных точек входа, subpath exports и результата валидации.
+- [Практические рецепты](./06-common-recipes.md) - Практические сценарии по выбору слоя, валидации payload, переиспользованию shape, построению состояния ошибок в UI и безопасному экспорту схемы.
+- [Справка для AI](./07-ai-reference.md) - Краткое описание контракта для AI agents, инструментов и быстрого поиска стабильной семантики библиотеки.
+- [Типы кодов нарушений](./08-violation-code-types.md) - Подробное руководство по `ViolationCodeRegistry`, `ViolationCode`, сохранению literal-кодов в descriptors и внешнему расширению реестра.
+
+## Переводы
+
+- [English](../en/00-index.md)

package/docs/ru/01-shape-api.md

@@ -0,0 +1,348 @@
+# API объектных схем
+
+[Оглавление документации](./00-index.md)  
+[English version](../en/01-shape-api.md)
+
+`shape(...)` — это переиспользуемый API объектных схем в `@modulify/validator`.
+
+Он сохраняет тот же runtime validation kernel, что и остальная библиотека, но добавляет небольшой неизменяемый object-oriented слой для:
+
+- валидации вложенных объектов;
+- переиспользуемых object schema;
+- производных схем вроде `pick(...)`, `omit(...)` и `partial(...)`;
+- object-level rules вроде `refine(...)` и `fieldsMatch(...)`;
+- descriptor-based introspection через `describe(...)`.
+
+## Быстрый старт
+
+```typescript
+import {
+  exact,
+  isString,
+  optional,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+const profile = shape({
+  id: isString,
+  nickname: optional(isString),
+  role: exact('admin'),
+}).strict()
+
+const [ok, validated, violations] = validate.sync({
+  id: 'u1',
+  nickname: 'neo',
+  role: 'admin',
+}, profile)
+```
+
+`shape(...)` возвращает обычный validator, поэтому его можно использовать везде, где принимается regular constraint.
+
+## Ментальная модель
+
+Shape по-прежнему остаётся validator-ом. Дополнительный API — это тонкая обёртка поверх object descriptor и небольшого набора immutable helpers для derivation.
+
+Каждое поле в descriptor может содержать:
+
+- один constraint;
+- массив constraint-ов, которые выполняются последовательно;
+- другой structural validator вроде `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)` или `discriminatedUnion(...)`.
+
+Поэтому object validation остаётся согласованной с остальной библиотекой:
+
+- field-level checks переиспользуют те же assertions и combinators;
+- violations сохраняют обычные вложенные `path`;
+- introspection идёт через тот же контракт `describe(...)`;
+- metadata остаётся явной через `meta(...)`.
+
+## Базовое создание shape
+
+```typescript
+import {
+  hasLength,
+  isDefined,
+  isString,
+  shape,
+} from '@modulify/validator'
+
+const registration = shape({
+  email: [isDefined, isString],
+  password: [isString, hasLength({ min: 8 })],
+})
+```
+
+Runtime behavior:
+
+- входное значение должно быть plain record-like object;
+- каждое объявленное поле валидируется по своему slot;
+- вложенные violations возвращаются на пути поля;
+- unknown keys по умолчанию разрешены.
+
+## Неизвестные ключи
+
+У shape есть два режима работы с неизвестными ключами:
+
+- `'passthrough'` — лишние ключи разрешены;
+- `'strict'` — лишние ключи создают `shape.unknown-key` violations на пути лишнего ключа.
+
+`shape(...)` по умолчанию создаётся в режиме `'passthrough'`.
+
+```typescript
+const profile = shape({
+  id: isString,
+})
+
+const strictProfile = profile.strict()
+const permissiveProfile = strictProfile.passthrough()
+```
+
+Важно:
+
+- `strict()` и `passthrough()` сохраняют тот же field descriptor;
+- `strict()` и `passthrough()` сохраняют существующие object-level rules;
+- меняется только поведение unknown keys.
+
+## Публичные свойства shape
+
+У экземпляров shape есть:
+
+- `descriptor` — текущий object descriptor;
+- `unknownKeys` — текущий режим unknown keys;
+- стандартное validator-поведение через `check(...)` и `run(...)`.
+
+Это удобно, когда одну и ту же shape нужно валидировать, описывать через `describe(...)` и затем выводить производные схемы без ручной пересборки.
+
+## Производные схемы
+
+Все helpers у shape immutable. Каждый вызов возвращает новую shape.
+
+### `pick(keys)` и `omit(keys)`
+
+Используются, когда нужен поднабор текущей object schema.
+
+```typescript
+const profile = shape({
+  id: isString,
+  nickname: optional(isString),
+  role: exact('admin'),
+})
+
+const publicProfile = profile.pick(['id', 'nickname'])
+const internalProfile = profile.omit(['nickname'])
+```
+
+### `partial()`
+
+`partial()` оборачивает каждое поле в `optional(...)`.
+
+```typescript
+const editableProfile = profile.partial()
+```
+
+Это соответствует текущей модели библиотеки, в которой:
+
+- отсутствующий ключ;
+- и ключ со значением `undefined`;
+
+во время валидации трактуются одинаково.
+
+### `extend(descriptor)`
+
+`extend(...)` добавляет или переопределяет поля через обычный object descriptor.
+
+```typescript
+const account = profile.extend({
+  team: isString,
+})
+```
+
+### `merge(shape)`
+
+`merge(...)` объединяет текущую shape с другой shape.
+
+```typescript
+const account = profile.merge(shape({
+  team: isString,
+  role: exact('editor'),
+}))
+```
+
+Поведение:
+
+- unknown-key mode берётся у receiver shape;
+- пересекающиеся ключи переопределяются правой shape;
+- object-level rules из merge target не пытаются автоматически объединяться в новый общий набор.
+
+## Семантика сохранения rules
+
+Есть намеренное различие между переключением режима и структурным derivation.
+
+`strict()` и `passthrough()` сохраняют object-level rules, потому что структура shape по сути остаётся той же.
+
+`pick()`, `omit()`, `partial()`, `extend()` и `merge()` намеренно сбрасывают object-level rules, потому что generic refinements непрозрачны и могут зависеть от полей, которых больше нет или которые теперь ведут себя иначе.
+
+Так derived schemas остаются предсказуемыми и библиотека не делает сомнительных предположений о валидности старых refinements.
+
+## Правила уровня объекта
+
+Shapes позволяют выражать cross-field invariants без внедрения второй schema language.
+
+### `refine(...)`
+
+`refine(...)` добавляет синхронное object-level rule, которое запускается только после того, как базовая shape уже успешно провалидировалась как объект.
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirmPassword: isString,
+}).refine(value => {
+  return value.password === value.confirmPassword
+    ? []
+    : [{
+      path: ['confirmPassword'],
+      code: 'shape.fields.mismatch',
+      args: [['password', 'confirmPassword']],
+    }]
+})
+```
+
+`refine(...)` специально остаётся тонким:
+
+- он только sync;
+- при успехе возвращает `[]`, `null` или `undefined`;
+- при ошибке возвращает один issue или массив issue;
+- `path` задаётся относительно текущей shape и по умолчанию равен `[]`;
+- `value` необязателен и по умолчанию берётся из значения объекта по этому относительному пути;
+- `code` остаётся machine-readable.
+
+Сгенерированные violations используют:
+
+- `violates.kind === 'validator'`;
+- `violates.name === 'shape'`.
+
+### Descriptor для refine rule
+
+Сами callbacks не сериализуются, но для rule можно добавить компактный machine-readable descriptor:
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirmPassword: isString,
+}).refine(value => {
+  return value.password === value.confirmPassword
+    ? []
+    : [{ path: ['confirmPassword'], code: 'shape.fields.mismatch' }]
+}, {
+  kind: 'passwordConfirmation',
+  metadata: {
+    fields: ['password', 'confirmPassword'],
+  },
+})
+```
+
+Позже это попадает в `describe(...)` в массив `rules`.
+
+### `fieldsMatch(...)`
+
+`fieldsMatch(...)` — небольшой helper для частого случая с полем подтверждения.
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirmPassword: isString,
+}).fieldsMatch(['password', 'confirmPassword'])
+```
+
+Он также поддерживает nested selectors:
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirm: shape({
+    password: isString,
+  }),
+}).fieldsMatch(['password', ['confirm', 'password']])
+```
+
+## Порядок валидации
+
+На верхнем уровне валидация shape устроена так:
+
+1. Вход должен быть plain record-like object.
+2. Каждое объявленное поле валидируется рекурсивно.
+3. В режиме `'strict'` выполняются проверки неизвестных ключей.
+4. Object-level rules запускаются только если structural validation до этого полностью прошла.
+
+Этот порядок важен, потому что object-level rules тогда работают уже с устойчивой провалидированной формой объекта.
+
+## Вложенные shape
+
+Shape можно свободно вкладывать друг в друга, потому что это обычные validators.
+
+```typescript
+const form = shape({
+  profile: shape({
+    email: isString,
+    nickname: optional(isString),
+  }).strict(),
+})
+```
+
+Вложенные ошибки сохраняют точные пути вроде `['profile', 'email']`.
+
+## Интроспекция
+
+Shape участвуют в публичном descriptor tree, который возвращает `describe(...)`.
+
+```typescript
+import { describe } from '@modulify/validator'
+
+const descriptor = describe(shape({
+  email: isString,
+}).strict())
+```
+
+Shape descriptors содержат:
+
+- `unknownKeys`;
+- `fields`;
+- `rules`;
+- опциональную `metadata`.
+
+Это полезно для adapters, tooling и производных export layers, например для JSON Schema.
+
+## Метаданные
+
+`meta(...)` может аннотировать и shape целиком, и отдельные поля, не меняя validation semantics.
+
+```typescript
+import {
+  describe,
+  meta,
+} from '@modulify/validator'
+
+const profile = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    format: 'email',
+  }),
+}).strict(), {
+  title: 'Profile',
+})
+
+const descriptor = describe(profile)
+```
+
+Metadata остаётся полностью явной:
+
+- никакого implicit inheritance по дереву нет;
+- metadata shape и metadata полей появляются ровно там, где был вызван `meta(...)`.
+
+## Практические замечания
+
+- `shape(...)` ориентирован на объекты, а не на schema-first подход;
+- он переиспользует те же constraints, что и остальная библиотека;
+- derived helpers намеренно маленькие и предсказуемые;
+- object-level rules выразительны, но остаются лёгкими;
+- расхождения между runtime semantics и внешними форматами схем лучше отражать явно через adapter layers вроде `describe(...)` или `toJsonSchema(...)`.