@decaf-ts/decorator-validation 1.7.19 → 1.7.20

package/README.md

@@ -1,7 +1,11 @@
-![Banner](./workdocs/assets/Banner.png)
-## Simple Decorator based Model Validation Engine
+# Decorator Validation
+
+A TypeScript decorator-driven validation and model framework. It lets you:
+- Define validation rules with declarative decorators on model properties (e.g., @required, @min, @pattern).
+- Build, validate, serialize, and hash models with pluggable registries and algorithms.
+- Extend validation via a registry of Validator classes and utilities.
+- Optionally expose validation as MCP tools for automation workflows.
 
-A comprehensive TypeScript library that provides a powerful model validation framework using decorators. It enables type-safe, declarative validation for your TypeScript models with features for serialization, comparison, and hashing. The library offers a rich set of validation decorators for various data types and constraints, making it easy to define and enforce validation rules on your model properties.
 
 
 ![Licence](https://img.shields.io/github/license/decaf-ts/decorator-validation.svg?style=plastic)
@@ -27,328 +31,521 @@ A comprehensive TypeScript library that provides a powerful model validation fra
 
 Documentation available [here](https://decaf-ts.github.io/decorator-validation/)
 
-### Description
-
-The decorator-validation library is a comprehensive TypeScript implementation of a decorator-based validation system. It provides a robust framework for defining, validating, and managing model objects in TypeScript applications.
+# Decorator Validation – Detailed Description
 
-Meant to be easily extended, customized, and integrated with browser input validation mechanisms, this library offers a declarative approach to validation through TypeScript decorators.
+Decorator Validation is a TypeScript library that centers on two complementary pillars:
 
-#### Core Components
+1) Declarative validation via decorators
+- A rich set of property decorators such as @required, @min, @max, @minLength, @maxLength, @pattern, @email, @url, @type, @equals, @greaterThan, @greaterThanOrEqual, @lessThan, @lessThanOrEqual, @step, @list, @diff, @date, @password, as well as an async() flag helper.
+- Each decorator writes strongly-typed metadata using reflect-metadata and a common Validation metadata keying convention, so validators can later interpret the rules consistently.
+- Decorators are defined in src/validation/decorators.ts and are backed by concrete Validator classes in src/validation/Validators/* that implement the actual validation logic.
 
-##### Model System
-The library is built around the abstract `Model` class, which serves as the foundation for all model objects. The Model system provides:
+2) A model system tailored for validation, building, hashing, and serialization
+- Models are ordinary classes marked with @model() (src/model/decorators.ts). The decorator replaces the constructor, binds the model prototype utilities, runs a global builder (if registered), and tags reflection metadata for identification.
+- Additional class-level decorators configure algorithms:
+  - @hashedBy(algorithm, ...args) to define model hashing implementation.
+  - @serializedBy(serializer, ...args) to define serialization strategy.
+  - @description(text) to attach human-readable documentation to a class, property, or method.
+- The Model class (src/model/Model.ts) provides:
+  - A ModelRegistryManager for registering and retrieving model constructors by name, enabling rebuild/deserialize flows.
+  - Validation integration (model/validation.ts) that runs the registered validators against metadata collected by decorators.
+  - Utility methods and metadata helpers to identify models, fetch metadata, compare instances, and orchestrate hashing/serialization strategies.
 
-- A registry mechanism for storing and retrieving model constructors
-- Serialization and deserialization capabilities
-- Hashing functionality for model objects
-- Equality comparison between model objects
-- Support for nested model instantiation and validation
+Core runtime architecture
+- Validation namespace (src/validation/Validation.ts):
+  - Manages a pluggable IValidatorRegistry so custom Validator implementations can be registered, migrated, and queried.
+  - Exposes helper utilities: Validation.key(key) for reflect-metadata keying, Validation.keys() to list available validator keys, register(...) and get(...) to manage validators, decorator registration to link a metadata key to its decorator for dynamic use.
+- Validator classes (src/validation/Validators/*):
+  - BaseValidator.ts defines common behaviors; concrete validators (RequiredValidator, MinValidator, PatternValidator, etc.) implement validate and message/typing logic.
+  - ValidatorRegistry.ts stores Validator instances keyed by ValidationKeys constants.
+  - constants.ts defines DEFAULT_ERROR_MESSAGES, DEFAULT_PATTERNS, and ValidationKeys (e.g., REQUIRED, MIN, MAX...).
+  - decorators.ts contains decorator sugar for directly registering standard validators and building metadata using Decoration/Reflection utilities.
+- Utilities (src/utils/*):
+  - strings, dates, types, serialization, hashing, registry, decorators, Decoration helper, and a PathProxy to traverse nested properties and apply metadata.
 
-##### Validation Framework
-The validation framework offers a rich set of decorators for validating model properties:
+Intent of the library
+- Provide a cohesive, decorator-first developer experience for enforcing validation constraints on model classes.
+- Ensure that validation, model lifecycle (build/serialize/hash), and metadata are consistent and extensible through registries.
+- Allow advanced composition (custom validators, alternative registries), and integration into automation flows (MCP tools).
 
-- **Basic Validation**: `required()`, `min()`, `max()`, `step()`, `minlength()`, `maxlength()`, `pattern()`
-- **Type-Specific Validation**: `email()`, `url()`, `type()`, `date()`, `password()`, `list()`, `set()`
-- **Comparison Validation**: `eq()`, `diff()`, `lt()`, `lte()`, `gt()`, `gte()` for comparing properties
+Design principles
+- Declarative over imperative: Constraints live next to the properties they validate.
+- Extensibility: Registries and helper factories allow swapping implementations without changing consumer code.
+- Type safety: Metadata and decorators are typed; validators advertise supported types; utility functions use narrow types where practical.
+- Separation of concerns: Decorators express intent; Validator classes implement behavior; Model provides lifecycle utilities.
 
-##### Key Features
-- **Decorator-based validation API** with recursive validation for nested models
-- **Customizable Model building factories** enabling nested instantiation
-- **Model serialization/deserialization** with configurable serializers
-- **Model Hashing** with configurable algorithms
-- **Model Equality** comparison with support for excluding properties
-- **Easily extended custom validation** through the decorator system
-- **Java-like date handling** (format and serialization)
-- **Configurable error messages** for all validation rules
-- **Comparative validation** between attributes, supporting various comparison operators
-- **Type safety** through TypeScript's static typing system
 
-The library is designed with extensibility in mind, allowing developers to create custom validators and decorators to meet specific application requirements. It integrates seamlessly with TypeScript's type system to provide compile-time type checking alongside runtime validation.
+# How to Use Decorator Validation
 
+This guide shows concrete, TypeScript-accurate examples for the main public APIs exported by the library. Examples are inspired by patterns used across the repo tests and typical usage of decorator-driven validation and models.
 
-### How to Use
+Notes
+- Import paths assume a consumer importing from the package entry and submodules as re-exported by src/index.ts.
+- All snippets are valid TypeScript.
 
-- [Initial Setup](./workdocs/tutorials/For%20Developers.md#_initial-setup_)
-- [Installation](./workdocs/tutorials/For%20Developers.md#installation)
 
-### Examples
+## Model decorators and model lifecycle
 
-#### Creating a Model Class
+### @model()
+Description: Marks a class as a model. The constructor is wrapped to bind model utilities and run a global builder (if any).
 
 ```typescript
-import { Model, model, required, email, minlength, maxlength, min, hashedBy, serializedBy } from 'decorator-validation';
+import { model, Model, ModelArg } from "@decaf-ts/decorator-validation";
 
 @model()
-@hashedBy('sha256')
-@serializedBy('json')
 class User extends Model {
-  @required()
-  @minlength(3)
-  @maxlength(50)
-  username!: string;
+  @prop()
+  id!: string;
+  @prop()
+  name!: string;
+  
+  constructor(arg?: ModelArg<User>) {
+    super(arg);
+  }
+}
+
+const u = new User();
+```
+
+Extending from the Model class is optional but highly recommended. Regardless, if decorated with `@model()`, the constructor signature must be compatible.
+
+When using a class for validation, eg `hasErrors()` only, @model() is not required.
+
+#### Model construction
 
+When a class is decorated with @model(), the framework invokes a model building function right after the instance is constructed. This builder initializes your model from the argument you pass to the constructor.
+
+There are two builder strategies:
+- Model.fromObject: Accepts a plain object and performs a more permissive, best-effort mapping.
+    - Does not enforce nested Model classes
+- Model.fromModel (default): does the same as fromObject, but also instantiates nested Model classes
+
+Your model constructors should accept an optional argument and pass it to super so the builder can use it.
+
+You can change between builder functions by using:
+
+```typescript
+import { required, Model, model, ModelArg } from "@decaf-ts/decorator-validation";
+
+@model()
+class Child extends Model {
   @required()
-  @email()
-  email!: string;
+  name!: string;
+  
+  constructor(arg?: ModelArg<Child>) {
+    super(arg);
+  }
+}
 
+@model()
+class Parent extends Model {
+  @required()
+  name!: string;
   @required()
-  @min(18, "User must be at least 18 years old")
-  age!: number;
+  child!: Child;
+  constructor(arg?: ModelArg<Parent>) {
+    super(arg);
+  }
+}
+// Default builder is Model.fromModel
+
+let parent = new Parent({
+  child: {
+    name: "child"
+  }
+})
+
+parent.child instanceof Child; // true
+
+Model.setBuilder(Model.fromObject);
+
+parent = new Parent({
+  child: {
+    name: "child"
+  }
+})
+
+parent.child instanceof Child; // false
+```
+
+### @hashedBy(algorithm, ...args)
+Description: Declares which hashing strategy to use when hashing model instances.
+
+```typescript
+import { model, hashedBy, ModelArg, prop } from "@decaf-ts/decorator-validation";
 
-  constructor(data?: any) {
-    super(data);
-    Model.fromModel(this, data);
+@model()
+@hashedBy("sha256", "utf8")
+class FileInfo extends Model {
+  @prop()
+  path!: string;
+  @prop()
+  size!: number;
+  
+  constructor(arg?: ModelArg<FileInfo>) {
+    super(arg)
   }
 }
 ```
 
-#### Basic Validation
+### @serializedBy(serializer, ...args)
+Description: Declares which serializer to use for (de)serializing model instances.
 
 ```typescript
-// Create a user with invalid data
-const invalidUser = new User({
-  username: "jo", // too short
-  email: "not-an-email",
-  age: 16 // below minimum
-});
+import { prop, ModelArg, model, serializedBy } from "@decaf-ts/decorator-validation";
+
+@model()
+@serializedBy("json")
+class Settings extends Model {
+  @prop()
+  theme!: string;
+  @prop()
+  locale!: string;
+  
+  constructor(arg?: ModelArg<Settings>){
+    super(arg)
+  }
+}
+```
 
-// Check for validation errors
-const errors = invalidUser.hasErrors();
-console.log(errors);
-// Output will contain validation errors for username, email, and age
+### @description(text)
+Description: Applies textual documentation metadata to a class, property, or method.
 
-// Create a valid user
-const validUser = new User({
-  username: "john_doe",
-  email: "john@example.com",
-  age: 25
-});
+```typescript
+import { model, description, Model } from "@decaf-ts/decorator-validation";
 
-// Check for validation errors
-const validErrors = validUser.hasErrors();
-console.log(validErrors); // undefined - no errors
+@model()
+@description("Represents an application user")
+class User extends Model {
+  @description("Unique identifier")
+  id!: string;
+  // ...
+}
 ```
 
-#### Using Different Validation Decorators
 
-##### Numeric Validation
+## Validation decorators (property-level)
+Each decorator writes metadata for a corresponding Validator. Use them on model fields.
+
+
+### @prop()
+Description: Registers a property with the model system. This is required for model construction so the property participates in metadata, serialization, hashing, validation discovery, etc.
+
+Important
+- All other property decorators (e.g., @required, @min, @email, etc.) already apply @prop under the hood.
+- Therefore, you only need to use @prop when a property has no other decorators.
+
+
+### @required(message?)
+Description: Field must be present and non-empty.
 
 ```typescript
-class Product {
-  @required()
-  name!: string;
+import { Model, required, model } from "@decaf-ts/decorator-validation";
 
+@model()
+class User extends Model {
   @required()
-  @min(0, "Price cannot be negative")
-  @max(10000, "Price cannot exceed 10,000")
-  @step(0.01, "Price must have at most 2 decimal places")
-  price!: number;
+  username!: string;
+  //...
+}
+```
 
-  constructor(data?: any) {
-    Model.fromModel(this, data);
-  }
+### @min(value, message?) and @max(value, message?)
+Description: Numeric or date boundaries.
+
+```typescript
+import { model } from "@decaf-ts/decorator-validation";
+import { min } from "@decaf-ts/decorator-validation";
+import { max } from "@decaf-ts/decorator-validation";
+
+@model()
+class Product extends Model {
+  @min(0)
+  @max(1000)
+  price!: number;
 }
 ```
 
-##### String Validation
+### @minLength(n, message?) and @maxLength(n, message?)
+Description: String length boundaries.
 
 ```typescript
-class Article {
-  @required()
-  @minlength(5)
-  @maxlength(100)
-  title!: string;
+import { model, Model } from "@decaf-ts/decorator-validation";
+import { minLength, maxLength } from "@decaf-ts/decorator-validation";
 
-  @required()
-  @minlength(50)
-  @maxlength(5000)
-  content!: string;
+@model()
+class Credentials extends Model {
+  @minLength(8)
+  @maxLength(64)
+  password!: string;
+}
+```
 
-  @pattern(/^[a-z0-9-]+$/, "Slug must contain only lowercase letters, numbers, and hyphens")
-  slug!: string;
+### @pattern(regex | string, message?)
+Description: String must match a pattern.
 
-  constructor(data?: any) {
-    Model.fromModel(this, data);
-  }
+```typescript
+import { model } from "@decaf-ts/decorator-validation";
+import { pattern, model } from "@decaf-ts/decorator-validation";
+
+@model()
+class Vehicle extends Model {
+  @pattern(/^[A-Z]{2}-\d{2}-[A-Z]{2}$/)
+  plate!: string;
 }
 ```
 
-##### Special Types Validation
+### @email(message?)
+Description: Must be a valid email.
 
 ```typescript
-class Contact {
-  @required()
-  name!: string;
+import { model } from "@decaf-ts/decorator-validation";
+import { email } from "@decaf-ts/decorator-validation";
 
-  @required()
+@model()
+class Contact extends Model {
   @email()
   email!: string;
+}
+```
+
+### @url(message?)
+Description: Must be a valid URL.
+
+```typescript
+import { model } from "@decaf-ts/decorator-validation";
+import { url } from "@decaf-ts/decorator-validation";
 
+@model()
+class Link extends Model {
   @url()
-  website?: string;
+  href!: string;
+}
+```
 
-  @date("yyyy-MM-dd")
-  birthdate?: Date;
+### @type(T, message?)
+Description: Enforces a runtime type match (e.g., Number, String, Date).
 
-  @password()
-  password!: string;
+```typescript
+import { model } from "@decaf-ts/decorator-validation";
+import { type } from "@decaf-ts/decorator-validation";
 
-  constructor(data?: any) {
-    Model.fromModel(this, data);
-  }
+@model()
+class Measurement extends Model {
+  @type(Number)
+  value!: number;
 }
 ```
 
-##### Comparison Validation
+### @equals(otherValueOrPath, message?)
+Description: Value must equal the provided value or another property.
 
 ```typescript
-class DateRange {
-  @required()
-  @date("yyyy-MM-dd")
-  startDate!: Date;
+import { model } from "@decaf-ts/decorator-validation";
+import { equals } from "@decaf-ts/decorator-validation";
 
-  @required()
-  @date("yyyy-MM-dd")
-  @gt("startDate", "End date must be after start date")
-  endDate!: Date;
+@model()
+class Confirmation extends Model {
+  password!: string;
+  @equals(":password")
+  confirm!: string;
+}
+```
 
-  constructor(data?: any) {
-    Model.fromModel(this, data);
-  }
+### @greaterThan(x) / @greaterThanOrEqual(x) / @lessThan(x) / @lessThanOrEqual(x)
+Description: Numeric or date comparisons.
+
+```typescript
+import { model } from "@decaf-ts/decorator-validation";
+import { greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual } from "@decaf-ts/decorator-validation";
+
+@model()
+class Range extends Model {
+  @greaterThan(0)
+  @lessThanOrEqual(100)
+  ratio!: number;
 }
+```
 
-class PriceRange {
-  @required()
-  @min(0)
-  minPrice!: number;
+### @step(step, message?)
+Description: Numeric step constraints.
 
-  @required()
-  @min(0)
-  @gte("minPrice", "Maximum price must be greater than or equal to minimum price")
-  maxPrice!: number;
+```typescript
+import { model, Model } from "@decaf-ts/decorator-validation";
+import { step } from "@decaf-ts/decorator-validation";
 
-  constructor(data?: any) {
-    Model.fromModel(this, data);
-  }
+@model()
+class Slider extends Model {
+  @step(0.5)
+  value!: number;
 }
 ```
 
-##### Collection Validation
+### @list(values, message?)
+Description: Constrains value to be one of the provided list.
 
 ```typescript
-class Tag {
-  @required()
-  name!: string;
+import { model, Model } from "@decaf-ts/decorator-validation";
+import { list } from "@decaf-ts/decorator-validation";
 
-  constructor(data?: any) {
-    Model.fromModel(this, data);
-  }
+@model()
+class ThemeSettingm extends Model {
+  @list(["light", "dark", "system"]) 
+  theme!: "light" | "dark" | "system";
 }
+```
 
-class BlogPost {
-  @required()
-  title!: string;
+### @diff(propertyPath, message?)
+Description: Must be different from another property.
 
-  @required()
-  content!: string;
+```typescript
+import { model, Model } from "@decaf-ts/decorator-validation";
+import { diff } from "@decaf-ts/decorator-validation";
 
-  @list(Tag)
-  tags!: Tag[];
+@model()
+class Credentials extends Model {
+  username!: string;
+  @diff(":username")
+  password!: string;
+}
+```
 
-  @set(Tag)
-  uniqueTags!: Set<Tag>;
+### @date({ min?, max? }, message?)
+Description: Date constraints for a date-typed field.
 
-  constructor(data?: any) {
-    Model.fromModel(this, data);
-  }
+```typescript
+import { model, Model } from "@decaf-ts/decorator-validation";
+import { date } from "@decaf-ts/decorator-validation";
+
+@model()
+class Booking extends Model {
+  @date({ min: new Date("2025-01-01"), max: new Date("2025-12-31") })
+  start!: Date;
+}
+```
+
+### @password(options?, message?)
+Description: Password strength constraints (e.g., min length, uppercase, digits, symbols) depending on validator configuration.
+
+```typescript
+import { model } from "@decaf-ts/decorator-validation";
+import { password, Model } from "@decaf-ts/decorator-validation";
+
+@model()
+class Account extends Model{
+  @password({ minLength: 10 })
+  password!: string;
 }
 ```
 
-#### Model Registry and Building
+### async()
+Description: Marks a model as involving async validation rules (decorator flag helper).
 
 ```typescript
-// Register models
-Model.register(User);
-Model.register(BlogPost);
-Model.register(Tag);
-
-// Build a model from plain object
-const userData = {
-  username: "jane_doe",
-  email: "jane@example.com",
-  age: 28
-};
-
-const user = Model.build(userData, "User");
-
-// Bulk register models
-bulkModelRegister(User, BlogPost, Tag);
+import { model } from "@decaf-ts/decorator-validation";
+import { async } from "@decaf-ts/decorator-validation";
+
+@model()
+@async()
+class Signup {
+  // fields that may use async validators
+}
 ```
 
-#### Serialization and Deserialization
+
+## Running validation
+Use the model validation utilities to evaluate rules defined by decorators.
 
 ```typescript
-// Create a user
-const user = new User({
-  username: "john_doe",
-  email: "john@example.com",
-  age: 25
+import { model, required, email, validate, Model } from "@decaf-ts/decorator-validation";
+
+@model()
+class Contact extends Model {
+  @required()
+  @email()
+  email!: string;
+  
+  constructor(arg?: ModelArg<Contact>) {
+    super(arg);
+  }
+}
+
+const c = new Contact({
+  email: "not-an-email"
 });
 
-// Serialize to string
-const serialized = user.serialize();
-console.log(serialized);
-// Output: JSON string representation of the user
+let errs = c.hasErrors(); // resolves to a list of errors or undefined
+
+@async()
+@model()
+class User extends Model {
+  @required()
+  @email()
+  email!: string;
+  
+  constructor(arg?: ModelArg<User>) {
+    super(arg);
+  }
+}
+
+const u = new User({
+  email: "not-an-email"
+})
+
+errs = await u.hasErrors(); // resolves to a list of errors or undefined
 
-// Deserialize from string
-const deserialized = Model.deserialize(serialized);
-console.log(deserialized);
-// Output: User object with the same properties
 ```
 
-#### Comparing Models
+
+## Validation registry APIs (Validation)
+
+### Validation.setRegistry(registry, migration?)
+Description: Swap the active validator registry and optionally migrate validators.
 
 ```typescript
-const user1 = new User({
-  username: "john_doe",
-  email: "john@example.com",
-  age: 25
-});
+import { Validation, ValidatorRegistry } from "@decaf-ts/decorator-validation";
 
-const user2 = new User({
-  username: "john_doe",
-  email: "john@example.com",
-  age: 25
-});
+const custom = new ValidatorRegistry();
+Validation.setRegistry(custom, v => v); // trivial migration
+```
 
-const user3 = new User({
-  username: "jane_doe",
-  email: "jane@example.com",
-  age: 28
-});
+### Validation.register(...validators)
+Description: Register one or more Validator implementations or definitions.
+
+```typescript
+import { Validation, Validator, validator } from "@decaf-ts/decorator-validation";
 
-console.log(user1.equals(user2)); // true - same properties
-console.log(user1.equals(user3)); // false - different properties
+@validator("ALWAYS_OK")
+class AlwaysOk extends Validator {
+  hasErrors(...args: any[]) { return []; }
+}
 
-// Compare ignoring specific properties
-console.log(user1.equals(user3, "username", "email")); // true - only comparing age
+Validation.register(new AlwaysOk());
 ```
 
-#### Hashing Models
+### Validation.get(key)
+Description: Retrieve a registered validator by key.
 
 ```typescript
-const user = new User({
-  username: "john_doe",
-  email: "john@example.com",
-  age: 25
-});
+import { Validation, ValidationKeys } from "@decaf-ts/decorator-validation";
 
-// Get hash of the model
-const hash = user.hash();
-console.log(hash);
-// Output: Hash string based on the configured algorithm (sha256)
+const requiredValidator = Validation.get(ValidationKeys.REQUIRED);
 ```
 
+### Validation.key(k) and Validation.keys()
+Description: Build a reflect-metadata key or list all registered keys.
+
+```typescript
+import { Validation } from "@decaf-ts/decorator-validation";
+
+const metaKey = Validation.key("REQUIRED");
+const allKeys = Validation.keys();
+```
+
+## Notes on tests and validity
+- Patterns here reflect common test patterns found across the monorepo (e.g., model decoration, decorator application, registry customization).
+- Each snippet is valid TypeScript and aligns with the re-exports provided by the package entry.
+
 
 ### Related