@ekaone/mask-email

A lightweight, zero-dependency TypeScript library for masking email addresses to protect user privacy.

Features

✨ Lightweight - Zero dependencies
🔒 Privacy-focused - Mask sensitive email information
📦 TypeScript - Full type safety and IntelliSense support
⚙️ Customizable - Flexible masking options
🎯 Simple API - Easy to use with sensible defaults

Installation

npm install @ekaone/mask-email

yarn add @ekaone/mask-email

pnpm add @ekaone/mask-email

Quick Start

import { maskEmail } from '@ekaone/mask-email';

maskEmail('[email protected]');
// Output: 'ek********@gmail.com'

Usage Examples

Basic Usage

import { maskEmail } from '@ekaone/mask-email';

// Default masking (shows first 2 characters)
maskEmail('[email protected]');
// Output: 'jo******@example.com'

maskEmail('[email protected]');
// Output: 'ad***@company.com'

Custom Visible Characters

Control how many characters remain visible at the beginning of the username:

// Show first 4 characters
maskEmail('[email protected]', { visibleChars: 4 });
// Output: 'ekao******@gmail.com'

// Show only 1 character
maskEmail('[email protected]', { visibleChars: 1 });
// Output: 'e*********@gmail.com'

Custom Mask Character

Change the masking character from the default *:

maskEmail('[email protected]', { maskChar: '#' });
// Output: 'us##@example.com'

maskEmail('[email protected]', { maskChar: '•' });
// Output: 'us••@example.com'

maskEmail('[email protected]', { maskChar: '-' });
// Output: '[email protected]'

Domain Masking

Mask the domain part of the email as well:

// Mask domain
maskEmail('[email protected]', { maskDomain: true });
// Output: 'us**@g****.com'

// Works with subdomains
maskEmail('[email protected]', { maskDomain: true });
// Output: 'co*****@m***.g*****.com'

Viewable Mode

Return the original email without masking (useful for admin views):

maskEmail('[email protected]', { viewable: true });
// Output: '[email protected]'

Combined Options

Mix and match options for custom masking behavior:

maskEmail('[email protected]', {
  visibleChars: 3,
  maskChar: '-',
  maskDomain: true
});
// Output: '[email protected]'

maskEmail('[email protected]', {
  visibleChars: 1,
  maskChar: '*',
  maskDomain: true
});
// Output: 'a****@m***.c******.com'

API Reference

maskEmail(email, options?)

Masks an email address according to the provided options.

Parameters

• email (string) - The email address to mask
• options (EmailOptions, optional) - Configuration options

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | maskChar | string | '*' | Character used for masking | | visibleChars | number | 2 | Number of characters to remain visible at the beginning | | maskDomain | boolean | false | If true, the domain part (after @) will also be masked | | viewable | boolean | false | If true, returns the original email without masking |

Returns

• (string) - The masked email address

TypeScript Types

interface EmailOptions {
  /** Character used for masking (default: '*') */
  maskChar?: string;
  /** Number of characters to remain visible at the beginning (default: 2) */
  visibleChars?: number;
  /** If true, returns the original email without masking (default: false) */
  viewable?: boolean;
  /** If true, the domain part (after @) will also be masked (default: false) */
  maskDomain?: boolean;
}

Real-World Use Cases

Display Emails in UI

const userEmail = '[email protected]';
const displayEmail = maskEmail(userEmail);

console.log(`Confirmation sent to: ${displayEmail}`);
// Output: "Confirmation sent to: cu******@company.com"

Logging Sensitive Data

const emails = [
  '[email protected]',
  '[email protected]',
  '[email protected]'
];

emails.forEach(email => {
  console.log('Processing:', maskEmail(email, { visibleChars: 3 }));
});
// Output:
// Processing: adm**@site.com
// Processing: use****@example.com
// Processing: con****@business.org

Role-Based Masking

function getUserEmailForDisplay(email: string, userRole: string) {
  if (userRole === 'admin') {
    return maskEmail(email, { viewable: true });
  } else if (userRole === 'moderator') {
    return maskEmail(email, { visibleChars: 4, maskDomain: false });
  } else {
    return maskEmail(email, { visibleChars: 2, maskDomain: true });
  }
}

console.log(getUserEmailForDisplay('[email protected]', 'admin'));
// Output: '[email protected]'

console.log(getUserEmailForDisplay('[email protected]', 'moderator'));
// Output: '[email protected]'

console.log(getUserEmailForDisplay('[email protected]', 'user'));
// Output: 'jo**@e******.com'

Privacy-Compliant Email Display

// Show masked email in public profiles
function displayPublicProfile(user: { name: string; email: string }) {
  return {
    name: user.name,
    email: maskEmail(user.email, { maskDomain: true })
  };
}

const profile = displayPublicProfile({
  name: 'John Doe',
  email: '[email protected]'
});

console.log(profile);
// Output: { name: 'John Doe', email: 'jo******@e******.com' }

Edge Cases

The library handles various edge cases gracefully:

// Very short usernames
maskEmail('[email protected]', { visibleChars: 2 });
// Output: '[email protected]' (shows all available characters)

// Invalid email format (no @ symbol)
maskEmail('notanemail');
// Output: 'notanemail' (returns as-is)

// Empty or null values
maskEmail('');
// Output: ''

maskEmail(null);
// Output: null

// Multiple @ symbols (technically invalid but handled)
maskEmail('user@[email protected]');
// Output: 'us*******@domain.com' (uses last @ as separator)

// Subdomains
maskEmail('[email protected]', { maskDomain: true });
// Output: 'us**@m***.g*****.com'

Browser Support

This library works in all modern browsers and Node.js environments that support ES2015+.

• ✅ Chrome (latest)
• ✅ Firefox (latest)
• ✅ Safari (latest)
• ✅ Edge (latest)
• ✅ Node.js 14+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker