@stll/stdnum 0.0.1 → 2.0.0

package/src/_util/generate.ts

@@ -22,3 +22,41 @@ export const randomInt = (
   max: number,
 ): number =>
   min + Math.floor(Math.random() * (max - min + 1));
+
+/**
+ * Pick a random element from a non-empty array.
+ * Throws if the array is empty so generators that
+ * declare a fixed pool fail loudly instead of
+ * returning `undefined`.
+ */
+export const randomPick = <T>(values: readonly T[]): T => {
+  if (values.length === 0) {
+    throw new Error("randomPick called with empty array");
+  }
+  const idx = randomInt(0, values.length - 1);
+  // SAFETY: idx is bounded by values.length and the
+  // array is non-empty (checked above).
+  const value = values[idx];
+  if (value === undefined) {
+    throw new Error("randomPick produced undefined");
+  }
+  return value;
+};
+
+/**
+ * Pick a random character from a non-empty string.
+ * Same contract as `randomPick` for arrays.
+ */
+export const randomChar = (chars: string): string => {
+  if (chars.length === 0) {
+    throw new Error("randomChar called with empty string");
+  }
+  const idx = randomInt(0, chars.length - 1);
+  // SAFETY: idx is bounded by chars.length and the
+  // string is non-empty (checked above).
+  const ch = chars[idx];
+  if (ch === undefined) {
+    throw new Error("randomChar produced undefined");
+  }
+  return ch;
+};

package/src/ad/nrt.ts

@@ -1,8 +1,8 @@
+const NRT_PREFIXES = "CDEGOPU";
+
 /** Generate a random valid Andorra NRT. */
 const generate = (): string => {
-  const prefixes = "CDEGOPU";
-  const prefix =
-    prefixes[randomInt(0, prefixes.length - 1)]!;
+  const prefix = randomChar(NRT_PREFIXES);
   const digits = randomDigits(6);
   const suffix = String.fromCodePoint(
     65 + randomInt(0, 25),
@@ -25,13 +25,20 @@ const generate = (): string => {
  * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Andorra-TIN.pdf
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
+import {
+  randomChar,
+  randomDigits,
+  randomInt,
+} from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const VALID_PREFIXES = "ACDEFGLOPU";
 
 const compact = (value: string): string =>
@@ -45,7 +52,11 @@ const validate = (value: string): ValidateResult => {
       "Andorra NRT must be 8 characters",
     );
   }
+  // SAFETY: v.length === 8 guarantees both positions
+  // exist; oxlint cannot see the length guard.
+  // eslint-disable-next-line no-non-null-assertion
   const prefix = v[0]!;
+  // eslint-disable-next-line no-non-null-assertion
   const tail = v[7]!;
   const digits = v.slice(1, 7);
   if (!/^[A-Z]$/.test(prefix) || !/^[A-Z]$/.test(tail)) {
@@ -90,12 +101,13 @@ const format = (value: string): string => {
 };
 
 /** Andorra NRT (Número de Registre Tributari). */
-const nrt: Validator = {
+const nrt: CountryValidator<"AD"> = {
   name: "Andorra Tax Number",
   localName: "Número de Registre Tributari",
   abbreviation: "NRT",
   aliases: ["NRT", "Número de Registre Tributari"] as const,
   candidatePattern: "[A-Z]-?\\d{6}-?[A-Z]",
+  scope: "country",
   country: "AD",
   entityType: "any",
   sourceUrl:

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,
@@ -28,8 +31,8 @@ const calcCheck = (
   weights: readonly number[],
 ): number => {
   let sum = 0;
-  for (let i = 0; i < digits.length; i++) {
-    sum += Number(digits[i]) * weights[i]!;
+  for (const [i, weight] of weights.entries()) {
+    sum += Number(digits[i]) * weight;
   }
   return (10 - (sum % 10)) % 10;
 };
@@ -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 } from "#util/generate";
+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",
@@ -36,7 +39,17 @@ const VALID_TYPES = new Set([
   "55",
 ]);
 
-const WEIGHTS = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+const WEIGHTS = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2] as const;
+
+const GENERATE_TYPES = [
+  "20",
+  "23",
+  "24",
+  "27",
+  "30",
+  "33",
+  "34",
+] as const;
 
 const compact = (value: string): string =>
   clean(value, " -.").trim();
@@ -49,8 +62,8 @@ const compact = (value: string): string =>
  */
 const calcCheckDigit = (body: string): number => {
   let sum = 0;
-  for (let i = 0; i < 10; i++) {
-    sum += Number(body[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += Number(body[i]) * weight;
   }
   const remainder = 11 - (sum % 11);
   if (remainder === 11) return 0;
@@ -98,9 +111,7 @@ const format = (value: string): string => {
 
 /** Generate a random valid CUIT. */
 const generate = (): string => {
-  const types = ["20", "23", "24", "27", "30", "33", "34"];
-  const type =
-    types[Math.floor(Math.random() * types.length)]!;
+  const type = randomPick(GENERATE_TYPES);
   const body = type + randomDigits(8);
   const check = calcCheckDigit(body);
   return body + String(check);
@@ -112,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",
@@ -122,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,22 +6,37 @@
  * 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
  * position 3 and equals the weighted sum mod 11.
  */
-const WEIGHTS = [3, 7, 9, 5, 8, 4, 2, 1, 6];
+const WEIGHTS = [3, 7, 9, 5, 8, 4, 2, 1, 6] as const;
 
 const compact = (value: string): string =>
   clean(value, " -/").trim();
@@ -43,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",
     );
   }
 
@@ -58,8 +84,8 @@ const validate = (value: string): ValidateResult => {
   // number is invalid.
   const digits = v.slice(0, 3) + v.slice(4);
   let sum = 0;
-  for (let i = 0; i < 9; i++) {
-    sum += Number(digits[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += Number(digits[i]) * weight;
   }
   const check = sum % 11;
   if (check === 10) {
@@ -84,8 +110,30 @@ const format = (value: string): string => {
   return `${v.slice(0, 4)} ${v.slice(4, 6)}${v.slice(6, 8)}${v.slice(8)}`;
 };
 
+/** Generate a random valid Austrian VNR. */
+const generate = (): string => {
+  for (;;) {
+    // 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");
+    const digits = `${serial}${day}${month}${year}`;
+
+    let sum = 0;
+    for (const [i, weight] of WEIGHTS.entries()) {
+      sum += Number(digits[i]) * weight;
+    }
+
+    const check = sum % 11;
+    if (check === 10) continue;
+    return `${serial}${String(check)}${day}${month}${year}`;
+  }
+};
+
 /** Austrian Social Insurance Number. */
-const vnr: Validator = {
+const vnr: CountryValidator<"AT"> = {
   name: "Austrian Social Insurance Number",
   localName: "Versicherungsnummer",
   abbreviation: "VNR",
@@ -96,6 +144,7 @@ const vnr: Validator = {
     "Sozialversicherungsnummer",
   ] as const,
   candidatePattern: "\\d{4}\\s?\\d{6}",
+  scope: "country",
   country: "AT",
   entityType: "person",
   sourceUrl:
@@ -105,7 +154,8 @@ const vnr: Validator = {
   compact,
   format,
   validate,
+  generate,
 };
 
 export default vnr;
-export { compact, format, validate };
+export { compact, format, generate, validate };

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/",