@modulify/validator 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.2.1](https://github.com/modulify/validator/compare/v0.2.0...v0.2.1) (2026-03-09)
+
+## [0.2.0](https://github.com/modulify/validator/compare/v0.1.0...v0.2.0) (2026-03-09)
+
+
+### ⚠ BREAKING CHANGES
+
+* Validation API was redesigned around typed tuples
+* legacy assertion entrypoints were removed, assertion exports now use camelCase names, and violations now expose structured metadata via violates.{predicate,rule,args}.
+* isObject now returns false on null values, added isShape predicate constructor for checking objects structures
+* Injecting check utility into Assertion
+
+### Features
+
+* Added JSON Schema export entrypoint ([0b3ec5b](https://github.com/modulify/validator/commit/0b3ec5b008418d7e7ceaa4a603341f24dc454b48))
+* Added metadata and introspection API ([16ea412](https://github.com/modulify/validator/commit/16ea41268424dc878271227ad4e58cd2cd089c2d))
+* Added simple runtime predicates for built-in values ([11c9f19](https://github.com/modulify/validator/commit/11c9f1996988e7c3ac45c8632caa1c7198ab2792))
+* Added violation collection utilities ([64e9e36](https://github.com/modulify/validator/commit/64e9e36da63a672263f5ac48ef7b22e992dc6148))
+* **assertions:** Added reusable assertion mixins for strings and numbers ([658dc9f](https://github.com/modulify/validator/commit/658dc9f32d1936fcd080969d55415aa5b450ec05))
+* **combinators:** Added object-level shape refinement runtime ([2e2607f](https://github.com/modulify/validator/commit/2e2607f29211db48e5d46652ccef6b4cc185647d))
+* **combinators:** Added tuple and record validators ([71742f9](https://github.com/modulify/validator/commit/71742f9216c7e20d6c3535af965dc2c134c5b4e8))
+* **combinators:** Added union variant validators ([8b9e131](https://github.com/modulify/validator/commit/8b9e131a06a87e9bf462c492cbf8a6facacb7230))
+* **combinators:** Extended fieldsMatch with nested selectors ([af5801e](https://github.com/modulify/validator/commit/af5801ed21dfa62e3f2ae88ad9e6db130ecbe293))
+* Expanded metadata introspection contracts ([a188152](https://github.com/modulify/validator/commit/a1881526b2bd25d18584b478a1650a23d2a28f16))
+* Injecting check utility into Assertion ([be8b22e](https://github.com/modulify/validator/commit/be8b22e23e968d39ade0198f85944b8f82e3183b))
+* isObject now returns false on null values, added isShape predicate constructor for checking objects structures ([ee70741](https://github.com/modulify/validator/commit/ee70741e6f8ad4f2da0913187b1663b2dc1da6ed))
+* redesign assertion API around structured violations ([acf16f3](https://github.com/modulify/validator/commit/acf16f39e26a38da944805dff8eb20ca416ad174))
+* Shape object API was unified ([c43f6b6](https://github.com/modulify/validator/commit/c43f6b61b3cacf33fca224c9f4ef93c794145028))
+* **types:** Added code-aware violation inference ([f9851db](https://github.com/modulify/validator/commit/f9851db28ac663a59a07fb6ca8396910a20929eb))
+* Validation API was redesigned around typed tuples ([d645441](https://github.com/modulify/validator/commit/d6454412b6ac514ff3c31cce6641fabe11c844c3))
+
 ## [0.1.0](https://github.com/modulify/validator/compare/v0.0.2...v0.1.0) (2024-12-22)
 
 

package/README.md

@@ -1,151 +1,368 @@
 # <img src="./logo.png" alt="Logo" width="36" /> `@modulify/validator`
 
+[![npm version](https://img.shields.io/npm/v/@modulify/validator.svg)](https://www.npmjs.com/package/@modulify/validator)
 [![codecov](https://codecov.io/gh/modulify/validator/branch/main/graph/badge.svg)](https://codecov.io/gh/modulify/validator)
 [![Tests Status](https://github.com/modulify/validator/actions/workflows/tests.yml/badge.svg)](https://github.com/modulify/validator/actions)
-[![npm version](https://badge.fury.io/js/%40modulify%2Fvalidator.svg)](https://www.npmjs.com/package/@modulify/validator)
 
-This library provides a declarative validation utility.
+`@modulify/validator` is a small TypeScript validation library built around three separate layers:
 
-The utility does not include text messages in the generated violations but instead provides metadata that can
-be used to create a custom view for them.
+- predicates for runtime checks and type narrowing;
+- assertions for machine-readable validation failures;
+- combinators for schema composition, including structural recursion over arrays and objects.
+
+The project is intentionally centered on structured metadata instead of built-in human-readable error messages.
+
+## What This Project Is
+
+This library is designed for cases where you want to:
+
+- keep simple type guards useful on their own;
+- validate nested data recursively;
+- receive structured violation objects instead of text messages;
+- decide later how those violations should be rendered or transformed.
+
+Typical outputs of the validation layer can be mapped into:
+
+- localized error messages;
+- form field error state;
+- API error payloads;
+- analytics/debug data;
+- custom UI or virtual DOM nodes.
+
+## Idea
+
+The project separates two concerns that are often mixed in one abstraction.
+
+### Predicates
+
+Predicates are small runtime checks that also act as TypeScript type guards.
+
+They answer questions like:
+
+- is this value a string?
+- is this value an object with a specific shape?
+- does this value satisfy a basic logical condition?
+
+This layer is meant to stay simple and independently useful even outside the validation pipeline.
+
+### Validators And Assertions
+
+Assertions are checks that can return a violation with structured metadata.
+
+Instead of generating a text message, an assertion returns data that describes:
+
+- what failed;
+- where it failed;
+- which semantic code failed;
+- which arguments or bounds were involved.
+
+That keeps presentation outside the library.
+
+### Why This Exists Alongside `zod`-Like Libraries
+
+Libraries such as `zod`, `yup`, and similar schema-oriented tools are well known and solve a large class of validation problems well.
+
+The goal of this project is different.
+
+It is not primarily trying to be:
+
+- a schema-definition DSL;
+- a form library with built-in message semantics;
+- an all-in-one parsing and presentation layer.
+
+Instead, this project focuses on:
+
+- small predicates for narrowing;
+- a separate assertion layer for diagnostics;
+- composable schema combinators;
+- machine-readable violations that consumers can map however they want.
+
+A short summary of the intended direction is:
+
+> Type-safe predicates for narrowing, and validators for machine-readable diagnostics.
+
+Or even shorter:
+
+> No messages, only meaning.
 
 ## Installation
 
 Using `yarn`:
 
-```
+```bash
 yarn add @modulify/validator
 ```
 
-or, using `npm`:
+Using `npm`:
 
-```
+```bash
 npm install @modulify/validator --save
 ```
 
-## Usage
+## Quick Example
 
 ```typescript
 import {
-  HasLength,
-  HasProperties,
-  IsDefined,
-  IsString,
+  each,
+  shape,
+  exact,
+  hasLength,
+  isDefined,
+  isString,
+  nullable,
+  optional,
   validate,
 } from '@modulify/validator'
 
-const violations = await validate({
+const [ok, validated, violations] = await validate({
   form: {
-    nickname: '',
+    nickname: undefined,
+    title: null,
     password: '',
+    role: 'admin',
   },
-}, HasProperties({
+}, shape({
   form: [
-    IsDefined(),
-    HasProperties({
-      nickname: IsString.That(HasLength({ min: 4 })),
-      password: IsString.That(HasLength({ min: 6 })),
+    isDefined,
+    shape({
+      nickname: optional([isString, hasLength({ min: 4 })]),
+      title: nullable(isString),
+      password: [isString, hasLength({ min: 6 })],
+      role: exact('admin'),
     }),
   ],
-})) /* [{
-  by: '@modulify/validator/IsString',
-  value: '',
-  path: ['form', 'nickname'],
-  reason: 'min',
-  meta: 4,
-}, {
-  by: '@modulify/validator/IsString',
-  value: '',
-  path: ['form', 'password'],
-  reason: 'min',
-  meta: 6,
-}] */
+}))
+
+if (ok) {
+  validated.form.nickname.toUpperCase()
+} else {
+  console.log(violations)
+}
 ```
 
-or (for synchronous validation):
+Synchronous validation:
 
 ```typescript
-const violations = validate.sync({
+const [ok, validated, violations] = validate.sync({
   form: {
     nickname: '',
     password: '',
   },
-}, HasProperties({
+}, shape({
   form: [
-    IsDefined(),
-    HasProperties({
-      nickname: IsString.That(HasLength({ min: 4 })),
-      password: IsString.That(HasLength({ min: 6 })),
+    isDefined,
+    shape({
+      nickname: [isString, hasLength({ min: 4 })],
+      password: [isString, hasLength({ min: 6 })],
     }),
   ],
 }))
+
+if (ok) {
+  validated.form.password.toUpperCase()
+}
 ```
 
-## Exported types
-
-* `Violation` – an object that contains information about a value – why it violates one or more constraints;
-  includes following fields:
-  * `value` – value that violates something;
-  * `path` – path to the value, an empty array for scalar values and represents full path to the value in a complex
-    object;
-  * `violates` – indicator of the violated constraint;
-  * `reason` – indicator of the reason why the constraint is violated;
-  * `meta` – some data to describe the reason – what exactly the boundaries were not met;
-  ```typescript
-  import type { Violation } from '@modulify/validator/types'
-  ```
-* `Predicate` – function that accepts a value and returns `true` or `false`; logical unit that is used for checking
-  multiple things: type or if the value satisfies certain criteria; accepts generic argument `T` to specify
-  the type of the value, if predicate returns `true`;
-  ```typescript
-  import type { Predicate } from '@modulify/validator/types'
-  ```
-* `Assertion` – extension of the `Predicate` type that includes:
-  * `fqn` – field – some predefined name that will be used as a value for the `violates` field of `Violation`;
-  * `bail` – field – flag that interrupts further validation if the assertion fails;
-  * `reason` – field, optional – string or symbol that is used to indicate, why assertion has failed;
-    always added to a violation object, if present;
-  * `meta` – field, optional – some metadata to use in further analysis; always added to a violation object, if present;
-  * `That` – method – used to extend assertion with other assertions;
-  * `also` – field – readonly array of other assertions that was attached by `That` method;
-  ```typescript
-  import type { Assertion } from '@modulify/validator/types'
-  ```
-
-## Exported members
-
-* `validate` – function that accepts a value for validation as the first argument, constraints as the second,
-  and path to a value as the third (that is optional and used mostly for internal purposes, as validation is recursive);
-  includes method `sync` that has the same arguments set but performs validation synchronously and throws error when
-  finds an asynchronous constraint;
-
-* `Assert` – creates assertion from logical predicate:
-  ```typescript
-  const IsSomething = Assert(isSomething, {
-    fqn: 'Some fqn',
-    bail: true,
-  })
-  ```
-  Arguments:
-  * Logical predicate
-  * Options, that includes `fqn`, `bail`, `reason` (optional), and `meta` (optional);
-* `HasLength` – checks length property of the specified string or array; can be configured with options:
-  * `exact` – if the length should be exactly equal the specified value;
-  * `max` – if the length should be equal or less than the specified value;
-  * `min` – if the length should be equal or greater than the specified value;
-  * `bail` – set this to true if you need to interrupt further validation if the assertion fails;
-* `IsBoolean` – checks if the value is **boolean**; interrupts further validation if fails;
-* `IsDate` – checks if the value is Date **object**; interrupts further validation if fails;
-* `IsDefined` – checks if the value is **not undefined**; interrupts further validation if fails;
-* `IsEmail` – checks if the value is a **valid email**; interrupts further validation if fails;
-* `IsNull` – checks if the value is **null**; interrupts further validation if fails;
-* `IsNumber` – checks if the value is **number**; interrupts further validation if fails;
-* `IsString` – checks if the value is **string**; interrupts further validation if fails;
-* `IsSymbol` – checks if the value is a **symbol**; interrupts further validation if fails;
-* `OneOf` – checks if the value equal to one of the specified values; can be configured with:
-  * `equalTo` – predicate f(a, b) that checks if two values are equal or not;
-  by default the strict `===` comparison is used
-  * `bail` – set this to true if you need to interrupt further validation if the assertion fails;
-
-* `Each` – a runner that runs validation for each element in array;
-* `HasProperties` – a runner that runs object's structure check.
+Sync narrowing of the original variable:
+
+```typescript
+import {
+  isDefined,
+  isString,
+  matches,
+} from '@modulify/validator'
+
+const value: unknown = 'nickname'
+
+if (matches.sync(value, [isDefined, isString])) {
+  value.toUpperCase()
+}
+```
+
+Typed success branch directly from `validate`:
+
+```typescript
+import {
+  shape,
+  isDefined,
+  isString,
+  validate,
+} from '@modulify/validator'
+
+const schema = shape({
+  name: [isDefined, isString],
+})
+
+const [ok, validated, violations] = await validate({ name: 'Kirill' }, schema)
+
+if (ok) {
+  validated.name.toUpperCase()
+} else {
+  console.log(violations)
+}
+```
+
+## Shape API
+
+`shape(...)` is the reusable object-shape API. It validates nested record-like objects and exposes small immutable helpers such as `strict()`, `pick()`, `omit()`, `partial()`, `extend()`, `merge()`, `refine()`, and `fieldsMatch(...)`.
+
+```typescript
+import {
+  isString,
+  optional,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+const profile = shape({
+  id: isString,
+  nickname: optional(isString),
+})
+
+const [ok] = validate.sync({
+  id: 'u1',
+  nickname: 'neo',
+}, profile)
+```
+
+Detailed guides:
+
+- [Shape API Guide](./docs/en/01-shape-api.md)
+
+## Metadata And Introspection
+
+`meta(...)` attaches machine-readable metadata to any constraint, and `describe(...)` returns a stable recursive descriptor tree for built-in constraints and compatible custom validators.
+
+```typescript
+import {
+  describe,
+  isString,
+  meta,
+  optional,
+  shape,
+} from '@modulify/validator'
+
+const registration = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    placeholder: 'name@example.com',
+  }),
+  nickname: optional(isString),
+}).strict(), {
+  title: 'Registration form',
+})
+
+const node = describe(registration)
+```
+
+Detailed guides:
+
+- [Metadata And Introspection Guide](./docs/en/02-metadata-and-introspection.md)
+- [Violation Code Types Guide](./docs/en/08-violation-code-types.md)
+
+## Mental Model
+
+A practical way to think about the library is:
+
+- predicates answer: does this value satisfy condition `X`?
+- assertions answer: if not, what exactly failed?
+- combinators answer: how should constraints be combined into a bigger schema, including recursive object and array traversal?
+
+In the current API this usually looks like:
+
+- leaf checks with assertions such as `isString`, `isDefined`, `hasLength`, `oneOf`;
+- schema composition with combinators such as `exact`, `optional`, `nullable`, `nullish`, `shape(...)`, `each(...)`;
+- typed validation through `validate(...)` or `validate.sync(...)`;
+- narrowing of the original sync variable through `matches.sync(...)`.
+
+## Violations
+
+`validate(...)` returns machine-readable `Violation[]`, and `collection(...)` can wrap that list into a small helper API for exact path lookups and tree traversal.
+
+```typescript
+import {
+  collection,
+  isString,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+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'])
+```
+
+Detailed guides:
+
+- [Violations Guide](./docs/en/03-violations.md)
+- [Violation Code Types Guide](./docs/en/08-violation-code-types.md)
+
+## JSON Schema Export
+
+`toJsonSchema(...)` derives a JSON Schema view from the same public descriptor tree returned by `describe(...)`.
+
+```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)
+```
+
+Detailed guides:
+
+- [JSON Schema Export Guide](./docs/en/04-json-schema-export.md)
+
+## Public API
+
+The detailed public API guide covers root exports, specialized subpath exports, the validation result tuple, and how the package surface is split between validation, predicates, violations, metadata, and JSON Schema export.
+
+Detailed guides:
+
+- [Public API Guide](./docs/en/05-public-api.md)
+
+## Recipes And AI Reference
+
+Two additional guides are useful when you want faster practical navigation instead of reading the whole conceptual set front to back.
+
+- [Common Recipes](./docs/en/06-common-recipes.md) - task-oriented examples for payload validation, wrapper choice, reusable shapes, form error mapping, and JSON Schema export.
+- [AI Reference](./docs/en/07-ai-reference.md) - compact contract summary for agents, tooling, and quick semantic lookup.
+
+## Notes
+
+- Assertions return structured metadata instead of messages.
+- Combinators are thin schema-building helpers layered on top of assertions and validators; `each` and `shape` are structural combinators in this model.
+- Predicates are intended to stay useful independently from the validation layer.
+- The library is easier to use when one stable violation format is kept across the whole project.
+- `validate(...)` narrows the `validated` tuple item, not the original input variable.
+- To narrow the original variable in sync code, use `matches.sync(...)`.
+
+## Translations
+
+- [Russian](./docs/ru/README.md)

package/dist/assert.cjs

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const metadata = require("./metadata.cjs.js");
+const assert = (predicate, meta, constraints = []) => {
+  const assertionCode = meta.code ?? meta.name;
+  const assertionArgs = meta.args ?? [];
+  const violationSubject = {
+    kind: "assertion",
+    name: meta.name,
+    code: assertionCode,
+    args: assertionArgs
+  };
+  const assertion = ((value) => {
+    if (!predicate(value)) {
+      return {
+        value,
+        violates: violationSubject
+      };
+    }
+    for (const [extract, check, code, ...args] of constraints) {
+      if (!check(extract(value), ...args)) {
+        const constraintSubject = {
+          kind: "assertion",
+          name: meta.name,
+          code,
+          args
+        };
+        return {
+          value,
+          violates: constraintSubject
+        };
+      }
+    }
+    return null;
+  });
+  Object.defineProperties(assertion, {
+    name: {
+      configurable: true,
+      value: meta.name
+    },
+    bail: {
+      enumerable: true,
+      value: meta.bail
+    },
+    constraints: {
+      enumerable: true,
+      value: constraints
+    },
+    check: {
+      enumerable: true,
+      value: (value) => predicate(value) && (!constraints.length || constraints.every(([extract, check, , ...args]) => check(extract(value), ...args)))
+    }
+  });
+  return metadata.attachConstraintDescriptor(assertion, () => ({
+    kind: "assertion",
+    name: meta.name,
+    bail: meta.bail,
+    code: assertionCode,
+    args: assertionArgs,
+    constraints: constraints.map(([, , code, ...args]) => ({
+      code,
+      args
+    }))
+  }));
+};
+exports.assert = assert;

package/dist/assert.d.ts

@@ -0,0 +1,16 @@
+import { Assertion, AssertionConstraint, Predicate } from '../types';
+type AssertMeta = {
+    name: string;
+    bail: boolean;
+    code?: string;
+    args?: readonly unknown[];
+};
+type ResolveAssertionCode<Name extends string, Code extends string | undefined> = Code extends string ? Code : Name;
+type ResolveAssertionArgs<Args extends readonly unknown[] | undefined> = Args extends readonly unknown[] ? Args : [];
+export declare const assert: <T, const Name extends string, const Bail extends boolean, const Code extends string | undefined = undefined, const Args extends readonly unknown[] | undefined = undefined, const C extends readonly AssertionConstraint[] = []>(predicate: Predicate<T>, meta: AssertMeta & {
+    name: Name;
+    bail: Bail;
+    code?: Code;
+    args?: Args;
+}, constraints?: C) => Assertion<T, C, ResolveAssertionCode<Name, Code>, ResolveAssertionArgs<Args>, Name>;
+export {};

package/dist/assert.mjs

@@ -0,0 +1,66 @@
+import { e as attachConstraintDescriptor } from "./metadata.es.js";
+const assert = (predicate, meta, constraints = []) => {
+  const assertionCode = meta.code ?? meta.name;
+  const assertionArgs = meta.args ?? [];
+  const violationSubject = {
+    kind: "assertion",
+    name: meta.name,
+    code: assertionCode,
+    args: assertionArgs
+  };
+  const assertion = ((value) => {
+    if (!predicate(value)) {
+      return {
+        value,
+        violates: violationSubject
+      };
+    }
+    for (const [extract, check, code, ...args] of constraints) {
+      if (!check(extract(value), ...args)) {
+        const constraintSubject = {
+          kind: "assertion",
+          name: meta.name,
+          code,
+          args
+        };
+        return {
+          value,
+          violates: constraintSubject
+        };
+      }
+    }
+    return null;
+  });
+  Object.defineProperties(assertion, {
+    name: {
+      configurable: true,
+      value: meta.name
+    },
+    bail: {
+      enumerable: true,
+      value: meta.bail
+    },
+    constraints: {
+      enumerable: true,
+      value: constraints
+    },
+    check: {
+      enumerable: true,
+      value: (value) => predicate(value) && (!constraints.length || constraints.every(([extract, check, , ...args]) => check(extract(value), ...args)))
+    }
+  });
+  return attachConstraintDescriptor(assertion, () => ({
+    kind: "assertion",
+    name: meta.name,
+    bail: meta.bail,
+    code: assertionCode,
+    args: assertionArgs,
+    constraints: constraints.map(([, , code, ...args]) => ({
+      code,
+      args
+    }))
+  }));
+};
+export {
+  assert
+};