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

Uploaded CPython 3.11+Windows x86-64

stella_stdnum-2.1.5-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (469.6 kB view details)

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

stella_stdnum-2.1.5-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (468.2 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

stella_stdnum-2.1.5-cp311-abi3-macosx_11_0_arm64.whl (426.2 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

stella_stdnum-2.1.5-cp311-abi3-macosx_10_12_x86_64.whl (441.9 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.5-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 c5d9afb1e23845549c65ec59481c7009b319d532424f80b83f4b78dc4f13e296
MD5 9332f1ef52b607a7cbff9ba2900c6d90
BLAKE2b-256 5eabd7fc865c61f9e8f2af11336cbf264060a14e7a395a4e88ded184e91667f7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.5-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 aac2354b754f6142c4bdcb06008bff38e8bcbd0af876d1f3e8628ca02f205fd6
MD5 427afab57c54f7bd717b22ab52502ac5
BLAKE2b-256 4cd1a8cdeec4c6f673414c59f84ae3d86886755c2a487c613002ae4afef69990

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.5-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 205caee2933777c3c0676987bc6d7a15584424b1c177b025d000add038a8c5e7
MD5 0360b9d97b650ab87175dbf3da7277fd
BLAKE2b-256 99734f228126e757a3f7fcfa616746e98a04fd43f13111066c37c264c58bb0cc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.5-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 444e9a91940dd627ef0b412773a17bfe922b8a3ad22738e7b86a3fcf10e77936
MD5 d92b6303cea4ff298a0cd265187bdd5f
BLAKE2b-256 37f5b6ae85b6af3acd9307681d0d2644ebc03917f9043ba9981d50340f599050

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.5-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 85b2d76e4f27d97f743c98d0cf54ddd28e62543b274d41fc10e777aec330baa4
MD5 4415dd0a0ecdfa0cfb0c20212eac69a9
BLAKE2b-256 08ccbf1d34af79c9dfe62158dc22860bc017dc1680a52066ef7a257e8c682c58

See more details on using hashes here.

Provenance

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

This release

2.1.5 This release

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