@lacussoft/cpf-val
Version:
Utility to validate CPF (Brazilian Individual's Taxpayer ID)
159 lines (109 loc) • 6.87 kB
Markdown
[](https://npmjs.com/package/@lacussoft/cpf-val)
[](https://bundlephobia.com/package/@lacussoft/cpf-val)
[](https://npmjs.com/package/@lacussoft/cpf-val)
[](https://github.com/LacusSolutions/br-utils-js/actions)
[](https://github.com/LacusSolutions/br-utils-js)
[](https://github.com/LacusSolutions/br-utils-js/blob/main/LICENSE)
> 🌎 [Acessar documentação em português](https://github.com/LacusSolutions/br-utils-js/blob/main/packages/cpf-val/README.pt.md)
A JavaScript/TypeScript utility to validate CPF (Brazilian Individual's Taxpayer ID) values.
## Platform Support
|  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| v16+ ✔ | v1.0+ ✔ | ⚠️ untested | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 11 ✔ |
## Features
- ✅ **Flexible input**: Accepts string or array of strings (formatted or raw)
- ✅ **Format agnostic**: Strips non-numeric characters before validation
- ✅ **TypeScript support**: Full type definitions and strict-mode compatible
- ✅ **Minimal dependencies**: No external dependencies, only internal packages `@lacussoft/utils`, and `@lacussoft/cpf-dv` for check digits calculation.
- ✅ **Error handling**: Specific type error for invalid input type
## Installation
```bash
# using NPM
$ npm install --save @lacussoft/cpf-val
# using Bun
$ bun add @lacussoft/cpf-val
```
## Quick Start
```ts
// ES Modules
import cpfVal from '@lacussoft/cpf-val'
// Common JS
const cpfVal = require('@lacussoft/cpf-val')
```
Basic usage:
```ts
cpfVal('12345678909') // true
cpfVal('123.456.789-09') // true
cpfVal('12345678910') // false (invalid check digits)
cpfVal(['123', '456', '789', '09']) // true (array of strings)
cpfVal(['1', '2', '3', '...', '0', '9']) // true (array of strings)
```
For legacy frontends, include the UMD build (e.g. minified) in a `<script>` tag; `cpfVal` is exposed globally:
```html
<script src="https://cdn.jsdelivr.net/npm/@lacussoft/cpf-val@latest/dist/cpf-val.min.js"></script>
```
## Usage
### `cpfVal` (helper function)
Validates a CPF string or array of strings. Returns `true` if the input is a valid CPF (11 digits after sanitization, eligible base, and correct check digits), otherwise `false`. Invalid input (e.g. wrong length, ineligible base such as repeated digits) yields `false` without throwing. This is a convenience wrapper around `new CpfValidator().isValid(cpfInput)`.
- **`cpfInput`**: `CpfInput` — string or array of strings (formatted or raw; non-numeric characters are stripped).
**Throws:** `CpfValidatorInputTypeError` if input is not string or string[].
### `CpfValidator` (class)
For reusable validation logic, use the class:
```ts
import { CpfValidator } from '@lacussoft/cpf-val'
const validator = new CpfValidator()
validator.isValid('123.456.789-09') // true
validator.isValid('12345678909') // true
validator.isValid(['123', '456', '789', '10']) // false
```
- **`constructor`**: `new CpfValidator()` — no options.
- **`isValid(cpfInput)`**: Returns `true` if the CPF is valid, `false` otherwise.
### Input formats
**String input:** plain digits or formatted CPF (e.g. `123.456.789-09`). Non-numeric characters are automatically stripped. Must be 11 digits after sanitization.
**Array of strings:** single-character or multi-character strings (joined before validation), e.g. `['1','2','3','4','5','6','7','8','9','0','9']`, `['123','456','789','09']`.
## API
### Exports
- **`cpfVal`** (default): `(cpfInput: CpfInput) => boolean`
- **`CpfValidator`**: Class to validate CPF (no options).
- **`CPF_LENGTH`**: `11` (constant).
- **Types**: `CpfInput` (`string | readonly string[]`).
### Errors & Exceptions
This package uses **TypeError** for invalid input type. Invalid CPF values (wrong length, ineligible base) return `false` and do not throw.
- **CpfValidatorTypeError** (_abstract_) — base for type errors
- **CpfValidatorInputTypeError** — input is not string or string[]
- **CpfValidatorException** (_abstract_) — base for non-type exceptions (currently unused by this package)
```ts
import cpfVal, {
CpfValidatorInputTypeError,
CpfValidatorTypeError,
} from '@lacussoft/cpf-val'
// Input type (e.g. number not allowed)
try {
cpfVal(12345678909)
} catch (e) {
if (e instanceof CpfValidatorInputTypeError) {
console.log(e.message) // CPF input must be of type string or string[]. Got integer number.
}
}
// Any type error from the package
try {
cpfVal(null)
} catch (e) {
if (e instanceof CpfValidatorTypeError) {
// handle
}
}
```
## Contribution & Support
We welcome contributions! Please see our [Contributing Guidelines](https://github.com/LacusSolutions/br-utils-js/blob/main/CONTRIBUTING.md) for details. If you find this project helpful, please consider:
- ⭐ Starring the repository
- 🤝 Contributing to the codebase
- 💡 [Suggesting new features](https://github.com/LacusSolutions/br-utils-js/issues)
- 🐛 [Reporting bugs](https://github.com/LacusSolutions/br-utils-js/issues)
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/LacusSolutions/br-utils-js/blob/main/LICENSE) file for details.
## Changelog
See [CHANGELOG](https://github.com/LacusSolutions/br-utils-js/blob/main/packages/cpf-val/CHANGELOG.md) for a list of changes and version history.
---
Made with ❤️ by [Lacus Solutions](https://github.com/LacusSolutions)