@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