# better-email-validator

> Zero dependency email validator with extra features

Latest version **1.0.0** (published 2021-11-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install better-email-validator
pnpm add better-email-validator
yarn add better-email-validator
bun add better-email-validator
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2021-11-22 |
| First published | 2021-11-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 24 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | TAB_mk |
| Maintainers | tab_mk |
| Keywords | email, validation, validator, validate, email validation, email validator, email validate |

## Links

- npm: https://www.npmjs.com/package/better-email-validator
- Repository: https://github.com/TABmk/better-email-validator
- Homepage: https://github.com/TABmk/better-email-validator#readme
- Issues: https://github.com/TABmk/better-email-validator/issues
- npm.io page: https://npm.io/package/better-email-validator

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2021-11-22

## README

[<img src="https://img.shields.io/npm/v/better-email-validator">](https://www.npmjs.com/package/better-email-validator) [<img src="https://img.shields.io/npm/l/better-email-validator">](https://github.com/TABmk/better-email-validator/blob/master/LICENSE) <img src="https://badgen.net/npm/types/better-email-validator">

<img src="https://badgen.net/npm/dt/better-email-validator">
<img src="https://badgen.net/npm/dm/better-email-validator">

__Help__ [<img src="https://img.shields.io/github/issues/tabmk/better-email-validator">](https://github.com/TABmk/better-email-validator/issues?q=is%3Aopen+is%3Aissue) [<img src="https://img.shields.io/github/issues-pr/tabmk/better-email-validator">](https://github.com/TABmk/better-email-validator/pulls?q=is%3Aopen+is%3Apr)

#### __Rate__ [<img src="https://img.shields.io/github/stars/tabmk/better-email-validator?style=social">](https://github.com/TABmk/better-email-validator)

# __BETTER-EMAIL-VALIDATOR__ 📧

Zero-dependency <img src="https://badgen.net/bundlephobia/dependency-count/better-email-validator">

lightweigh <img src="https://badgen.net/bundlephobia/minzip/better-email-validator">

📨 Email adress validator with extra features 🛠

---
# ⚠️ Disclaimer ⚠️
Read license before use it!

---
# How can u help / TODO

It would be awesome if you help with something of this:

- Add new regexp [here](https://github.com/TABmk/better-email-validator/blob/master/extra/rfc.ts)
- Add new domains to build-in whitelist [here](https://github.com/TABmk/better-email-validator/blob/master/extra/whitelist.ts)
- Test existing prepared regex
- Test existing tools (methods)
- Write tests
- Add new tools for emails
- Make Readme better (i'll add TypeDoc soon, maybe)
- Add JSDocs
- Fix mistakes in Readme
- Add code examples

---
You can compile .js files by command `yarn build` or `npm run build`

And run example with `yarn example` or `npm run example`

---

## __Install__
```
npm i better-email-validator

    or

yarn add better-email-validator
```

## __Usage__

### Import
```
import { RFC5322, RFC822 EmailValidator } from 'better-email-validator';

    or

const { RFC5322, RFC822 EmailValidator } = require('better-email-validator');
```

### RFC
`RFC5322` and `RFC822` are constant variables which contains implementation of specifications. Both `RegExp`

### EmailValidator
This is main class which contains all methods

Create new instance:
```
const EV = new EmailValidator({
  // params
});
```

#### Params
| Param | Description | Type | Default |
| -- | -- | -- | -- |
| regex | Main checker. Pass own regexp or use prepared `RFC5322` or `RFC822` | RegExp | `RFC5322` |
| dotsRegEx | Regex for checking dots in name | RegExp | `/[.](?=.*[@])/g` |
| allowDots | Is dots allowed in name | boolean | `true` |
| allowTags | Is tags allowed in name (aa`+bb`@ccc.dd) | boolean | `true` |
| allowSubdomain | Is subdomains allowed in domain | boolean | `true` |
| tagSymbols | List of chars for tags. (Ex.: `+` for Gmail, `-` for qmail, etc) | Array<string> | `[ '+' ]` |
| tagRegExPattern | Regex pattern for tags check | string | `'(%TAG%.*)@'` |
| details | false = methods return only boolean. true = object (check `IDetails` below)  | boolean | `false` |
| allowOnlyWhiteList | Allow only whitelisted domains. Check `extra/whitelist.ts` | boolean | `false` |
| domains | If `allowOnlyWhiteList` = true, expands it. If not = this array counts as whitelist | Array<string> | `[]` |

##### IDetails
```
interface IDetails {
  result: boolean,
  errorCode: string, // 'ok' if result 'true'
  errorInfo: string, // empty if result 'true'
}
```

#### Examples
```
const EV = new EmailValidator({
  domains: [ 'tab.mk' ],
  allowOnlyWhiteList: true,
  allowDots: false,
  details: true,
});

// domain whitelisted (wl expanded by 'domains')
EV.validate('someemail@tab.mk');
// => {
//      result: true,
//      errorCode: 'ok',
//      errorInfo: ''
//    }

// domain not whitelisted
EV.validate('someemail@unknown.domain');
// => {
//      result: false,
//      errorCode: 'domain',
//      errorInfo: 'unknown.domain'
//    }

// domain whitelisted (from build-in wl), but dots in name
EV.validate('s.o.m.e.email@gmail.com');
// => {
//      result: false,
//      errorCode: 'dots',
//      errorInfo: 'Dots count: 4'
//    }
```

### Methods
#### validate (email: string): string
Checks for
|Name|Condition|errorCode|
|--|--|--|
|subdomain|allowSubdomain === false && checkSubDomain === true|subdomain|
|dots|checkDots => 1 && allowDots === false|dots|
|tag|checkTags.length && allowTags === false|tag|
|whitelist|domains.length && domains.includes|domain|
|main regex|regex.test|regex|

success return `true` or `{result: true, errorCode: 'ok', errorInfo: ''}` if details enabled

Example:
```
EV.validate('aaa@aa.aa');
// => true

EV.validate('aaa@aa.aa'); // with build-in whitelist + details
// => {
//      result: false,
//      errorCode: 'domain',
//      errorInfo: 'aa.aa'
//    }
```

#### compare (email1: string, email2: string, strict = true): boolean
Compares two emails with considering instance params. Params can be ignored by passing `false` as third param

Example:
```
EV.compare('AAA.bb+cc@gmail.com', 'aaabb@gmail.com');
// => false

EV.compare('AAA.bb+cc@gmail.com', 'aaabb@gmail.com', false);
// => true
```
#### clear (email: string, strict = true): string
Clears email with considering instance params. Params can be ignored by passing `false` as third param

Example
```
// allowDots: false
EV.clear('AAA.bb+cc@gmail.com');
// => AAAbb+cc@gmail.com

// allowTags: false
EV.clear('AAA.bb+cc@gmail.com');
// => AAA.bb@gmail.com

EV.clear('AAA.bb+cc@gmail.com', false);
// => AAAbb@gmail.com
```
#### getDomain (email: string): string
Returns domain from email address

Example:
```
EV.getDomain('aaa@gmail.com');
// => gmail.com
```
#### checkSubDomain (email: string): boolean
Returns `true` if email domain contains subdomain

Example:
```
EV.getDomain('aaa@gmail.com');
// => false

EV.getDomain('aaa@xxx.gmail.com');
// => true
```
#### checkDots (email: string): number
Returns number of dots in name
Example:
```
EV.getDomain('aaa@gmail.com');
// => 0

EV.getDomain('a.a.a@gmail.com');
// => 2
```
#### checkTags (email: string): string
Returns first found tag in name or empty string if nothing found

Example:
```
EV.getDomain('aaa@gmail.com');
// => ''

// with default settings
EV.getDomain('aaa+bb@gmail.com');
// => '+'

// tagSymbols: [ '-', '+' ]
EV.getDomain('aaa-bb+cc@gmail.com');
// => '-'
// first match only
```
#### removeDots (email: string): string
Returns cleared email from dots
Example:
```
EV.removeDots('a.a.a@gmail.com');
// => 'aaa@gmail.com'
```
#### removeTag (email: string): string
Returns cleared email from tags
Example:
```
EV.removeDots('aaa+bb@gmail.com');
// => 'aaa@gmail.com'

// tagSymbols: [ '-', '+' ]
EV.removeDots('aaa=bb-cc+dd@gmail.com');
// => 'aaa=bb@gmail.com'
```

---
_Source: https://npm.io/package/better-email-validator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._