@m8t-jacob/faker-pl

Fully typed TypeScript generator of realistic Polish test data: NIP, PESEL, REGON, IBAN, ID card numbers, names, companies, and addresses — every identifier ships with a genuinely correct checksum, not just the right shape.

• Strict TypeScript, ships dual ESM + CJS builds with .d.ts
• Zero runtime dependencies, no I/O — pure generation logic
• Deterministic: seed the shared PRNG with seed(n) for reproducible fixtures
• Tree-shakeable; import the whole package or a single subpath
• Not for real identifiers. Generated NIP/PESEL/REGON/IBAN/ID card numbers pass their checksum algorithms but do not correspond to real people, companies, or bank accounts. Never use them outside of testing.

Install

npm install @m8t-jacob/faker-pl

Quickstart

import { fakeAddress, fakeFullName, fakeNip, fakePesel, seed } from '@m8t-jacob/faker-pl';

seed(42); // optional: makes every call below reproducible

fakeNip(); // '5261040567'
fakePesel({ gender: 'female' }); // '90...' with an even 10th digit
fakeFullName(); // 'Adam Nowak'
fakeAddress(); // { street: 'Kwiatowa', houseNumber: '42', postalCode: '00-950', city: 'Warszawa' }

You can also import from a subpath if you only need one module, which keeps bundlers from pulling in the others:

import { fakeNip } from '@m8t-jacob/faker-pl/nip';
import { fakePesel } from '@m8t-jacob/faker-pl/pesel';
import { fakeRegon } from '@m8t-jacob/faker-pl/regon';
import { fakeIbanPl } from '@m8t-jacob/faker-pl/iban';
import { fakeIdCard } from '@m8t-jacob/faker-pl/idcard';
import { fakeFirstName, fakeFullName, fakeLastName } from '@m8t-jacob/faker-pl/person';
import { fakeCompanyName } from '@m8t-jacob/faker-pl/company';
import { fakeAddress } from '@m8t-jacob/faker-pl/address';

API

Identifiers

Function	Description
fakeNip(): string	10-digit NIP with a correct checksum (weights [6,5,7,2,3,4,5,6,7], mod 11)
fakePesel(options?): string	11-digit PESEL with a correct checksum, encoded birth date and gender digit
fakeRegon(options?): string	9-digit (or 14-digit, { long: true }) REGON with a correct checksum
fakeIbanPl(): string	PL + 26-digit IBAN with a correct ISO 13616 mod-97 checksum
fakeIdCard(): string	3 letters + 6-digit ID card (dowód osobisty) number with a correct checksum

fakePesel accepts { gender?: 'male' | 'female'; birthDate?: Date; minYear?: number; maxYear?: number }. If birthDate is omitted, a random date is chosen between minYear (default 1900) and maxYear (default: the current year). The century is encoded into the month per the official rules (1900s: +0, 2000s: +20, 2100s: +40, 2200s: +60, 1800s: +80).

fakeRegon accepts { long?: boolean }; when true, generates the 14-digit "local unit" form (a valid 9-digit REGON extended with 4 more digits and a second checksum).

People, companies, and addresses

Function	Description
fakeFirstName(gender?): string	Random Polish first name from a built-in list
fakeLastName(gender?): string	Random Polish surname, correctly inflected for gender
fakeFullName(gender?): string	"<first> <last>" with a consistent gender for both parts
fakeCompanyName(): string	Fictional core name + Polish legal form (e.g. Sp. z o.o.)
fakeAddress(): Address	{ street, houseNumber, postalCode, city }

All three gender parameters are optional; when omitted, gender is randomized (and, for fakeLastName/fakeFirstName, independently of any other call).

Determinism

Function	Description
seed(n: number): void	Seeds the shared PRNG (mulberry32) used by every fake* generator

Without calling seed, the PRNG is seeded from Math.random() on module load, so every process run produces different data. Call seed(n) with a fixed number at the start of a test (or test suite) to make every subsequent fake* call reproducible.

import { fakeNip, seed } from '@m8t-jacob/faker-pl';

seed(1);
fakeNip(); // always the same value, right after seeding with 1

fakerPL namespace object

For callers who prefer a single namespaced import:

import { fakerPL } from '@m8t-jacob/faker-pl';

fakerPL.seed(1);
fakerPL.pesel({ gender: 'female' });
fakerPL.address();

🇵🇱 Po polsku

@m8t-jacob/faker-pl to generator realistycznych polskich danych testowych: NIP, PESEL, REGON, IBAN, numery dowodów osobistych, imiona i nazwiska, nazwy firm oraz adresy. W przeciwieństwie do zwykłego losowania cyfr, każdy wygenerowany identyfikator ma poprawnie wyliczoną sumę kontrolną według oficjalnego algorytmu — dzięki temu dane nadają się do testowania walidacji, importów czy integracji, a nie tylko wyglądają podobnie. Biblioteka nie ma żadnych zależności runtime'owych i nie wykonuje operacji I/O. Wygenerowane numery nigdy nie odpowiadają realnym osobom, firmom ani rachunkom bankowym — służą wyłącznie do testów. Funkcja seed(n) pozwala uzyskać deterministyczne (powtarzalne) dane w testach.

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