@modulify/validator 0.1.0 → 0.2.1

package/docs/en/03-violations.md

@@ -0,0 +1,267 @@
+# Violations
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/03-violations.md)
+
+`@modulify/validator` returns structured violations instead of built-in human-readable error messages.
+
+This part of the API has two layers:
+
+- raw `Violation[]` results returned by `validate(...)` and `validate.sync(...)`;
+- `ViolationCollection`, a thin utility wrapper built by `collection(...)`.
+
+## Quick Start
+
+```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'])
+```
+
+## Why Violations Are Structured
+
+The library intentionally returns data, not presentation.
+
+That keeps message rendering outside the validation layer and makes the same result reusable for:
+
+- localized UI messages;
+- form error state;
+- API payloads;
+- analytics and diagnostics;
+- custom adapters and tooling.
+
+## The `Violation` Shape
+
+A violation contains:
+
+- `value` - the value that failed validation;
+- `path` - where the failure happened inside a nested object or array;
+- `violates` - a machine-readable description of what failed.
+
+Example:
+
+```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`
+
+The `violates` field contains structured failure metadata.
+
+Important parts:
+
+- `kind` - which layer produced the failure;
+- `name` - which assertion or validator produced it;
+- `code` - a semantic failure code;
+- `args` - structured payload for the failure.
+
+This allows consumers to decide how to render or transform failures later.
+
+## `violates.kind`
+
+`violates.kind` tells you which layer produced the failure:
+
+- `'assertion'`
+- `'validator'`
+- `'runtime'`
+
+Examples:
+
+- `isString` failures are assertion-level;
+- `shape.unknown-key` is validator-level;
+- rejected async validations can surface as runtime-level failures.
+
+## Nested Paths
+
+`path` is a regular `PropertyKey[]`.
+
+That means:
+
+- object properties stay as property keys;
+- array positions stay as numeric indexes;
+- nested failures keep their full absolute path from the root input.
+
+Example:
+
+- `['profile', 'email']`
+- `['items', 0, 'title']`
+
+This is one of the reasons the library can stay adapter-friendly without stringifying field paths.
+
+## Validation Results
+
+`validate(...)` and `validate.sync(...)` return:
+
+```typescript
+type ValidationTuple<T> =
+  | [ok: true, validated: T, violations: []]
+  | [ok: false, validated: unknown, violations: Violation[]]
+```
+
+That means:
+
+- success returns an empty violation list;
+- failure returns the original input plus collected structured violations.
+
+## `ViolationCollection`
+
+`ViolationCollection` is a thin convenience wrapper around `Violation[]`.
+
+It keeps the raw list model, but adds a few operations for post-processing:
+
+- `size`
+- iteration with `for...of`
+- `.forEach(...)`
+- `.map(...)`
+- `.at(path)`
+- `.tree()`
+
+The goal is convenience, not a second error model.
+
+## `collection(...)`
+
+Use `collection(...)` to wrap a raw `Violation[]` result:
+
+```typescript
+const errors = collection(violations)
+```
+
+This is especially useful once validation has already happened and you want to:
+
+- inspect one field;
+- build a nested UI tree;
+- group or map failure codes;
+- reuse helper methods without changing the underlying data format.
+
+## Exact Path Lookup With `.at(path)`
+
+`.at(path)` performs exact path matching.
+
+```typescript
+const rootErrors = errors.at([])
+const emailErrors = errors.at(['profile', 'email'])
+```
+
+Important semantics:
+
+- `at([])` means root-level violations;
+- violations without a path are treated as root-level by the collection utilities;
+- `at(['profile'])` does not include `['profile', 'email']`;
+- the result is another `ViolationCollection`.
+
+This makes path lookups predictable and easy to reason about.
+
+## Tree View With `.tree()`
+
+`.tree()` builds a nested machine-readable tree from the current collection.
+
+```typescript
+const tree = errors.tree()
+```
+
+This is useful when a consumer wants:
+
+- hierarchical traversal;
+- nested error rendering;
+- path-aware UI state;
+- a structured debugging view.
+
+Tree nodes expose:
+
+- `path`
+- `self`
+- `subtree`
+- `children`
+- `.at(path)`
+
+## `ViolationTreeNode`
+
+The tree view is shaped like this:
+
+```typescript
+type ViolationTreeNode = {
+  path: readonly PropertyKey[]
+  self: ViolationCollection
+  subtree: ViolationCollection
+  children: ReadonlyMap<PropertyKey, ViolationTreeNode>
+  at(path: readonly PropertyKey[]): ViolationTreeNode | undefined
+}
+```
+
+Important differences:
+
+- `self` contains only violations exactly on the current path;
+- `subtree` contains current-path violations plus all descendant violations.
+
+## Tree Path Semantics
+
+Tree nodes keep absolute paths.
+
+Also:
+
+- intermediate nodes may exist even when they have no own violations;
+- they can still be useful because descendants may have failures;
+- the tree is built from path arrays, not from dot-separated strings.
+
+This keeps the structure aligned with the raw violation format.
+
+## Practical Example
+
+```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()
+```
+
+From one raw violation list you can derive:
+
+- exact-path collections;
+- mapped codes;
+- a nested traversal tree.
+
+## Practical Notes
+
+- keep `Violation[]` as the canonical transport format;
+- use `collection(...)` only when the helper API improves ergonomics;
+- treat `code` and `args` as your main integration points;
+- keep message rendering outside the validation layer;
+- prefer path-array handling over string path serialization.

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

@@ -0,0 +1,264 @@
+# JSON Schema Export
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/04-json-schema-export.md)
+
+`@modulify/validator/json-schema` provides a thin JSON Schema export layer on top of the public descriptor contract.
+
+It is intentionally a derivation layer, not a second schema model. The exporter reads public descriptors and builds a JSON Schema view from them.
+
+## Quick Start
+
+```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)
+```
+
+## Mental Model
+
+The export flow is intentionally small:
+
+1. validators expose public descriptors through `describe(...)`;
+2. `toJsonSchema(...)` derives a JSON Schema document from those descriptors;
+3. unsupported or opaque nodes are either dropped in best-effort mode or rejected in strict mode.
+
+This separation matters because:
+
+- runtime validation stays runtime-first;
+- exporter behavior stays explicit;
+- custom tooling can depend on one public introspection contract.
+
+## Entry Point
+
+Import JSON Schema export from the dedicated subpath:
+
+```typescript
+import {
+  JsonSchemaExportError,
+  toJsonSchema,
+} from '@modulify/validator/json-schema'
+```
+
+The root package intentionally does not re-export this API.
+
+## Supported Built-In Mappings
+
+The exporter covers the built-in descriptor set that already participates in public introspection.
+
+### Leaf assertions
+
+Supported practical mappings include:
+
+- `isString` -> `type: 'string'`
+- `isNumber` -> `type: 'number'`
+- `isBoolean` -> `type: 'boolean'`
+- `isNull` -> `type: 'null'`
+- `isEmail` -> `type: 'string'` plus `format: 'email'`
+- `exact(...)` -> `const`
+- `oneOf(...)` -> `enum`
+- `hasLength(...)` -> string/array length constraints
+
+### Wrappers
+
+Supported wrappers:
+
+- `optional(...)`
+- `nullable(...)`
+- `nullish(...)`
+
+`optional(...)` affects object `required` calculation. `nullable(...)` and `nullish(...)` are exported as unions with `null`.
+
+### Structural combinators
+
+Supported structural mappings:
+
+- `shape(...)`
+- `each(...)`
+- `tuple(...)`
+- `record(...)`
+
+### Branching combinators
+
+Supported branching mappings:
+
+- `union(...)`
+- `discriminatedUnion(...)`
+
+### Sequential slots
+
+Array slots with multiple constraints are exported as JSON Schema `allOf`.
+
+## Object Schema Mapping
+
+`shape(...)` is exported as a JSON Schema object with:
+
+- `type: 'object'`
+- `properties`
+- `required`
+- `additionalProperties`
+
+Unknown-key handling maps like this:
+
+- `.strict()` -> `additionalProperties: false`
+- default or `.passthrough()` -> `additionalProperties: true`
+
+## `required` And `undefined`
+
+One important boundary is object field presence.
+
+The runtime layer treats:
+
+- a missing key;
+- and a key whose value is `undefined`;
+
+as the same case in several practical scenarios, especially around `optional(...)` and derived helpers such as `partial()`.
+
+JSON Schema does not model that behavior the same way. Because of that, the exporter approximates field presence through JSON Schema `required` rather than claiming exact semantic parity.
+
+That approximation is intentional and should be treated as an interoperability layer, not as a promise that runtime and JSON Schema semantics are identical.
+
+## Metadata Mapping
+
+The exporter does not blindly copy all metadata into JSON Schema.
+
+Instead, it maps a small explicit whitelist:
+
+- `title`
+- `description`
+- `format`
+- `default`
+- `examples`
+- `deprecated`
+- `readOnly`
+- `writeOnly`
+
+Other metadata stays library-specific and is left out of the exported schema automatically.
+
+This keeps the metadata layer explicit and avoids turning it into implicit export magic.
+
+## Best-Effort Mode
+
+Best-effort mode is the default:
+
+```typescript
+const schema = toJsonSchema(profile)
+```
+
+In this mode:
+
+- unsupported or opaque nodes become permissive `{}` schema nodes;
+- unsupported object-level shape rules are dropped;
+- dropped shape rules are marked with a `$comment` when practical.
+
+This mode is useful when you want the broadest possible external schema even if some runtime semantics cannot be expressed faithfully.
+
+## Strict Mode
+
+Strict mode rejects unsupported nodes:
+
+```typescript
+const schema = toJsonSchema(profile, { mode: 'strict' })
+```
+
+When export cannot be represented faithfully, the exporter throws `JsonSchemaExportError`.
+
+That error exposes:
+
+- the descriptor that failed;
+- the machine-readable reason;
+- the descriptor path where the failure happened.
+
+Strict mode is useful when silent fallback would be misleading.
+
+## Unsupported And Opaque Cases
+
+Some runtime behavior does not have a faithful JSON Schema representation.
+
+Important examples:
+
+- custom validators without a supported public descriptor;
+- unknown custom descriptor kinds;
+- object-level `refine(...)` rules;
+- descriptor nodes whose semantics depend on runtime-only behavior;
+- values that are not representable as practical JSON Schema constants or enums.
+
+The exporter keeps these boundaries explicit instead of guessing.
+
+## Relationship To `describe(...)`
+
+`toJsonSchema(...)` is downstream from `describe(...)`.
+
+That means:
+
+- JSON Schema export should rely on public descriptors;
+- exporter logic should not depend on private runtime shape internals;
+- custom validators participate by exposing a public descriptor contract first.
+
+This keeps the architecture thin and stable for external tooling.
+
+## Example: Metadata-Aware Shape Export
+
+```typescript
+const profile = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    format: 'email',
+  }),
+  age: optional(isNumber),
+}).strict(), {
+  title: 'Profile',
+})
+
+const schema = toJsonSchema(profile)
+```
+
+Practical result:
+
+- shape metadata can become schema metadata;
+- field metadata can become property metadata;
+- strict object behavior becomes `additionalProperties: false`.
+
+## Example: Strict Failure
+
+```typescript
+const schema = shape({
+  publishedAt: custom({
+    check(value: unknown): value is string {
+      return typeof value === 'string'
+    },
+    run() {
+      return []
+    },
+  }),
+})
+
+toJsonSchema(schema, { mode: 'strict' })
+```
+
+This throws because the custom validator stays opaque to the exporter.
+
+## Practical Notes
+
+- treat JSON Schema export as an interoperability layer;
+- use best-effort mode when partial export is acceptable;
+- use strict mode when unsupported semantics must fail loudly;
+- keep custom descriptors compact and public if they are meant to participate in export;
+- do not assume JSON Schema export replaces runtime validation semantics.

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

@@ -0,0 +1,123 @@
+# Public API
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/05-public-api.md)
+
+This guide summarizes the package surface of `@modulify/validator` and its supported subpath exports.
+
+It is meant as a navigation document:
+
+- where each public entrypoint lives;
+- which groups of functions are exported together;
+- what the validation result looks like;
+- which APIs belong to dedicated subpaths such as predicates and JSON Schema export.
+
+## Root Package
+
+The root package exports:
+
+- `validate`
+- `validate.sync`
+- `matches.sync`
+- `meta`
+- `describe`
+- `custom`
+- `collection`
+- `ViolationCollection`
+- all exports from `./assertions`
+- all exports from `./combinators`
+
+Use the root package when you need the main validation API, composed validators, metadata/introspection, and violation utilities.
+
+## Assertions And Combinators
+
+The root package includes:
+
+- low-level assertion construction through `assert(...)`
+- built-in assertions such as `isString`, `isNumber`, `isBoolean`, `isNull`, `isEmail`, `hasLength(...)`, `oneOf(...)`
+- structural combinators such as `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`
+- wrapper combinators such as `optional(...)`, `nullable(...)`, `nullish(...)`
+- branching combinators such as `union(...)` and `discriminatedUnion(...)`
+- exact-value matching through `exact(...)`
+
+This is the main runtime-facing API surface of the library.
+
+## Metadata And Introspection
+
+The same root package also includes:
+
+- `meta(...)`
+- `describe(...)`
+- `custom(...)`
+
+Together these provide the public machine-readable descriptor contract and the metadata layer built on top of it.
+
+## Violation Utilities
+
+The root package also includes:
+
+- raw violation results returned by `validate(...)`
+- `collection(...)`
+- `ViolationCollection`
+
+These are the main utilities for post-processing machine-readable validation failures.
+
+## Validation Result
+
+`validate(...)` and `validate.sync(...)` return:
+
+```typescript
+type ValidationTuple<T> =
+  | [ok: true, validated: T, violations: []]
+  | [ok: false, validated: unknown, violations: Violation[]]
+```
+
+Practical meaning:
+
+- `ok` tells whether validation succeeded;
+- `validated` becomes strongly typed only in the success branch;
+- `violations` is empty on success and contains structured failures on error.
+
+## Predicates Subpath
+
+Predicates are available from:
+
+```typescript
+@modulify/validator/predicates
+```
+
+This subpath contains reusable runtime/type-guard helpers and predicate combinators such as:
+
+- `isString`
+- `isNumber`
+- `isRecord`
+- `isArray`
+- `isShape`
+- `And`, `Or`, `Not`
+
+Use this subpath when you want guard-style runtime checks without pulling in the higher-level validation layer.
+
+## JSON Schema Export Subpath
+
+JSON Schema export is available from:
+
+```typescript
+@modulify/validator/json-schema
+```
+
+This subpath contains:
+
+- `toJsonSchema(...)`
+- `JsonSchemaExportError`
+
+It is intentionally kept separate from the root package so that export-specific concerns stay isolated from the main validation entrypoint.
+
+## How To Read The Package Surface
+
+At a high level:
+
+- root package = validation, combinators, metadata, violations;
+- `./predicates` = standalone runtime/type-guard helpers;
+- `./json-schema` = derived JSON Schema export layer.
+
+This split keeps the main API discoverable while still allowing specialized subpaths where needed.