@modulify/validator 0.1.0 → 0.2.0

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

@@ -0,0 +1,348 @@
+# Shape API
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/01-shape-api.md)
+
+`shape(...)` is the reusable object-shape API in `@modulify/validator`.
+
+It keeps the same runtime validation kernel as the rest of the library, but adds a small immutable object-oriented layer for:
+
+- nested object validation;
+- reusable object schemas;
+- derived shapes such as `pick(...)`, `omit(...)`, and `partial(...)`;
+- object-level rules such as `refine(...)` and `fieldsMatch(...)`;
+- descriptor-based introspection through `describe(...)`.
+
+## Quick Start
+
+```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(...)` returns a validator, so it can be used anywhere a regular constraint is accepted.
+
+## Mental Model
+
+A shape is still a validator. The extra API is a thin wrapper around an object descriptor and a small set of immutable derivation helpers.
+
+Each field in the descriptor may contain:
+
+- a single constraint;
+- an array of constraints that run sequentially;
+- another structural validator such as `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)`, or `discriminatedUnion(...)`.
+
+That means object validation stays aligned with the rest of the library:
+
+- field-level checks reuse the same assertions and combinators;
+- violations keep regular nested `path` values;
+- introspection goes through the same `describe(...)` contract;
+- metadata stays opt-in through `meta(...)`.
+
+## Basic Shape Construction
+
+```typescript
+import {
+  hasLength,
+  isDefined,
+  isString,
+  shape,
+} from '@modulify/validator'
+
+const registration = shape({
+  email: [isDefined, isString],
+  password: [isString, hasLength({ min: 8 })],
+})
+```
+
+Runtime behavior:
+
+- the input must be a plain record-like object;
+- every declared field is validated against its own slot;
+- nested violations are reported on the field path;
+- unknown keys are allowed by default.
+
+## Unknown Keys
+
+Shapes have two unknown-key modes:
+
+- `'passthrough'` - extra keys are allowed;
+- `'strict'` - extra keys produce `shape.unknown-key` violations on the extra key path.
+
+`shape(...)` starts in `'passthrough'` mode.
+
+```typescript
+const profile = shape({
+  id: isString,
+})
+
+const strictProfile = profile.strict()
+const permissiveProfile = strictProfile.passthrough()
+```
+
+Important behavior:
+
+- `strict()` and `passthrough()` keep the same field descriptor;
+- `strict()` and `passthrough()` keep existing object-level rules;
+- only the unknown-key handling changes.
+
+## Exposed Shape Properties
+
+Shape instances expose:
+
+- `descriptor` - the current object descriptor;
+- `unknownKeys` - the current unknown-key mode;
+- all standard validator behavior through `check(...)` and `run(...)`.
+
+This is useful when a shape needs to be validated, described, and then derived further without rebuilding it from scratch.
+
+## Derived Shapes
+
+All shape helpers are immutable. Each call returns a new shape.
+
+### `pick(keys)` and `omit(keys)`
+
+Use these when you need a subset of the current 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()` wraps every field in `optional(...)`.
+
+```typescript
+const editableProfile = profile.partial()
+```
+
+This follows the current library model where:
+
+- an omitted key;
+- and a key with value `undefined`;
+
+are treated the same during validation.
+
+### `extend(descriptor)`
+
+`extend(...)` adds or overrides fields using a plain object descriptor.
+
+```typescript
+const account = profile.extend({
+  team: isString,
+})
+```
+
+### `merge(shape)`
+
+`merge(...)` merges another shape into the current one.
+
+```typescript
+const account = profile.merge(shape({
+  team: isString,
+  role: exact('editor'),
+}))
+```
+
+Behavior notes:
+
+- the receiver keeps its own unknown-key mode;
+- overlapping keys are overridden by the right-hand shape;
+- object-level rules from the merged shape are not combined into a new shared rule set.
+
+## Rule Retention Semantics
+
+There is an intentional distinction between mode switches and structural derivations.
+
+`strict()` and `passthrough()` keep object-level rules because the same shape structure is still present.
+
+`pick()`, `omit()`, `partial()`, `extend()`, and `merge()` drop object-level rules intentionally, because generic refinements are opaque and may depend on fields that are no longer present or now behave differently.
+
+This keeps derived schemas predictable instead of guessing whether an old refinement is still valid.
+
+## Object-Level Rules
+
+Shapes can express cross-field invariants without introducing a second schema language.
+
+### `refine(...)`
+
+`refine(...)` adds a synchronous object-level rule that runs only after the base shape has already validated successfully as an object.
+
+```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(...)` is intentionally thin:
+
+- it is sync-only;
+- it returns `[]`, `null`, or `undefined` when the rule passes;
+- it returns one issue or an array of issues when it fails;
+- `path` is relative to the current shape and defaults to `[]`;
+- `value` is optional and defaults to the object value at that relative path;
+- `code` stays machine-readable.
+
+Produced violations use:
+
+- `violates.kind === 'validator'`;
+- `violates.name === 'shape'`.
+
+### Describing a refine rule
+
+Callbacks themselves are not serialized, but you can attach a compact machine-readable descriptor to the rule:
+
+```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'],
+  },
+})
+```
+
+This shows up later in `describe(...)` under the shape `rules` array.
+
+### `fieldsMatch(...)`
+
+`fieldsMatch(...)` is a small helper for the common confirmation-field case.
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirmPassword: isString,
+}).fieldsMatch(['password', 'confirmPassword'])
+```
+
+It also supports nested selectors:
+
+```typescript
+const registration = shape({
+  password: isString,
+  confirm: shape({
+    password: isString,
+  }),
+}).fieldsMatch(['password', ['confirm', 'password']])
+```
+
+## Validation Order
+
+At a high level, shape validation works like this:
+
+1. The input must be a plain record-like object.
+2. Every declared field is validated recursively.
+3. Strict unknown-key checks run if the shape is in `'strict'` mode.
+4. Object-level rules run only if structural validation succeeded first.
+
+That ordering matters because object-level rules can then assume a stable validated object shape.
+
+## Nested Shapes
+
+Shapes can be nested freely because they are regular validators.
+
+```typescript
+const form = shape({
+  profile: shape({
+    email: isString,
+    nickname: optional(isString),
+  }).strict(),
+})
+```
+
+Nested failures keep precise paths such as `['profile', 'email']`.
+
+## Introspection
+
+Shapes participate in the public descriptor tree returned by `describe(...)`.
+
+```typescript
+import { describe } from '@modulify/validator'
+
+const descriptor = describe(shape({
+  email: isString,
+}).strict())
+```
+
+Shape descriptors expose:
+
+- `unknownKeys`;
+- `fields`;
+- `rules`;
+- optional `metadata`.
+
+This is useful for adapters, tooling, and derived exports such as JSON Schema.
+
+## Metadata
+
+`meta(...)` can annotate shapes and their fields without changing 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 stays explicit:
+
+- there is no implicit inheritance across the tree;
+- shape metadata and field metadata are attached exactly where `meta(...)` was applied.
+
+## Practical Notes
+
+- `shape(...)` is object-focused, not schema-first;
+- it reuses the same constraints you already use elsewhere in the library;
+- derived helpers are intentionally small and predictable;
+- object-level rules are expressive, but intentionally lightweight;
+- mismatch between runtime semantics and external schema formats should be handled explicitly through adapter layers such as `describe(...)` or `toJsonSchema(...)`.

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

@@ -0,0 +1,276 @@
+# Metadata And Introspection
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/02-metadata-and-introspection.md)
+
+`@modulify/validator` exposes a public introspection layer built around two small entrypoints:
+
+- `meta(...)` for attaching machine-readable metadata to any constraint;
+- `describe(...)` for reading a stable recursive descriptor tree from built-in constraints and compatible custom validators.
+
+This layer is intentionally adapter-oriented. It exists so application code and tooling can inspect validation structures without depending on private runtime internals.
+
+## Quick Start
+
+```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)
+```
+
+## What `meta(...)` Does
+
+`meta(...)` attaches read-only machine-readable metadata to a constraint without changing validation semantics.
+
+That means:
+
+- the original constraint is not mutated;
+- validation success and failure behavior stays the same;
+- the metadata becomes visible through `describe(...)`;
+- nested metadata remains attached exactly where it was applied.
+
+Example:
+
+```typescript
+const email = meta(isString, {
+  title: 'Email',
+  widget: 'email',
+})
+```
+
+The same mechanism works for:
+
+- assertions;
+- wrappers such as `optional(...)`;
+- object shapes;
+- structural validators such as `each(...)` or `tuple(...)`;
+- custom validators.
+
+## Metadata Is Explicit, Not Inherited
+
+Metadata does not automatically flow through the descriptor tree.
+
+If metadata is attached to a parent shape, it stays on that shape node. If metadata is attached to a child field, it stays on that child field node.
+
+```typescript
+const profile = meta(shape({
+  email: meta(isString, { title: 'Email' }),
+  name: isString,
+}), {
+  title: 'Profile',
+})
+```
+
+In this example:
+
+- the shape node gets `title: 'Profile'`;
+- the `email` field gets `title: 'Email'`;
+- the `name` field gets no metadata unless you annotate it explicitly.
+
+This keeps metadata predictable and avoids hidden tree-wide behavior.
+
+## Metadata Merging
+
+If `meta(...)` is applied multiple times to the same constraint, metadata objects are merged from left to right.
+
+```typescript
+const annotated = meta(
+  meta(isString, { title: 'Email' }),
+  { placeholder: 'name@example.com' }
+)
+```
+
+This produces one descriptor node whose `metadata` contains both keys.
+
+## What `describe(...)` Returns
+
+`describe(...)` returns a stable recursive descriptor tree.
+
+The descriptor is intentionally machine-readable rather than presentation-oriented. It is designed for adapters and tooling, not for rendering built-in human-readable messages.
+
+Examples of built-in `kind` values:
+
+- `'assertion'`;
+- `'allOf'`;
+- `'optional'`, `'nullable'`, `'nullish'`;
+- `'shape'`, `'each'`, `'tuple'`, `'record'`;
+- `'union'`, `'discriminatedUnion'`;
+- `'validator'` as a generic fallback for custom validators without a public structural descriptor.
+
+## Assertion Descriptors
+
+Leaf assertions produce descriptors with:
+
+- `kind: 'assertion'`;
+- `name`;
+- `bail`;
+- primary `code` and `args`;
+- `constraints` for extra checker pipeline entries;
+- optional `metadata`.
+
+Example:
+
+```typescript
+const descriptor = describe(meta(isString, { title: 'Display name' }))
+```
+
+This makes assertion metadata visible without changing the assertion runtime itself.
+
+## Wrapper And Structural Descriptors
+
+Composed validators describe themselves recursively.
+
+Examples:
+
+- `optional(...)` exposes `child`;
+- `each(...)` exposes `item`;
+- `tuple(...)` exposes `items`;
+- `union(...)` exposes `branches`;
+- `record(...)` exposes `values`.
+
+This recursive structure is what makes adapter layers possible without touching runtime validator internals.
+
+## Shape Descriptors
+
+Shapes provide one of the richest built-in descriptor nodes.
+
+Shape descriptors include:
+
+- `metadata`;
+- `unknownKeys` with `'passthrough'` or `'strict'`;
+- `fields` with one descriptor per object field;
+- `rules` with compact summaries of object-level rules such as `refine(...)` and `fieldsMatch(...)`.
+
+Example:
+
+```typescript
+const descriptor = describe(shape({
+  email: meta(isString, { format: 'email' }),
+  password: isString,
+}).strict())
+```
+
+This is especially useful for:
+
+- form adapters;
+- contract adapters;
+- custom documentation generators;
+- JSON Schema export through a separate derivation layer.
+
+## Object-Level Rules In Introspection
+
+`refine(...)` callbacks themselves are not serialized.
+
+Instead, shapes keep lightweight rule descriptors in `rules`.
+
+Built-in examples:
+
+- `fieldsMatch(...)` produces a compact `fieldsMatch` rule descriptor;
+- `refine(...)` can accept a custom compact rule descriptor object.
+
+This keeps the public descriptor tree stable and serializable enough for tooling, while avoiding the impossible task of serializing arbitrary callbacks.
+
+## Custom Validators
+
+Custom validators can participate in the same introspection layer through `custom(...)` plus a public `describe()` method.
+
+```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
+  },
+})
+```
+
+Then:
+
+- `describe(isoDate)` returns that public descriptor;
+- `meta(...)` can still annotate the custom validator above it.
+
+If a custom validator does not expose `describe()`, `describe(...)` falls back to:
+
+```typescript
+{ kind: 'validator' }
+```
+
+That fallback is intentionally minimal.
+
+## Adapter Example
+
+A small adapter can walk a shape descriptor and collect 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'])
+  )
+}
+```
+
+This is the main purpose of the introspection layer: external code can derive its own view without knowing how runtime validation is implemented internally.
+
+## Relationship To JSON Schema Export
+
+`toJsonSchema(...)` is a separate layer derived from the public descriptor contract.
+
+That means:
+
+- `describe(...)` is the public introspection source of truth;
+- JSON Schema export builds on top of that public shape;
+- the library does not maintain a second hidden schema model for exporters.
+
+This separation is intentional:
+
+- runtime validation stays runtime-first;
+- metadata stays explicit;
+- export behavior can evolve as a thin adapter layer.
+
+## Practical Boundaries
+
+Current boundaries of the metadata and introspection layer:
+
+- no built-in message rendering or i18n;
+- no metadata inheritance across the tree;
+- no separate schema DSL alongside runtime constraints;
+- no serialization of runtime callbacks from `refine(...)`;
+- custom validators without public descriptors intentionally remain opaque.
+
+## Practical Notes
+
+- use `meta(...)` when you need machine-readable annotations, not hidden behavior;
+- use `describe(...)` when you need a stable structural view of a constraint tree;
+- keep custom descriptors compact and ecosystem-facing;
+- prefer deriving external formats from descriptors instead of re-reading private validator internals.