Polish Validators

This npm package provides a series of validation functions to check the validity of common Polish identifiers, international standards, and other regulated numbers. Each function is designed to handle specific formatting rules and checksum requirements, making it suitable for validating a range of national and international numbers.

Note: All functions that check validity also have their counterparts that check invalidity. For example, both isPeselValid and isPeselInvalid are available.

Highlights

Supports TypeScript!
Includes full JSDoc documentation
Includes 100+ unit tests

Installation

npm install polish-validators --save

Usage

import * from 'polish-validators';
// or
import { /* function names here */ } from 'polish-validators';

PESEL

isPeselValid

isPeselValid(pesel: string): boolean

Validates a PESEL (Polish national identification number) string.

This function validates the control number and ensures the birthdate is also valid.

Note: This validator isn't perfect. Some invalid numbers might still return true. For example, people born before the year 1931 might accidentally swap their birthyear and birthday and the function will still pass. 1st, 5th, and 9th or 2nd, 6th, and 10th numbers may also be swapped while still passing. There is nothing that can really be done about that, other than validating against a database of PESEL numbers.

Parameters:
- pesel: The 11-digit PESEL number as a string.
Returns: true if the PESEL is valid; false otherwise.

getBirthdateFromPesel

getBirthdateFromPesel(pesel: string): Date

Extracts the birthdate from a valid PESEL number.

Parameters:
- pesel: The 11-digit PESEL number as a string.
Returns: A Date object containing the year, month, and day extracted from the PESEL. Throws an error if an invalid PESEL is given.

extractSexFromPesel

extractSexFromPesel(pesel: string): PeselSex

Extracts the sex from a valid PESEL number.

Parameters:
- pesel: The 11-digit PESEL number as a string.
Returns: Either "male" or "female". Throws an error if an invalid PESEL is given.

NIP

isNipValid

isNipValid(nip: string): boolean

Validates a NIP (Polish tax identification number) string. This function checks the format of the NIP, ensuring it has either 10 or 13 digits, is not all zeros, and meets a specific checksum requirement. Any dashes or whitespace are ignored.

Parameters:
- nip: The NIP number as a string, which may include dashes or whitespace.
Returns: true if the NIP is valid; false otherwise.

formatNip

formatNip(nip: string, format: NipFormat = NipFormat.Format3223): string

Formats a valid NIP into the specified format.

Parameters:
- nip: The NIP as a string, which may include dashes or whitespace.
- format: The format to be applied. Can be either "3-2-2-3" or "3-3-2-2". Optional, defaults to "3-2-2-3".
Returns: the NIP formatted according to the given format, or "Nieprawidłowy NIP" if the NIP is invalid.

REGON

isRegonValid

isRegonValid(regon: string): boolean

Validates a REGON (Polish National Business Registry Number) string. The function checks for 9- or 14-digit formats and calculates a checksum according to REGON requirements. Any dashes or whitespace are ignored.

Parameters:
- regon: The REGON number as a string, which may include dashes or whitespace.
Returns: true if the REGON is valid; false otherwise.

Postal Code (Kod Pocztowy)

isPostalCodeValid

isPostalCodeValid(code: string): boolean

Validates a Polish postal code format. This function checks that the code follows the format XX-XXX, where each X is a digit. The dash in the format is optional, but putting a dash in the wrong place will result in the code being invalid.

This function does not validate whether a code actually exists. There are over 40,000 unique postal codes in Poland, and they do not follow a specific pattern.

Parameters:
- code: The postal code as a string.
Returns: true if the postal code format is valid; false otherwise.

ID Card Number (Seria i Numer Dowodu Osobistego)

isIdCardNumberValid

isIdCardNumberValid(number: string): boolean

Validates a Polish ID card number. The function verifies that the number matches a specific pattern (AAA XXXXXX where each A is any letter a-z and each X is any digit) and validates the control digit based on a checksum calculation. Any dashes or whitespace are ignored.

Parameters:
- number: The ID card number as a string.
Returns: true if the ID card number is valid; false otherwise.

Doctor Number (Numer PWK Lekarza)

isDoctorNumberValid

isDoctorNumberValid(number: string): boolean

Validates a doctor's identifier in Poland, ensuring it has 7 digits and passes a checksum validation. Any characters other than digits will result in the identifier being invalid.

Parameters:
- number: The doctor's identification number as a string.
Returns: true if the doctor's number is valid; false otherwise.

Credit Card Number (Numer Karty Płatniczej)

isCreditCardNumberValid

isCreditCardNumberValid(number: string): boolean

Validates a credit card number using the Luhn algorithm. The function requires a 16-digit credit card number. Any dashes or whitespace are ignored.

Parameters:
- number: The 16-digit credit card number as a string.
Returns: true if the credit card number is valid; false otherwise.

getCreditCardType

getCreditCardType(number: string): CreditCardType | null

Determines the type of credit card based on the first digit of the card number.

Parameters:
- number: The credit card number as a string.
Returns: The credit card type (CreditCardType), or null if the type cannot be determined.

CreditCardType

The CreditCardType is a custom object-based enum, defined as:

export const CreditCardType = {
  Airline: 'airline',
  ClubCard: 'clubcard',
  Visa: 'Visa',
  MasterCard: 'mastercard',
  Finances: 'finances',
  Fuel: 'fuel',
  Telecommunication: 'telecommunication',
  Other: 'other',
} as const;
export type CreditCardType = (typeof CreditCardType)[keyof typeof CreditCardType];

IBAN

isIbanValid

isIbanValid(iban: string): boolean

Validates an International Bank Account Number (IBAN). The function checks for proper length, format, and passes the IBAN checksum requirements. In the case of IBANs starting with PL (or with no country code), the 3rd-5th digits are validated against a list of Polish banks. Any whitespace is ignored, but other characters will result in the IBAN being invalid.

Parameters:
- iban: The IBAN number as a string, with or without spaces.
Returns: true if the IBAN is valid; false otherwise.

getCountryIbanDataFromIban

getCountryIbanDataFromIban(iban: string): { country: string; length: number } | null

Extracts country-specific information from the IBAN.

Parameters:
- iban: The IBAN number as a string.
Returns: An object containing the country name and IBAN length for the given IBAN, or null if not valid.

getBankNameFromIban

getBankNameFromIban(iban: string): string | null

Fetches the bank name based on the IBAN, specifically for Polish IBANs. If a non-Polish IBAN is supplied, it will always return null. Bank names are all in Polish.

Parameters:
- iban: The IBAN number as a string.
Returns: The bank name as a string, or null if not available.

IMEI

isImeiValid

isImeiValid(imei: string): boolean

Validates an IMEI (International Mobile Equipment Identity) number, using the Luhn algorithm. Checks that the IMEI is 15 digits. Any dashes, slashes, or whitespace are ignored.

Parameters:
- imei: The 15-digit IMEI number as a string.
Returns: true if the IMEI is valid; false otherwise.

ISBN

isIsbnValid

isIsbnValid(isbn: string): boolean

Validates an ISBN (International Standard Book Number), supporting both ISBN-10 and ISBN-13 formats. Ensures that the ISBN has the correct format and checksum. Any dashes or whitespace are ignored.

Parameters:
- isbn: The ISBN as a string.
Returns: true if the ISBN is valid; false otherwise.

getRegionNameFromIsbn

getRegionNameFromIsbn(isbn: string): string | null

Determines the region name associated with an ISBN based on its prefix. Region names are all in Polish.

Parameters:
- isbn: The ISBN as a string.
Returns: The region name as a string, or null if not recognized.