### Install with Yarn

Source: https://github.com/bnurbekov/company-email-validator/blob/main/README.md

Install the company-email-validator package using yarn.

```bash
yarn add company-email-validator
```

--------------------------------

### Install with NPM

Source: https://github.com/bnurbekov/company-email-validator/blob/main/README.md

Install the company-email-validator package using npm.

```bash
npm install company-email-validator
```

--------------------------------

### Run Tests with npm

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/implementation-details.md

Execute the test suite using npm. Ensure Mocha and Chai are installed as dev dependencies.

```bash
npm test
```

--------------------------------

### Install company-email-validator with pnpm

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/configuration.md

Use pnpm to install the company-email-validator package. This is a fast, disk-space-efficient package manager.

```bash
pnpm add company-email-validator
```

--------------------------------

### Validate Company Domain (TypeScript)

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Demonstrates how to use the `isCompanyDomain` function in TypeScript. This example shows conditional logic based on whether a domain is classified as a company domain.

```typescript
import * as CompanyEmailValidator from 'company-email-validator';

const domain = "example.com";
if (CompanyEmailValidator.isCompanyDomain(domain)) {
    console.log(`${domain} is a company domain`);
} else {
    console.log(`${domain} is a free provider domain`);
}
```

--------------------------------

### Update Company Email Validator Package

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/free-email-providers.md

Install the latest version of the company-email-validator package to get updated provider lists. This command updates the package to its newest version.

```bash
npm update company-email-validator
```

--------------------------------

### Handle Case Insensitivity in Emails and Domains

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

The `isCompanyEmail` and `isCompanyDomain` functions are case-insensitive. This example shows that different casing for company domains returns `true`, while for free providers it returns `false`.

```javascript
const { isCompanyEmail, isCompanyDomain } = require('company-email-validator');

// All return true (same company domain)
console.log(isCompanyEmail('user@ACME.COM'));
console.log(isCompanyEmail('user@Acme.Com'));
console.log(isCompanyEmail('user@acme.com'));

// All return false (same free provider)
console.log(isCompanyDomain('GMAIL.COM'));
console.log(isCompanyDomain('Gmail.Com'));
console.log(isCompanyDomain('gmail.com'));
```

--------------------------------

### Validate Company Email in Next.js API Route

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

Integrate company email validation into a Next.js API route handler. This example checks if the request method is POST and returns a JSON response indicating whether the provided email is a company email.

```typescript
import type { NextApiRequest, NextApiResponse } from 'next';
import { isCompanyEmail } from 'company-email-validator';

export default function handler(
    req: NextApiRequest,
    res: NextApiResponse
) {
    if (req.method !== 'POST') {
        return res.status(405).end();
    }
    
    const email: string = req.body.email;
    const isCompany: boolean = isCompanyEmail(email);
    
    res.json({ isCompanyEmail: isCompany });
}
```

--------------------------------

### Package.json Configuration for Module Entry Points

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

This configuration specifies the main entry point ('index') and the TypeScript typings file ('index.d.ts') for the package. Ensure these match your project structure.

```json
{
    "main": "index",
    "typings": "index.d.ts"
}
```

--------------------------------

### Project File Organization

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/DOCUMENTATION-INDEX.md

Lists the directory structure for all documentation files within the project. This helps users locate specific documentation topics.

```markdown
```
/workspace/home/output/
├── README.md                      (Main entry point)
├── DOCUMENTATION-INDEX.md         (This file)
├── api-reference.md               (Function reference)
├── module-reference.md            (Module architecture)
├── types.md                       (TypeScript types)
├── configuration.md               (Configuration reference)
├── implementation-details.md      (Internal architecture)
├── free-email-providers.md        (Provider list reference)
└── usage-guide.md                 (Practical examples)
```
```

--------------------------------

### Importing Module Exports (CommonJS/TypeScript)

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Demonstrates how to import the `isCompanyEmail` and `isCompanyDomain` functions using CommonJS and TypeScript syntax.

```javascript
// CommonJS
const { isCompanyEmail, isCompanyDomain } = require('company-email-validator');

// TypeScript
import { isCompanyEmail, isCompanyDomain } from 'company-email-validator';
```

--------------------------------

### User Signup Flow Logic

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Integrates `isCompanyEmail` into a user signup process to enforce the use of company emails for employees. Throws an error if a non-company email is provided when employee status is claimed.

```javascript
const { isCompanyEmail } = require('company-email-validator');

function signupUser(email, claimsEmployeeStatus) {
    if (claimsEmployeeStatus && !isCompanyEmail(email)) {
        throw new Error('Please use your company email');
    }
    
    const accountType = isCompanyEmail(email) ? 'employee' : 'basic';
    return { email, accountType };
}
```

--------------------------------

### Basic Usage in Node.js

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Import and use the isCompanyEmail function in a standard Node.js environment.

```javascript
const validator = require('company-email-validator');
console.log(validator.isCompanyEmail('test@example.com'));
```

--------------------------------

### CommonJS Import Patterns

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Demonstrates various ways to import the validator module in a CommonJS environment (Node.js default). Includes full, destructured, and lazy imports.

```javascript
// Full import
const validator = require('company-email-validator');
validator.isCompanyEmail('test@example.com');
```

```javascript
// Destructured import
const { isCompanyEmail, isCompanyDomain } = require('company-email-validator');
isCompanyEmail('test@example.com');
```

```javascript
// Lazy import
const { isCompanyEmail } = require('company-email-validator');
if (condition) {
    isCompanyEmail('test@example.com');
}
```

--------------------------------

### Basic Usage with TypeScript

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Use the `isCompanyEmail` function with TypeScript, importing the entire module.

```typescript
import * as CompanyEmailValidator from 'company-email-validator';

const email: string = 'user@google.com';
const isCompany: boolean = CompanyEmailValidator.isCompanyEmail(email);

if (isCompany) {
    console.log('Company email');
} else {
    console.log('Free provider email');
}
```

--------------------------------

### Import Patterns: CommonJS with Destructuring

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Import specific functions using destructuring for direct access.

```javascript
const { isCompanyEmail, isCompanyDomain } = require('company-email-validator');
isCompanyEmail("test@example.com");
```

--------------------------------

### Validate Company Email (TypeScript)

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Demonstrates how to use the isCompanyEmail function in a TypeScript project. Import the module and check the boolean result to determine if the email is from a company.

```typescript
import * as CompanyEmailValidator from 'company-email-validator';

const isCompany: boolean = CompanyEmailValidator.isCompanyEmail("test@utterly.app");
if (isCompany) {
    console.log("User has a company email");
} else {
    console.log("User has a free provider email");
}
```

--------------------------------

### Free Provider Domain Set Structure

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/implementation-details.md

This snippet shows the structure of the exported free email provider domain set. It is created from a newline-separated list of domains and is used for O(1) average-case lookup performance.

```javascript
const free_email_provider_set = /* Set created from domain list */
```

--------------------------------

### Build User Profile Service with Company Email Validation

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Use `isCompanyEmail` to categorize user emails and assign appropriate account tiers. This is useful for services that differentiate features or access based on email domain.

```javascript
const { isCompanyEmail } = require('company-email-validator');

class UserProfileService {
    constructor() {
        this.users = new Map();
    }
    
    createProfile(email) {
        const isCompany = isCompanyEmail(email);
        const domain = email.split('@')[1] || null;
        
        const profile = {
            email,
            domain,
            emailType: isCompany ? 'work' : 'personal',
            accountTier: isCompany ? 'professional' : 'basic',
            createdAt: new Date().toISOString(),
            verificationRequired: !isCompany
        };
        
        this.users.set(email, profile);
        return profile;
    }
    
    getProfile(email) {
        return this.users.get(email) || null;
    }
    
    listCompanyUsers() {
        return Array.from(this.users.values())
            .filter(profile => profile.emailType === 'work');
    }
}

// Usage
const service = new UserProfileService();
service.createProfile('alice@acme.com');
service.createProfile('bob@gmail.com');
service.createProfile('charlie@acme.com');

console.log('Company users:', service.listCompanyUsers().length); // 2
```

--------------------------------

### Usage in TypeScript

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Import and utilize the isCompanyEmail function within a TypeScript project, demonstrating type safety.

```typescript
import { isCompanyEmail } from 'company-email-validator';
const result: boolean = isCompanyEmail('test@example.com');
```

--------------------------------

### ES Modules / TypeScript Import Patterns

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Shows how to import the validator module using ES Module syntax, common in modern JavaScript and TypeScript projects. Includes namespace, named, and type imports.

```typescript
// Namespace import
import * as CompanyEmailValidator from 'company-email-validator';
CompanyEmailValidator.isCompanyEmail('test@example.com');
```

```typescript
// Named imports
import { isCompanyEmail, isCompanyDomain } from 'company-email-validator';
isCompanyEmail('test@example.com');
```

```typescript
// Type imports (TypeScript only)
import type { EmailValidator } from 'company-email-validator';
```

--------------------------------

### Import Patterns: CommonJS

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Import the validator module using require and call its functions.

```javascript
const validator = require('company-email-validator');
validator.isCompanyEmail("test@example.com");
```

--------------------------------

### Import Patterns: ES Modules (TypeScript)

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Import all module exports as a namespace in ES Modules.

```typescript
import * as CompanyEmailValidator from 'company-email-validator';
CompanyEmailValidator.isCompanyEmail("test@example.com");
```

--------------------------------

### Module Exports

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

The module exports 'isCompanyEmail' and 'isCompanyDomain' functions.

```javascript
module.exports = {
    isCompanyEmail: Function,
    isCompanyDomain: Function
}
```

--------------------------------

### Define Free Email Provider Domains

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/implementation-details.md

This internal module defines a canonical set of known free email provider domains. It processes a newline-separated string of domains and exports a Set for efficient O(1) lookups.

```javascript
const free_email_provider_domains = `0.pl\n0-00.usa.cc\n... (thousands more)`
// Module exports a Set for O(1) lookup
module.exports = /* Set built from domains */
```

--------------------------------

### Unsupported Overload Signatures

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

The library does not support optional parameters or union types for function overloads. Use the fixed signature provided by the library.

```typescript
// Not available: optional parameter overload
isCompanyEmail(email?: string): boolean

// Not available: union type overload
isCompanyEmail(emailOrDomain: string | URL): boolean
```

--------------------------------

### Basic Usage with TypeScript Named Imports

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Import and use `isCompanyEmail` and `isCompanyDomain` functions directly using named imports in TypeScript.

```typescript
import { isCompanyEmail, isCompanyDomain } from 'company-email-validator';

const email = 'john@company.example';
const domain = 'company.example';

const isCompanyEmail: boolean = isCompanyEmail(email);
const isCompanyDomain: boolean = isCompanyDomain(domain);
```

--------------------------------

### Assign Account Tiers Based on Email Type

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Determine the account tier ('premium' or 'free') for a user based on whether their email address is a company email.

```javascript
// Assign different account tiers based on email type
const tier = isCompanyEmail(email) ? 'premium' : 'free';
```

--------------------------------

### Basic Usage with CommonJS Destructuring

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Import and use `isCompanyEmail` and `isCompanyDomain` functions directly using destructuring in CommonJS.

```javascript
const { isCompanyEmail, isCompanyDomain } = require('company-email-validator');

const email = 'test@mycompany.com';
const domain = 'mycompany.com';

console.log(isCompanyEmail(email));     // true
console.log(isCompanyDomain(domain));   // true
```

--------------------------------

### User Signup with Email Classification

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Classify users during signup based on whether their email is a company email using `isCompanyEmail` and `isCompanyDomain`. Handles cases where a user claims to be an employee but uses a personal email.

```javascript
const { isCompanyEmail, isCompanyDomain } = require('company-email-validator');

class UserRegistration {
    registerUser(email, isEmployeeClaim) {
        const isActuallyCompany = isCompanyEmail(email);
        
        if (isEmployeeClaim && !isActuallyCompany) {
            // User claimed to be an employee but email doesn't match
            return {
                success: false,
                message: 'Please use your company email address',
                error: 'EMAIL_MISMATCH'
            };
        }
        
        if (isActuallyCompany) {
            // Mark user as employee for premium features
            return {
                success: true,
                userType: 'employee',
                features: ['premium', 'team-management']
            };
        } else {
            // Regular user with free account
            return {
                success: true,
                userType: 'regular',
                features: ['basic']
            };
        }
    }
}

// Usage
const registration = new UserRegistration();
console.log(registration.registerUser('alice@techcorp.com', true));
// {
//     success: true,
//     userType: 'employee',
//     features: ['premium', 'team-management']
// }

console.log(registration.registerUser('bob@gmail.com', true));
// {
//     success: false,
//     message: 'Please use your company email address',
//     error: 'EMAIL_MISMATCH'
// }
```

--------------------------------

### Efficiently Check Thousands of Emails

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Use the `filter` method with `isCompanyEmail` for large email lists. This approach offers O(n) time complexity for validating n emails.

```javascript
const { isCompanyEmail } = require('company-email-validator');

// For large batches, simple filter is efficient
const largeEmailList = /* ... array of 100k+ emails ... */;

const companyEmails = largeEmailList.filter(isCompanyEmail);

// Performance: O(n) where n is number of emails
// Lookup is O(1), so overall linear time complexity
```

--------------------------------

### Verify if a Domain is a Company Domain

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/free-email-providers.md

Use the isCompanyDomain function to check if a domain is likely a company domain. Domains not found in the free provider list are assumed to be company domains. For strict verification, additional checks are recommended.

```javascript
const { isCompanyDomain } = require('company-email-validator');

// Safe assumption: if not in free list, treat as company domain
const isLikelyCompany = isCompanyDomain('some-domain.io');

// For strict verification, implement additional checks
function strictlyVerifyCompanyDomain(domain) {
    // 1. Check if it's NOT a free provider
    if (!isCompanyDomain(domain)) {
        return false; // Known free provider
    }
    
    // 2. Additional verification (if needed)
    // - Check DNS records
    // - Verify MX records
    // - Contact domain owner
    
    return true; // Likely company domain
}
```

--------------------------------

### Module Exports

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

The company-email-validator module exports two public functions: `isCompanyEmail` and `isCompanyDomain`.

```APIDOC
## Module Level Exports

The module exports exactly two public functions:

```javascript
{
    isCompanyEmail: Function,      // (email: string) => boolean
    isCompanyDomain: Function       // (domain: string) => boolean
}
```
```

--------------------------------

### isCompanyDomain Function Implementation

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/implementation-details.md

This function checks if a domain name belongs to a company. It normalizes the domain to lowercase and checks if it is present in the free provider set. This method is faster than `isCompanyEmail` as it skips email syntax validation.

```javascript
exports.isCompanyDomain = function(domain) {
    // 1. Normalize: convert to lowercase
    domain = domain.toLowerCase();
    
    // 2. Classify: return true if NOT in free provider set
    return !free_email_provider_set.has(domain);
}
```

--------------------------------

### Type-Safe Email Validation with Configuration

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

Implement flexible email validation logic using a configuration object. This function checks if an email is a company email and optionally validates against a list of allowed domains.

```typescript
import { isCompanyEmail, isCompanyDomain } from 'company-email-validator';

interface EmailValidationConfig {
    requireCompanyEmail: boolean;
    allowedDomains?: string[];
}

function validateEmailWithConfig(
    email: string,
    config: EmailValidationConfig
): boolean {
    const isCompany: boolean = isCompanyEmail(email);
    
    if (config.requireCompanyEmail && !isCompany) {
        return false;
    }
    
    if (config.allowedDomains) {
        const domain: string = email.split('@')[1] || '';
        return config.allowedDomains.includes(domain);
    }
    
    return true;
}
```

--------------------------------

### TypeScript Configuration for ES Modules

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/configuration.md

Add these options to your tsconfig.json if your project targets ES modules. This helps with module interoperability.

```json
{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}
```

--------------------------------

### Usage in Web Frameworks (Express/Koa)

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Integrate the isCompanyEmail function into a web framework's request handling, such as validating an email from a POST request body.

```javascript
const { isCompanyEmail } = require('company-email-validator');

app.post('/register', (req, res) => {
    if (!isCompanyEmail(req.body.email)) {
        return res.status(400).send('Use company email');
    }
    // ...
});
```

--------------------------------

### Public API Exports

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Illustrates the symbols that are publicly exported by the module, intended for use by external code. Only `isCompanyEmail` and `isCompanyDomain` are available.

```javascript
exports.isCompanyEmail = function (email) { ... }
exports.isCompanyDomain = function(domain) { ... }
```

--------------------------------

### Check if a Domain is a Free Provider

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/free-email-providers.md

Use the `isCompanyDomain` function to determine if a given domain is recognized as a free email provider. This function is part of the company-email-validator library.

```javascript
const { isCompanyDomain } = require('company-email-validator');

if (!isCompanyDomain('gmail.com')) {
    console.log('gmail.com is a known free provider');
}

if (isCompanyDomain('mycompany.com')) {
    console.log('mycompany.com is not in the free provider list');
}
```

--------------------------------

### Batch Email Classification with Details

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Process a list of emails to classify each one as 'company' or 'personal', and determine if its domain is a company domain using `isCompanyEmail` and `isCompanyDomain`.

```javascript
const { isCompanyEmail, isCompanyDomain } = require('company-email-validator');

function classifyEmails(emailList) {
    return emailList.map(email => {
        const domain = email.split('@')[1];
        const isCompany = isCompanyEmail(email);
        
        return {
            email,
            domain,
            classification: isCompany ? 'company' : 'personal',
            isCompanyDomain: isCompanyDomain(domain)
        };
    });
}

// Usage
const results = classifyEmails([
    'user@github.com',
    'admin@github.com',
    'dev@github.io'
]);

console.log(results);
// [
//     { email: 'user@github.com', domain: 'github.com', classification: 'company', isCompanyDomain: true },
//     { email: 'admin@github.com', domain: 'github.com', classification: 'company', isCompanyDomain: true },
//     { email: 'dev@github.io', domain: 'github.io', classification: 'company', isCompanyDomain: true }
// ]
```

--------------------------------

### Usage in Serverless Functions

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Employ the isCompanyEmail function within a serverless function (e.g., AWS Lambda via `exports.handler`) to validate email addresses from incoming events.

```javascript
const { isCompanyEmail } = require('company-email-validator');

exports.handler = async (event, context) => {
    const email = event.body.email;
    return {
        statusCode: 200,
        body: JSON.stringify({
            isCompany: isCompanyEmail(email)
        })
    };
};
```

--------------------------------

### Allow Specific Company Domains

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Whitelist specific company domains by checking if the domain is included in a predefined list and is recognized as a company domain by `isCompanyDomain`.

```javascript
// Allow only specific company domains
const allowed = ['acme.com', 'apex.io'];
const isDomainAllowed = allowed.includes(domain) && isCompanyDomain(domain);
```

--------------------------------

### Email Validator Integration for Syntax Checking

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

This code demonstrates how the 'email-validator' npm dependency is used within the 'isCompanyEmail' function to perform RFC 5321/5322 syntax validation on email addresses. It returns false immediately if the email format is invalid.

```javascript
if (!validator.validate(email)) {
    return false;  // Invalid format
}
```

--------------------------------

### Import Patterns: ES Modules with Named Imports

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Import specific functions directly using named imports in ES Modules.

```typescript
import { isCompanyEmail, isCompanyDomain } from 'company-email-validator';
isCompanyEmail("test@example.com");
```

--------------------------------

### Validate Email Syntax with email-validator

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/implementation-details.md

Use this package to validate the syntax of an email address according to RFC 5321/5322. It returns true for valid formats and false for invalid ones. The validation is case-insensitive.

```javascript
const validator = require("email-validator");
validator.validate(email: string): boolean
```

--------------------------------

### isCompanyEmail Function Implementation

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/implementation-details.md

This function checks if an email address belongs to a company. It normalizes the email, validates its syntax using `email-validator`, extracts the domain, and checks if the domain is present in the free provider set.

```javascript
exports.isCompanyEmail = function (email) {
    // 1. Normalize: convert to lowercase
    email = email.toLowerCase();
    
    // 2. Validate: check email syntax
    if (!validator.validate(email)) {
        return false;
    }
    
    // 3. Extract: get domain from email
    let fields = email.split('@');
    let domain = fields[1];
    
    // 4. Classify: return true if NOT in free provider set
    return !free_email_provider_set.has(domain);
}
```

--------------------------------

### Module Exports - Company Email Validator

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

The module exports two public functions: `isCompanyEmail` and `isCompanyDomain`. Use these to validate email addresses or domains against a list of free providers.

```javascript
module.exports = {
    isCompanyEmail: Function,      // (email: string) => boolean
    isCompanyDomain: Function       // (domain: string) => boolean
}
```

--------------------------------

### Basic Usage with CommonJS

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Check if an email is from a company domain or if a domain is a company domain using CommonJS module syntax.

```javascript
const CompanyEmailValidator = require('company-email-validator');

// Check if an email is from a company domain
if (CompanyEmailValidator.isCompanyEmail('employee@acme.com')) {
    console.log('Valid company email');
} else {
    console.log('Not a company email (or invalid format)');
}

// Check if a domain is a company domain
if (CompanyEmailValidator.isCompanyDomain('acme.com')) {
    console.log('Company domain');
} else {
    console.log('Free provider domain');
}
```

--------------------------------

### Implementing Type Guards with `isCompanyEmail` in TypeScript

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

Create a type guard function `isCompanyEmployee` that uses `isCompanyEmail` to narrow down the type of a `User` object to `CompanyEmployee`. This requires importing `isCompanyEmail`.

```typescript
import { isCompanyEmail } from 'company-email-validator';

interface User {
    email: string;
    name: string;
}

interface CompanyEmployee extends User {
    employeeId: string;
}

function isCompanyEmployee(user: User): user is CompanyEmployee {
    return isCompanyEmail(user.email);
}

const users: User[] = [
    { email: 'alice@acme.com', name: 'Alice' },
    { email: 'bob@gmail.com', name: 'Bob' },
];

const employees = users.filter(isCompanyEmployee);
```

--------------------------------

### TypeScript Type Definitions

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Import and use the type definitions for `isCompanyEmail` and `isCompanyDomain` functions in your TypeScript projects.

```typescript
import { isCompanyEmail, isCompanyDomain } from 'company-email-validator';

const email: string = 'test@example.com';
const result: boolean = isCompanyEmail(email);

const domain: string = 'example.com';
const isDomainCompany: boolean = isCompanyDomain(domain);
```

--------------------------------

### Batch Email Processing

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Applies `isCompanyEmail` to a list of emails using `map` to classify each email as 'company' or 'personal'. This is useful for batch processing and analysis.

```javascript
const { isCompanyEmail } = require('company-email-validator');

const emails = ['alice@acme.com', 'bob@gmail.com', 'charlie@startup.io'];

const classified = emails.map(email => ({
    email,
    type: isCompanyEmail(email) ? 'company' : 'personal'
}));
```

--------------------------------

### isCompanyEmail(email: string): boolean

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Validates whether a given email address belongs to a company domain. It checks email syntax, extracts the domain, and verifies it against a list of free email providers.

```APIDOC
## isCompanyEmail(email: string): boolean

### Description
Validates whether a given email address belongs to a company domain.

### Parameters
#### Path Parameters
- **email** (string) - Required - The email address to validate.

### Returns
- **boolean** - `true` if the email is a company email, `false` otherwise.

### Example
```javascript
const validator = require('company-email-validator');

validator.isCompanyEmail('alice@acme.com');      // true
validator.isCompanyEmail('bob@gmail.com');       // false
validator.isCompanyEmail('invalid-email');       // false
```
```

--------------------------------

### Classify an Email as Company or Free Provider

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/free-email-providers.md

Use the isCompanyEmail function for a quick classification of an email address. It determines if the email belongs to a known free provider or is likely a company email.

```javascript
const { isCompanyEmail } = require('company-email-validator');

// Quick classification
if (isCompanyEmail('user@domain.com')) {
    console.log('Likely company email');
} else {
    console.log('Known free provider email');
}
```

--------------------------------

### Direct Export of Validation Functions

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Use this method to export the validation functions directly from the module. This is suitable for CommonJS environments.

```javascript
module.exports = {
    isCompanyEmail: function (email) { ... },
    isCompanyDomain: function(domain) { ... }
}
```

--------------------------------

### Restrict Feature Access with Company Email

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Use `isCompanyEmail` to ensure that only users with company email addresses can access specific features. Throws an error if the email is not a company email.

```javascript
// Restrict feature access to company email users
if (!isCompanyEmail(userEmail)) {
    throw new Error('Feature requires company email');
}
```

--------------------------------

### Usage in React/Next.js

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Incorporate the isCompanyEmail function into a React component for client-side email validation, managing state for user input.

```typescript
import { isCompanyEmail } from 'company-email-validator';

export function SignupForm() {
    const [email, setEmail] = React.useState('');
    const isValid = isCompanyEmail(email);
    
    return <form>{/* ... */}</form>;
}
```

--------------------------------

### Validate Email in Form Submission

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Use `isCompanyEmail` to ensure users submit their company email addresses during registration. Throws an error for non-company emails.

```javascript
const { isCompanyEmail } = require('company-email-validator');

function validateRegistrationEmail(email) {
    if (!isCompanyEmail(email)) {
        throw new Error('Please use your company email address');
    }
    return true;
}

// Usage
try {
    validateRegistrationEmail('user@startup.io');  // true
    validateRegistrationEmail('user@gmail.com');   // throws error
} catch (error) {
    console.error(error.message);
}
```

--------------------------------

### API Request Authorization with Company Email Check

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Implement authorization logic for API requests, restricting certain features like beta access to users with company emails. This snippet shows how to conditionally grant access based on email domain.

```javascript
const { isCompanyEmail } = require('company-email-validator');

function handleSignupRequest(req, res) {
    const { email, requestType } = req.body;
    
    // Beta features require company email
    if (requestType === 'beta-access' && !isCompanyEmail(email)) {
        return res.status(403).json({
            error: 'BETA_REQUIRES_COMPANY_EMAIL',
            message: 'Beta features are available to company email users only'
        });
    }
    
    // Standard signup available to all
    if (requestType === 'standard') {
        return res.status(200).json({
            success: true,
            tier: isCompanyEmail(email) ? 'professional' : 'basic'
        });
    }
}

// Usage
handleSignupRequest(
    { body: { email: 'user@company.com', requestType: 'beta-access' } },
    {
        status: (code) => ({
            json: (data) => console.log(code, data)
        })
    }
);
// 200 { success: true, tier: 'professional' }
```

--------------------------------

### Unsupported Generic Type Usage

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

The functions do not accept generic type parameters. Use the standard function signature without specifying types.

```typescript
// Not available: generics
isCompanyEmail<T extends string>(email: T): boolean
```

--------------------------------

### Domain Classification

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Utilize `isCompanyDomain` to filter a list of domains and identify company-specific domains. This function returns `true` for company domains and `false` otherwise.

```javascript
const { isCompanyDomain } = require('company-email-validator');

const domains = ['gmail.com', 'acme.com', 'yahoo.com'];
const companyDomains = domains.filter(isCompanyDomain);

console.log(companyDomains);  // ['acme.com']
```

--------------------------------

### Domain-Based Access Control

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/usage-guide.md

Implement access control by checking if an email's domain is both company-approved and a valid company domain using `isCompanyDomain`.

```javascript
const { isCompanyDomain } = require('company-email-validator');

function canRegisterForBetaProgram(email) {
    const domain = email.split('@')[1];
    
    // Only allow employees from specific approved domains
    const approvedDomains = ['acme.com', 'apex.io', 'zenith.dev'];
    const isDomainApproved = approvedDomains.includes(domain);
    const isDomainCompany = isCompanyDomain(domain);
    
    return isDomainApproved && isDomainCompany;
}

// Usage
console.log(canRegisterForBetaProgram('alice@acme.com'));      // true (approved)
console.log(canRegisterForBetaProgram('bob@apex.io'));         // true (approved)
console.log(canRegisterForBetaProgram('charlie@gmail.com'));   // false (not company)
console.log(canRegisterForBetaProgram('dave@unknown.dev'));    // false (not approved)
```

--------------------------------

### Validate Company Domain

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Use the `isCompanyDomain` function to verify if a domain is a company domain. This function checks against a list of free providers and does not validate domain syntax.

```javascript
const validator = require('company-email-validator');

validator.isCompanyDomain('acme.com');           // true
validator.isCompanyDomain('gmail.com');          // false
```

--------------------------------

### Normalize Email and Domain to Lowercase

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/implementation-details.md

Both validation functions normalize input to lowercase before processing to ensure consistent results regardless of input capitalization. This applies to both the email address and its domain.

```javascript
email = email.toLowerCase();     // "Test@Domain.Com" → "test@domain.com"
domain = domain.toLowerCase();   // "Gmail.COM" → "gmail.com"
```

--------------------------------

### Validate Company Email (TypeScript)

Source: https://github.com/bnurbekov/company-email-validator/blob/main/README.md

Use the CompanyEmailValidator.isCompanyEmail function to check if an email is a company email. Import the package as a namespace.

```typescript
import * as CompanyEmailValidator from 'company-email-validator';

CompanyEmailValidator.isCompanyEmail("test@utterly.app"); // true

CompanyEmailValidator.isCompanyEmail("test@gmail.com"); // false
```

--------------------------------

### Segment Users by Email Type for Analytics

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Filter a list of emails to segment users into 'company' and 'personal' categories for analytics purposes using `isCompanyEmail`.

```javascript
// Segment users by email type for analytics
const segments = {
    company: emails.filter(isCompanyEmail),
    personal: emails.filter(e => !isCompanyEmail(e))
};
```

--------------------------------

### isCompanyDomain

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Validates whether a given domain is a company domain (not a free email provider domain). It checks if the domain exists in a predefined list of free email providers.

```APIDOC
## isCompanyDomain

### Description
Validates whether a given domain is a company domain (not a free email provider domain).

### Method Signature
```javascript
isCompanyDomain(domain: string): boolean
```

### Parameters
#### Path Parameters
- **domain** (string) - Required - The email domain to validate (e.g., "gmail.com", "utterly.app"). Case-insensitive.

### Return Type
`boolean` — Returns `true` if the domain is not in the free email provider list (indicating a company domain), or `false` if the domain is a known free provider.

### Examples
```javascript
const CompanyEmailValidator = require('company-email-validator');

// Company domains - returns true
CompanyEmailValidator.isCompanyDomain("utterly.app"); // true
CompanyEmailValidator.isCompanyDomain("mycompany.com"); // true

// Free provider domains - returns false
CompanyEmailValidator.isCompanyDomain("gmail.com"); // false
CompanyEmailValidator.isCompanyDomain("outlook.com"); // false

// Case-insensitive validation
CompanyEmailValidator.isCompanyDomain("UTTERLY.APP"); // true
CompanyEmailValidator.isCompanyDomain("GMAIL.COM"); // false
```
```

--------------------------------

### Synchronous Email Validation

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

Use this pattern for correct synchronous validation. Avoid treating the result as a Promise or using `await` as the function is not asynchronous.

```typescript
// ✓ Correct - synchronous
const result: boolean = isCompanyEmail('test@example.com');

// ✗ Incorrect - not a Promise
const result: Promise<boolean> = isCompanyEmail('test@example.com');

// ✗ Incorrect - not async
async function checkEmail(email: string): Promise<boolean> {
    return await isCompanyEmail(email); // isCompanyEmail is not awaitable
}
```

--------------------------------

### Classify Emails into Company and Personal Lists

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

Use this function to categorize an array of email addresses into two distinct lists: company emails and personal emails. It relies on the `isCompanyEmail` function from the 'company-email-validator' library.

```typescript
import { isCompanyEmail } from 'company-email-validator';

interface ClassifiedEmails {
    company: string[];
    personal: string[];
}

function classifyEmails(emails: string[]): ClassifiedEmails {
    return {
        company: emails.filter(isCompanyEmail),
        personal: emails.filter((e) => !isCompanyEmail(e)),
    };
}

const result: ClassifiedEmails = classifyEmails([
    'alice@company.com',
    'bob@gmail.com',
]);
```

--------------------------------

### Validate Company Domain (JavaScript)

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Use this function to check if a given domain is a company domain or a free email provider domain. It performs case-insensitive checks against a list of known free providers.

```javascript
const CompanyEmailValidator = require('company-email-validator');

// Company domains - returns true
CompanyEmailValidator.isCompanyDomain("utterly.app"); // true
CompanyEmailValidator.isCompanyDomain("mycompany.com"); // true
CompanyEmailValidator.isCompanyDomain("acme.co.uk"); // true

// Free provider domains - returns false
CompanyEmailValidator.isCompanyDomain("gmail.com"); // false
CompanyEmailValidator.isCompanyDomain("outlook.com"); // false
CompanyEmailValidator.isCompanyDomain("yahoo.com"); // false

// Case-insensitive validation
CompanyEmailValidator.isCompanyDomain("UTTERLY.APP"); // true
CompanyEmailValidator.isCompanyDomain("GMAIL.COM"); // false
CompanyEmailValidator.isCompanyDomain("Gmail.Com"); // false
```

--------------------------------

### Safe Usage of isCompanyEmail

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/module-reference.md

Always ensure the input is a string before calling isCompanyEmail to prevent type errors. The function itself never throws exceptions.

```javascript
// Never throws, always returns boolean
isCompanyEmail('invalid-input');           // Returns false
isCompanyEmail(null);                      // Type error (not caught)
isCompanyEmail(undefined);                 // Type error (not caught)
isCompanyEmail(123);                       // Type error (not caught)

// For safety, ensure correct types:
if (typeof email === 'string') {
    isCompanyEmail(email);  // Safe
}
```

--------------------------------

### isCompanyDomain

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/api-reference.md

Checks if a given domain is recognized as a company domain. This function is part of the public API and can be directly invoked by users.

```APIDOC
## isCompanyDomain

### Description
Checks if the provided domain name is recognized as a company domain.

### Method
Function Call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **domain** (string) - Required - The domain name to validate.

### Request Example
```javascript
const { isCompanyDomain } = require('company-email-validator');
isCompanyDomain("example.com");
```

### Response
#### Success Response
- **boolean** - Returns `true` if the domain is a company domain, `false` otherwise.

#### Response Example
```json
{
  "example": "true"
}
```
```

--------------------------------

### TypeScript Module Declaration

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

Declares the module for TypeScript environments, exporting the isCompanyEmail and isCompanyDomain functions with their respective signatures.

```typescript
declare module 'company-email-validator' {
    export function isCompanyEmail(email: string): boolean;
    export function isCompanyDomain(domain: string): boolean;
}
```

--------------------------------

### Basic Email Validation in TypeScript

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/types.md

Use `isCompanyEmail` to check if an email address belongs to a company domain. Ensure the 'company-email-validator' library is imported.

```typescript
import { isCompanyEmail, isCompanyDomain } from 'company-email-validator';

const email: string = 'test@example.com';
const result: boolean = isCompanyEmail(email);

if (result) {
    console.log('Company email');
} else {
    console.log('Personal or free provider email');
}
```

--------------------------------

### Validate Company Email Address

Source: https://github.com/bnurbekov/company-email-validator/blob/main/_autodocs/README.md

Use the `isCompanyEmail` function to check if an email belongs to a company domain. It validates email syntax, extracts the domain, and checks against a list of free providers.

```javascript
const validator = require('company-email-validator');

validator.isCompanyEmail('alice@acme.com');      // true
validator.isCompanyEmail('bob@gmail.com');       // false
validator.isCompanyEmail('invalid-email');       // false
```