numerik-js

Validate and parse Polish identification numbers — PESEL, NIP, REGON, KRS, NRB, VAT-EU, IBAN, ID Card, and Passport. Rich value objects, detailed error reasons, zero production dependencies. TypeScript-first.

JavaScript/TypeScript port of slashlab/numerik (PHP).

Installation

npm install @slashlab/numerik-js
# or
pnpm add @slashlab/numerik-js

Quick Start

import { Numerik } from '@slashlab/numerik-js'

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

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

// Parse to value object
const pesel = Numerik.pesel().parse('92060512186')
pesel.getBirthDate()    // Date object: 1992-06-05
pesel.getGender()       // Gender.Female
pesel.isAdult()         // true

// Try-parse (returns null on failure instead of throwing)
const parsed = Numerik.nip().tryParse('5260250274')
parsed?.getFormatted()  // '526-025-02-74'

Strict mode

All identifiers accept an optional strict flag (default: true). In non-strict mode formatting variations (spaces, dashes) are accepted:

Numerik.nip(false).isValid('526 025 02 74')  // true
Numerik.nip(true).isValid('526 025 02 74')   // false

Zod integration

import { peselSchema, nipParseSchema } from '@slashlab/numerik-js/zod'
import { z } from 'zod'

const schema = z.object({
  pesel: peselSchema(),           // validates, keeps string
  nip: nipParseSchema(),          // validates and transforms to Nip value object
})

Supported identifiers

Group	Identifier	Class
Personal	PESEL	PeselIdentifier
Personal	ID Card	IdCardIdentifier
Personal	Passport	PassportIdentifier
Tax	NIP	NipIdentifier
Tax	VAT-EU	VatEuIdentifier
Business	REGON	RegonIdentifier
Business	KRS	KrsIdentifier
Banking	NRB	NrbIdentifier
Banking	IBAN	IbanIdentifier

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT — see LICENSE.

---

If this saved you time → ☕ Buy me a coffee