@decaf-ts/decorator-validation 1.7.1 → 1.7.3

package/README.md

@@ -1,6 +1,9 @@
 ![Banner](./workdocs/assets/Banner.png)
 ## Simple Decorator based Model Validation Engine
 
+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)
 ![GitHub language count](https://img.shields.io/github/languages/count/decaf-ts/decorator-validation?style=plastic)
 ![GitHub top language](https://img.shields.io/github/languages/top/decaf-ts/decorator-validation?style=plastic)
@@ -15,12 +18,6 @@
 ![Pull Requests](https://img.shields.io/github/issues-pr-closed/decaf-ts/decorator-validation.svg)
 ![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)
 
-![Line Coverage](workdocs/reports/coverage/badge-lines.svg)
-![Function Coverage](workdocs/reports/coverage/badge-functions.svg)
-![Statement Coverage](workdocs/reports/coverage/badge-statements.svg)
-![Branch Coverage](workdocs/reports/coverage/badge-branches.svg)
-
-
 ![Forks](https://img.shields.io/github/forks/decaf-ts/decorator-validation.svg)
 ![Stars](https://img.shields.io/github/stars/decaf-ts/decorator-validation.svg)
 ![Watchers](https://img.shields.io/github/watchers/decaf-ts/decorator-validation.svg)
@@ -32,21 +29,42 @@ Documentation available [here](https://decaf-ts.github.io/decorator-validation/)
 
 ### Description
 
-Simple implementation of a Typescript decorator based validation system.
+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.
+
+Meant to be easily extended, customized, and integrated with browser input validation mechanisms, this library offers a declarative approach to validation through TypeScript decorators.
+
+#### Core Components
 
-Meant to be easily extended, customized and integrated with the browser's input validation mechanisms
+##### Model System
+The library is built around the abstract `Model` class, which serves as the foundation for all model objects. The Model system provides:
+
+- 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
+
+##### Validation Framework
+The validation framework offers a rich set of decorators for validating model properties:
+
+- **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
+
+##### 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.
 
-Standalone module, defines the base Model class:
-- decorator based validation api with recursive validation;
-- Customizable Model building factories enabling nested instantiation;
-- Model serialization/deserialization;
-- Model Hashing;
-- Model Equality;
-- Easily extended custom validation;
-- Java like date handling (format and serialization);
-- Configurable error messages;
-- TODO: comparative validation (between attributes, hierarchical, dates);
-- TODO: Model Deep Cloning;
 
 ### How to Use
 
@@ -55,7 +73,281 @@ Standalone module, defines the base Model class:
 
 ### Examples
 
-
+#### Creating a Model Class
+
+```typescript
+import { Model, model, required, email, minlength, maxlength, min, hashedBy, serializedBy } from 'decorator-validation';
+
+@model()
+@hashedBy('sha256')
+@serializedBy('json')
+class User extends Model {
+  @required()
+  @minlength(3)
+  @maxlength(50)
+  username!: string;
+
+  @required()
+  @email()
+  email!: string;
+
+  @required()
+  @min(18, "User must be at least 18 years old")
+  age!: number;
+
+  constructor(data?: any) {
+    super(data);
+    Model.fromModel(this, data);
+  }
+}
+```
+
+#### Basic Validation
+
+```typescript
+// Create a user with invalid data
+const invalidUser = new User({
+  username: "jo", // too short
+  email: "not-an-email",
+  age: 16 // below minimum
+});
+
+// Check for validation errors
+const errors = invalidUser.hasErrors();
+console.log(errors);
+// Output will contain validation errors for username, email, and age
+
+// Create a valid user
+const validUser = new User({
+  username: "john_doe",
+  email: "john@example.com",
+  age: 25
+});
+
+// Check for validation errors
+const validErrors = validUser.hasErrors();
+console.log(validErrors); // undefined - no errors
+```
+
+#### Using Different Validation Decorators
+
+##### Numeric Validation
+
+```typescript
+class Product {
+  @required()
+  name!: string;
+
+  @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;
+
+  constructor(data?: any) {
+    Model.fromModel(this, data);
+  }
+}
+```
+
+##### String Validation
+
+```typescript
+class Article {
+  @required()
+  @minlength(5)
+  @maxlength(100)
+  title!: string;
+
+  @required()
+  @minlength(50)
+  @maxlength(5000)
+  content!: string;
+
+  @pattern(/^[a-z0-9-]+$/, "Slug must contain only lowercase letters, numbers, and hyphens")
+  slug!: string;
+
+  constructor(data?: any) {
+    Model.fromModel(this, data);
+  }
+}
+```
+
+##### Special Types Validation
+
+```typescript
+class Contact {
+  @required()
+  name!: string;
+
+  @required()
+  @email()
+  email!: string;
+
+  @url()
+  website?: string;
+
+  @date("yyyy-MM-dd")
+  birthdate?: Date;
+
+  @password()
+  password!: string;
+
+  constructor(data?: any) {
+    Model.fromModel(this, data);
+  }
+}
+```
+
+##### Comparison Validation
+
+```typescript
+class DateRange {
+  @required()
+  @date("yyyy-MM-dd")
+  startDate!: Date;
+
+  @required()
+  @date("yyyy-MM-dd")
+  @gt("startDate", "End date must be after start date")
+  endDate!: Date;
+
+  constructor(data?: any) {
+    Model.fromModel(this, data);
+  }
+}
+
+class PriceRange {
+  @required()
+  @min(0)
+  minPrice!: number;
+
+  @required()
+  @min(0)
+  @gte("minPrice", "Maximum price must be greater than or equal to minimum price")
+  maxPrice!: number;
+
+  constructor(data?: any) {
+    Model.fromModel(this, data);
+  }
+}
+```
+
+##### Collection Validation
+
+```typescript
+class Tag {
+  @required()
+  name!: string;
+
+  constructor(data?: any) {
+    Model.fromModel(this, data);
+  }
+}
+
+class BlogPost {
+  @required()
+  title!: string;
+
+  @required()
+  content!: string;
+
+  @list(Tag)
+  tags!: Tag[];
+
+  @set(Tag)
+  uniqueTags!: Set<Tag>;
+
+  constructor(data?: any) {
+    Model.fromModel(this, data);
+  }
+}
+```
+
+#### Model Registry and Building
+
+```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);
+```
+
+#### Serialization and Deserialization
+
+```typescript
+// Create a user
+const user = new User({
+  username: "john_doe",
+  email: "john@example.com",
+  age: 25
+});
+
+// Serialize to string
+const serialized = user.serialize();
+console.log(serialized);
+// Output: JSON string representation of the user
+
+// Deserialize from string
+const deserialized = Model.deserialize(serialized);
+console.log(deserialized);
+// Output: User object with the same properties
+```
+
+#### Comparing Models
+
+```typescript
+const user1 = new User({
+  username: "john_doe",
+  email: "john@example.com",
+  age: 25
+});
+
+const user2 = new User({
+  username: "john_doe",
+  email: "john@example.com",
+  age: 25
+});
+
+const user3 = new User({
+  username: "jane_doe",
+  email: "jane@example.com",
+  age: 28
+});
+
+console.log(user1.equals(user2)); // true - same properties
+console.log(user1.equals(user3)); // false - different properties
+
+// Compare ignoring specific properties
+console.log(user1.equals(user3, "username", "email")); // true - only comparing age
+```
+
+#### Hashing Models
+
+```typescript
+const user = new User({
+  username: "john_doe",
+  email: "john@example.com",
+  age: 25
+});
+
+// Get hash of the model
+const hash = user.hash();
+console.log(hash);
+// Output: Hash string based on the configured algorithm (sha256)
+```
 
 
 ### Related