stella

@stll/stdnum

Validate, compact, format, generate, and parse standard identifiers through a single Rust implementation. The npm package uses a native N-API binding on Node.js and Bun; @stll/stdnum-wasm serves browsers and edge runtimes, and the same registry is available from Python as stella-stdnum.

This package covers 11 global identifiers and 96 countries through 176 per-module entry points.

Install

npm install @stll/stdnum
# or
bun add @stll/stdnum

For browser or edge runtimes, install both packages:

npm install @stll/stdnum @stll/stdnum-wasm

For Python 3.11 or newer:

pip install stella-stdnum

Usage

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

cz.ico.validate("25596641");
// { valid: true, compact: "25596641" }

cz.ico.validate("12345678");
// { valid: false, error: { code: "INVALID_CHECKSUM", ... } }

cz.rc.format("7103192745");
// "710319/2745"

cz.ico.validateMany(["25596641", "12345678"]);
// [{ valid: true, compact: "25596641" }, { valid: false, error: ... }]

Tree-shaking

Import only what you need:

import ico from "@stll/stdnum/cz/ico";
import iban from "@stll/stdnum/iban";

ico.validate("25596641");
iban.validate("CZ65 0800 0000 1920 0014 5399");

Browser and edge runtimes

Initialize the WebAssembly runtime once before calling the synchronous validator subpaths:

import { initialize } from "@stll/stdnum/browser";
import ico from "@stll/stdnum/cz/ico";

await initialize();
ico.validate("25596641");

Concurrent calls to initialize() share the same promise. Calling a validator before initialization throws StdnumNotInitializedError from @stll/stdnum/browser.

The WASM package also exposes the registry API asynchronously:

import { validate } from "@stll/stdnum-wasm";

await validate("cz.ico", "25596641");

Python

import stella_stdnum

result = stella_stdnum.validate("cz.ico", "25596641")
assert result.valid
assert result.compact == "25596641"

results = stella_stdnum.validate_many("cz.ico", ["25596641", "12345678"])
assert [result.valid for result in results] == [True, False]

The Rust registry owns validator behavior and metadata. TypeScript subpaths, catalog files, and exact TypeScript/Python registry types are generated from that registry. One committed fixture set checks the Rust, Node.js, WASM, and Python surfaces, and ty checks the installed Python wheel as a real consumer.

Oracle Validation

The repo ships two oracle modes:

  • bun run oracle Runs the strict gate. It keeps only high-confidence cross-checks that are stable enough for CI.
  • bun run oracle:survey Runs the broader ecosystem survey. It includes noisier third-party validators and mutation probes to surface drift without treating every disagreement as a release blocker.

Both commands accept ORACLE_SAMPLES=<n> to trade off runtime against coverage.

bun run performance:oracles is an optional local diagnostic for the handful of specialized JavaScript oracles it covers. It is deliberately not a CI gate: those country-specific comparisons are not representative of the library as a whole. The benchmark alternates execution order and compares paired medians to reduce host noise.

Dependabot watches every JavaScript, Python, Ruby, PHP, and Rust oracle manifest. Its weekly update PRs rerun the strict correctness gates against the new upstream versions before they can merge.

Supported Identifiers

International

Identifier Module Type
Business Identifier Code bic company
Credit Card Number creditcard any
Bitcoin Base58Check Address crypto/btcbase58 any
Bitcoin Bech32 Address crypto/btcbech32 any
Ethereum Address crypto/eth any
Cryptocurrency Wallet Address crypto/wallet any
EU VAT Number eu/vat company
IBAN iban any
International Securities Identification Number isin any
Legal Entity Identifier lei company
Luhn luhn any

Countries

96 countries supported (click to expand)
Country Module Identifier
AD ad/nrt NRT
AE ae/eid EID
AI ai/tin TIN
AL al/nipt NIPT
AM am/tin TIN
AR ar/cbu CBU
ar/cuit CUIT
ar/dni DNI
AT at/businessid FN
at/tin TIN
at/uid UID
at/vnr VNR
AU au/abn ABN
au/acn ACN
au/tfn TFN
AZ az/voen VÖEN
BA ba/jmbg JMBG
BD bd/nid NID
BE be/bis BIS
be/nn NN
be/vat BTW
BG bg/egn ЕГН
bg/pnf ЛНЧ
bg/vat ИН по ДДС
BH bh/cpr CPR
BR br/cnpj CNPJ
br/cpf CPF
BY by/unp УНП
BZ bz/tin TIN
CA ca/bn BN
ca/sin SIN
CH ch/ssn AHV
ch/uid UID
ch/vat MWST
CL cl/rut RUT
CN cn/ric RIC
cn/uscc USCC
CO co/nit NIT
CR cr/cpf CPF
CU cu/ni NI
CY cy/vat ΦΠΑ
CZ cz/bankaccount Číslo účtu
cz/dic DIČ
cz/ico IČO
cz/rc RČ
DE de/handelsreg HReg
de/idnr IdNr
de/stnr StNr
de/svnr SVNR
de/vat USt-IdNr.
DK dk/cpr CPR
dk/cvr CVR
dk/vat CVR
DO do/rnc RNC
EC ec/ruc RUC
EE ee/ik IK
ee/registrikood Registrikood
ee/vat KMKR
EG eg/tn TN
ES es/cif CIF
es/dni DNI
es/nie NIE
es/nss NSS
es/vat NIF
FI fi/hetu HETU
fi/vat ALV nro
fi/ytunnus Y-tunnus
FR fr/nif NIF
fr/nir NIR
fr/siren SIREN
fr/siret SIRET
fr/tva TVA
GB gb/nhs NHS
gb/nino NINO
gb/sedol SEDOL
gb/utr UTR
gb/vat VAT
GE ge/pin PIN
GH gh/tin TIN
GR gr/amka ΑΜΚΑ
gr/vat ΑΦΜ
GT gt/nit NIT
HK hk/hkid HKID
HR hr/vat OIB
HU hu/vat ANUM
ID id/npwp NPWP
IE ie/pps PPS
ie/vat VAT
IL il/idnr ת.ז.
IN in/aadhaar Aadhaar
in/gstin GSTIN
in/pan PAN
IQ iq/nid NID
IR ir/nid NID
IS is/kennitala kt.
is/vsk VSK
IT it/codicefiscale CF
it/iva P.IVA
JP jp/cn CN
jp/mynumber My Number
KR kr/brn BRN
kr/rrn RRN
KW kw/civil Civil ID
KZ kz/iin IIN
LI li/peid PEID
LK lk/nic NIC
LT lt/asmens AK
lt/vat PVM kodas
LU lu/vat TVA
LV lv/vat PVN
MA ma/ice ICE
MC mc/tva TVA
MD md/idno IDNO
ME me/pib PIB
MK mk/edb EDB
MT mt/vat VAT
MU mu/brn BRN
MX mx/clabe CLABE
mx/curp CURP
mx/rfc RFC
MY my/nric NRIC
NG ng/nin NIN
NI ni/ruc RUC
NL nl/bsn BSN
nl/kvk KvK
nl/vat BTW
NO no/fodselsnummer Fødselsnr
no/mva MVA
no/orgnr Orgnr
NZ nz/ird IRD
PA pa/ruc RUC
PE pe/ruc RUC
PH ph/philid PhilID
PK pk/cnic CNIC
PL pl/nip NIP
pl/pesel PESEL
pl/regon REGON
PT pt/cc CC
pt/vat NIF
RO ro/cnp CNP
ro/vat CIF
RS rs/pib PIB
RU ru/inn ИНН
SE se/orgnr Orgnr
se/personnummer PN
se/vat Momsnr.
SG sg/uen UEN
SI si/emso EMŠO
si/vat DDV
SK sk/dic IČ DPH
sk/ico IČO
sk/rc RČ
TH th/tin TIN
TR tr/tckimlik T.C. Kimlik
tr/vkn VKN
TW tw/ubn UBN
UA ua/edrpou ЄДРПОУ
US us/ein EIN
us/itin ITIN
us/rtn RTN
us/ssn SSN
UY uy/rut RUT
VE ve/rif RIF
VN vn/mst MST
ZA za/idnr SA ID

API

Every identifier exports the same interface:

type Validator = {
  name: string;
  localName: string;
  abbreviation: string;
  country?: CountryCode;
  entityType: "person" | "company" | "any";
  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 =
  | { valid: true; compact: string }
  | {
      valid: false;
      error: {
        code:
          | "INVALID_FORMAT"
          | "INVALID_LENGTH"
          | "INVALID_CHECKSUM"
          | "INVALID_COMPONENT";
        message: string;
      };
    };

Additional exports

Many person-type validators export parse(), returning structured data extracted from the identifier:

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:

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

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

Unicode handling

All validators normalize Unicode artifacts before validation: fullwidth digits, various dashes, non-breaking spaces, zero-width characters, and other common OCR/PDF copy-paste issues are handled automatically.

Development

bun install
bun run rust:check
bun run codegen:check
bun run typecheck
bun test
bun run lint     # oxlint
bun run format   # oxfmt

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jan-kubica from gravatar.com jan-kubica

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

stella_stdnum-2.3.2-cp311-abi3-win_amd64.whl (386.8 kB view details)

Uploaded CPython 3.11+Windows x86-64

stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (473.8 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (472.8 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

stella_stdnum-2.3.2-cp311-abi3-macosx_11_0_arm64.whl (431.4 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

stella_stdnum-2.3.2-cp311-abi3-macosx_10_12_x86_64.whl (445.0 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file stella_stdnum-2.3.2-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.3.2-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4901df7d38a924f3fdb1e541ed1e94e38b6cba3b5636dd6707318e042cf603f0
MD5 0a8930492af60bf9d5e0850357990a4f
BLAKE2b-256 86678ac1e50e82e8e20b884462a7138da830382e7a40e18c98203349f828a4ea

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.3.2-cp311-abi3-win_amd64.whl:

Publisher: release.yml on stella/stdnum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 54da8f8609cf480dbf9ab0b995482eab17c5dcf0d35df8384d8c1b750da3b100
MD5 24859c26c2566d9db85399b59b0abde6
BLAKE2b-256 1468db7cb737ce2e9eaa708480c94284a86cba56188972a065ba3de58b937b04

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on stella/stdnum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bb23a79d1731e3fb5df1a913667772913225dddd08f6914e61fc509cfccbd83a
MD5 aba5b939e845445b5ecd28ed9e476874
BLAKE2b-256 8fcbb53dd9d89576c36c09469287fb4084faa3649fc88c07eed73422a3c00683

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.3.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on stella/stdnum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stella_stdnum-2.3.2-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.3.2-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f5531383fd7b19635b421121d398cd824eb4ecb6b9a42d3d34c585ec52f0988f
MD5 56673dbea4d0e9352265bce6b3c05f78
BLAKE2b-256 74d2ac4f96c4366067fd1058dee3fcdb307b978d72e35fe2239c42c89aada1e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.3.2-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on stella/stdnum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file stella_stdnum-2.3.2-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.3.2-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 a90bd9b4a24b6a0374a06c749939d8eefaf3763fe85eef8c5e581a82b1575d87
MD5 85fa8344813cd6f1932c220ba8a50768
BLAKE2b-256 ed73f8f316547aeaf7da840f04cb4cbdc9e92603961cbf228d6e707d20ed5e89

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.3.2-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on stella/stdnum

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.3.2 This release

5 files

2.3.1

5 files

2.3.0

5 files

2.2.1

5 files

2.2.0

5 files

2.1.6

5 files

2.1.5

5 files

2.1.4

5 files

2.1.3

5 files

2.1.2

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page