Skip to content
Numerik JS Numerik JS

Numerik JS

Validate and parse Polish identification numbers with rich value objects and detailed failure reasons.
Get started View on GitHub

Overview

Section titled “Overview”

@slashlab/numerik-js is a zero-dependency TypeScript library. Validation tells you why input failed, not just that it failed. Types are bundled — no @types/ package needed.

Personal

Section titled “Personal”

PESEL

Validates and parses Poland’s universal citizen identifier. Extracts birth date, gender, century, age, and ordinal number directly from the number.

ID Card

Validates Polish national identity card numbers (dowód osobisty). Three-letter series plus six digits, validated with the ICAO 9303 weighted checksum.

Passport

Validates Polish passport numbers. Two-letter series plus seven digits, validated with the same ICAO 9303 algorithm used in travel documents globally.

Tax & Business

Section titled “Tax & Business”

NIP

Validates tax identification numbers for individuals and legal entities. Returns the issuing tax office code and formatted display form.

VAT-EU

Validates intra-EU VAT numbers for Polish taxpayers (PL + NIP). Strips the country prefix and applies the NIP MOD-11 algorithm. Returns the NIP and formatted display form.

REGON

Handles both 9-digit (individual) and 14-digit (legal entity with local unit) REGON numbers, including multi-stage checksum validation.

KRS

Validates court register numbers with automatic zero-padding normalisation. Documents the offline vs. online verification limitation.

Banking

Section titled “Banking”

NRB

Validates Polish bank account numbers using the MOD-97 checksum. Accepts raw, spaced, and IBAN-prefixed formats. Returns sort code, bank code, and account number.

IBAN

Validates Polish IBANs (PL + NRB). Requires the country prefix and applies MOD-97. Returns NRB, sort code, bank code, and account number.

At a glance

Section titled “At a glance”
import { Numerik, Gender } from '@slashlab/numerik-js'


// Simple boolean check
Numerik.pesel().isValid('92060512186')   // true
Numerik.nip().isValid('5260250274')      // true


// Rich result with failure details
const result = Numerik.pesel().validate('92060512185') // wrong checksum digit
result.isFailed()                        // true
result.getFirstFailure()?.reason         // ValidationFailureReason.InvalidChecksum


// Parse to a value object
const pesel = Numerik.pesel().parse('92060512186')
pesel.getBirthDate()                     // Date — 1992-06-05
pesel.getGender()                        // Gender.Female
pesel.getAge()                           // calculated from today
pesel.isAdult()                          // true

Key properties

Section titled “Key properties”
  • Zero production dependencies — core package has no runtime dependencies.
  • Bundled types — TypeScript types ship with the package; no @types/ needed.
  • ESM + CJS — ships both formats; works in Node, Deno, Bun, and bundlers.
  • Rich failure reasons — ValidationFailureReason enum covers format, checksum, encoded-date, and semantic failures.
  • Zod integration — optional Zod schemas via the /zod sub-path export (requires zod peer dependency).
  • Input length guard — inputs over 32 characters are rejected immediately.