test-numbers-generator

Generate and validate European test phone numbers (mobile and landline) in safe, non-existent ranges.

Features

• 📱 Mobile Numbers: Generate test mobile numbers for 17 European and North African countries
• 🏠 Landline Numbers: Generate test landline numbers for all supported countries
• 🆔 Dutch Identifiers: Generate and validate Dutch BSN, IBAN, KvK numbers
• 📮 Postcodes: Generate and validate postcodes for multiple countries
• 🌍 Real Address Data: Fetch real Dutch postcodes and address data using the PDOK Locatieserver API
• 🔍 Address Validation: Check address details by postcode and house number
• 🏘️ Place Names: Fetch random valid Dutch place names

Supported Countries

🇳🇱 Netherlands • 🇩🇪 Germany • 🇧🇪 Belgium • 🇫🇷 France • 🇬🇧 United Kingdom • 🇪🇸 Spain • 🇮🇹 Italy • 🇦🇹 Austria • 🇨🇭 Switzerland • 🇸🇪 Sweden • 🇳🇴 Norway • 🇩🇰 Denmark • 🇫🇮 Finland • 🇵🇹 Portugal • 🇮🇪 Ireland • 🇹🇷 Turkey • 🇲🇦 Morocco

Installation

npm install test-numbers-generator

Usage

Mobile Phone Numbers

import { generateTestMobileNumber, isTestMobileNumber } from 'test-numbers-generator';

// Generate a mobile number (uses international 00 prefix)
const mobileNL = generateTestMobileNumber.Netherlands();
console.log(mobileNL); // "0031 6 12345678"

const mobileDE = generateTestMobileNumber.Germany();
console.log(mobileDE); // "0049 015 1234567" (or 016/017)

const mobileFR = generateTestMobileNumber.France();
console.log(mobileFR); // "0033 6 12345678" (or 7)

// Validate mobile numbers
console.log(isTestMobileNumber.Netherlands(mobileNL)); // true
console.log(isTestMobileNumber.Germany("0049 018 1234567")); // false (invalid prefix)

Landline Phone Numbers

import { generateTestLandlineNumber, isTestLandlineNumber } from 'test-numbers-generator';

const landlineNL = generateTestLandlineNumber.Netherlands();
console.log(landlineNL); // "010 991234567"

const landlineDE = generateTestLandlineNumber.Germany();
console.log(landlineDE); // "030 9912345"

// Validate landline numbers
console.log(isTestLandlineNumber.Netherlands(landlineNL)); // true

Dutch BSN (Burgerservicenummer)

import { generateTestBSN, isValidBSN } from 'test-numbers-generator';

const bsn = generateTestBSN();
console.log(bsn); // "999012345" (test range)
console.log(isValidBSN(bsn)); // true
console.log(isValidBSN("123456789")); // false (invalid checksum)

Dutch IBAN

import { generateTestDutchIBAN, isValidDutchIBAN } from 'test-numbers-generator';

const iban = generateTestDutchIBAN();
console.log(iban); // "NL99INGB0123456789"
console.log(isValidDutchIBAN(iban)); // true

KvK Numbers

import { generateTestKvKNumber } from 'test-numbers-generator';

const kvk = generateTestKvKNumber();
console.log(kvk); // "12345678"

Postcodes

import { generateTestPostcode, isValidDutchPostcode } from 'test-numbers-generator';

const postcodeNL = generateTestPostcode.Netherlands();
console.log(postcodeNL); // "9999 XX"
console.log(isValidDutchPostcode(postcodeNL)); // true

Real Dutch Address Data (PDOK API)

import { 
  fetchRandomDutchPostcodeFromPDOK, 
  checkAdresByPostcodeHuisnummer,
  fetchPostcodesMetHuisnummerToevoeging,
  getRandomPlaatsnaam 
} from 'test-numbers-generator';

// Fetch a real, existing Dutch postcode
const realPostcode = await fetchRandomDutchPostcodeFromPDOK();
console.log(realPostcode); // "1011 AC"

// Check address details by postcode and house number
const address = await checkAdresByPostcodeHuisnummer('1011 AC', 1);
console.log(address); // { straatnaam: 'Prins Hendrikkade', woonplaats: 'Amsterdam' }

// Find postcodes with house number additions (like 12A, 12-B)
const postcodesWithAdditions = await fetchPostcodesMetHuisnummerToevoeging('Amsterdam', 20);
console.log(postcodesWithAdditions); // Set of postcodes

// Get a random valid Dutch place name
const placeName = await getRandomPlaatsnaam();
console.log(placeName); // "Amsterdam"

Mobile Number Format Details

All mobile numbers are generated using the international 00 prefix format and follow official country specifications:

• 🇳🇱 Netherlands: 0031 6 xxxxxxxx (9 digits after 06)
• 🇩🇪 Germany: 0049 015/016/017 xxxxxxx (10-11 digits after country code)
• 🇧🇪 Belgium: 0032 047/048/049 xxxxxxx (9 digits total)
• 🇫🇷 France: 0033 6/7 xxxxxxxx (8 digits after prefix)
• 🇬🇧 United Kingdom: 0044 7 xxxxxxxxx (9 digits after 7)
• 🇪🇸 Spain: 0034 6/7xxxxxxxx (9 digits total)
• ��🇹 Italy: 0039 3xx xxxxxxx (10 digits total)
• 🇦🇹 Austria: 0043 06xx xxxxxxx (10-13 digits total)
• 🇨🇭 Switzerland: 0041 07x xxxxxx (9 digits total)
• 🇸🇪 Sweden: 0046 7 xxxxxxxx (8 digits after 7)
• 🇳🇴 Norway: 0047 4x/9x xxxxxx (8 digits total)
• 🇩🇰 Denmark: 0045 xxxxxxxx (8 digits, various prefixes)
• 🇫🇮 Finland: 00358 04x/050 xxxxxx (9-10 digits total)
• 🇵🇹 Portugal: 00351 9x xxxxxxx (9 digits total)
• 🇮🇪 Ireland: 00353 08x xxxxxx (9 digits total)
• 🇹🇷 Turkey: 0090 053x xxxxxx (10 digits total)
• 🇲🇦 Morocco: 00212 06/07 xxxxxxx (9 digits total)

API Reference

Types

type SupportedCountry = 
  | 'Netherlands' | 'Germany' | 'Belgium' | 'France' | 'UnitedKingdom' 
  | 'Spain' | 'Italy' | 'Austria' | 'Switzerland' | 'Sweden' 
  | 'Norway' | 'Denmark' | 'Finland' | 'Portugal' | 'Ireland' 
  | 'Turkey' | 'Morocco';

type PhoneNumberType = 'mobile' | 'landline';

Functions

// Phone number generators
generateTestMobileNumber: Record<SupportedCountry, () => string>
generateTestLandlineNumber: Record<SupportedCountry, () => string>

// Phone number validators
isTestMobileNumber: Record<SupportedCountry, (number: string) => boolean>
isTestLandlineNumber: Record<SupportedCountry, (number: string) => boolean>
isTestPhoneNumber(number: string): boolean

// Dutch identifiers
generateTestBSN(): string
isValidBSN(bsn: string): boolean
generateTestDutchIBAN(): string
isValidDutchIBAN(iban: string): boolean
generateTestKvKNumber(): string

// Postcodes
generateTestPostcode: Record<SupportedPostcodeCountry, () => string>
isValidDutchPostcode(postcode: string): boolean

// Real address data (async)
fetchRandomDutchPostcodeFromPDOK(): Promise<string>
checkAdresByPostcodeHuisnummer(postcode: string, huisnummer: number): Promise<AddressInfo>
fetchPostcodesMetHuisnummerToevoeging(plaats: string, limit?: number): Promise<Set<string>>
getRandomPlaatsnaam(): Promise<string>

Test Numbers Policy

All generated numbers are designed to be safe for testing:

• 📱 Mobile numbers use realistic formats but are in test ranges
• 🏠 Landline numbers include "99" sequences to indicate test numbers
• 🆔 BSN numbers use the 999xxxxxx test range
• 🏦 IBAN numbers use test bank codes
• 📮 Postcodes use 9999 XX format for tests

⚠️ Important: These numbers should only be used for testing purposes and are not real, active numbers.

Contributing

Contributions are welcome! Please ensure all tests pass:

npm test
npm run test:coverage

License

MIT