@gfinnovation/br-validations

@gfinnovation/br-validations

TypeScript utilities for validating, formatting, cleaning, and transforming Brazilian CPF and CNPJ documents.

The package supports:

• Individual and Unified CPF/CNPJ validation
• Individual and Unified CPF/CNPJ formatting
• Individual and Unified CPF/CNPJ cleaning
• Alphanumeric CNPJ validation
• class-validator decorator for CPF/CNPJ validation
• class-transformer decorator for automatic CPF/CNPJ normalization
• TypeScript support
• ESM and CommonJS builds

---

Installation

npm install @gfinnovation/br-validations

If you use decorators with class-validator or class-transformer, also install:

npm install class-validator class-transformer reflect-metadata

NestJS Integration (v11.0.0)

If you are using this package inside a NestJS (v11.0.0) project, ensure you have the core common utilities installed:

# npm
npm i @nestjs/common@^11.0.0

# yarn
yarn add @nestjs/common@^11.0.0

# pnpm
pnpm add @nestjs/common@^11.0.0

And import metadata once in your application entrypoint:

import 'reflect-metadata';

---

Features

Feature	Supported
Validate CPF
Validate CNPJ
Validate Alphanumeric CNPJ
Unified Validate (CPF/CNPJ)
Format CPF
Format CNPJ
Unified Format (CPF/CNPJ)
Clean CPF
Clean CNPJ
Unified Clean (CPF/CNPJ)
Concat CPF (padStart)
Concat CNPJ (padStart)
Unified Concat (CPF/CNPJ)
Mask CPF
Mask CNPJ
Unified Mask (CPF/CNPJ)
NestJS v11.0.0 compatible
class-validator decorator
class-transformer decorator
TypeScript support

---

Importing

import {
  // CPF Utilities
  validateCPF,
  formatCPF,
  cleanCPF,
  concatCpf,
  maskCpf,

  // CNPJ Utilities
  validateCNPJ,
  formatCNPJ,
  cleanCNPJ,
  concatCnpj,
  maskCnpj,

  // Unified Utilities (CPF or CNPJ)
  cpfCnpjValidate,
  cpfCnpjFormat,
  cpfCnpjClean,
  cpfCnpjConcat,
  cpfCnpjMask,

  // Decorators
  IsCpfCnpjValid,
  CpfCnpjTransform,
} from '@gfinnovation/br-validations';

---

Unified Utilities (CPF / CNPJ)

These functions dynamically detect whether the input is a CPF or CNPJ and apply the corresponding logic.

cpfCnpjValidate

Validates either a CPF or a CNPJ (including alphanumeric CNPJ).

import { cpfCnpjValidate } from '@gfinnovation/br-validations';

cpfCnpjValidate('589.831.040-15'); // true (CPF)
cpfCnpjValidate('12.345.678/0001-95'); // true (CNPJ)
cpfCnpjValidate('invalid-value'); // false

---

cpfCnpjFormat

Formats a raw string into a standard CPF or CNPJ mask based on length.

import { cpfCnpjFormat } from '@gfinnovation/br-validations';

cpfCnpjFormat('12345678900'); // 123.456.789-00
cpfCnpjFormat('12345678000195'); // 12.345.678/0001-95

---

cpfCnpjClean

Removes punctuation and symbols from both CPF and CNPJ formatted strings.

import { cpfCnpjClean } from '@gfinnovation/br-validations';

cpfCnpjClean('123.456.789-00'); // 12345678900
cpfCnpjClean('12.345.678/0001-95'); // 12345678000195

---

---

cpfCnpjConcat

Attempts to determine whether the input represents a CPF or CNPJ.

• Adds leading zeros to numeric CPF/CNPJ values.
• Supports alphanumeric CNPJ.
• Throws an error if the value cannot be converted into a valid CPF or CNPJ.
• Throws an error if the value is ambiguous and could represent both.

import { cpfCnpjConcat } from '@gfinnovation/br-validations';

cpfCnpjConcat('1234567890');
cpfCnpjConcat('12345678000195');
cpfCnpjConcat('11ANEA76000175');

---

cpfCnpjMask

import { cpfCnpjMask } from '@gfinnovation/br-validations';

cpfCnpjMask('58983104015');
cpfCnpjMask('12345678000195');

CPF Specific Utilities

validateCPF

import { validateCPF } from '@gfinnovation/br-validations';

validateCPF('589.831.040-15'); // true
validateCPF('123.456.789-00'); // false

formatCPF

import { formatCPF } from '@gfinnovation/br-validations';

formatCPF('12345678900'); // 123.456.789-00

cleanCPF

import { cleanCPF } from '@gfinnovation/br-validations';

cleanCPF('123.456.789-00'); // 12345678900

concatCpf

import { concatCpf } from '@gfinnovation/br-validations';

concatCpf('12345'); // 00000012345

maskCpf

import { maskCpf } from '@gfinnovation/br-validations';

maskCpf('58983104015'); // 589.***.***-15

---

CNPJ Specific Utilities

validateCNPJ

Supports numeric, alphanumeric, and formatted variants.

import { validateCNPJ } from '@gfinnovation/br-validations';

validateCNPJ('12.345.678/0001-95'); // true
validateCNPJ('11.ANE.A76/0001-75'); // true

formatCNPJ

import { formatCNPJ } from '@gfinnovation/br-validations';

formatCNPJ('12345678000195'); // 12.345.678/0001-95
formatCNPJ('11ANEA76000175'); // 11.ANE.A76/0001-75

cleanCNPJ

import { cleanCNPJ } from '@gfinnovation/br-validations';

cleanCNPJ('11.ANE.A76/0001-75'); // 11ANEA76000175

concatCnpj

import { concatCnpj } from '@gfinnovation/br-validations';

concatCnpj('12345'); // 00000000012345
concatCnpj('11ANEA76000175'); // 11ANEA76000175

maskCnpj

import { maskCnpj } from '@gfinnovation/br-validations';

maskCnpj('12345678000195'); // 12.***.***/**01-95

---

class-validator Decorator

IsCpfCnpjValid

Decorator for validating CPF or CNPJ fields inside DTOs.

import { IsCpfCnpjValid } from '@gfinnovation/br-validations';

class CreateUserDto {
  @IsCpfCnpjValid()
  document: string;
}

---

class-transformer Decorator

CpfCnpjTransform

Automatically pads and transforms CPF or CNPJ values during data instantiation.

import 'reflect-metadata';
import { CpfCnpjTransform } from '@gfinnovation/br-validations';

class PaymentDto {
  tpPessoaPagdr: string;

  @CpfCnpjTransform()
  documento: string;
}

---

NestJS Example

Combines @nestjs/common decorators with @gfinnovation/br-validations for data transfer objects (DTOs) and automatic payload validation/transformation:

import { Controller, Post, Body, UsePipes, ValidationPipe } from '@nestjs/common';
import { IsCpfCnpjValid, CpfCnpjTransform } from '@gfinnovation/br-validations';

export class CreateUserDto {
  tpPessoaPagdr: string;

  @CpfCnpjTransform()
  @IsCpfCnpjValid()
  documento: string;
}

@Controller('users')
export class UsersController {
  @Post()
  @UsePipes(new ValidationPipe({ transform: true }))
  create(@Body() createUserDto: CreateUserDto) {
    return {
      message: 'User validated and formatted successfully',
      data: createUserDto,
    };
  }
}

---

NestJS Pipe Example

This package does not provide a NestJS pipe implementation.

If you need to normalize and validate route parameters, create a custom pipe using the validation functions exported by this package.

import {
  ArgumentMetadata,
  BadRequestException,
  Injectable,
  PipeTransform,
} from '@nestjs/common';

import {
  validateCPF,
  validateCNPJ,
  cpfCnpjClean,
} from '@gfinnovation/br-validations';

@Injectable()
export class CpfCnpjPipeTransform implements PipeTransform {
  transform(
    value: string | number | null | undefined,
    metadata: ArgumentMetadata,
  ): string {
    if (value == null) {
      throw new BadRequestException('CPF/CNPJ is required');
    }

    value = cpfCnpjClean(String(value).trim().toUpperCase());

    const isNumeric = /^\d+$/.test(value);

    const normalized = isNumeric
      ? value.length <= 11
        ? value.padStart(11, '0')
        : value.padStart(14, '0')
      : value;

    if (normalized.length === 11 && !validateCPF(normalized)) {
      throw new BadRequestException('Invalid CPF');
    }

    if (normalized.length === 14 && !validateCNPJ(normalized)) {
      throw new BadRequestException('Invalid CNPJ');
    }

    return normalized;
  }
}

Usage:

@Get(':document')
findByDocument(
  @Param('document', CpfCnpjPipeTransform)
  document: string,
) {
  return document;
}

---

Build

npm run build

---

Test

npm test

---

TypeScript Configuration

If you use decorators, enable the following in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

---

Troubleshooting & pnpm Support

Because pnpm handles nested node_modules strictly using hard links, it will not automatically resolve optional peer dependencies required by `decorators unless they are explicitly installed in the root project.

Missing Peer Dependencies Error

If you use @IsCpfCnpjValid or @CpfCnpjTransform and experience runtime errors or type failures using pnpm, verify you have installed the required validation peer dependencies:

pnpm add class-validator class-transformer reflect-metadata

Decorator Metadata Issues

If NestJS fails to inject or read your DTO types during request validation, ensure your .npmrc or project configurations do not strictly isolate the metadata context, and that reflect-metadata is imported at the very top of your application entry point (main.ts):

import 'reflect-metadata'; // Must be the first line
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

---

License

ISC