@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?

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

String Rules

Type Rules

File Rules

Database Rules

Enum Rules

Conditional Rules

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: `typescript 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

```typescript
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

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.1.8] - 2025-10-05

Added

• Enhanced package description with emojis and key benefits
• Expanded keywords list (30+ targeted terms) for better discoverability
• Added comprehensive examples documentation (EXAMPLES.md)
• Created detailed documentation structure (docs/README.md)
• Added comparison table vs competitors (Joi, Yup, express-validator)
• Enhanced README with better visual hierarchy and badges
• Added GitHub profile README to showcase the package
• Improved package.json metadata (author details, funding, maintainers)

Changed

• Updated package description for better SEO and marketing
• Enhanced README with "Why choose" section highlighting unique advantages
• Added social links and sponsorship options
• Improved competitive positioning and feature comparison

[1.1.7] - 2024-06-14

Changed

• Updated package configuration for dual registry publishing
• Enhanced GitHub Actions workflows
• Improved NPM publishing with provenance

[1.1.6] - 2024-06-14

Changed

• Fixed workflow authentication issues
• Updated package configuration

[1.1.5] - 2024-06-14

Changed

• Added GitHub Packages publishing support
• Updated repository configuration

[1.1.4] - 2024-06-14

Changed

• Updated package.json configuration
• Fixed repository URL format

[1.1.0] - 2024-03-19

Added

• Optional MySQL dependency for database validations
• Custom validation rules support
• File upload validation with MIME type checking
• Comprehensive test coverage
• TypeScript type definitions
• Documentation improvements

Changed

• Made MySQL an optional dependency
• Improved error messages
• Enhanced validation rules
• Better TypeScript configuration
• Stricter type checking

Fixed

• File cleanup error handling
• Database validation error handling
• Type definitions for custom validators

[1.0.0] - 2024-03-19

Added

• Initial release
• Basic validation rules
• Express request validation
• TypeScript support
• MySQL database validation
• File upload validation
• Custom validation support