@th3hero/request-validator

🚀 The Ultimate Request Validation Library for Node.js - Lightweight, fast, and feature-rich validation with TypeScript support. Perfect for Express, Next.js, Fastify, and any Node.js framework.

Why choose @th3hero/request-validator?

✅ Zero External Dependencies - No bloat, just pure validation power
✅ 20+ Built-in Rules - From basic validation to complex database checks
✅ TypeScript First - Full type safety and IntelliSense support
✅ Framework Agnostic - Works with Express, Next.js, Fastify, Koa, and more
✅ Database Integration - Built-in MySQL support for unique/exists validation
✅ File Upload Validation - Secure file validation with MIME type checking
✅ Async Support - Handle complex validation scenarios
✅ High Performance - Optimized for speed and efficiency

📋 Table of Contents

• Features
• Installation
• Quick Start
• Validation Rules
• Database Integration
• File Upload Validation
• Custom Validation Rules
• Error Handling
• TypeScript Support
• Best Practices
• Contributing
• Testing
• License

✨ Features

• 🚀 Simple Function-Based API: Easy to use with a clean, intuitive interface
• 🔍 Comprehensive Validation Rules: Over 20 built-in validation rules
• 🎯 Database Integration: Built-in support for unique/exists validations with MySQL
• 📁 File Upload Validation: Support for file uploads with MIME type checking
• 🧪 Extensive Test Coverage: Thoroughly tested with Jest (90%+ coverage)
• ⚡️ High Performance: Optimized for speed and efficiency
• 🔒 Secure by Default: Built-in security features
• 📝 TypeScript Support: Full TypeScript support with type definitions
• 🔄 Async Validation: Support for asynchronous validation rules
• 🎨 Customizable: Easy to extend with custom validation rules
• 🛠️ Zero External Validation Dependencies: Custom-built validation functions
• 🌐 Framework Agnostic: Works with Express, Next.js, Fastify, Koa, and more

🚀 Installation

# Using npm
npm install @th3hero/request-validator

# Using yarn
yarn add @th3hero/request-validator

# Using pnpm
pnpm add @th3hero/request-validator

📦 Dependencies

This library has the following dependencies:

Core Dependencies

• express (^4.18.2) - For request handling and types

Optional Dependencies

• mysql (^2.18.1) - For database validations (only required if using database validation rules)

Development Dependencies

• TypeScript and related type definitions
• Jest for testing
• Various type definitions for better TypeScript support

Note: While the library has these dependencies, they are only required if you use the specific features that need them. For example:

• MySQL is only required if you use database validation rules (unique/exists)
• Express is only required if you're using it in an Express.js application

⚡ Quick Start

Basic Usage

import { validateInput } from '@th3hero/request-validator';
import { Request } from 'express';

// Define validation rules
const rules = {
    username: 'required|min:3|max:15',
    email: 'required|email|unique:users,email',
    password: 'required|min:8',
    age: 'integer|min:18',
    status: 'in:active,inactive,pending'
};

// Validate request
app.post('/users', async (req: Request, res) => {
    const result = await validateInput(req, rules);
    
    if (result.failed) {
        return res.status(400).json({ errors: result.errors });
    }
    
    // Process valid request...
});

With File Upload

🆚 Why Choose @th3hero/request-validator?

Feature	@th3hero/request-validator	Joi	Yup	express-validator
Bundle Size	🟢 ~15KB	🟡 ~200KB	🟡 ~150KB	🟡 ~100KB
Zero Dependencies	✅ Yes	❌ No	❌ No	❌ No
TypeScript Support	✅ First-class	✅ Good	✅ Good	❌ Limited
Database Integration	✅ Built-in	❌ No	❌ No	❌ No
File Upload Validation	✅ Built-in	❌ No	❌ No	✅ Yes
Async Validation	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Custom Validators	✅ Easy	✅ Complex	✅ Complex	✅ Complex
Framework Agnostic	✅ Yes	✅ Yes	✅ Yes	❌ Express only
Learning Curve	🟢 Simple	🟡 Medium	🟡 Medium	🟡 Medium
Performance	🟢 Fast	🟡 Good	🟡 Good	🟡 Good

Key Advantages:

• 🚀 Zero External Dependencies: No bloat, just pure validation power
• 📦 Lightweight: Only ~15KB vs 100-200KB for alternatives
• 🔧 Database Ready: Built-in MySQL support for unique/exists validation
• 📁 File Upload Support: Secure file validation with MIME type checking
• 🎯 Framework Agnostic: Works with Express, Next.js, Fastify, Koa, and more
• ⚡ High Performance: Optimized for speed and efficiency
• 🛡️ Security First: Built-in security features and sanitization

📋 Validation Rules

Basic Rules

Rule	Description	Example	Error Message
required	Field must be present and not empty	username: 'required'	"username is required"
nullable	Field can be null or undefined	middle_name: 'nullable'	-
not-empty	Field cannot be empty	description: 'not-empty'	"description cannot be empty"
numeric	Field must be a number	age: 'numeric'	"age must be a number"
confirmed	Field must have a matching confirmation field	password: 'confirmed'	"password must be confirmed"
digits:length	Field must contain exactly the specified number of digits	phone: 'digits:10'	"phone must be exactly 10 digits"

String Rules

Rule	Description	Example	Error Message
min:length	Minimum string length	username: 'min:3'	"username must be at least 3 characters long"
max:length	Maximum string length	username: 'max:15'	"username must not exceed 15 characters"
string	Must be a string	note: 'string'	"note must be a string"
alpha	Must contain only letters	name: 'alpha'	"name must contain only letters"
alphanumeric	Must contain only letters and numbers	username: 'alphanumeric'	"username must contain only letters and numbers"
regex:/pattern/	Must match the regular expression	username: 'regex:/^[a-z0-9-]+$/'	"username format is invalid"

Type Rules

Rule	Description	Example	Error Message
email	Valid email address	email: 'email'	"Invalid email address for email"
integer	Must be an integer	age: 'integer'	"age must be an integer"
boolean	Must be a boolean	active: 'boolean'	"active must be a boolean"
date:format	Valid date with format	birth_date: 'date:YYYY-MM-DD'	"birth_date must be a valid date with format YYYY-MM-DD"
url	Must be a valid URL	website: 'url'	"website must be a valid URL"
array	Must be an array	tags: 'array'	"tags must be an array"
object	Must be an object	settings: 'object'	"settings must be an object"

File Rules

Rule	Description	Example	Error Message
file	Must be a file upload	profile_picture: 'file'	"profile_picture is required"
mimetype:types	Valid MIME types	avatar: 'mimetype:image/jpeg,image/png'	"Invalid file format for avatar. Supported media types are image/jpeg, image/png"
max_size:size	File size must not exceed the specified size	avatar: 'max_size:2048'	"avatar file size must not exceed 2048 bytes"

Database Rules

Rule	Description	Example	Error Message
unique:table,column	Must be unique in database	email: 'unique:users,email'	"email already exists"
exists:table,column	Must exist in database	user_id: 'exists:users,id'	"user_id does not exist"

Enum Rules

Rule	Description	Example	Error Message
in:values	Must be one of the values	status: 'in:active,inactive,pending'	"status must be one of the following values: active, inactive, pending"

Conditional Rules

Rule	Description	Example	Error Message
required_if:field,value	Required if field equals value	spouse_name: 'required_if:marital_status,married'	"spouse_name is required when marital_status is married"

Database Integration

The library provides optional database validation rules that require MySQL. To use these features:

1. Install MySQL:

npm install mysql

2. Set up the database connection:

import { setDatabase } from '@th3hero/request-validator';
import mysql from 'mysql';

const pool = mysql.createPool({
    host: 'localhost',
    user: 'your_username',
    password: 'your_password',
    database: 'your_database'
});

setDatabase(pool);

If you try to use database validation rules without setting up the database connection, the library will throw an error with a helpful message.

File Upload Validation

Basic File Upload

const rules = {
    avatar: 'file|mimetype:image/jpeg,image/png'
};

app.post('/upload', async (req: Request, res) => {
    const result = await validateInput(req, rules);
    
    if (result.failed) {
        return res.status(400).json({ errors: result.errors });
    }
    
    // Process valid file upload...
});

Multiple Files

const rules = {
    documents: 'file|mimetype:application/pdf'
};

app.post('/upload-documents', async (req: Request, res) => {
    const result = await validateInput(req, rules);
    
    if (result.failed) {
        return res.status(400).json({ errors: result.errors });
    }
    
    // Process valid file uploads...
});

Custom Validation Rules

Define Custom Validator

const customValidators = {
    isFortyTwo: (value: any) => value === 42 || 'Value must be 42',
    isAdult: (value: any) => {
        const age = parseInt(value);
        return age >= 18 || 'Must be at least 18 years old';
    }
};

const req = {
    body: { value: 42, age: 20 },
    customValidators
};

Use Custom Validator

const rules = {
    value: 'isFortyTwo',
    age: 'isAdult'
};

app.post('/validate', async (req: Request, res) => {
    const result = await validateInput(req, rules);
    
    if (result.failed) {
        return res.status(400).json({ errors: result.errors });
    }
    
    // Process valid request...
});

Error Handling

Basic Error Handling

const result = await validateInput(req, rules);

if (result.failed) {
    return res.status(400).json({ errors: result.errors });
}

Custom Error Handling

try {
    const result = await validateInput(req, rules);
    
    if (result.failed) {
        // Log validation errors
        console.error('Validation failed:', result.errors);
        
        // Return custom error response
        return res.status(400).json({
            success: false,
            message: 'Validation failed',
            errors: result.errors
        });
    }
    
    // Process valid request...
} catch (error) {
    // Handle unexpected errors
    console.error('Validation error:', error);
    return res.status(500).json({
        success: false,
        message: 'Internal server error'
    });
}

TypeScript Support

Type Definitions

import { Request } from 'express';
import { ValidationRules, ValidationResult } from '@th3hero/request-validator';

interface UserRequest extends Request {
    body: {
        username: string;
        email: string;
        password: string;
    };
    files?: {
        avatar?: Express.Multer.File[];
    };
}

const rules: ValidationRules = {
    username: 'required|min:3',
    email: 'required|email',
    password: 'required|min:8',
    avatar: 'file|mimetype:image/jpeg,image/png'
};

app.post('/users', async (req: UserRequest, res) => {
    const result: ValidationResult = await validateInput(req, rules);
    
    if (result.failed) {
        return res.status(400).json({ errors: result.errors });
    }
    
    // Process valid request...
});

🎯 Best Practices

1. Always Validate Input

   // Good
   app.post('/users', async (req, res) => {
       const result = await validateInput(req, rules);
       if (result.failed) return res.status(400).json({ errors: result.errors });
       // Process request...
   });
   
   // Bad
   app.post('/users', async (req, res) => {
       // Process request without validation...
   });

2. Use Specific Rules

   // Good
   const rules = {
       email: 'required|email|unique:users,email',
       password: 'required|min:8|max:20'
   };
   
   // Bad
   const rules = {
       email: 'required',
       password: 'required'
   };

3. Handle File Uploads Properly

   // Good
   const rules = {
       avatar: 'file|mimetype:image/jpeg,image/png'
   };
   
   // Bad
   const rules = {
       avatar: 'file'
   };

4. Use Custom Validators for Complex Rules

   // Good
   const customValidators = {
       isAdult: (value) => parseInt(value) >= 18 || 'Must be at least 18 years old'
   };
   
   // Bad
   const rules = {
       age: 'integer|min:18' // Less flexible
   };

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🧪 Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ Support the Project

If you find this library helpful, please consider:

• ⭐ Star the repository on GitHub
• 📦 Use it in your projects and spread the word
• 🐛 Report bugs or suggest features
• 💡 Contribute code or documentation
• ☕ Buy me a coffee if you want to support development

---

Made with ❤️ by Alok Kumar