@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