kr-validators

Custom validation decorators for Korean-specific data such as resident IDs, phone numbers, business numbers, card numbers, emails, and postal codes.
This library is designed to work seamlessly with NestJS and class-validator for a clean, reusable validation process.

Features

• Resident ID Validator: Validate Korean resident identification numbers.
• Phone Number Validator: Validate Korean phone numbers.
• Business Number Validator: Validate Korean business registration numbers.
• Email Validator: Validate email addresses.
• Postal Code Validator: Validate Korean postal codes.
• Lightweight and optimized for NestJS applications.
• Fully compatible with class-validator.

Installation

Install the package via NPM:

npm install kr-validators

Usage

NestJS Integration Example

1. Import and apply the decorators in your DTO

import {
  IsEmail,
  IsPhoneNumber,
  IsResidentIDNumber,
  IsBusinessNumber,
  IsPostalCode,
} from 'kr-validators';

export class CreateUserDto {
  @IsEmail({ message: '유효한 이메일 주소를 입력해주세요.' })
  email: string;

  @IsPhoneNumber({ message: '유효하지 않은 전화번호입니다.' })
  phone: string;

  @IsResidentIDNumber({ message: '유효하지 않은 주민등록번호입니다.' })
  residentId: string;

  @IsBusinessNumber({ message: '유효하지 않은 사업자등록번호입니다.' })
  businessNumber: string;

  @IsPostalCode({ message: '유효하지 않은 우편번호입니다.' })
  postalCode: string;
}

2. Apply the DTO in your controller

Use the CreateUserDto in your NestJS controller to validate incoming request data automatically.

import { Body, Controller, Post } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('users')
export class UserController {
  @Post()
  createUser(@Body() createUserDto: CreateUserDto) {
    // The validation is automatically triggered when the request data is bound to the DTO.
    return { message: 'User created successfully', data: createUserDto };
  }
}

In this example:

• Automatic Validation: The CreateUserDto class is automatically validated when the request body is bound to it.
  NestJS's built-in ValidationPipe triggers the validation process without requiring manual checks.

• Error Handling: If the incoming data fails validation, a 400 Bad Request response is returned automatically with detailed error messages.

• Successful Requests: If the data passes validation, the createUser method is executed, and the validated data is returned in the response.

Example Scenarios

Invalid Request Body

{
  "email": "not-an-email",
  "phone": "123",
  "residentId": "123456",
  "businessNumber": "12345",
  "postalCode": "123"
}

Invalid Response

If the incoming data fails validation, the API will return a 400 Bad Request response with detailed error messages for each invalid field.

{
  "statusCode": 400,
  "message": [
    "유효한 이메일 주소를 입력해주세요.",
    "유효하지 않은 전화번호입니다.",
    "유효하지 않은 주민등록번호입니다.",
    "유효하지 않은 사업자등록번호입니다.",
    "유효하지 않은 우편번호입니다."
  ],
  "error": "Bad Request"
}

Each error message corresponds to the field that failed validation, making it easy to identify and correct issues in the request payload.

Valid Request Body

{
  "email": "[email protected]",
  "phone": "010-1234-5678",
  "residentId": "9201011234567",
  "businessNumber": "1234567890",
  "postalCode": "06236"
}

Successful Response

{
  "message": "User created successfully",
  "data": {
    "email": "[email protected]",
    "phone": "010-1234-5678",
    "residentId": "9201011234567",
    "businessNumber": "1234567890",
    "postalCode": "06236"
  }
}

This shows how custom validators integrate seamlessly into a NestJS controller. By defining validations in DTOs, you ensure that incoming data is always consistent and secure before reaching your application logic.

Validation Rules

1. Resident ID Validator:

   • Must be 13 digits.
   • Luhn algorithm-based checksum validation.

2. Phone Number Validator:

   • Formats: 010-1234-5678, 01012345678.

3. Business Number Validator:

   • 10-digit Korean business registration number.

4. Email Validator:

   • Standard email format validation.

5. Postal Code Validator:

   • Validates Korean postal codes (5-digit).

API Reference

1. @IsEmail(validationOptions?: ValidationOptions)

Validates the email address.

2. @IsPhoneNumber(validationOptions?: ValidationOptions)

Validates the phone number in Korean formats.

3. @IsResidentIdNumber(validationOptions?: ValidationOptions)

Validates a Korean resident ID number.

4. @IsBusinessNumber(validationOptions?: ValidationOptions)

Validates a Korean business registration number.

5. @IsPostalCode(validationOptions?: ValidationOptions)

Validates a Korean postal code.

Contributing

We welcome contributions! Please follow these steps:

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

License

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

Author

Created by hoonapps.
Visit the GitHub Repository for more projects.

Need help?

Feel free to reach out at [email protected] or create an issue in the repository!