brazilian-values, the Brazilian formatting and validation helpers, and where their limits are

Brazilian formatting and validation as a set of importable functions

brazilian-values is a small TypeScript library with one job: formatting and validating the values that Brazilian software has to deal with. The project description names the range, money in BRL, CPF, CNPJ, CEP, RG, CAEPF, phone numbers, dates and plain numbers, and the API listing in the documentation is organised into three groups of functions, formatters, converters and validators.

The formatters group contains formatToBRL, formatToCapitalized, formatToCEP, formatToCNPJ, formatToCAEPF, formatToCPF, formatToCPFOrCNPJ, formatToDate, formatToDateTime, formatToList, formatToNumber, formatToPhone, formatToRG and formatToHiddenDigits. The converters group is much smaller, parseToArray, parseToDate and parseToNumber. The validators group holds isCEP, isCNPJ, isCAEPF, isCPF, isCPFOrCNPJ, isDate, isDDD and isPhone.

The important design decision is that these are plain functions rather than classes, and that they take and return strings and numbers in the shapes your code already has. There is no document object, no locale object to configure, and no per-validator option object. For a checkout form or an invoicing screen, that means the import is the whole integration.

The licence is MIT, the current version is 0.14.1, and the last push was on 2026-09-21 with the 0.14.1 tag on the same day. The 0.14.0 release came on 2026-07-23 and 0.13.1 on 2025-06-20, so the release cadence has tightened considerably over the last year.

Installing from npm, yarn, or a CDN script tag

The package is published to npm, so installation is a normal dependency add:

bash npm install brazilian-values --save

or with yarn:

bash yarn add brazilian-values

For a page that does not have a bundler, the same code is available on the JSDelivr and UNPKG CDNs, and the documentation notes that on both you can request the package you want or take the default, which is the UMD build. The manifest confirms the arrangement with separate cdn, unpkg and jsdelivr fields all pointing at the minified UMD bundle.

The UMD build exposes the library as a single global object named BrazilianValues, and the documented usage shows a currency format call on it:

  BrazilianValues.formatToBRL(100);
  //=> 'R$ 100,00'

That global name is worth noting if you have more than one script on a page, and it is the reason the ES module entry point is the better choice for anything with a build step.

The published files are limited to the dist and types directories, and the manifest marks sideEffects as false, which tells a bundler it may drop the module entirely if nothing from it is used. Combined with the fact that every export is an individual named function, that means a build only carries the helpers you actually import.

A validator and a formatter used together on a CNPJ

The documented usage pattern is short and is worth copying exactly, because the order matters. You import the two functions you need, check the value, then format it:

js import { isCNPJ, formatToCNPJ } from 'brazilian-values';

const value = '12727442000113'

if (!isCNPJ(value)) throw new Error('CNPJ is not valid.'); const document = formatToCNPJ(value); //=> '12.727.442/0001-13'

So a raw string of digits goes in, isCNPJ decides whether it is a valid company identifier, and formatToCNPJ returns the masked form. If the value fails the check, the example throws before the formatting call ever happens.

The formatter is written to be forgiving about its input, which is what makes it usable on partially typed form fields. The documentation for formatToCNPJ shows three cases: a short numeric string, a full fourteen digit CNPJ, and a string that already contains the punctuation characters. All three end up masked consistently.

js formatToCNPJ('32284981000138') //=> '32.284.981/0001-38'

Notice that the third case strips the existing separators and reapplies them, so formatting an already formatted value is idempotent rather than doubling up the dots and slashes. That property is worth testing for in your own usage, because it is what allows a formatting function to sit in a render path that runs on every keystroke without corrupting the value.

The same shape holds for CPF, and formatToCPFOrCNPJ exists for the common case where a single field accepts either document type and the format is decided by the number of characters.

Currency and number formatting, including the negative sign placement

The BRL formatter is where the Brazilian conventions are most visible, and the documented examples show the details rather than the summary.

js formatToBRL(1928.93) //=> 'R$ 1.928,93'

formatToBRL('9211928.18203') //=> 'R$ 9.211.928,18'

formatToBRL(-18.49) //=> 'R$ -18,49'

Three things are visible there. The thousands separator is a dot and the decimal separator is a comma, which is the reverse of the English convention, and the currency prefix is the R$ symbol with a space. The third example shows that a negative value keeps the minus sign between the symbol and the digits, giving R$ -18,49, rather than putting it in front of the symbol.

The formatter accepts both a number and a string that contains a number, and the second example shows it truncating the extra decimals rather than rounding them, since 9211928.18203 comes back as R$ 9.211.928,18.

formatToNumber is the same number formatting without the currency symbol, and its documented cases include zero, a negative value, a leading-dot fraction written as .981, and a numeric string. That last group matters for form handling, where a value typed by a user arrives as a string and has to be displayed consistently with the values that came from the database as numbers.

The documentation also warns that formatToRG currently supports only the SP and RJ formats, and that other states are only escaped in the input. That is an honest limitation to design around if you handle identity documents from other Brazilian states.

Where brazilian-values is the wrong tool

The first wrong case is validation that depends on an external source of truth. These validators check the structure and the check digits of a CPF, CNPJ or CEP. They do not consult any registry, so a well formed number that was never issued passes every check. If your requirement is to know whether a document exists, this library is the wrong tool and you need a registry service, with its own latency, cost and failure modes.

The second wrong case is a language or locale strategy with more than Brazil in it. The library is Brazilian specific by design. If your product serves several countries, the right architecture is a per-country formatting layer that this library can implement one country of, not a single import at the top of your application.

The third wrong case is server side rendering of currency in a system where the server and the browser may disagree about locale. The functions take a value and a fixed convention, with no locale parameter, so a single number formatted on the server and on the client is consistent. That is a virtue. It is also a limit if you need the same code to produce en-US output for one audience and pt-BR output for another, because there is no option to switch.

The fourth wrong case is a project that needs a specific state of RG that is not SP or RJ, or a CAEPF layout different from the one shown.

The fifth wrong case is expecting a maintained major version. The version is 0.14.1, and the 0.x series carries no stability promise about its public API. The function list in the documentation is the contract to check against when you upgrade, not the semver number.

The build and test setup behind a zero dependency library

The manifest is worth reading even if you never open the source, because it describes what the package guarantees and how it is produced.

The runtime dependency list is empty. Everything in the package is implemented in the library itself, with no third party runtime dependency to keep in step with your project. The devDependencies are the build and test toolchain: ava as the test runner, bili as the bundler, rollup-plugin-typescript2 to compile the TypeScript, ts-node and typescript itself.

The scripts section shows how that toolchain is used. The build script is bili. The test script runs the type tests and then the unit tests in sequence, with test:types executing tsc against tsconfig.build.json with noEmit, and test:unit running ava. The prepublishOnly script runs the full test suite and the build before publishing, which means a published version has passed both the type check and the unit tests.

The test directory and the ava.config.js file at the top level confirm ava is where the assertions live, and tsconfig.json and tsconfig.build.json separate the development configuration from the one used for the published build.

There is also a Dockerfile in the repository, and its shape is minimal. It starts from node:12-alpine, sets a working directory, copies the package manifests, installs bash and updates the package index, runs yarn install, copies the rest of the source, and installs the package into that image with yarn add. It is a self-contained environment for the library rather than a published image, and the node:12 base is the one number in the repository that a current project should not copy without checking.

Alternative approaches: a formatting library, or the platform

The realistic alternatives to this library are two, and they differ in where the Brazilian conventions live.

The first is a general purpose internationalisation library, where you configure a locale and call its formatting and parsing functions. The difference in approach is that the locale data comes from the internationalisation library, which means the Brazilian rules are one configuration among many, and the library carries much more than the rules you need. The difference in outcome is that such a library can format the same number in several currencies and locales, where brazilian-values can only produce Brazilian output, but it also brings its own locale data versions, its own bundle weight and its own API to learn.

The second alternative is doing it by hand, with regular expressions or the Intl built into the runtime. The difference in approach is that the rules live in your codebase rather than in a dependency, so nothing to install and nothing to update. The difference in outcome is that you now own the check digit algorithm for CPF and CNPJ, the CEP mask, the BRL rounding behaviour, and every future rule change, and the documentation is your own.

The case for a dedicated library like this one is that the rules are fiddly and specific. CPF and CNPJ use check digits, CAEPF has its own layout, RG differs by state, phone numbers change shape with the number of digits, and the date format is DD/MM/YYYY. Those are the cases where a shared, tested implementation is worth more than a regex you write once.

The case against is that the surface area is small and the dependency is real. It ships a UMD global, a set of named functions and an MIT licence, and you can read all of it.

Editorial conclusion

brazilian-values suits a JavaScript or TypeScript product written for Brazil that needs CPF, CNPJ, CEP, BRL and date formatting without pulling in a general internationalisation library, and that accepts validators as structural checks rather than registry lookups. It does not suit a multi-country product that needs one codebase to emit several locales, a requirement to confirm that a document was actually issued, or an RG layout outside SP and RJ. Before you adopt it, call the formatters twice on the same input to confirm the masking is idempotent, check the version number because the package is still on 0.14.1 with no API stability promise, and read the RG note in the documentation, since only the SP and RJ formats are currently handled.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. VitorLuizC/brazilian-values on GitHub