@stll/stdnum 1.0.0 → 2.0.0

package/src/ae/eid.ts

@@ -10,6 +10,11 @@
  * @see https://u.ae/en/information-and-services/visa-and-emirates-id/emirates-id
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnChecksum,
   luhnValidate,
@@ -19,8 +24,6 @@ import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string =>
   clean(value, " -/");
 
@@ -77,12 +80,13 @@ const generate = (): string => {
 };
 
 /** UAE Emirates ID. */
-const eid: Validator = {
+const eid: CountryValidator<"AE"> = {
   name: "Emirates ID",
   localName: "رقم الهوية",
   abbreviation: "EID",
   aliases: ["EID", "Emirates ID", "رقم الهوية"] as const,
   candidatePattern: "784-\\d{4}-\\d{7}-\\d",
+  scope: "country",
   country: "AE",
   entityType: "person",
   lengths: [15],

package/src/ai/tin.ts

@@ -23,12 +23,15 @@ const generate = (): string => {
  * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Anguilla-TIN.pdf
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string => {
   return clean(value, " -").trim();
 };
@@ -74,12 +77,13 @@ const format = (value: string): string => {
  * (format-only validation, no published check
  * digit algorithm).
  */
-const tin: Validator = {
+const tin: CountryValidator<"AI"> = {
   name: "Anguilla Tax Identification Number",
   localName: "Tax Identification Number",
   abbreviation: "TIN",
   aliases: ["TIN"] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "AI",
   entityType: "any",
   lengths: [10] as const,

package/src/al/nipt.ts

@@ -18,12 +18,15 @@ const generate = (): string => {
  * @see https://www.tatime.gov.al/eng/c/4/103/business-lifecycle
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 const NIPT_RE = /^[A-M]\d{8}[A-Z]$/;
 
 const compact = (value: string): string => {
@@ -57,13 +60,14 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Albanian NIPT (tax identification number). */
-const nipt: Validator = {
+const nipt: CountryValidator<"AL"> = {
   name: "Albanian Tax Number",
   localName:
     "Numri i Identifikimit për Personin e Tatueshëm",
   abbreviation: "NIPT",
   aliases: ["NIPT", "NUIS"] as const,
   candidatePattern: "[A-Z]\\d{8}[A-Z]",
+  scope: "country",
   country: "AL",
   entityType: "any",
   sourceUrl: "https://www.tatime.gov.al/",

package/src/am/tin.ts

@@ -16,13 +16,16 @@ const generate = (): string => randomDigits(8);
  * @see https://www.src.am/en/taxpayerSearchSystemPage/112
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string =>
   clean(value, " -").trim();
 
@@ -49,12 +52,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Armenian Tax Identification Number. */
-const tin: Validator = {
+const tin: CountryValidator<"AM"> = {
   name: "Armenian Tax ID",
   localName: "Հարկ վճարողի հաշվառման համար",
   abbreviation: "TIN",
   aliases: ["ՀՎՀՀ", "TIN"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "AM",
   entityType: "any",
   lengths: [8] as const,

package/src/ar/cbu.ts

@@ -8,13 +8,16 @@
  * @see https://es.wikipedia.org/wiki/Clave_bancaria_uniforme
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const WEIGHTS_BLOCK1 = [7, 1, 3, 9, 7, 1, 3];
 const WEIGHTS_BLOCK2 = [
   3, 9, 7, 1, 3, 9, 7, 1, 3, 9, 7, 1, 3,
@@ -84,12 +87,13 @@ const generate = (): string => {
 };
 
 /** Argentine Uniform Bank Key. */
-const cbu: Validator = {
+const cbu: CountryValidator<"AR"> = {
   name: "Argentine Bank Account Number",
   localName: "Clave Bancaria Uniforme",
   abbreviation: "CBU",
   aliases: ["CBU", "Clave Bancaria Uniforme"] as const,
   candidatePattern: "\\d{22}",
+  scope: "country",
   country: "AR",
   entityType: "any",
   sourceUrl:

package/src/ar/cuit.ts

@@ -16,13 +16,16 @@
  * @see https://en.wikipedia.org/wiki/CUIT_(Argentina)
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits, randomPick } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const VALID_TYPES = new Set([
   "20",
   "23",
@@ -120,7 +123,7 @@ const generate = (): string => {
  * Examples sourced from python-stdnum test suite
  * (ar.cuit module).
  */
-const cuit: Validator = {
+const cuit: CountryValidator<"AR"> = {
   name: "Argentine Tax ID",
   localName: "Clave Única de Identificación Tributaria",
   abbreviation: "CUIT",
@@ -130,6 +133,7 @@ const cuit: Validator = {
     "Clave Única de Identificación Tributaria",
   ] as const,
   candidatePattern: "\\d{2}-?\\d{8}-?\\d",
+  scope: "country",
   country: "AR",
   entityType: "any",
   compact,

package/src/ar/dni.ts

@@ -11,13 +11,16 @@ const generate = (): string => randomDigits(8);
  * @see https://en.wikipedia.org/wiki/Documento_Nacional_de_Identidad_(Argentina)
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string =>
   clean(value, " -.").trim();
 
@@ -53,7 +56,7 @@ const format = (value: string): string => {
 };
 
 /** Argentine National Identity Document. */
-const dni: Validator = {
+const dni: CountryValidator<"AR"> = {
   name: "Argentine Identity Card",
   localName: "Documento Nacional de Identidad",
   abbreviation: "DNI",
@@ -63,6 +66,7 @@ const dni: Validator = {
     "Documento de Identidad",
   ] as const,
   candidatePattern: "\\d{1,2}\\.?\\d{3}\\.?\\d{3}",
+  scope: "country",
   country: "AR",
   entityType: "person",
   sourceUrl:

package/src/at/businessid.ts

@@ -16,12 +16,15 @@ const generate = (): string => {
  * @see https://www.justiz.gv.at/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 const FN_RE = /^\d+[a-z]$/i;
 
 const compact = (value: string): string => {
@@ -54,12 +57,13 @@ const format = (value: string): string =>
   `FN ${compact(value)}`;
 
 /** Austrian Company Register Number. */
-const businessid: Validator = {
+const businessid: CountryValidator<"AT"> = {
   name: "Austrian Company Register Number",
   localName: "Firmenbuchnummer",
   abbreviation: "FN",
   aliases: ["Firmenbuchnummer", "FN", "FBN"] as const,
   candidatePattern: "FN\\s?\\d{5,6}[a-z]?",
+  scope: "country",
   country: "AT",
   entityType: "company",
   sourceUrl: "https://www.justiz.gv.at/",

package/src/at/tin.ts

@@ -10,13 +10,16 @@
  * @see https://service.bmf.gv.at/Service/Anwend/Behoerden/show_mast.asp
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 /** Luhn-variant doubling table: position-dependent. */
 const DOUBLE = "0246813579";
 
@@ -69,12 +72,13 @@ const generate = (): string => {
 };
 
 /** Austrian Tax Identification Number. */
-const tin: Validator = {
+const tin: CountryValidator<"AT"> = {
   name: "Austrian Tax Identification Number",
   localName: "Abgabenkontonummer",
   abbreviation: "TIN",
   aliases: ["Steuernummer", "St.Nr.", "TIN"] as const,
   candidatePattern: "\\d{2}-?\\d{3}/\\d{4}",
+  scope: "country",
   country: "AT",
   entityType: "any",
   sourceUrl:

package/src/at/uid.ts

@@ -8,14 +8,17 @@
  * @see https://www.bmf.gv.at/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { luhnChecksum } from "#checksums/luhn";
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string => {
   let v = clean(value, " -/");
   if (v.startsWith("AT") || v.startsWith("at")) {
@@ -68,7 +71,7 @@ const generate = (): string => {
 };
 
 /** Austrian VAT Identification Number. */
-const uid: Validator = {
+const uid: CountryValidator<"AT"> = {
   name: "Austrian VAT Number",
   localName: "Umsatzsteuer-Identifikationsnummer",
   abbreviation: "UID",
@@ -78,6 +81,7 @@ const uid: Validator = {
     "ATU",
   ] as const,
   candidatePattern: "ATU\\d{8}",
+  scope: "country",
   country: "AT",
   entityType: "company",
   sourceUrl: "https://www.bmf.gv.at/",

package/src/at/vnr.ts

@@ -6,17 +6,31 @@
  * The check digit is computed using a weighted sum
  * mod 11 over the 9 non-check digits.
  *
+ * The 6-digit "birth date" field is not always a real
+ * calendar date. Sozialversicherung.at documents that
+ * persons with unknown date of birth are issued
+ * substitute values (01.01. or 01.07.), and that
+ * months 13, 14, etc. are issued when the daily serial
+ * pool for a given substitute date is exhausted. We
+ * therefore do not enforce a calendar-valid month here.
+ * The day field, however, is always within 01-31 — even
+ * in the documented overflow cases the day stays "01"
+ * — so we keep the day-bounds check.
+ *
  * @see https://de.wikipedia.org/wiki/Sozialversicherungsnummer#%C3%96sterreich
- * @see https://www.sozialversicherung.at/
+ * @see https://www.sozialversicherung.at/cdscontent/?contentid=10007.820902&viewmode=content
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 /**
  * Weights for the 9 non-check digits (positions
  * 0,1,2, then 4,5,6,7,8,9). Check digit is at
@@ -44,13 +58,24 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
-  // Validate birth date (DDMMYY in positions 4-9)
+  // Per sozialversicherung.at, the 3-digit serial
+  // (positions 0-2) never starts with zero.
+  if (v[0] === "0") {
+    return err(
+      "INVALID_COMPONENT",
+      "Austrian VNR serial must not start with zero",
+    );
+  }
+
+  // Day (positions 4-5) is always within 01-31, even
+  // in the documented substitute and overflow cases
+  // where the month is shifted. The month is left
+  // unchecked per the source.
   const day = Number(v.slice(4, 6));
-  const month = Number(v.slice(6, 8));
-  if (day < 1 || day > 31 || month < 1 || month > 12) {
+  if (day < 1 || day > 31) {
     return err(
       "INVALID_COMPONENT",
-      "Austrian VNR contains an invalid birth date",
+      "Austrian VNR day field must be within 01-31",
     );
   }
 
@@ -88,7 +113,9 @@ const format = (value: string): string => {
 /** Generate a random valid Austrian VNR. */
 const generate = (): string => {
   for (;;) {
-    const serial = randomDigits(3);
+    // Serial must not start with zero (see validate).
+    const serial =
+      String(randomInt(1, 9)) + randomDigits(2);
     const day = String(randomInt(1, 28)).padStart(2, "0");
     const month = String(randomInt(1, 12)).padStart(2, "0");
     const year = String(randomInt(0, 99)).padStart(2, "0");
@@ -106,7 +133,7 @@ const generate = (): string => {
 };
 
 /** Austrian Social Insurance Number. */
-const vnr: Validator = {
+const vnr: CountryValidator<"AT"> = {
   name: "Austrian Social Insurance Number",
   localName: "Versicherungsnummer",
   abbreviation: "VNR",
@@ -117,6 +144,7 @@ const vnr: Validator = {
     "Sozialversicherungsnummer",
   ] as const,
   candidatePattern: "\\d{4}\\s?\\d{6}",
+  scope: "country",
   country: "AT",
   entityType: "person",
   sourceUrl:

package/src/au/abn.ts

@@ -9,13 +9,16 @@
  * @see https://abr.business.gov.au/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const WEIGHTS = [
   10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19,
 ] as const;
@@ -65,12 +68,13 @@ const generate = (): string => {
 };
 
 /** Australian Business Number. */
-const abn: Validator = {
+const abn: CountryValidator<"AU"> = {
   name: "Australian Business Number",
   localName: "Australian Business Number",
   abbreviation: "ABN",
   aliases: ["ABN", "Australian Business Number"] as const,
   candidatePattern: "\\d{2}\\s?\\d{3}\\s?\\d{3}\\s?\\d{3}",
+  scope: "country",
   country: "AU",
   entityType: "company",
   sourceUrl: "https://abr.business.gov.au/",

package/src/au/acn.ts

@@ -9,13 +9,16 @@
  * @see https://asic.gov.au/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const WEIGHTS = [8, 7, 6, 5, 4, 3, 2, 1] as const;
 
 const compact = (value: string): string =>
@@ -66,12 +69,13 @@ const generate = (): string => {
 };
 
 /** Australian Company Number. */
-const acn: Validator = {
+const acn: CountryValidator<"AU"> = {
   name: "Australian Company Number",
   localName: "Australian Company Number",
   abbreviation: "ACN",
   aliases: ["ACN", "Australian Company Number"] as const,
   candidatePattern: "\\d{3}\\s?\\d{3}\\s?\\d{3}",
+  scope: "country",
   country: "AU",
   entityType: "company",
   sourceUrl: "https://asic.gov.au/",

package/src/au/tfn.ts

@@ -9,13 +9,16 @@
  * @see https://www.ato.gov.au/Individuals/Tax-file-number/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const WEIGHTS = [1, 4, 3, 7, 5, 8, 6, 9, 10] as const;
 
 const compact = (value: string): string =>
@@ -64,12 +67,13 @@ const generate = (): string => {
 };
 
 /** Australian Tax File Number. */
-const tfn: Validator = {
+const tfn: CountryValidator<"AU"> = {
   name: "Tax File Number",
   localName: "Tax File Number",
   abbreviation: "TFN",
   aliases: ["TFN", "Tax File Number"] as const,
   candidatePattern: "\\d{8,9}",
+  scope: "country",
   country: "AU",
   entityType: "person",
   sourceUrl:

package/src/az/voen.ts

@@ -13,12 +13,15 @@
  * @see https://www.taxes.gov.az/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 /** Weights for check digit computation (positions 0-7). */
 const WEIGHTS = [4, 1, 8, 6, 2, 7, 5, 3] as const;
 
@@ -106,12 +109,13 @@ const generate = (): string => {
  *
  * Examples sourced from python-stdnum test suite.
  */
-const voen: Validator = {
+const voen: CountryValidator<"AZ"> = {
   name: "Azerbaijani Tax ID",
   localName: "Vergi Ödəyicisinin Eyniləşdirmə Nömrəsi",
   abbreviation: "VÖEN",
   aliases: ["VÖEN"] as const,
   candidatePattern: "\\d{10}",
+  scope: "country",
   country: "AZ",
   entityType: "any",
   lengths: [10] as const,

package/src/ba/jmbg.ts

@@ -8,6 +8,12 @@
  * @see https://en.wikipedia.org/wiki/Unique_Master_Citizen_Number
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
@@ -15,12 +21,6 @@ import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type {
-  ParsedPersonId,
-  ValidateResult,
-  Validator,
-} from "../types";
-
 const WEIGHTS = [
   7, 6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2,
 ] as const;
@@ -106,12 +106,13 @@ const generate = (): string => {
 };
 
 /** Bosnian Unique Master Citizen Number. */
-const jmbg: Validator<ParsedPersonId> = {
+const jmbg: CountryValidator<"BA", ParsedPersonId> = {
   name: "Bosnian Personal ID",
   localName: "Jedinstveni matični broj građana",
   abbreviation: "JMBG",
   aliases: ["JMBG", "matični broj"] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "BA",
   entityType: "person",
   lengths: [13] as const,

package/src/bd/nid.ts

@@ -30,13 +30,16 @@ const generate = (): string => {
  * @see https://www.nidw.gov.bd/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits, randomPick } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 /**
  * Valid RMO (residential/municipal/other) codes.
  * 1 = Rural, 2 = Municipality, 3 = City,
@@ -106,7 +109,7 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Bangladesh National Identity Number. */
-const nid: Validator = {
+const nid: CountryValidator<"BD"> = {
   name: "National Identity Number",
   localName: "জাতীয় পরিচয়পত্র",
   abbreviation: "NID",
@@ -116,6 +119,7 @@ const nid: Validator = {
     "National ID Card",
   ] as const,
   candidatePattern: "\\d{10,17}",
+  scope: "country",
   country: "BD",
   entityType: "person",
   lengths: [10, 13, 17],