@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