@modulify/validator 0.1.0 → 0.2.1

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

@@ -0,0 +1,273 @@
+# Common Recipes
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/06-common-recipes.md)
+
+This guide answers the practical question:
+
+> Which part of `@modulify/validator` should I use for task `X`?
+
+It is intentionally recipe-oriented. Use it when you already understand the project direction and want a fast path to a concrete implementation.
+
+## Pick The Right Layer First
+
+Use this quick rule of thumb:
+
+- use `@modulify/validator/predicates` when you only need runtime checks and type guards;
+- use built-in assertions such as `isString`, `isDefined`, `hasLength(...)`, `oneOf(...)` when you want machine-readable failures;
+- use combinators such as `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)`, `discriminatedUnion(...)` when validation becomes structural;
+- use `meta(...)` and `describe(...)` when another layer needs stable machine-readable descriptors;
+- use `toJsonSchema(...)` only when you need an interoperability/export view, not as the source of runtime truth.
+
+## Validate An API Payload
+
+Use `shape(...)` plus 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)
+```
+
+Practical pattern:
+
+- use `.strict()` for request payloads when unknown keys should be rejected;
+- keep leaf checks small and composable;
+- use the `validated` tuple item inside the success branch;
+- use `violations` as structured data for API responses, logs, or UI mapping.
+
+## Narrow An Existing Variable In Sync Code
+
+Use `matches.sync(...)`.
+
+```typescript
+import {
+  isDefined,
+  isString,
+  matches,
+} from '@modulify/validator'
+
+const value: unknown = source()
+
+if (matches.sync(value, [isDefined, isString])) {
+  value.toUpperCase()
+}
+```
+
+Use this when you want to narrow the original variable itself.
+
+Do not use `validate.sync(...)` for this purpose if your main goal is narrowing the original variable. `validate.sync(...)` narrows the `validated` tuple item, not the original input binding.
+
+## Model Optional, Nullable, And Nullish Fields
+
+Use the wrapper that matches your runtime meaning:
+
+- `optional(x)` means `undefined` is accepted;
+- `nullable(x)` means `null` is accepted;
+- `nullish(x)` means both `null` and `undefined` are accepted.
+
+```typescript
+const profile = shape({
+  nickname: optional(isString),
+  middleName: nullable(isString),
+  bio: nullish(isString),
+})
+```
+
+Practical rule:
+
+- use `optional(...)` for omitted or unset fields;
+- use `nullable(...)` when `null` is a meaningful explicit value;
+- use `nullish(...)` only when both cases are intentionally allowed.
+
+## Reuse One Shape In Multiple Views
+
+Build one base shape, then derive from it.
+
+```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 })
+```
+
+Use this pattern when one domain object appears in:
+
+- API payloads;
+- form state;
+- internal service boundaries;
+- public views with a reduced field set.
+
+Remember that structural derivations such as `pick()`, `omit()`, `partial()`, `extend()`, and `merge()` intentionally drop object-level rules.
+
+## Attach UI Metadata Without Coupling UI To Validation
+
+Use `meta(...)` on any constraint.
+
+```typescript
+import {
+  isString,
+  meta,
+  shape,
+} from '@modulify/validator'
+
+const registration = shape({
+  email: meta(isString, {
+    title: 'Email',
+    description: 'Primary login address',
+  }),
+})
+```
+
+This is useful when a separate layer needs:
+
+- field titles;
+- placeholders or display hints;
+- domain-specific metadata for rendering;
+- descriptor-driven tooling.
+
+Only some metadata keys are later mapped into JSON Schema. Other keys remain library-specific.
+
+## Build Field Error State For Forms
+
+Use `collection(...)` on top of `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'])
+```
+
+This is the recommended shape when you need exact path lookups instead of string parsing.
+
+## Add Cross-Field Rules
+
+Use `fieldsMatch(...)` for common confirmation cases and `refine(...)` for everything else.
+
+```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']],
+    }]
+})
+```
+
+Choose `fieldsMatch(...)` when the rule is exactly equality between two selectors.
+
+Choose `refine(...)` when:
+
+- more than two fields participate;
+- the rule is domain-specific;
+- the output path needs custom control;
+- you want a custom descriptor for introspection.
+
+## Write A Custom Validator That Tooling Can Understand
+
+Use `custom(...)` and provide `describe()` if the validator should participate in public 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,
+    }
+  },
+})
+```
+
+Without `describe()`, the validator remains intentionally opaque to `describe(...)` and `toJsonSchema(...)`.
+
+## Export JSON Schema Safely
+
+Use `toJsonSchema(...)` in two different modes depending on the consumer.
+
+```typescript
+import { toJsonSchema } from '@modulify/validator/json-schema'
+
+const schema = toJsonSchema(profile)
+const strictSchema = toJsonSchema(profile, { mode: 'strict' })
+```
+
+Use best-effort mode when:
+
+- external consumers can tolerate permissive `{}` nodes;
+- a partial export is better than no export;
+- you want the broadest schema view.
+
+Use strict mode when:
+
+- lossy export would be misleading;
+- JSON Schema is part of a contract;
+- unsupported runtime semantics must fail loudly.
+
+## Recommended Reading Order
+
+If you are new to the library, the shortest useful reading path is:
+
+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` when you want the compact contract summary

package/docs/en/07-ai-reference.md

@@ -0,0 +1,215 @@
+# AI Reference
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/07-ai-reference.md)
+
+This page is a compact contract summary for AI agents, code generators, IDE tools, and human readers who want the shortest possible set of stable rules.
+
+Treat it as the "canonical quick reference" layer above the longer guides.
+
+## Core Model
+
+`@modulify/validator` is organized into three runtime layers:
+
+- predicates: runtime checks and type guards;
+- assertions: machine-readable leaf failures;
+- combinators: structural composition over assertions and validators.
+
+The library does not center itself around built-in human-readable messages.
+
+Violations are structured data first.
+
+## Canonical Entry Points
+
+Use the root package for:
+
+- `validate`
+- `validate.sync`
+- `matches.sync`
+- `meta`
+- `describe`
+- `custom`
+- `collection`
+- built-in assertions
+- combinators
+
+Use `@modulify/validator/predicates` for standalone guard-style runtime checks.
+
+Use `@modulify/validator/json-schema` for:
+
+- `toJsonSchema(...)`
+- `JsonSchemaExportError`
+
+## Validation Result Contract
+
+```typescript
+type ValidationTuple<T> =
+  | [ok: true, validated: T, violations: []]
+  | [ok: false, validated: unknown, violations: Violation[]]
+```
+
+Important consequences:
+
+- `validate(...)` narrows the `validated` tuple item in the success branch;
+- `validate(...)` does not narrow the original input variable;
+- `matches.sync(...)` is the API that narrows the original variable;
+- `violations` is always empty on success.
+
+## Wrapper Semantics
+
+- `optional(x)` accepts `undefined`
+- `nullable(x)` accepts `null`
+- `nullish(x)` accepts `null | undefined`
+
+These wrappers model runtime acceptance, not UI wording.
+
+## Shape Semantics
+
+`shape(...)` validates plain record-like objects.
+
+Defaults:
+
+- unknown keys are allowed;
+- unknown-key mode is `'passthrough'`;
+- object-level rules are empty.
+
+Mode switches:
+
+- `.strict()` keeps the same fields and rules, but rejects unknown keys;
+- `.passthrough()` keeps the same fields and rules, but allows unknown keys.
+
+Structural derivations:
+
+- `.pick(...)`
+- `.omit(...)`
+- `.partial(...)`
+- `.extend(...)`
+- `.merge(...)`
+
+Important rule:
+
+- structural derivations intentionally drop object-level rules;
+- mode switches intentionally keep object-level rules.
+
+## Violations Contract
+
+Violations are machine-readable objects with:
+
+- failed value;
+- path;
+- semantic subject in `violates`.
+
+Do not depend on text parsing for downstream processing.
+
+Prefer:
+
+- `violations`
+- `collection(...)`
+- path-based lookups
+
+Over:
+
+- string matching;
+- ad-hoc message parsing;
+- field-name extraction from text.
+
+## Metadata Contract
+
+`meta(...)` attaches opaque machine-readable metadata to any constraint.
+
+`describe(...)` returns a stable recursive descriptor tree.
+
+Custom validators may participate in this contract by exposing `describe()`.
+
+Without `describe()`, a custom validator remains opaque and usually appears as:
+
+```typescript
+{ kind: 'validator' }
+```
+
+## JSON Schema Contract
+
+`toJsonSchema(...)` is a derived interoperability layer.
+
+It is not the source of runtime truth.
+
+Best-effort mode:
+
+- default mode;
+- unsupported nodes become permissive `{}` schemas;
+- unsupported shape rules may be dropped with `$comment`.
+
+Strict mode:
+
+- throws `JsonSchemaExportError`;
+- exposes `descriptor`, `reason`, and `path`.
+
+Important mismatch:
+
+- JSON Schema `required` is only an approximation of runtime `undefined` semantics;
+- do not assume perfect semantic parity between runtime validation and exported JSON Schema.
+
+## Canonical Patterns
+
+Use this when you want to validate a payload:
+
+```typescript
+const [ok, validated, violations] = validate.sync(input, schema)
+```
+
+Use this when you want to narrow the original variable:
+
+```typescript
+if (matches.sync(value, schema)) {
+  // value is narrowed here
+}
+```
+
+Use this when you want reusable object schemas:
+
+```typescript
+const schema = shape({...}).strict()
+const partial = schema.partial()
+const subset = schema.pick([...])
+```
+
+Use this when another layer needs machine-readable introspection:
+
+```typescript
+const descriptor = describe(schema)
+```
+
+Use this when another system needs an export view:
+
+```typescript
+const jsonSchema = toJsonSchema(schema)
+```
+
+## Do / Do Not
+
+Do:
+
+- keep leaf constraints small and composable;
+- treat `violations` as data, not messages;
+- use `shape(...)` for reusable object contracts;
+- add `describe()` to custom validators that should participate in tooling;
+- use strict JSON Schema export only when lossy export is unacceptable.
+
+Do not:
+
+- expect `validate(...)` to narrow the original input binding;
+- assume `toJsonSchema(...)` is a full mirror of runtime semantics;
+- assume structural shape derivations keep object-level rules;
+- rely on undocumented private internals instead of `describe(...)`;
+- build downstream logic around human-readable strings.
+
+## Best Sources Of Truth
+
+For implementation details and edge cases, prefer this order:
+
+1. `README.md`
+2. `docs/en/*.md`
+3. `tests/*.test.ts`
+4. `tests/*.test-d.ts`
+
+Tests are the most precise source for behavior that is easy to misunderstand from prose alone.