CPF: Cadastro de Pessoas Físicas - FabioMarciano/validocs GitHub Wiki

CPF or Cadastro de Pessoas Físicas is a brazilian federal document required for natural persons.

The CPF is a number made of 11 digits. Nine (9) of them distributed in three (3) groups with three (3) digits each and a pair (2) of verifying digit. To test the document validity is necessary to make a mathematical operation to calculate the pair of verifying digits one by one.

Number mask

Normally (for better readability) the number is masked using two dots and a hyphen: xxx.xxx.xxx-xx.

The mask is not necessary to validate the number.

Fiscal Regions

The eight first CPF numbers are random values, the ninth number is a value between 0 and 9 that represents the fiscal region where the number was requested. There are ten (10) fiscal regions. Each fiscal region is composed of one or more states of the brazilian federation:

  • 0: RS
  • 1: DF, GO, MT, MS, TO
  • 2: AC, AP, AM, PA, RO, RR
  • 3: CE, MA, PI
  • 4: AL, PB, PE, RN
  • 5: BA, SE
  • 6: MG
  • 7: ES, RJ
  • 8: SP
  • 9: PR, SC

Usage

Importing

To import the CPF module you can:

import CPF from 'validocs/cpf';

Or:

import { CPF } from 'validocs';

You may also import it using the require syntax:

const CPF = require('validocs/cpf');

Or:

const { CPF } = require('validocs');

The Cpf type

In order to declare our Cpf variables and constants properly with typescript, we have to import the Cpf type and use it this way:

import CPF from 'validocs/cpf';

let cpf: CPF.Cpf;

Or import just the type:

import { Cpf } from 'validocs/cpf';

let cpf: Cpf;

Constants

There are some CPF related defined constants that could be used to help with validations, tests, conditions and whatever is needed:

FISCAL_REGION_DATA

It is a bi-dimensional array that stores all fiscal regions.

CPF.FISCAL_REGION_DATA

UNMASKED_FISCAL_REGION_DIGIT_INDEX

It is the index of position of the fiscal region digit on unmasked CPFs.

CPF.UNMASKED_FISCAL_REGION_DIGIT_INDEX

FORMATED_FISCAL_REGION_DIGIT_INDEX

It is the index of position of the fiscal region digit on formated CPFs.

CPF.FORMATED_FISCAL_REGION_DIGIT_INDEX

UNMASKED_LENGTH

The unmasked CPF length.

CPF.UNMASKED_LENGTH

FORMATED_LENGTH

The formated CPF length.

CPF.FORMATED_LENGTH

FiscalRegion

Is an enumerated list that stores all Cpf Fiscal Regions from 0 to 9 (FR0 ... FR9).

CPF.FiscalRegion.FR0
// Fiscal Region 0

CPF.FiscalRegion.FR1
// Fiscal Region 1

CPF.FiscalRegion.FR2
// Fiscal Region 2

...

CPF.FiscalRegion.FR9
// Fiscal Region 9

It can be used together the FISCAL_REGION_DATA constant:

console.log(CPF.FISCAL_REGION_DATA[CPF.FiscalRegion.FR8]);
// ['SP']

Functions

Format

Returns a well-formed Cpf number (Cpf string like type). The value to be formatted is a Cpf string like type with 1 to 11 characters because the function have the ability to mask it partially using the mask function.

format(cpf: Cpf): Cpf
Param Type Description Example
cpf Cpf The value to be formated '11111111111'

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.format('11111111111'));
// 111.111.111-11

Mask

Formats a given Cpf number (even partially). Use it in cases if need to gradually mask an incomplete number (e.g.: while user input). This function use to be slower than the format function.

mask(cpf: Cpf): Cpf
Param Type Description Example
cpf Cpf The value to be formated '11111111111'

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.mask('11111111111'));
// 111.111.111-11

console.log(CPF.mask('111111111'));
// 111.111.111

console.log(CPF.mask('1111111'));
// 111.111.1

console.log(CPF.mask('111'));
// 111

Unmask

Removes all non-digit characters of a given Cpf number (even partially). In other words is the opposite of the format and mask functions.

unmask(cpf: Cpf): Cpf
Param Type Description Example
cpf Cpf The value to be unmasked '111.111.111-11'

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.unmask('111.111.111-11'));
// 11111111111

console.log(CPF.unmask('111.111.1-'));
// 1111111

Sequence

Checks if the given Cpf number is made with repeated numbers (e.g.: 11111111111, 2222222222, ...).

sequence(cpf: Cpf): boolean
Param Type Description Example
cpf Cpf The value to be checked '111.111.111-11'

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.sequence('111.111.111-11'));
// true

console.log(CPF.sequence('222.222.222-22'));
// true

console.log(CPF.sequence('123.456.789-01'));
// false

Test

Tests if the given value is a valid Cpf number.

test(cpf: Cpf, { strict = false }: Options = {}): boolean
Param Type Required Description Example
cpf Cpf yes The value to be checked '111.111.111-11'
options Options no An object with options to be used on test { strict: true }
options.strict boolean no If true check if the Cpf number is well-formed. Default: false. { strict: true }

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.test('053.134.390-14'));
// true
// valid

console.log(CPF.test('05313439014'));
// true
// valid

console.log(CPF.test('053.134.390-14', { strict: true }));
// true
// valid and well-formed

console.log(CPF.test('05313439014', { strict: true }));
// false
// valid but not well-formed

console.log(CPF.test('222.222.222-22'));
// false
// invalid and well-formed

console.log(CPF.test('22222222222', { strict: true }));
// false
// invalid and not well-formed

Region

Returns the fiscal region of a given Cpf number or undefined if not valid (strict mode).

region(cpf: Cpf, { strict = false }: Options = {}): string | undefined
Param Type Required Description Example
cpf Cpf yes The value to be checked '111.111.111-11'
options Options no An object with options to be used on test { strict: true }
options.strict boolean no If true check if the Cpf number is valid. Default: false. { strict: true }

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.region('111.111.111-11'));
// DF, GO, MT, MS, TO

console.log(CPF.region('111.111.111-11', { strict: true }));
// undefined
// CPF number is not valid

Make

Returns a random and valid Cpf value.

make({ strict = true, fiscalRegion }: ExtendedOptions = {}): Cpf
Param Type Required Description Example
options Options no An object with options to be used on test { strict: true }
options.strict boolean no If true, formats the Cpf number. Default: true. { strict: false }
options.fiscalRegion CPF.FiscalRegion no Uses the given value to create the random Cpf number. { fiscalRegion: CPF.FiscalRegion.FR0 }

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.make({fiscalRegion: CPF.FiscalRegion.FR0}));
// 855.911.930-21

console.log(CPF.make({strict: false, fiscalRegion: CPF.FiscalRegion.FR0}));
// 85591193021

Digit

Returns the calculated digit value of a given Cpf base. The Cpf base could be a 9 (random) or 10 (valid) length, masked or not, string.

digit(base: string): number
Param Type Required Description Example
options Options no An object with options to be used on test { strict: true }
base string yes A 9 or 10 length number. '855.911.930'

Example:

import { CPF } from 'validocs/cpf';

console.log(CPF.digit('855.911.930'));
// 2

console.log(CPF.digit('855.911.930-2'));
// 1