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:
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.3.0-cp311-abi3-win_amd64.whl (386.4 kB view details)

Uploaded CPython 3.11+Windows x86-64

stella_stdnum-2.3.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (473.3 kB view details)

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

stella_stdnum-2.3.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (472.4 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

stella_stdnum-2.3.0-cp311-abi3-macosx_11_0_arm64.whl (430.8 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

stella_stdnum-2.3.0-cp311-abi3-macosx_10_12_x86_64.whl (444.5 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for stella_stdnum-2.3.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 9d8b31f5bcaefbf8b26591c2545950b8368d5462284507e10467048151fd7fd5
MD5 d7b39ee06a74e42d92c730d16b23237b
BLAKE2b-256 7b1e3039a97fae015c1168a9dcb82be2c0b3198dd632871198cf0e983bdc357d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.3.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 64f4e32be200a1946ad7cf1667848446f121624cd5257f67de36d905add7beaa
MD5 4bc1560db5f74742645e41b3db15e452
BLAKE2b-256 6ba4083522cb4443f0f4fbf8280a12b39247ea358734518242a9795925aae00f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.3.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 2379bf7d00a98e514902d9682ac445a669d76481a52e3e30867121013929f5ff
MD5 54d965b962fb85cddb0e1a6c46be7051
BLAKE2b-256 c564c356176bd6a6c455c7b763d0cbda1e4df549831cd4edc2f0345e92fa8932

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.3.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d9efba3421a6b8b72ae8b41433efac72d1cee5d34828c047796a004bfadbf881
MD5 7732750d8b994e41da25cdbf9fcae219
BLAKE2b-256 206f27e89682970bb0fa39bb8627c20ef9d1e2dd6ad82ff64794946a289daa43

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.3.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 12d87455602dad347ff1ec47722d9f00c65b03c3b6778e79480fe42ca143bfd0
MD5 471507d81c82f5005fdc2f5e3626e7a1
BLAKE2b-256 2eca27ada40fa4438049595dbb6d36d83270df93140b354819aeb87fdd8e050d

See more details on using hashes here.

Provenance

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

This release

2.3.0 This release

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