GitHub - ekaone/mask-card: A pure masking utility, lightweight, zero-dependency TypeScript library for masking credit card numbers

A lightweight, zero-dependency TypeScript library for masking credit card numbers to protect sensitive payment information.

Features

🔒 PCI DSS friendly - Defaults align with common display guidelines (last 4 digits)
✨ Lightweight - Small footprint, zero dependencies
📦 TypeScript - Full type safety and IntelliSense support
🎨 Auto-format - maskCardAuto picks spacing by detected card brand (Visa, Amex, Diners, etc.)
🏷️ Card type detection - detectCardType and getCardTypeGrouping for BIN-style routing
✅ Luhn checks - isValidCardLuhn / isValidCard for checksum (and optional 13–19 length)
📋 Batch - maskCardBatch to mask many numbers with one options object
🧩 Helpers - getCardLast, getCardFirst, getCardLast4, getCardFirst6
⚙️ Flexible - Mask character, grouping, shortened masks, preserve separators, validation
🎯 Universal - Works with major brands (Visa, Mastercard, Amex, Discover, JCB, Diners, UnionPay, Maestro)

Installation

npm install @ekaone/mask-card

yarn add @ekaone/mask-card

pnpm add @ekaone/mask-card

Quick Start

import { maskCard } from '@ekaone/mask-card';

maskCard('4532123456789012');
// Output: '************9012'

Usage Examples

Basic Usage

import { maskCard } from '@ekaone/mask-card';

// Default masking (shows last 4 digits)
maskCard('4532123456789012');
// Output: '************9012'

// Accepts number input
maskCard(4532123456789012);
// Output: '************9012'

// Auto-strips formatting
maskCard('4532-1234-5678-9012');
// Output: '************9012'

Show Beginning Digits

Control how many digits to show at the start:

// Show first 4 digits (card type indicator)
maskCard('4532123456789012', { unmaskedStart: 4 });
// Output: '4532********9012'

// Show first 6 digits (BIN number)
maskCard('4532123456789012', { unmaskedStart: 6 });
// Output: '453212******9012'

// Show only first digit
maskCard('4532123456789012', { unmaskedStart: 1, unmaskedEnd: 0 });
// Output: '4***************'

Show Ending Digits

Control how many digits to show at the end:

// Show last 6 digits
maskCard('4532123456789012', { unmaskedEnd: 6 });
// Output: '**********789012'

// Hide all digits (complete masking)
maskCard('4532123456789012', { unmaskedStart: 0, unmaskedEnd: 0 });
// Output: '****************'

Custom Mask Character

Change the masking character from the default *:

maskCard('4532123456789012', { maskChar: '•' });
// Output: '••••••••••••9012'

maskCard('4532123456789012', { maskChar: 'X' });
// Output: 'XXXXXXXXXXXX9012'

maskCard('4532123456789012', { maskChar: '#' });
// Output: '############9012'

Grouping Digits

Add spacing for better readability:

// Group by 4 digits (standard format)
maskCard('4532123456789012', { grouping: 4 });
// Output: '**** **** **** 9012'

// Amex-style grouping (4-6-5)
maskCard('378282246310005', { grouping: [4, 6, 5] });
// Output: '**** ****** *0005'

// Group by 3 digits
maskCard('4532123456789012', { grouping: 3 });
// Output: '*** *** *** *** 9012'

Preserve Original Spacing

Maintain the formatting from the input:

maskCard('4532 1234 5678 9012', { preserveSpacing: true });
// Output: '**** **** **** 9012'

maskCard('4532-1234-5678-9012', { preserveSpacing: true });
// Output: '****-****-****-9012'

maskCard('4532.1234.5678.9012', { preserveSpacing: true });
// Output: '****.****.****.9012'

Shortened Mask

Show a shorter mask for compact displays:

maskCard('4532123456789012', { showLength: false });
// Output: '****9012'

maskCard('4532123456789012', { showLength: false, unmaskedEnd: 6 });
// Output: '****789012'

maskCard('4532123456789012', { showLength: false, unmaskedStart: 4 });
// Output: '4532****9012'

Input Validation

Validate card number length:

// Valid card (13-19 digits)
maskCard('4532123456789012', { validateInput: true });
// Output: '************9012'

// Invalid card (throws error)
try {
  maskCard('123', { validateInput: true });
} catch (error) {
  console.error(error.message);
  // Output: 'Invalid card number: must be 13-19 digits'
}

Combined Options

Mix and match options for custom behavior:

maskCard('4532123456789012', {
  maskChar: '•',
  unmaskedStart: 4,
  grouping: 4
});
// Output: '4532 •••• •••• 9012'

maskCard('4532123456789012', {
  maskChar: 'X',
  unmaskedEnd: 6,
  grouping: 4
});
// Output: 'XXXX XXXX XX78 9012'

Auto-format (`maskCardAuto`)

Detects the card brand from the number and applies brand-typical spacing (Amex 4-6-5, Diners 4-6-4, most others 4-4-4-4). Group sizes are adjusted for PAN lengths that are not 16 digits (e.g. 13- or 19-digit numbers). You can still pass grouping in options to override detection. preserveSpacing is always turned off for this helper so the output uses normalized spaces (not the input’s dashes or spaces).

import { maskCardAuto } from '@ekaone/mask-card';

maskCardAuto('4532123456789012');
// '**** **** **** 9012'

maskCardAuto('378282246310005');
// '**** ****** *0005'

maskCardAuto('4532123456789012', { maskChar: '•', unmaskedStart: 4 });
// '4532 •••• •••• 9012'

Batch masking (`maskCardBatch`)

Applies the same MaskCardOptions to every element. Non-arrays or nullish inputs return an empty array.

import { maskCardBatch } from '@ekaone/mask-card';

maskCardBatch(['4532123456789012', '5500000000000004'], { grouping: 4 });
// ['**** **** **** 9012', '**** **** **** 0004']

For brand-specific spacing on each row, map with maskCardAuto instead of a single grouping in batch.

Card type detection

import { detectCardType, getCardTypeGrouping } from '@ekaone/mask-card';

detectCardType('4532123456789012'); // 'visa'

getCardTypeGrouping('amex'); // [4, 6, 5]

detectCardType returns one of: visa, mastercard, amex, discover, jcb, diners, unionpay, maestro, or unknown (see CardType below). It ignores non-digits; empty or invalid input yields unknown.

Luhn validation

import { isValidCardLuhn, isValidCard } from '@ekaone/mask-card';

isValidCardLuhn('4532123456789014'); // true (mod-10 + formatting stripped)

isValidCard('4111111111111111'); // true — Luhn + length 13–19
isValidCard('4111111111111111', false); // true — Luhn only, skips length check

// All-zero strings fail intentionally (checksum would pass but not a real PAN)
isValidCardLuhn('0000000000000000'); // false

Helpers (first / last digits)

Useful for labels, BIN display, or “last four” copy (still follow your PCI / retention policies).

import { getCardLast, getCardFirst, getCardLast4, getCardFirst6 } from '@ekaone/mask-card';

getCardLast(4, '4532-1234-5678-9012'); // '9012'
getCardFirst(6, '4532123456789012');   // '453212'
getCardLast4('4532123456789012');      // '9012'
getCardFirst6('4532123456789012');     // '453212'

getCardLast(0, '4532123456789012');    // '' — counts ≤ 0 return ''

API Reference

`maskCard(input, options?)`

Masks a credit card number according to the provided options.

Parameter	Description
input	`CardInput` — string or number; non-digits are stripped
options	`MaskCardOptions` (optional)
returns	`MaskedResult` — masked string

`MaskCardOptions`

Option	Type	Default	Description
`maskChar`	`string`	`'*'`	Character used for masking
`unmaskedStart`	`number`	`0`	Digits to show at the start
`unmaskedEnd`	`number`	`4`	Digits to show at the end
`preserveSpacing`	`boolean`	`false`	Keep non-digit separators from the input (spaces, dashes, dots, etc.)
`grouping`	`number \| number[]`	`undefined`	Uniform group size (e.g. `4`) or pattern (e.g. `[4, 6, 5]`). Arrays are adjusted so the full masked length is covered
`showLength`	`boolean`	`true`	If `false`, collapse the middle to a short mask
`validateInput`	`boolean`	`false`	If `true`, require 13–19 digits or throw

`maskCardAuto(input, options?)`

Same options as maskCard, except grouping defaults from getCardTypeGrouping(detectCardType(input)) when omitted, and preserveSpacing is forced to false.

Parameter	Description
input	`CardInput`
options	`MaskCardOptions` (optional)
returns	`MaskedResult`

`maskCardBatch(cards, options?)`

Parameter	Description
cards	`CardInput[]`
options	`MaskCardOptions` (optional), applied to each item
returns	`MaskedResult[]` — empty array if `cards` is missing or not an array

`detectCardType(input)`

Parameter	Description
input	`CardInput`
returns	`CardType`

`getCardTypeGrouping(cardType)`

Parameter	Description
cardType	`CardType`
returns	`number[]` — e.g. `[4, 6, 5]` for Amex, `[4, 6, 4]` for Diners, `[4, 4, 4, 4]` for most other labels

`getCardLast(count, input)` / `getCardFirst(count, input)`

Parameter	Description
count	Positive finite number; `≤ 0` or non-finite → `''`
input	`CardInput`
returns	`string` — digits only (non-digits stripped); up to `count` from end or start

`getCardLast4(input)` / `getCardFirst6(input)`

Convenience wrappers: getCardLast(4, input) and getCardFirst(6, input).

Parameter	Description
input	`CardInput`
returns	`string` — digits only

`isValidCardLuhn(input)`

Luhn (mod 10) on digits after stripping non-digits. Requires at least two digits. Returns false for all-zero strings, nullish input, or failed checksum.

Parameter	Description
input	`CardInput`
returns	`boolean`

`isValidCard(input, checkLength?)`

Parameter	Description
input	`CardInput`
checkLength	`boolean` (default `true`) — if `true`, length must be 13–19 inclusive
returns	`boolean`

TypeScript types

export type MaskChar = string;

export type CardType =
  | 'visa'
  | 'mastercard'
  | 'amex'
  | 'discover'
  | 'jcb'
  | 'diners'
  | 'unionpay'
  | 'maestro'
  | 'unknown';

export interface MaskCardOptions {
  maskChar?: MaskChar;
  unmaskedStart?: number;
  unmaskedEnd?: number;
  preserveSpacing?: boolean;
  grouping?: number | number[];
  showLength?: boolean;
  validateInput?: boolean;
}

export type CardInput = string | number;
export type MaskedResult = string;

import {
  maskCard,
  maskCardAuto,
  maskCardBatch,
  detectCardType,
  getCardTypeGrouping,
  getCardLast4,
  isValidCard,
  type MaskCardOptions,
  type CardInput,
  type CardType,
} from '@ekaone/mask-card';

Real-World Use Cases

E-commerce Checkout Display

const cardNumber = '4532123456789012';
const maskedCard = maskCard(cardNumber);

console.log(`Payment method: Card ending in ${maskedCard.slice(-4)}`);
// Output: "Payment method: Card ending in 9012"

Banking App - Card Selection

const userCards = [
  { type: 'Visa', number: '4532123456789012' },
  { type: 'Mastercard', number: '5500000000000004' },
  { type: 'Amex', number: '378282246310005' }
];

userCards.forEach(card => {
  const masked = maskCard(card.number, { unmaskedStart: 4 });
  console.log(`${card.type}: ${masked}`);
});
// Output:
// Visa: 4532********9012
// Mastercard: 5500********0004
// Amex: 3782*******0005

Receipt/Invoice Printing

const receiptCard = '4532123456789012';
const formatted = maskCard(receiptCard, {
  maskChar: '•',
  grouping: 4
});

console.log(`Card: ${formatted}`);
// Output: "Card: •••• •••• •••• 9012"

Security Levels

function maskCardBySecurityLevel(card: string, level: 'low' | 'medium' | 'high') {
  switch (level) {
    case 'low':
      return maskCard(card, { unmaskedEnd: 8 });
    case 'medium':
      return maskCard(card, { unmaskedEnd: 4 });
    case 'high':
      return maskCard(card, { unmaskedStart: 0, unmaskedEnd: 0 });
  }
}

const card = '4532123456789012';
console.log('Low:   ', maskCardBySecurityLevel(card, 'low'));
console.log('Medium:', maskCardBySecurityLevel(card, 'medium'));
console.log('High:  ', maskCardBySecurityLevel(card, 'high'));
// Output:
// Low:    ********56789012
// Medium: ************9012
// High:   ****************

Customer Service Display

// Show more context for verification
function displayForSupport(cardNumber: string) {
  return maskCard(cardNumber, {
    unmaskedStart: 6,
    unmaskedEnd: 4,
    grouping: 4
  });
}

console.log(displayForSupport('4532123456789012'));
// Output: '4532 12** **** 9012'

Audit Logging

function logPayment(cardNumber: string, amount: number) {
  const maskedCard = maskCard(cardNumber, {
    unmaskedStart: 1,
    unmaskedEnd: 0
  });
  
  console.log(`Payment of $${amount} using card ${maskedCard}`);
}

logPayment('4532123456789012', 99.99);
// Output: "Payment of $99.99 using card 4***************"

Security & Compliance

PCI DSS Guidelines

This library follows PCI DSS (Payment Card Industry Data Security Standard) requirements for card display:

⚠️ PCI DSS Requirement 3.3: When displaying Primary Account Numbers (PAN):

Maximum visible: First 6 digits + Last 4 digits
Recommended: Last 4 digits only (default)

// ✅ PCI Compliant (Last 4 only - Default)
maskCard('4532123456789012');
// Output: '************9012'

// ✅ PCI Compliant (Maximum allowed: First 6 + Last 4)
maskCard('4532123456789012', { unmaskedStart: 6 });
// Output: '453212******9012'

// ⚠️ Exceeds PCI recommendation (use only for non-production)
maskCard('4532123456789012', { unmaskedStart: 8, unmaskedEnd: 4 });
// Output: '45321234****9012'

Security Best Practices

Never log unmasked card numbers in production
Use last 4 digits for user identification (default behavior)
Enable validation in production: { validateInput: true }
This library is for display only - Never store unmasked cards
Backend compliance - Ensure your server properly handles card data

Important Notice

🔒 This library is designed for display, logging, and light client-side validation. It does not:

Store card data securely
Tokenize cards for payment processing
Replace server-side validation (always verify payments on your backend)
Handle actual payment transactions by itself
Encrypt or hash card data

Luhn (isValidCardLuhn / isValidCard) checks the checksum only: a passing result does not mean the account is open, has funds, or was issued. Never log full PANs in production.

This is a pure masking utility that works in both frontend and backend environments (Node.js, browser, serverless functions, etc.).

Always ensure your systems comply with PCI DSS requirements when handling real payment card data.

Supported Card Types

Works with all major card brands:

// Visa (16 digits)
maskCard('4532123456789012');
// Output: '************9012'

// Mastercard (16 digits)
maskCard('5500000000000004');
// Output: '************0004'

// American Express (15 digits)
maskCard('378282246310005');
// Output: '***********0005'

// Discover (16 digits)
maskCard('6011000000000004');
// Output: '************0004'

// JCB (16 digits)
maskCard('3530111333300000');
// Output: '************0000'

// Diners Club (14 digits)
maskCard('30569309025904');
// Output: '**********5904'

Edge Cases

The library handles various edge cases gracefully:

// Very short numbers
maskCard('1234');
// Output: '1234' (all visible when length ≤ unmaskedEnd)

// Empty input
maskCard('');
// Output: ''

// Null/undefined
maskCard(null);
// Output: ''

// Mixed characters (auto-strips non-digits)
maskCard('4532-ABCD-5678-9012');
// Output: '************9012'

// Whitespace only
maskCard('   ');
// Output: ''

// Very long numbers
maskCard('45321234567890123456789');
// Output: '*******************6789' (validates with validateInput: true)

Performance

⚡ Lightweight: < 2KB gzipped (minified)
🚀 Zero dependencies
💨 Fast execution (< 1ms for typical cards)
🌳 Tree-shakeable

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+

TypeScript Support

Full TypeScript support with types exported from the package entry (see TypeScript types under API Reference).

Contributing

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

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

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run examples
npm run example

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.cursor/skills/mask-card		.cursor/skills/mask-card
.github/workflows		.github/workflows
examples		examples
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Features

Installation

Quick Start

Usage Examples

Basic Usage

Show Beginning Digits

Show Ending Digits

Custom Mask Character

Grouping Digits

Preserve Original Spacing

Shortened Mask

Input Validation

Combined Options

Auto-format (maskCardAuto)

Batch masking (maskCardBatch)

Card type detection

Luhn validation

Helpers (first / last digits)

API Reference

maskCard(input, options?)

MaskCardOptions

maskCardAuto(input, options?)

maskCardBatch(cards, options?)

detectCardType(input)

getCardTypeGrouping(cardType)

getCardLast(count, input) / getCardFirst(count, input)

getCardLast4(input) / getCardFirst6(input)

isValidCardLuhn(input)

isValidCard(input, checkLength?)

TypeScript types

Real-World Use Cases

E-commerce Checkout Display

Banking App - Card Selection

Receipt/Invoice Printing

Security Levels

Customer Service Display

Audit Logging

Security & Compliance

PCI DSS Guidelines

Security Best Practices

Important Notice

Supported Card Types

Edge Cases

Performance

Browser Support

TypeScript Support

Contributing

Development

License

Links

Related Packages

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Auto-format (`maskCardAuto`)

Batch masking (`maskCardBatch`)

`maskCard(input, options?)`

`MaskCardOptions`

`maskCardAuto(input, options?)`

`maskCardBatch(cards, options?)`

`detectCardType(input)`

`getCardTypeGrouping(cardType)`

`getCardLast(count, input)` / `getCardFirst(count, input)`

`getCardLast4(input)` / `getCardFirst6(input)`

`isValidCardLuhn(input)`

`isValidCard(input, checkLength?)`

Packages