Validant


Validant is a TypeScript-first validation library for real-world, dynamic rules — no DSLs, just types and functions.

``ts
// Define your model
interface User {
name: string;
email: string;
age: number;
}

// Create validation rules
const userRule: ValidationRule = {
name: [required("Name is required")],
email: [required(), emailAddress("Invalid email")],
age: [required(), minNumber(18, "Must be 18+")]
};

// Validate
const validator = new Validator();
const result = validator.validate(user, userRule);
`

Table of Contents

- ✨ Why Validant?
- 📊 Benchmark Results
- 🧩 When validation is complex and not just "required()"
- 🏁 Getting Started
- 📦 Installation
- 🛠️ Validation Rule, Not Schema
- ✅ IntelliSense That Just Works
- 🛡️ Type Safe
- 🔒 Safe at Compile Time
- 🔒 Safe at Run Time
- ✅ Type Freedom
- 🛠️ Validation
- ⚡Sync Validation
- Object Level Validation
- Field Level Validation
- 🌐 Async Validation
- Async Object Level Validation
- Async Field Level Validation
- ✅ Intuitive Error Structure
- 🔧 Custom Validation
- 🧩 Inline Custom Rule Example
- 🧩 Composable Rule
- 🔓 Loose Coupling
- 🧮 Array Validation
- ⚠️ Error Structure Breakdown
- 🧱 {} Object Error
- [🧱 [] Array Error](#-array-error)
- 🛡️ Type-Safe Error
- 🧬 Validation Context Awareness: Property, Root Object, and Arrays
- 🔹Property-Level Awareness
- 🔹Root object awareness
- 🔹Array (Item) Awareness
- Examples
- Sync Example
- Async Examples
- 🧩 Validation Rule Composition
- 📚 API Reference
- Types
- Custom Validate Function
- Built-in Rules
- 🔄 Flat Error Structure for UI/API

✨ Why Validant?

- 🔄 TYPE-FIRST, NOT SCHEMA-FIRST = LOOSE COUPLING: Unlike other libraries that generate types from schemas, Validant starts from your own types — allowing you to decouple your app from any validation library, including this one.
- 🧠 No DSLs. No special syntax. Just plain functions.
- 🧩 Composable: Easily combine validations and reuse them across your codebase.
- 🪶 Zero dependencies. Minimal API. Maximum control.
- 🧪 Made for TypeScript first: Validant is written in and only tested with TypeScript. It's built for modern TypeScript-first projects. It might work in JavaScript — but it's never been tested there.
- ✅ Deep, fine-grained validation on individual fields — sync or async, arrays, nested objects, also support Validate per Field

🧩 When validation is complex and not just "required()"

`ts

import {
ValidationRule,
AsyncValidationRule,
Validator,
AsyncValidator,
required,
minNumber,
maxNumber,
emailAddress,
isString,
isNumber,
elementOf,
arrayMinLen,
arrayMaxLen,
ValidateFunc,
AsyncValidateFunc,
RuleViolation,
ValidationResult
} from '../../index';

// =============================================================================
// DOMAIN MODELS
// =============================================================================

interface Address {
street: string;
city: string;
state: string;
zipCode: string;
country: string;
}

interface Person {
firstName: string;
lastName: string;
dateOfBirth: Date;
ssn: string; // Social Security Number
address: Address;
phone: string;
email: string;
}

interface PolicyHolder extends Person {
policyNumber: string;
policyStartDate: Date;
policyEndDate: Date;
premiumAmount: number;
coverageType: 'BASIC' | 'PREMIUM' | 'COMPREHENSIVE';
riskScore: number; // 1-100, calculated by underwriting
}

interface Vehicle {
vin: string; // Vehicle Identification Number
make: string;
model: string;
year: number;
mileage: number;
value: number; // Current market value
primaryUse: 'PERSONAL' | 'COMMERCIAL' | 'BUSINESS';
safetyRating: number; // 1-5 stars
antiTheftDevices: string[];
}

interface Incident {
incidentDate: Date;
incidentTime: string; // HH:MM format
location: Address;
description: string;
policeReportNumber?: string;
weatherConditions: 'CLEAR' | 'RAIN' | 'SNOW' | 'FOG' | 'ICE' | 'SEVERE';
roadConditions: 'DRY' | 'WET' | 'ICY' | 'CONSTRUCTION' | 'POOR_VISIBILITY';
atFaultParties: string[]; // Can be multiple parties
witnessCount: number;
}

interface Damage {
component: string; // e.g., "Front Bumper", "Engine", "Windshield"
severity: 'MINOR' | 'MODERATE' | 'SEVERE' | 'TOTAL_LOSS';
estimatedCost: number;
repairShop?: string;
partsRequired: string[];
laborHours: number;
isPreExistingDamage: boolean;
}

interface MedicalClaim {
injuredParty: Person;
injuryType: string;
severity: 'MINOR' | 'MODERATE' | 'SEVERE' | 'CRITICAL';
treatmentFacility: string;
doctorName: string;
estimatedTreatmentCost: number;
isPreExistingCondition: boolean;
requiresSpecialistCare: boolean;
}

interface InsuranceClaim {
claimNumber: string;
claimType: 'AUTO_ACCIDENT' | 'THEFT' | 'VANDALISM' | 'NATURAL_DISASTER' | 'COMPREHENSIVE';
policyHolder: PolicyHolder;
claimant: Person; // Person filing the claim (might be different from policy holder)
vehicle: Vehicle;
incident: Incident;
damages: Damage[];
medicalClaims: MedicalClaim[];
claimAmount: number; // Total claimed amount
supportingDocuments: string[]; // Document IDs
attorneyInvolved: boolean;
attorneyDetails?: {
name: string;
barNumber: string;
firm: string;
phone: string;
};
priorClaims: number; // Number of claims in last 5 years
submissionDate: Date;
adjusterId?: string;
}

// =============================================================================
// MOCK EXTERNAL SERVICES
// =============================================================================

interface ExternalServices {
validateSSN(ssn: string): Promise;
validateVIN(vin: string): Promise<{ isValid: boolean; vehicleInfo?: any }>;
validatePolicyStatus(policyNumber: string): Promise<{ isActive: boolean; hasOutstandingPremiums: boolean }>;
}

// Mock implementation
const externalServices: ExternalServices = {
async validateSSN(ssn: string): Promise {
await new Promise(resolve => setTimeout(resolve, 10));
return /^\d{3}-\d{2}-\d{4}$/.test(ssn);
},

async validateVIN(vin: string): Promise<{ isValid: boolean; vehicleInfo?: any }> {
await new Promise(resolve => setTimeout(resolve, 15));
const isValid = /^[A-HJ-NPR-Z0-9]{17}$/.test(vin);
return {
isValid,
vehicleInfo: isValid ? { decoded: true } : undefined
};
},

async validatePolicyStatus(policyNumber: string): Promise<{ isActive: boolean; hasOutstandingPremiums: boolean }> {
await new Promise(resolve => setTimeout(resolve, 10));
return {
isActive: !policyNumber.includes('EXPIRED'),
hasOutstandingPremiums: policyNumber.includes('OVERDUE')
};
}
};

// =============================================================================
// BUSINESS RULE VALIDATORS
// =============================================================================

function validateSSNFormat(): AsyncValidateFunc {
return async function (ssn: string) {
if (!ssn) return undefined;

const isValidFormat = await externalServices.validateSSN(ssn);
if (!isValidFormat) {
return {
ruleName: 'validateSSNFormat',
attemptedValue: ssn,
errorMessage: 'Invalid Social Security Number format or number does not exist.'
};
}
};
}

function validateVINNumber(): AsyncValidateFunc {
return async function (vin: string, claim: InsuranceClaim) {
if (!vin) return undefined;

const result = await externalServices.validateVIN(vin);
if (!result.isValid) {
return {
ruleName: 'validateVINNumber',
attemptedValue: vin,
errorMessage: 'Invalid Vehicle Identification Number. Please verify the VIN.'
};
}
};
}

function validatePolicyActive(): AsyncValidateFunc {
return async function (policyNumber: string, claim: InsuranceClaim) {
if (!policyNumber) return undefined;

const status = await externalServices.validatePolicyStatus(policyNumber);

if (!status.isActive) {
return {
ruleName: 'validatePolicyActive',
attemptedValue: policyNumber,
errorMessage: 'Policy is not active. Claims cannot be processed for inactive policies.'
};
}

if (status.hasOutstandingPremiums) {
return {
ruleName: 'validatePolicyActive',
attemptedValue: policyNumber,
errorMessage: 'Policy has outstanding premiums. Please resolve payment issues before filing a claim.'
};
}
};
}

function validateIncidentDate(): ValidateFunc {
return function (incidentDate: Date, claim: InsuranceClaim) {
if (!incidentDate) return undefined;

const now = new Date();
const policyStart = claim.policyHolder.policyStartDate;
const policyEnd = claim.policyHolder.policyEndDate;

// Can't be in the future
if (incidentDate > now) {
return {
ruleName: 'validateIncidentDate',
attemptedValue: incidentDate,
errorMessage: 'Incident date cannot be in the future.'
};
}

// Must be within policy period
if (incidentDate < policyStart || incidentDate > policyEnd) {
return {
ruleName: 'validateIncidentDate',
attemptedValue: incidentDate,
errorMessage: Incident must have occurred during the policy period (${policyStart.toDateString()} - ${policyEnd.toDateString()}).
};
}

// Claims must be filed within 30 days of incident (business rule)
const daysSinceIncident = Math.floor((now.getTime() - incidentDate.getTime()) / (1000 60 60 * 24));
if (daysSinceIncident > 30) {
return {
ruleName: 'validateIncidentDate',
attemptedValue: incidentDate,
errorMessage: 'Claims must be filed within 30 days of the incident. Late filing requires special approval.'
};
}
};
}

// =============================================================================
// COMPREHENSIVE VALIDATION RULES
// =============================================================================

const insuranceClaimValidationRules: AsyncValidationRule = {
claimNumber: [
required('Claim number is required.'),
isString('Claim number must be a string.'),
function (claimNumber: string) {
if (!/^INS-\d{4}-\d{6}$/.test(claimNumber)) {
return {
ruleName: 'claimNumberFormat',
attemptedValue: claimNumber,
errorMessage: 'Claim number must follow format: INS-YEAR-XXXXXX (e.g., INS-2024-000001)'
};
}
}
],

claimType: [
required('Claim type is required.'),
elementOf(['AUTO_ACCIDENT', 'THEFT', 'VANDALISM', 'NATURAL_DISASTER', 'COMPREHENSIVE'], 'Invalid claim type.')
],

policyHolder: {
firstName: [required('Policy holder first name is required.'), isString()],
lastName: [required('Policy holder last name is required.'), isString()],

dateOfBirth: [
required('Date of birth is required.'),
function (dob: Date, claim: InsuranceClaim) {
const age = Math.floor((Date.now() - dob.getTime()) / (1000 60 60 24 365));
if (age < 16) {
return {
ruleName: 'minimumAge',
attemptedValue: dob,
errorMessage: 'Policy holder must be at least 16 years old.'
};
}
if (age > 100) {
return {
ruleName: 'maximumAge',
attemptedValue: dob,
errorMessage: 'Please verify date of birth. Age appears to be over 100 years.'
};
}
}
],

ssn: [
required('Social Security Number is required.'),
validateSSNFormat()
],

policyNumber: [
required('Policy number is required.'),
validatePolicyActive()
],

email: [required(), emailAddress()],

premiumAmount: [
required(),
minNumber(100, 'Minimum premium amount is $100.'),
maxNumber(50000, 'Premium amount seems unusually high. Please verify.')
],

coverageType: [
required(),
elementOf(['BASIC', 'PREMIUM', 'COMPREHENSIVE'], 'Invalid coverage type.')
],

riskScore: [
required(),
minNumber(1, 'Risk score must be between 1 and 100.'),
maxNumber(100, 'Risk score must be between 1 and 100.')
],

address: {
street: [required()],
city: [required()],
state: [required()],
zipCode: [
required(),
function (zipCode: string) {
if (!/^\d{5}(-\d{4})?$/.test(zipCode)) {
return {
ruleName: 'zipCodeFormat',
attemptedValue: zipCode,
errorMessage: 'ZIP code must be in format: 12345 or 12345-6789'
};
}
}
],
country: [required()]
}
},

claimant: {
firstName: [required()],
lastName: [required()],
email: [required(), emailAddress()],
ssn: [validateSSNFormat()],
address: {
street: [required()],
city: [required()],
state: [required()],
zipCode: [required()],
country: [required()]
}
},

vehicle: {
vin: [
required('Vehicle VIN is required.'),
validateVINNumber()
],

make: [required()],
model: [required()],

year: [
required(),
minNumber(1990, 'Vehicles older than 1990 require special underwriting.'),
maxNumber(new Date().getFullYear() + 1, 'Vehicle year cannot be in the future.')
],

mileage: [
required(),
minNumber(0, 'Mileage cannot be negative.'),
function (mileage: number, claim: InsuranceClaim) {
const vehicleAge = new Date().getFullYear() - claim.vehicle.year;
const expectedMaxMileage = vehicleAge * 15000;

if (mileage > expectedMaxMileage * 1.5) {
return {
ruleName: 'mileageValidation',
attemptedValue: mileage,
errorMessage: Mileage (${mileage.toLocaleString()}) appears unusually high for a ${claim.vehicle.year} vehicle.
};
}
}
],

value: [
required(),
minNumber(1000, 'Vehicle value must be at least $1,000 to be eligible for coverage.')
],

primaryUse: [
required(),
elementOf(['PERSONAL', 'COMMERCIAL', 'BUSINESS'], 'Invalid primary use type.')
],

safetyRating: [
required(),
minNumber(1, 'Safety rating must be between 1 and 5.'),
maxNumber(5, 'Safety rating must be between 1 and 5.')
]
},

incident: {
incidentDate: [
required('Incident date is required.'),
validateIncidentDate()
],

incidentTime: [
required(),
function (time: string) {
if (!/^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$/.test(time)) {
return {
ruleName: 'timeFormat',
attemptedValue: time,
errorMessage: 'Time must be in HH:MM format (24-hour).'
};
}
}
],

description: [
required(),
function (description: string) {
if (description.length < 50) {
return {
ruleName: 'descriptionLength',
attemptedValue: description,
errorMessage: 'Incident description must be at least 50 characters long.'
};
}
}
],

weatherConditions: [
required(),
elementOf(['CLEAR', 'RAIN', 'SNOW', 'FOG', 'ICE', 'SEVERE'], 'Invalid weather condition.')
],

roadConditions: [
required(),
elementOf(['DRY', 'WET', 'ICY', 'CONSTRUCTION', 'POOR_VISIBILITY'], 'Invalid road condition.')
],

witnessCount: [
required(),
minNumber(0, 'Witness count cannot be negative.'),
maxNumber(20, 'Witness count seems unusually high. Please verify.')
],

location: {
street: [required()],
city: [required()],
state: [required()],
zipCode: [required()],
country: [required()]
}
},

damages: {
arrayRules: [
arrayMinLen(1, 'At least one damage entry is required.')
],
arrayElementRule: {
component: [required()],
severity: [
required(),
elementOf(['MINOR', 'MODERATE', 'SEVERE', 'TOTAL_LOSS'], 'Invalid damage severity.')
],
estimatedCost: [
required(),
minNumber(1, 'Damage cost must be greater than $0.'),
maxNumber(200000, 'Damage cost exceeds maximum limit.')
],
laborHours: [
required(),
minNumber(0, 'Labor hours cannot be negative.'),
maxNumber(500, 'Labor hours seem excessive.')
]
}
},

claimAmount: [
required('Claim amount is required.'),
minNumber(1, 'Claim amount must be greater than $0.')
],

supportingDocuments: {
arrayRules: [
arrayMinLen(1, 'At least one supporting document is required.')
]
},

priorClaims: [
required(),
minNumber(0, 'Prior claims count cannot be negative.'),
function (priorClaims: number, claim: InsuranceClaim) {
if (priorClaims >= 5) {
return {
ruleName: 'priorClaimsLimit',
attemptedValue: priorClaims,
errorMessage: 'Policy holders with 5+ prior claims require executive approval.'
};
}
}
],

submissionDate: [
required(),
function (submissionDate: Date) {
const now = new Date();
if (submissionDate > now) {
return {
ruleName: 'submissionDateFuture',
attemptedValue: submissionDate,
errorMessage: 'Submission date cannot be in the future.'
};
}
}
]
};
`

🏁 Getting Started

$3

`
npm install validant

or

yarn add validant
`

$3

Your model is your source of truth.

If you already have a model (and you should), Validant wraps validations around it — not the other way around:

`ts
class Account {
name: string;
age: number;
email: string;
}
`

Then you simply declare your validation rule dan validate:

`ts
import { minNumber, required, emailAddress, ValidationRule } from "validant";

const validationRule: ValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [required(), emailAddress("Invalid email address")],
};

// validate
const validator = new Validator();
const validationResult = validator.validate(account, validationRule);
`

If your model already defines the structure, why repeat it with something like name: string() or username: z.string()?

It works with literal object as well:

`ts
import { minNumber, required, emailAddress, ValidationRule } from "validant";

const account = {
name: "",
age: 0,
email: "",
};

const validationRule: ValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [required(), emailAddress("Invalid email address")],
};
`

$3

Here's how validation rules align seamlessly with IntelliSense:

!image

Because Validant uses your existing model, the validation rule knows your properties — their names and types — without extra declarations.

No inference hacks. No schema dance. Just proper TypeScript support, right out of the box.

🛡️ Type Safe

$3

No mismatched property names. No type mismatches. TypeScript will catch it — instantly.

!image

For example, Account doesn't have a creditCardNumber — and TypeScript will let you know right away.

This is especially useful when your model changes: the validation rule will break where it should, making it easy to stay in sync.

Rules are type-safe too — they know exactly what type they're validating, and you can build your own custom rules with full type awareness.

!image

Even with inferred literal objects, type safety still holds:

!image

$3

Need runtime guarantees? Validant has built-in rules for that too:

`ts
import {
emailAddress,
isString,
minNumber,
required,
ValidationRule,
} from "validant";

const validationRule: ValidationRule = {
name: [isString("Name should be string")],
age: [required()],
};
`

or you can do it your own way:

`ts
import {
emailAddress,
isString,
minNumber,
required,
ValidationRule,
} from "validant";

const validationRule: ValidationRule = {
name: [
(name, account) => {
const isString = typeof name === "string"; // check yourself, either return error or throw
if (!isString) {
return {
ruleName: "",
attemptedValue: name,
errorMessage: "Please enter the name with string",
};
}
},
],
age: [required()],
};
`

You are not enforced to define all properties, you can set partially set validation for age only:

`ts
import { minNumber, required, emailAddress, ValidationRule } from "validant";

const validationRule: ValidationRule = {
age: [required(), minNumber(17, "Should be at least 17 years old.")],
};
`

✅ Type Freedom

Validant works seamlessly with any kind of TypeScript structure — whether you're using interface, type, class, or even inferring types from objects.

$3

`ts
import { minNumber, required, emailAddress, ValidationRule } from "validant";

class Account {
name: string;
age: number;
email: string;
}

const validationRule: ValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [required(), emailAddress("Invalid email address")],
};
`

$3

`ts
import { minNumber, required, emailAddress, ValidationRule } from "validant";

interface Account {
name: string;
age: number;
email: string;
}

const validationRule: ValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [required(), emailAddress("Invalid email address")],
};
`

$3

`ts
import { minNumber, required, emailAddress, ValidationRule } from "validant";

type Account = {
name: string;
age: number;
email: string;
};

const validationRule: ValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [required(), emailAddress("Invalid email address")],
};
`

$3

`ts
import { minNumber, required, emailAddress, ValidationRule } from "validant";

type Account = {
name: string;
age: number;
email: string;
};

const account: Account = {
name: "",
age: 0,
email: "",
};

const validationRule: ValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [required(), emailAddress("Invalid email address")],
};
`

Use what fits your project best — Validant adapts to your TypeScript style.

🛠️ Validation

Validant supports both synchronous and asynchronous validation.

$3

#### Object Level Validation

Validation rules are represented as:

ValidationRule

`ts
import {
Validator,
ValidationRule,
Validator,
required,
minNumber,
emailAddress,
} from "validant";

// Given your data model:
interface Account {
name: string;
age: number;
email: string;
}

// validation rules
const validationRule: ValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [required(), emailAddress("Invalid email address")],
};
`

Instantiate validator and validate

`ts
const account: Account = {
name: "",
age: 0,
email: "",
};

// validate
const validator = new Validator();
const validationResult = validator.validate(account, validationRule);
`

The result looks like this:

`ts
{
message: "Validation failed. Please check and fix the errors to continue.",
isValid: false,
errors: {
name: [
{
attemptedValue: "",
errorMessage: "Account name is required.",
ruleName: "required"
}
],
age: [
{
attemptedValue: 0,
errorMessage: "Should be at least 17 years old.",
ruleName: "minNumber"
}
],
email: [
{
errorMessage: "This field is required.",
attemptedValue: "",
ruleName: "required"
},
{
errorMessage: "Invalid email address",
attemptedValue: "",
ruleName: "emailAddress"
}
]
},
};
`

#### Field Level Validation

You can validate a specific field of an object easily by calling validator.validateField(fieldName, object).

`ts
const account: Account = {
name: "",
age: 0,
email: "",
};

// Create a validator with your validation rules
const validator = new Validator();

// Validate the "name" field of the account object
const validationResult = validator.validateField(account, "name", validationRule);
`

The result will be an object like this:

`ts
{
isValid: false,
fieldName: "name",
errors: [
{
attemptedValue: "",
errorMessage: "This field is required.",
ruleName: "required"
}
]
}
`

This lets you perform precise, field-level validation with clear error feedback.

$3

#### Async Object Level Validation

If you want to use an async function as your rule function, you need to define your rule with: AsyncValidationRule.

Async rules are represented as:

AsyncValidationRule

`ts
import {
AsyncValidationRule,
AsyncValidator,
required,
minNumber,
emailAddress,
} from "validant";

// Given your data model:
interface Account {
name: string;
age: number;
email: string;
}

// validation rules
const validationRule: AsyncValidationRule = {
name: [required("Account name is required.")],
age: [required(), minNumber(17, "Should be at least 17 years old.")],
email: [
required(),
emailAddress("Invalid email address"),
// AsyncValidationRule allows you to accept async function rule, while ValidationRule not.
async (email: string) => {
/ ...check api or database /
},
],
};
`

Instantiate the AsyncValidator and validate

`ts
const account: Account = {
name: "",
age: 0,
email: "",
};

// validate
const validator = new AsyncValidator();
const validationResult = await validator.validateAsync(account, validationRule);
`

You'll get the same structured result:

`ts
// The validationResult above is equivalent to the following:
{
message: "Validation failed. Please check and fix the errors to continue.",
isValid: false,
errors: {
name: [
{
attemptedValue: "",
errorMessage: "Account name is required.",
ruleName: "required"
}
],
age: [
{
attemptedValue: 0,
errorMessage: "Should be at least 17 years old.",
ruleName: "minNumber"
}
],
email: [
{
errorMessage: "This field is required.",
attemptedValue: "",
ruleName: "required"
},
{
errorMessage: "Invalid email address",
attemptedValue: "",
ruleName: "emailAddress"
}
]
},
};
`

#### Async Field Level Validation

You can validate a specific field of an object easily by calling validator.validateFieldAsync(fieldName, object).

`ts
const account: Account = {
name: "",
age: 0,
email: "",
};

// Create a validator with your validation rules
const validator = new AsyncValidator();

// Validate the "email" field of the account object
const validationResult = await validator.validateFieldAsync(account, "email", validationRule);
`

The result will be an object like this:

`ts
{
isValid: false,
fieldName: "email",
errors: [
{
errorMessage: "This field is required.",
attemptedValue: "",
ruleName: "required"
},
{
errorMessage: "Invalid email address",
attemptedValue: "",
ruleName: "emailAddress"
}
]
}
`

This lets you perform precise, async field-level validation with clear error feedback.

#### ✅ Intuitive Error Structure

As you can see the above validationResult.errors mirrors the shape of your original object — field by field.
There's no guesswork, no opaque path strings ("user[0].email"), and no nested issues[] array to parse.

Validant gives you direct, predictable access to error messages using the same property keys as your data model.

#### You already know how to access your errors:

`ts
if (validationResult.errors.email) {
console.error(validationResult.errors.email.join(" "));
}
`

- ❌ No weird formats.
- ✅ The errors = your original object properties

🔧 Custom Validation

Validant provides complete control through custom validation functions with strict type signatures.

$3

`typescript
/**
* The return type if when validation failed
*/
export interface RuleViolation {
ruleName: string;
attemptedValue: any;
errorMessage: string;
}

/**
* Rule function signature
* @template TValue - Type of the property being validated
* @template TRoot - Type of the root object
*/
export type ValidateFunc = (
value: TValue,
root: TRoot
) => RuleViolation | undefined;
`

Key Advantages

- ✅ The root provides full access to the object being validated.
- ✅ All custom rules are context-aware — validating against sibling fields is easy.
- ❌ No hacks or workarounds needed.

$3

You can define your custom validation both inline or as a separated function.

`ts
interface LoginRequest {
userName: string;
password: string;
}

const loginRule: ValidationRule = {
userName: [
function (username, loginRequest) {
if (!username) {
return {
ruleName: "custom",
attemptedValue: username,
errorMessage: "Please enter username.",
};
}
},
function (username, loginRequest) {
if (username.toLocaleLowerCase().includes("admin")) {
return {
ruleName: "custom",
attemptedValue: username,
errorMessage: "Admin is not allowed to login.",
};
}
},
],
password: [
function (password, loginRequest) {
if (!password) {
return {
ruleName: "any",
attemptedValue: password,
errorMessage: "Please enter password.",
};
}
},
],
};
`

Validation Execution

`ts
const loginRequest: LoginRequest = {
userName: "",
password: "",
};

const validator = new Validator();
const result = validator.validate(loginRequest, loginRule);
`

Result Structure

`ts
{
message: "Validation failed. Please check and fix the errors to continue.",
isValid: false,
errors: {
userName: [
{
errorMessage: "Please enter username.",
attemptedValue: "",
ruleName: "custom"
}
],
password: [
{
errorMessage: "Please enter password.",
attemptedValue: "",
ruleName: "custom"
}
],
},
};
`

$3

Not a fan of bulky inline validations? If you feel the above inline validation is fat, lets turn them into reusable function instead with a meaningful function name:

`ts
interface LoginRequest {
userName: string;
password: string;
}

function requiredUserNameRule(): ValidateFunc {
return function (username, loginRequest) {
if (!username) {
return {
ruleName: requiredUserNameRule.name,
attemptedValue: username,
errorMessage: "Please enter username.",
};
}
};
}

function adminShouldBeBlocked(): ValidateFunc {
return function (username, loginRequest) {
if (username.toLocaleLowerCase().includes("admin")) {
return {
ruleName: adminShouldBeBlocked.name,
attemptedValue: username,
errorMessage: "Admin is not allowed to login.",
};
}
};
}

function requiredPasswordRule(): ValidateFunc {
return function (password, loginRequest) {
if (!password) {
return {
ruleName: requiredPasswordRule.name,
attemptedValue: password,
errorMessage: "Please enter password.",
};
}
};
}

// Much simpler. you can put above custom rules into its own files, its your choice
const loginRule: ValidationRule = {
userName: [requiredUserNameRule(), adminShouldBeBlocked()],
password: [requiredPasswordRule()],
};
`

🔓 Loose Coupling

The adminShouldBeBlocked function represents a domain-specific business validation. It's too valuable to be tightly coupled to any particular validation library. That logic belongs to your domain, not to infrastructure.

The type ValidateFunc is simply a helper — it gives you compile-time type safety and ensures your rule is compatible with the validation engine. But it's not mandatory to explicitly annotate every rule with it.

For example, this will still work seamlessly:

`ts
// The ValidateFunc removed
function adminShouldBeBlocked() {
return function (username, loginRequest) {
if (username.toLocaleLowerCase().includes("admin")) {
return {
ruleName: adminShouldBeBlocked.name,
attemptedValue: username,
errorMessage: "Admin is not allowed to login.",
};
}
};
}
`

As long as the function conforms to the expected shape, it will integrate with the validation system automatically — making your domain logic loosely coupled, portable, and testable without dragging in validation dependencies.

This approach encourages separation of concerns:

- Keep domain rules in domain layers.
- Easy to test.
- Keep validation orchestration in the validation layer.
- Compose them freely using meaningful, reusable functions.

Even if you change your framework in the future, the adminShouldBeBlocked remains highly reusable. An adapter function is all it takes to integrate it elsewhere.

🧮 Array Validation

Validating arrays in Validant is simple yet powerful. You can apply rules both to the array itself (e.g. length checks) and to each individual item in the array.

$3

`ts
interface OrderItem {
productId: number;
quantity: number;
}

interface Order {
id: string;
orderItems: OrderItem[];
}

const orderRule: ValidationRule = {
orderItems: {
arrayRules: [arrayMinLen(1)], // Array-level rules
arrayElementRule: {
// Item-level rules
productId: [required()],
quantity: [
minNumber(1, "Min qty is 1."),
maxNumber(5, "Max qty is 5."),
],
},
},
};
`

$3

1. Empty Array Validation

`ts
const emptyOrder: Order = {
id: "1",
orderItems: [], // Fails arrayMinLen
};

const validator = new Validator();
const result = validator.validate(emptyOrder, orderRule);
`

The above validation results error structure:

`ts
{
message: "Validation failed. Please check and fix the errors to continue.",
isValid: false,
errors: {
orderItems: {
arrayErrors: [
{
errorMessage: "The minimum length for this field is 1.",
attemptedValue: [],
ruleName: "arrayMinLen"
}
]
}
}
}
`

2. Invalid Items Validation

`ts
const invalidItemsOrder: Order = {
id: "1",
orderItems: [
{
productId: 1, // Valid
quantity: 0, // Fails minNumber
},
],
};
`

The above validation results the following error structure

`ts
{
message: "Validation failed. Please check and fix the errors to continue.",
isValid: false,
errors: {
orderItems: {
arrayElementErrors: [
{
index: 0,
attemptedValue: {
productId: 1,
quantity: 0
},
errors: {
quantity: [
{
errorMessage: "Min qty is 1.",
attemptedValue: 0,
ruleName: "minNumber"
}
]
}
}
]
}
}
}
`

$3

✅ Dual-Level Validation

- arrayRules: Validate the array itself (length, required, etc.). Array level error is represented in the errors property
- arrayElementRule: Validate each item's structure. Array item error is represented in the arrayElementErrors property.

✅ Precise Error Reporting

- Clear distinction between array-level and item-level errors
- Includes index references for invalid items
- Errors are structured by index, so you know which item failed and why.

✅ Type-Safe Nesting

- Item rules maintain full type checking against the item type
- Works with any depth of nested arrays
- Dont worry if your property names or data structure change, TypeScript (and your editor) will catch it instantly

❌ No confusing string paths like "orderItems[0].quantity"

- Good luck debugging when property names change, or when you're trying to trace validation errors in deeply nested structures.
- Binding errors back to your UI? Prepare for brittle code and guesswork.

⚠️ Error Structure Breakdown

The error is separated into 2 models

- Object Error
- Array error

$3

Object error is represented by:

`ts
export type ErrorOf = {
[key in keyof T]?: T[key] extends Date
? RuleViolation[]
: T[key] extends PossiblyUndefined>
? ErrorOfArray
: T[key] extends PossiblyUndefined