Instalacja i szybki start

Wymagania

• Node.js 22 lub nowszy (lub dowolne środowisko wykonawcze obsługujące moduły ES i nowoczesne Date)
• TypeScript 5.0+ (opcjonalnie — biblioteka dostarcza dołączone typy i działa w zwykłym JavaScript)

Instalacja

1. Zainstaluj bibliotekę

   npm

   npm install @slashlab/numerik-js

   pnpm

   pnpm add @slashlab/numerik-js

   yarn

   yarn add @slashlab/numerik-js

   bun

   bun add @slashlab/numerik-js

2. Brak konfiguracji

   Biblioteka dostarcza buildy ESM i CJS. Nie ma kroku konfiguracji, pliku konfiguracyjnego ani potrzeby tree-shakingu.

3. Użyj

   import { Numerik } from '@slashlab/numerik-js'
   
   Numerik.pesel().isValid('92060512186') // true

Szybki start

Sprawdzenie poprawności

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

Numerik.pesel().isValid('92060512186')                    // true
Numerik.idCard().isValid('ABC123454')                     // true
Numerik.passport().isValid('AB1234564')                   // true
Numerik.nip().isValid('5260250274')                       // true
Numerik.vatEu().isValid('PL5260250274')                   // true
Numerik.regon().isValid('850518457')                      // true
Numerik.krs().isValid('0000127206')                       // true
Numerik.nrb().isValid('61102010260000000000000000')       // true
Numerik.iban().isValid('PL61102010260000000000000000')    // true

Szczegółowa walidacja

validate() nigdy nie rzuca wyjątku. Zwraca ValidationResult z listą błędów, gdy walidacja nie przejdzie.

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

const result = Numerik.pesel().validate('92060512186')
result.isValid               // true
result.failures              // []

const failed = Numerik.pesel().validate('00000000000')
failed.isFailed()            // true
failed.getFirstFailure()?.reason         // ValidationFailureReason.AllZeros
failed.getFirstFailure()?.message        // komunikat w języku angielskim

Parsowanie do obiektu z danymi

W przypadku sukcesu parse() zwraca obiekt wartości. W przypadku niepowodzenia rzuca ValidationException.

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

const pesel = Numerik.pesel().parse('92060512186')
pesel.getBirthDate()         // Date — 1992-06-05
pesel.getGender()            // Gender.Female
pesel.getAge()               // number — obliczane na bieżąco
pesel.isAdult()              // true

Użyj tryParse(), gdy wolisz null zamiast wyjątku w przypadku niepowodzenia:

const pesel = Numerik.pesel().tryParse('bad-input') // null

Wybór właściwej metody

Metoda	Zwraca	Rzuca	Kiedy używać
isValid()	boolean	nigdy	Szybkie sprawdzenie poprawności
validate()	ValidationResult	nigdy	Gdy potrzebujesz powodu błędu
parse()	obiekt wartości	ValidationException	Gdy potrzebujesz wyodrębnionych danych i wolisz wyjątki
tryParse()	obiekt wartości lub null	nigdy	Gdy potrzebujesz wyodrębnionych danych, ale wolisz null zamiast wyjątku

Tryb ścisły

Wszystkie identyfikatory obsługują flagę strict (domyślnie true). W trybie ścisłym stosowane są dodatkowe sprawdzenia semantyczne — na przykład PESEL odrzuca przyszłe daty urodzenia i wzorce, w których wszystkie cyfry są identyczne.

// Tryb ścisły włączony (domyślnie)
Numerik.pesel().isValid('11111111111')          // false — wszystkie cyfry identyczne

// Tryb ścisły wyłączony
Numerik.pesel(false).isValid('11111111111')     // true jeśli suma kontrolna przejdzie

// Sprawdź, czy tryb ścisły jest aktywny
Numerik.pesel().isStrict()    // true
Numerik.pesel(false).isStrict() // false

Integracja z Zod

Opcjonalna dodatkowa ścieżka importu /zod dostarcza schematy Zod dla wszystkich identyfikatorów. Wymaga zod jako zewnętrznej zależności.

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

// Waliduje ciąg znaków — błędy pojawiają się jako problemy Zod
const schema = peselSchema()
schema.parse('92060512186') // '92060512186'

// Waliduje i przekształca do obiektu wartości Pesel
const parseSchema = peselParseSchema()
const pesel = parseSchema.parse('92060512186') // instancja Pesel
pesel.getBirthDate() // Date

Następne kroki

• Przeglądaj dokumentację PESEL, Dowód osobisty, Paszport, NIP, VAT-EU, REGON, KRS, NRB lub IBAN z pełną listą metod.
• Zobacz Wyniki walidacji, Obsługę błędów, Algorytmy i Zod w Przewodniku, by poznać wszystko poza podstawami.