@modulify/validator 0.0.2 → 0.2.0

package/README.md

@@ -1,187 +1,368 @@
-# `@modulify/validator`
+# <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)
 
+`@modulify/validator` is a small TypeScript validation library built around three separate layers:
 
-This library provides a declarative validation util.
+- 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 util does not provide any text messages in the constraints produced and gives only metadata that can
-be used to create a custom view for them.
+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 {
-  Collection,
-  Exists,
-  Length,
-  createValidator,
+  each,
+  shape,
+  exact,
+  hasLength,
+  isDefined,
+  isString,
+  nullable,
+  optional,
+  validate,
 } from '@modulify/validator'
 
-const validator = createValidator()
+const [ok, validated, violations] = await validate({
+  form: {
+    nickname: undefined,
+    title: null,
+    password: '',
+    role: 'admin',
+  },
+}, shape({
+  form: [
+    isDefined,
+    shape({
+      nickname: optional([isString, hasLength({ min: 4 })]),
+      title: nullable(isString),
+      password: [isString, hasLength({ min: 6 })],
+      role: exact('admin'),
+    }),
+  ],
+}))
 
-const violations = validator.validate({
+if (ok) {
+  validated.form.nickname.toUpperCase()
+} else {
+  console.log(violations)
+}
+```
+
+Synchronous validation:
+
+```typescript
+const [ok, validated, violations] = validate.sync({
   form: {
     nickname: '',
     password: '',
   },
-}, new Collection({
+}, shape({
   form: [
-    new Exists(),
-    new Collection({
-      nickname: new Length({ min: 4 }),
-      password: new Length({ min: 6 }),
+    isDefined,
+    shape({
+      nickname: [isString, hasLength({ min: 4 })],
+      password: [isString, hasLength({ min: 6 })],
     }),
   ],
-}), /* do not set or set to true for async validation */ false) /* [{
-  by: '@modulify/validator/Length',
-  value: '',
-  path: ['form', 'nickname'],
-  reason: 'min',
-  meta: 4,
-}, {
-  by: '@modulify/validator/Length',
-  value: '',
-  path: ['form', 'password'],
-  reason: 'min',
-  meta: 6,
-}] */
+}))
+
+if (ok) {
+  validated.form.password.toUpperCase()
+}
+```
+
+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()
+}
 ```
 
-### Constraints
+Typed success branch directly from `validate`:
 
-Constraints provide information of how the value should be validated.
+```typescript
+import {
+  shape,
+  isDefined,
+  isString,
+  validate,
+} from '@modulify/validator'
 
-Available from the box:
+const schema = shape({
+  name: [isDefined, isString],
+})
 
-* `Collection` &ndash; used for validating objects' structure;
-* `Each` &ndash; used for validating arrays' elements; applies specified constraints to each element of an array;
-* `Exists` &ndash; used for checking if a value is defined; useful for finding missing keys;
-* `Length` &ndash; used for checking arrays' and string's length, available settings (all optional) are:
-  * `exact` &ndash; `number`, array or string should have exactly specified count of elements or characters;
-  * `max` &ndash; `number`, maximum elements in array or maximum characters in string;
-  * `min` &ndash; `number`, minimum elements in array or minimum characters in string;
-* `OneOf` &ndash; used for restricting which values can be used.
+const [ok, validated, violations] = await validate({ name: 'Kirill' }, schema)
 
-There is no any basic constraint class to extend, but they should follow signature
-described in `types/index.d.ts` &ndash; `Constraint`.
+if (ok) {
+  validated.name.toUpperCase()
+} else {
+  console.log(violations)
+}
+```
 
-### Validators
+## Shape API
 
-Validators provide validation logic that relies on information provided by constraints.
+`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(...)`.
 
-There is no any basic validator class to extend, but they should follow signature
-described in `types/index.d.ts` &ndash; `ConstraintValidator`.
+```typescript
+import {
+  isString,
+  optional,
+  shape,
+  validate,
+} from '@modulify/validator'
 
-### Provider
+const profile = shape({
+  id: isString,
+  nickname: optional(isString),
+})
 
-Provider is used to bind constraints with their validators, provides a validator for a constraint.
+const [ok] = validate.sync({
+  id: 'u1',
+  nickname: 'neo',
+}, profile)
+```
 
-All providers should follow signature described in `types/index.d.ts` &ndash; `Provider`.
+Detailed guides:
 
-This feature is responsible for extending validation capabilities. Custom provider can be passed into
-`createValidator` function or `override` method of `Validator` instance.
+- [Shape API Guide](./docs/en/01-shape-api.md)
 
-There is a built-in provider &ndash; `ProviderChain`. It allows to "chain" providers &ndash; if
-suitable validator was not found in currently used provider, it will try to find it in previous provider that was
-overridden by `override` method.
+## 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 type {
-  Constraint,
-  ConstraintValidator,
-  ConstraintViolation,
-  Key,
-  Provider,
+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 {
-  ProviderChain,
-  createValidator,
+  collection,
+  isString,
+  shape,
+  validate,
 } from '@modulify/validator'
 
-class Email implements Constraint {
-  public readonly name = '@app/validator/Email'
+const [ok, validated, violations] = validate.sync({
+  profile: {
+    email: '',
+  },
+}, shape({
+  profile: shape({
+    email: isString,
+  }),
+}))
 
-  toViolation (value: unknown, path: Key[]): ConstraintViolation {
-    return {
-      by: this.name,
-      value,
-      path,
-    }
-  }
-}
+const errors = collection(violations)
 
-class EmailValidator implements ConstraintValidator {
-  private readonly _constraint: Email
+const rootErrors = errors.at([])
+const emailErrors = errors.at(['profile', 'email'])
+```
 
-  constructor (constraint: Email) {
-    this._constraint = constraint
-  }
+Detailed guides:
 
-  validate (value: unknown, path?: Key[]): ConstraintViolation | null {
-    if (!(typeof value === 'string') || !/\S+@\S+\.\S+/.test(value)) {
-      return this._constraint.toViolation(value, path)
-    }
+- [Violations Guide](./docs/en/03-violations.md)
+- [Violation Code Types Guide](./docs/en/08-violation-code-types.md)
 
-    return null
-  }
-}
-```
+## JSON Schema Export
 
-then
+`toJsonSchema(...)` derives a JSON Schema view from the same public descriptor tree returned by `describe(...)`.
 
 ```typescript
-const provider = new ProviderChain(new class implements Provider {
-  get (constraint: Constraint) {
-    return constraint instanceof Email ? new EmailValidator(constraint) : null
-  }
-
-  override (provider: Provider): Provider {
-    return new ProviderChain(provider, this)
-  }
+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)
 ```
 
-or
+Detailed guides:
 
-```typescript
-const provider = new class implements Provider {
-  get (constraint: Constraint) {
-    return constraint instanceof Email ? new EmailValidator(constraint) : null
-  }
-
-  override (provider: Provider): Provider {
-    return new ProviderChain(provider, this)
-  }
-}
-```
+- [JSON Schema Export Guide](./docs/en/04-json-schema-export.md)
 
-and then
+## Public API
 
-```typescript
-const validator = createValidator(provider)
-```
+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.
 
-or
+Detailed guides:
 
-```typescript
-const validator = createValidator()
-const overridden = validator.override(provider) // it creates new validator instance, so validator !== overridden
-```
+- [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
+};