Skip to content

docs: update README to reflect current API surface #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jan-kubica merged 2 commits into from
Mar 25, 2026
Merged

docs: update README to reflect current API surface #75

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4332df
docs: update README to reflect current API surface
jan-kubica Mar 25, 2026
25988cb
fix: correct detectNetwork usage and country count
jan-kubica Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
258 changes: 220 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,43 +45,190 @@ iban.validate("CZ65 0800 0000 1920 0014 5399");

## Supported Identifiers

### Czech Republic

| Identifier | Module | Type |
| ----------------- | -------- | ------- |
| IČO (Company ID) | `cz/ico` | company |
| DIČ (VAT Number) | `cz/dic` | any |
| RČ (Birth Number) | `cz/rc` | person |

### Slovakia

| Identifier | Module | Type |
| ------------------- | -------- | ------- |
| RČ (Birth Number) | `sk/rc` | person |
| IČ DPH (VAT Number) | `sk/dic` | company |

### Germany

| Identifier | Module | Type |
| ------------------ | --------- | ------- |
| USt-IdNr. (VAT ID) | `de/vat` | company |
| IdNr (Tax ID) | `de/idnr` | person |

### Poland

| Identifier | Module | Type |
| ------------------------- | ---------- | ------- |
| NIP (VAT Number) | `pl/nip` | company |
| PESEL (National ID) | `pl/pesel` | person |
| REGON (Business Register) | `pl/regon` | company |

### International

| Identifier | Module | Type |
| ------------------ | ------ | ------- |
| IBAN | `iban` | any |
| Credit Card (Luhn) | `luhn` | any |
| LEI | `lei` | company |
| Identifier | Module | Type |
| ------------------ | ------------ | ------- |
| BIC (ISO 9362) | `bic` | company |
| Credit Card (Luhn) | `creditcard` | any |
| IBAN | `iban` | any |
| ISIN (ISO 6166) | `isin` | any |
| LEI | `lei` | company |
| Luhn | `luhn` | any |
| EU VAT | `eu/vat` | company |

### Countries

<details>
<summary>96 countries supported (click to expand)</summary>

| Country | Module | Identifier |
| ------------------------- | ------------------ | ------------ |
| AD Andorra | `ad/nrt` | NRT |
| AE United Arab Emirates | `ae/eid` | EID |
| AI Anguilla | `ai/tin` | TIN |
| AL Albania | `al/nipt` | NIPT |
| AM Armenia | `am/tin` | TIN |
| AR Argentina | `ar/cbu` | CBU |
| | `ar/cuit` | CUIT |
| | `ar/dni` | DNI |
| AT Austria | `at/businessid` | FN |
| | `at/tin` | TIN |
| | `at/uid` | UID |
| | `at/vnr` | VNR |
| AU Australia | `au/abn` | ABN |
| | `au/acn` | ACN |
| | `au/tfn` | TFN |
| AZ Azerbaijan | `az/voen` | VÖEN |
| BA Bosnia and Herzegovina | `ba/jmbg` | JMBG |
| BD Bangladesh | `bd/nid` | NID |
| BE Belgium | `be/bis` | BIS |
| | `be/nn` | NN |
| | `be/vat` | BTW |
| BG Bulgaria | `bg/egn` | ЕГН |
| | `bg/pnf` | ЛНЧ |
| | `bg/vat` | ИН по ДДС |
| BH Bahrain | `bh/cpr` | CPR |
| BR Brazil | `br/cnpj` | CNPJ |
| | `br/cpf` | CPF |
| BY Belarus | `by/unp` | УНП |
| BZ Belize | `bz/tin` | TIN |
| CA Canada | `ca/bn` | BN |
| | `ca/sin` | SIN |
| CH Switzerland | `ch/ssn` | AHV |
| | `ch/uid` | UID |
| | `ch/vat` | MWST |
| CL Chile | `cl/rut` | RUT |
| CN China | `cn/ric` | RIC |
| | `cn/uscc` | USCC |
| CO Colombia | `co/nit` | NIT |
| CR Costa Rica | `cr/cpf` | CPF |
| CU Cuba | `cu/ni` | NI |
| CY Cyprus | `cy/vat` | ΦΠΑ |
| CZ Czech Republic | `cz/dic` | DIČ |
| | `cz/ico` | IČO |
| | `cz/rc` | RČ |
| DE Germany | `de/handelsreg` | HReg |
| | `de/idnr` | IdNr |
| | `de/stnr` | StNr |
| | `de/svnr` | SVNR |
| | `de/vat` | USt-IdNr. |
| DK Denmark | `dk/cpr` | CPR |
| | `dk/cvr` | CVR |
| | `dk/vat` | CVR |
| DO Dominican Republic | `do/rnc` | RNC |
| EC Ecuador | `ec/ruc` | RUC |
| EE Estonia | `ee/ik` | IK |
| | `ee/registrikood` | Registrikood |
| | `ee/vat` | KMKR |
| EG Egypt | `eg/tn` | TN |
| ES Spain | `es/cif` | CIF |
| | `es/dni` | DNI |
| | `es/nie` | NIE |
| | `es/nss` | NSS |
| | `es/vat` | NIF |
| FI Finland | `fi/hetu` | HETU |
| | `fi/vat` | ALV nro |
| | `fi/ytunnus` | Y-tunnus |
| FR France | `fr/nif` | NIF |
| | `fr/nir` | NIR |
| | `fr/siren` | SIREN |
| | `fr/siret` | SIRET |
| | `fr/tva` | TVA |
| GB United Kingdom | `gb/nino` | NINO |
| | `gb/sedol` | SEDOL |
| | `gb/utr` | UTR |
| | `gb/vat` | VAT |
| GE Georgia | `ge/pin` | PIN |
| GH Ghana | `gh/tin` | TIN |
| GR Greece | `gr/amka` | ΑΜΚΑ |
| | `gr/vat` | ΑΦΜ |
| GT Guatemala | `gt/nit` | NIT |
| HK Hong Kong | `hk/hkid` | HKID |
| HR Croatia | `hr/vat` | OIB |
| HU Hungary | `hu/vat` | ANUM |
| ID Indonesia | `id/npwp` | NPWP |
| IE Ireland | `ie/pps` | PPS |
| | `ie/vat` | VAT |
| IL Israel | `il/idnr` | ת.ז. |
| IN India | `in/aadhaar` | Aadhaar |
| | `in/gstin` | GSTIN |
| | `in/pan` | PAN |
| IQ Iraq | `iq/nid` | NID |
| IR Iran | `ir/nid` | NID |
| IS Iceland | `is/kennitala` | kt. |
| | `is/vsk` | VSK |
| IT Italy | `it/codicefiscale` | CF |
| | `it/iva` | P.IVA |
| JP Japan | `jp/cn` | CN |
| | `jp/mynumber` | My Number |
| KR South Korea | `kr/brn` | BRN |
| | `kr/rrn` | RRN |
| KW Kuwait | `kw/civil` | Civil ID |
| KZ Kazakhstan | `kz/iin` | IIN |
| LI Liechtenstein | `li/peid` | PEID |
| LK Sri Lanka | `lk/nic` | NIC |
| LT Lithuania | `lt/asmens` | AK |
| | `lt/vat` | PVM kodas |
| LU Luxembourg | `lu/vat` | TVA |
| LV Latvia | `lv/vat` | PVN |
| MA Morocco | `ma/ice` | ICE |
| MC Monaco | `mc/tva` | TVA |
| MD Moldova | `md/idno` | IDNO |
| ME Montenegro | `me/pib` | PIB |
| MK North Macedonia | `mk/edb` | EDB |
| MT Malta | `mt/vat` | VAT |
| MU Mauritius | `mu/brn` | BRN |
| MX Mexico | `mx/clabe` | CLABE |
| | `mx/curp` | CURP |
| | `mx/rfc` | RFC |
| MY Malaysia | `my/nric` | NRIC |
| NG Nigeria | `ng/nin` | NIN |
| NI Nicaragua | `ni/ruc` | RUC |
| NL Netherlands | `nl/bsn` | BSN |
| | `nl/kvk` | KvK |
| | `nl/vat` | BTW |
| NO Norway | `no/fodselsnummer` | Fødselsnr |
| | `no/mva` | MVA |
| | `no/orgnr` | Orgnr |
| NZ New Zealand | `nz/ird` | IRD |
| PA Panama | `pa/ruc` | RUC |
| PE Peru | `pe/ruc` | RUC |
| PH Philippines | `ph/philid` | PhilID |
| PK Pakistan | `pk/cnic` | CNIC |
| PL Poland | `pl/nip` | NIP |
| | `pl/pesel` | PESEL |
| | `pl/regon` | REGON |
| PT Portugal | `pt/cc` | CC |
| | `pt/vat` | NIF |
| RO Romania | `ro/cnp` | CNP |
| | `ro/vat` | CIF |
| RS Serbia | `rs/pib` | PIB |
| RU Russia | `ru/inn` | ИНН |
| SE Sweden | `se/orgnr` | Orgnr |
| | `se/personnummer` | PN |
| | `se/vat` | Momsnr. |
| SG Singapore | `sg/uen` | UEN |
| SI Slovenia | `si/emso` | EMŠO |
| | `si/vat` | DDV |
| SK Slovakia | `sk/dic` | IČ DPH |
| | `sk/ico` | IČO |
| | `sk/rc` | RČ |
| TH Thailand | `th/tin` | TIN |
| TR Turkey | `tr/tckimlik` | T.C. Kimlik |
| | `tr/vkn` | VKN |
| TW Taiwan | `tw/ubn` | UBN |
| UA Ukraine | `ua/edrpou` | ЄДРПОУ |
| US United States | `us/ein` | EIN |
| | `us/itin` | ITIN |
| | `us/rtn` | RTN |
| | `us/ssn` | SSN |
| UY Uruguay | `uy/rut` | RUT |
| VE Venezuela | `ve/rif` | RIF |
| VN Vietnam | `vn/mst` | MST |
| ZA South Africa | `za/idnr` | SA ID |

</details>

## API

Expand All @@ -97,6 +244,17 @@ type Validator = {
compact: (value: string) => string;
format: (value: string) => string;
validate: (value: string) => ValidateResult;

// Optional metadata
description?: string;
sourceUrl?: string;
lengths?: readonly number[];
examples?: readonly string[];
aliases?: readonly string[];
candidatePattern?: string;

// Available on most validators
generate?: () => string;
};

type ValidateResult =
Expand All @@ -116,8 +274,32 @@ type ValidateResult =

### Additional exports

- `cz.rc` exports `parse(value)` returning
`{ birthDate: Date, gender: "male" | "female" }`
Many person-type validators export `parse()`, returning
structured data extracted from the identifier:

```typescript
import { cz } from "@stll/stdnum";

cz.rc.parse("7103192745");
// { birthDate: Date, gender: "male" }
```

Validators with `parse()`: BA JMBG, BG ЕГН, CN RIC,
CU NI, CZ RČ, DK CPR, EE IK, FI HETU, FR NIR,
IT CF, KR RRN, KW Civil ID, KZ IIN, LK NIC,
MX CURP, MY NRIC, NO Fødselsnr, PL PESEL, RO CNP,
SE PN, SI EMŠO, SK RČ, ZA SA ID.

`detectNetwork()` and the `CardNetwork` type are
top-level named exports:

```typescript
import { detectNetwork } from "@stll/stdnum";
import type { CardNetwork } from "@stll/stdnum";

detectNetwork("4111111111111111");
// "visa"
```

## Unicode handling

Expand All @@ -131,7 +313,7 @@ handled automatically.

```bash
bun install
bun test # 76 tests
bun test # 4,185 tests
bun run lint # oxlint
bun run format # oxfmt
```
Expand Down
Loading