@m8t-jacob/validate

Zero-dependency, fully typed validators for Polish identifiers: NIP, PESEL, REGON, KRS, IBAN/NRB and ID card numbers.

• Zero runtime dependencies
• Strict TypeScript, ships dual ESM + CJS builds with .d.ts
• Tree-shakeable, pure functions — nothing throws
• Accepts loosely formatted input (spaces, dashes, PL prefixes)
• Optional Zod adapter (@m8t-jacob/validate/zod)

Install

npm install @m8t-jacob/validate

Quickstart

import { isValidNip, isValidPesel, formatNip } from '@m8t-jacob/validate';

isValidNip('123-456-32-18'); // true
isValidPesel('90010100054'); // true
formatNip('1234563218'); // '123-456-32-18'

API

Function	Description
isValidNip(value: string): boolean	Validates a NIP (tax ID) checksum
isValidPesel(value: string): boolean	Validates a PESEL checksum and embedded birth date
isValidRegon(value: string): boolean	Validates a 9- or 14-digit REGON checksum
isValidKrs(value: string): boolean	Validates a KRS (court register) number format
isValidIbanPl(value: string): boolean	Validates a Polish IBAN or bare NRB (ISO 13616 mod-97)
isValidIdCard(value: string): boolean	Validates an ID card (dowód osobisty) number checksum
getPeselBirthDate(pesel: string): Date | null	Extracts the birth date encoded in a valid PESEL
getPeselGender(pesel): 'male' | 'female' | null	Extracts the gender encoded in a valid PESEL
normalizeNip(value: string): string	Strips formatting/PL prefix from a NIP
normalizePesel(value: string): string	Strips formatting from a PESEL
normalizeRegon(value: string): string	Strips formatting from a REGON
normalizeKrs(value: string): string	Strips formatting from a KRS number
normalizeIban(value: string): string	Uppercases and strips formatting from an IBAN/NRB
normalizeIdCard(value: string): string	Uppercases and strips formatting from an ID card number
formatNip(value: string): string	Formats a NIP as XXX-XXX-XX-XX

All isValid* functions accept arbitrarily formatted strings and never throw — invalid or garbage input (including non-string values at runtime) simply returns false.

Zod adapter

Install zod yourself (it's an optional peer dependency) and import from the /zod subpath:

npm install zod

import { z } from 'zod';
import { zNip, zPesel } from '@m8t-jacob/validate/zod';

const schema = z.object({
  nip: zNip(),
  pesel: zPesel({ message: 'Nieprawidłowy numer PESEL' }),
});

schema.parse({ nip: '123-456-32-18', pesel: '90010100054' });

Available schemas: zNip(), zPesel(), zRegon(), zKrs(), zIbanPl(), zIdCard(). Each accepts an optional { message?: string } to override the default bilingual (PL/EN) error message.

🇵🇱 Po polsku

@m8t-jacob/validate to biblioteka bez zależności do walidacji polskich identyfikatorów: NIP, PESEL, REGON, KRS, IBAN/NRB oraz numeru dowodu osobistego. Wszystkie funkcje akceptują dowolnie sformatowany tekst (spacje, myślniki, prefiks PL) i nigdy nie rzucają wyjątków — dla nieprawidłowych danych zwracają false/null. Opcjonalny adapter do Zod (/zod) pozwala łatwo wpiąć walidację w istniejące schematy.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the development workflow and GOOD_FIRST_ISSUES.md for ideas if you're looking for a place to start. This project follows the Contributor Covenant.

License

MIT © 2026 Jakub Jagiełło