Tracely

Lightweight and decorator-based validation library for TypeScript classes using metadata reflection.

✨ Features

• Simple and declarative validation using decorators
• Supports numbers, strings, dates, logic rules, nested objects and arrays
• Built-in validation engine
• TypeScript-native, ideal for DTO validation or form data
• No runtime dependencies other than reflect-metadata

📦 Installation

npm install tracely

Also ensure your tsconfig.json includes:

{
  "experimentalDecorators": true,
  "emitDecoratorMetadata": true
}

🚀 Usage

1. Define your DTO

import {
  Min, Max, NotBlank, Email, Pattern, Future,
  Valid, RequiredIf, AssertTrue, Size, Each, validate
} from 'tracely';

class Address {
  @NotBlank()
  street: string;

  @NotBlank()
  city: string;
}

class UserDto {
  @Min(18)
  @Max(99)
  age: number;

  @Email()
  email: string;

  @Size(2)
  tags: string[];

  @Future()
  expiryDate: string;

  @Valid()
  address: Address;

  @RequiredIf('subscribe', true)
  phone?: string;

  @AssertTrue()
  acceptedTerms: boolean;
}

2. Validate the DTO

const dto = new UserDto();
dto.age = 15;
dto.email = "bad-email";
dto.tags = ["ok"];
dto.expiryDate = "2000-01-01";
dto.subscribe = true;
dto.acceptedTerms = false;
dto.address = new Address();

const errors = validate(dto);
console.log(errors);

Output [ "age must be >= 18", "email must match pattern /^[^\s@]+@[^\s@]+\.[^\s@]+$/", "tags must contain at least 2 elements", "expiryDate must be in the future", "phone is required because subscribe = true", "acceptedTerms must be true", "address.street must not be blank", "address.city must not be blank" ]

🧩 Supported Decorators

🧮 Numbers

@Min(n)

@Max(n)

@DecimalMin(value: string, inclusive?: boolean)

@DecimalMax(value: string, inclusive?: boolean)

@Positive()

@PositiveOrZero()

@Negative()

@NegativeOrZero()

📏 Strings & Patterns

@NotBlank()

@Size(min, max?) – works on strings or arrays

@Pattern(regex)

@Email()

@URL()

@UUID()

📆 Dates

@Past()

@PastOrPresent()

@Future()

@FutureOrPresent()

🔁 Structures

@Valid() – validate nested objects

@Each(validator) – validate each item in an array (e.g., @EachEmail())

🧠 Logical

@RequiredIf(prop, value)

@AssertTrue()

@AssertFalse()

🧠 License

MIT – built with ❤️ by developers, for developers.