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

Uploaded CPython 3.11+Windows x86-64

stella_stdnum-2.1.6-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (469.2 kB view details)

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

stella_stdnum-2.1.6-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (468.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

stella_stdnum-2.1.6-cp311-abi3-macosx_11_0_arm64.whl (425.8 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

stella_stdnum-2.1.6-cp311-abi3-macosx_10_12_x86_64.whl (441.5 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.6-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 f8029b3f35b14071a6a73ad427fe5323a2dc8dfd61485fdbb2c6d10c347fc63d
MD5 6ff67b678064ad34804889371d59719f
BLAKE2b-256 58798e458ce33cc7b25c141a669771099084093bbe54e8efa2e3e06e9a4ccc99

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.6-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c3eae91a26fac60dd40ba80cf222841ae8675bfbb58effa0440bac79f3759b5e
MD5 6db085ef22c4e9fcbc23b06ae0dfa66c
BLAKE2b-256 4b17ef6f00a5a572c7f62f22d9a1eb482a3550d969df4bbca8ef4ae41ea96557

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.6-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 7fff717fa4384d0dbce4dade322e4975b51de6e1c8f3007025b275e2547497a4
MD5 e8fb45ee9cfb9b4f6bef3c0cbf90a2af
BLAKE2b-256 598505ff93a979bd46872aad3c8df4523cbcf43e846c568f6d0c6a30638b6339

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.6-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1577f4c38aba823b3c9fc3f1c67680ec29bfe4b738ce89b641f2571763e41bdc
MD5 78f4172298323b81213c9e9d20d7bab7
BLAKE2b-256 0fbb57718c8dd5feefa0a02ada2f52fba109ebecb9cabb60efe7fdb7c1f7c69e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for stella_stdnum-2.1.6-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6f6a2478ea01ff19fd68a02c7ca3c768d731d68c7365c2b1ce1cc89a35d4a102
MD5 ec2b13c56b48afdd0fdbde7c10e54db2
BLAKE2b-256 f10db8f89bb9782a865b3c5246ff7339c014fa30b55adeade6361cce53d2bafd

See more details on using hashes here.

Provenance

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

This release

2.1.6 This release

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