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 175 per-module entry points.

Install

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

For browser or edge runtimes:

npm install @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

The WASM package 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/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:
Newer release available (2.3.2)

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.1.3-cp311-abi3-win_amd64.whl (931.9 kB view details)

Uploaded CPython 3.11+Windows x86-64

stella_stdnum-2.1.3-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

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

stella_stdnum-2.1.3-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (967.5 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

stella_stdnum-2.1.3-cp311-abi3-macosx_11_0_arm64.whl (891.8 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

stella_stdnum-2.1.3-cp311-abi3-macosx_10_12_x86_64.whl (946.5 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.3-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 597968b4530c02f7be67887ad08101dd964b609205528b5cf8268af7f24410f4
MD5 77059f59e8406b0423a68baf0d27bc04
BLAKE2b-256 9e13a73d91aa3699ae6a75c32781de5b1b3a70f047ac609130ca27e3b146ca69

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.1.3-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.1.3-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.1.3-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 82a77c3daab7ccf690b177eca1a7e669398a274acd252e81a9e9e0b060249a46
MD5 1cd3d903ecc6834d59f721790f21ccd2
BLAKE2b-256 3fa98db0ef20a1f7cbfed108cffebcb4d7bba67daeaf8a27bca32e0f5413d1b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.1.3-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.1.3-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.1.3-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 520d94ea9a38fefb510c64fdc8a71fd3e4c3d42a6e65e30d85b3dfed1a0791fb
MD5 71ea0b092465a743be5b433f77527114
BLAKE2b-256 8879999e13ea4e4ebace0fc88a6f15502f3ef3360b1824d517c8e8cb895dc029

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.1.3-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.1.3-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.1.3-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8707acb116079d057fd4bf661cde030a31a6b54c700c2599998006624f863c4a
MD5 4cb302de323c482799279b367b5ab467
BLAKE2b-256 871415592338a8c1e82f09274d5650951bb3091cf392dcd98312020b25a84410

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.1.3-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.1.3-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for stella_stdnum-2.1.3-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 4481a26a740ef24cd6478e82b23fa33cad890939accb2f5bfad73a36e463c9d6
MD5 0676bdf7f97558893ba79825a98800e1
BLAKE2b-256 1ba86899456caf92d3e7283233adc07854676a4f530f46935c1e9c1523f9d876

See more details on using hashes here.

Provenance

The following attestation bundles were made for stella_stdnum-2.1.3-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

2.3.2

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

This release

2.1.3 This release

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