@stll/stdnum 0.0.1 → 2.0.0

package/src/dk/cvr.ts

@@ -13,14 +13,17 @@
  * for CVR.
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 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";
-
 const WEIGHTS = [2, 7, 6, 5, 4, 3, 2, 1];
 
 const compact = (value: string): string =>
@@ -67,12 +70,13 @@ const generate = (): string => {
 };
 
 /** Danish Central Business Register Number. */
-const cvr: Validator = {
+const cvr: CountryValidator<"DK"> = {
   name: "Danish Business Register Number",
   localName: "CVR-nummer",
   abbreviation: "CVR",
   aliases: ["CVR-nummer", "CVR"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "DK",
   entityType: "company",
   sourceUrl: "https://erhvervsstyrelsen.dk/",

package/src/dk/vat.ts

@@ -11,14 +11,17 @@
  * for CVR.
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 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";
-
 const WEIGHTS = [2, 7, 6, 5, 4, 3, 2, 1];
 
 const compact = (value: string): string => {
@@ -71,15 +74,17 @@ const generate = (): string => {
 };
 
 /** Danish VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"DK"> = {
   name: "Danish VAT Number",
   localName: "Momsregistreringsnummer",
   abbreviation: "CVR",
   aliases: ["momsnummer", "SE-nummer"] as const,
   candidatePattern: "DK\\d{8}",
+  scope: "country",
   country: "DK",
   entityType: "company",
   sourceUrl: "https://erhvervsstyrelsen.dk/",
+  lengths: [8] as const,
   examples: ["13585628"] as const,
   compact,
   format,

package/src/do/rnc.ts

@@ -14,14 +14,17 @@
  * @see https://dgii.gov.do/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { luhnValidate } 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";
-
 /**
  * Weights for the 9-digit RNC check digit.
  * Applied to positions 0-7; check digit is at
@@ -38,8 +41,8 @@ const compact = (value: string): string =>
  */
 const calcRncCheckDigit = (value: string): string => {
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += Number(value[i]) * RNC_WEIGHTS[i]!;
+  for (const [i, weight] of RNC_WEIGHTS.entries()) {
+    sum += Number(value[i]) * weight;
   }
   const remainder = sum % 11;
   return String(((10 - remainder) % 9) + 1);
@@ -102,7 +105,7 @@ const generate = (): string => {
  *
  * Examples sourced from python-stdnum test suite.
  */
-const rnc: Validator = {
+const rnc: CountryValidator<"DO"> = {
   name: "Dominican Republic Tax ID",
   localName: "Registro Nacional del Contribuyente",
   abbreviation: "RNC",
@@ -111,6 +114,7 @@ const rnc: Validator = {
     "Registro Nacional del Contribuyente",
   ] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "DO",
   entityType: "any",
   lengths: [9, 11] as const,

package/src/ec/ruc.ts

@@ -17,13 +17,16 @@
  * @see https://www.sri.gob.ec/
  */
 
+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";
-
 const compact = (value: string): string =>
   clean(value, " -");
 
@@ -46,8 +49,8 @@ const mod11Checksum = (
   weights: readonly number[],
 ): number => {
   let sum = 0;
-  for (let i = 0; i < weights.length; i++) {
-    sum += Number(digits[i]) * weights[i]!;
+  for (const [i, weight] of weights.entries()) {
+    sum += Number(digits[i]) * weight;
   }
   return sum % 11;
 };
@@ -169,7 +172,7 @@ const generate = (): string => {
 };
 
 /** Ecuadorian tax identification number. */
-const ruc: Validator = {
+const ruc: CountryValidator<"EC"> = {
   name: "Registro Único de Contribuyentes",
   localName: "Registro Único de Contribuyentes",
   abbreviation: "RUC",
@@ -178,6 +181,7 @@ const ruc: Validator = {
     "Registro Único de Contribuyentes",
   ] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "EC",
   entityType: "any",
   description:

package/src/ee/ik.ts

@@ -5,9 +5,24 @@
  * gender/century digit, YYMMDD, 3-digit serial, and
  * a check digit computed with two-pass weighted sums.
  *
+ * Canonical sources:
+ * - Estonian legislation for the personal code format
+ * - OECD Estonia TIN sheet summarising the same
+ *   first-digit ranges for cross-border tax use
+ *
+ * These sources are why we restrict the first digit
+ * to 1-6 rather than accepting speculative 7/8 forms.
+ *
  * @see https://www.riigiteataja.ee/en/eli/512012015003/consolide
+ * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Estonia-TIN.pdf
  */
 
+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 +30,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_1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 1] as const;
 const WEIGHTS_2 = [3, 4, 5, 6, 7, 8, 9, 1, 2, 3] as const;
 
@@ -31,8 +40,6 @@ const centuryMap: Record<number, number> = {
   4: 1900,
   5: 2000,
   6: 2000,
-  7: 2100,
-  8: 2100,
 };
 
 const compact = (value: string): string =>
@@ -65,7 +72,9 @@ const validate = (value: string): ValidateResult => {
   }
 
   const g = Number(v[0]);
-  if (g < 1 || g > 8) {
+  // Official Estonian structure uses 1-6:
+  // 1-2 = 1800s, 3-4 = 1900s, 5-6 = 2000s.
+  if (g < 1 || g > 6) {
     return err(
       "INVALID_COMPONENT",
       "Isikukood gender/century digit is invalid",
@@ -135,12 +144,13 @@ const generate = (): string => {
 };
 
 /** Estonian Personal Identification Code. */
-const ik: Validator = {
+const ik: CountryValidator<"EE", ParsedPersonId> = {
   name: "Estonian Personal ID",
   localName: "Isikukood",
   abbreviation: "IK",
   aliases: ["isikukood", "IK"] as const,
   candidatePattern: "[1-6]\\d{10}",
+  scope: "country",
   country: "EE",
   entityType: "person",
   sourceUrl:
@@ -148,6 +158,7 @@ const ik: Validator = {
   examples: ["36805280109"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/ee/registrikood.ts

@@ -7,14 +7,17 @@
  * @see https://www.rik.ee/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+import { twoPassCheck } from "./ik";
+
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } 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";
-import { twoPassCheck } from "./ik";
-
 const VALID_FIRST = new Set(["1", "7", "8", "9"]);
 
 const compact = (value: string): string =>
@@ -52,21 +55,23 @@ const validate = (value: string): ValidateResult => {
 
 const format = (value: string): string => compact(value);
 
+const REGISTRIKOOD_FIRSTS = [1, 7, 8, 9] as const;
+
 /** Generate a random valid Estonian Registrikood. */
 const generate = (): string => {
-  const firsts = [1, 7, 8, 9];
-  const first = String(firsts[randomInt(0, 3)]!);
+  const first = String(randomPick(REGISTRIKOOD_FIRSTS));
   const payload = first + randomDigits(6);
   return payload + String(twoPassCheck(payload));
 };
 
 /** Estonian Company Registration Code. */
-const registrikood: Validator = {
+const registrikood: CountryValidator<"EE"> = {
   name: "Estonian Company Registration Code",
   localName: "Registrikood",
   abbreviation: "Registrikood",
   aliases: ["registrikood"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "EE",
   entityType: "company",
   sourceUrl: "https://www.rik.ee/",

package/src/ee/vat.ts

@@ -8,14 +8,17 @@
  * @see https://www.emta.ee/en
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 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 = [3, 7, 1, 3, 7, 1, 3, 7, 1];
 
 const compact = (value: string): string => {
@@ -62,7 +65,7 @@ const generate = (): string => {
 };
 
 /** Estonian VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"EE"> = {
   name: "Estonian VAT Number",
   localName: "Käibemaksukohustuslase number",
   abbreviation: "KMKR",
@@ -71,6 +74,7 @@ const vat: Validator = {
     "KMKR",
   ] as const,
   candidatePattern: "EE\\d{9}",
+  scope: "country",
   country: "EE",
   entityType: "company",
   sourceUrl: "https://www.emta.ee/en",

package/src/eg/tn.ts

@@ -11,13 +11,16 @@ const generate = (): string => randomDigits(9);
  * @see https://www.eta.gov.eg/
  */
 
+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";
-
 /**
  * Arabic-Indic and Extended Arabic-Indic digit map.
  * Converts Arabic numeral characters to ASCII digits.
@@ -81,12 +84,13 @@ const format = (value: string): string => {
 };
 
 /** Egyptian Tax Registration Number. */
-const tn: Validator = {
+const tn: CountryValidator<"EG"> = {
   name: "Egyptian Tax Registration Number",
   localName: "الرقم الضريبي",
   abbreviation: "TN",
   aliases: ["الرقم الضريبي", "tax number"] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "EG",
   entityType: "any",
   compact,

package/src/es/cif.ts

@@ -9,14 +9,17 @@
  * @see https://www.agenciatributaria.es/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+import { cifChecksum } from "./vat";
+
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
+import { randomChar, randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-import { cifChecksum } from "./vat";
-
 const CIF_PREFIXES = "ABCDEFGHJNPQRSUVW";
 const CIF_LETTERS = "JABCDEFGHI";
 
@@ -72,8 +75,7 @@ const format = (value: string): string => compact(value);
 
 /** Generate a random valid Spanish CIF. */
 const generate = (): string => {
-  const letter =
-    CIF_PREFIXES[randomInt(0, CIF_PREFIXES.length - 1)]!;
+  const letter = randomChar(CIF_PREFIXES);
   const payload = randomDigits(7);
   const check = cifChecksum(payload);
   if ("KPQS".includes(letter))
@@ -82,7 +84,7 @@ const generate = (): string => {
 };
 
 /** Spanish Company Tax ID (CIF). */
-const cif: Validator = {
+const cif: CountryValidator<"ES"> = {
   name: "Spanish Company Tax ID",
   localName: "Código de Identificación Fiscal",
   abbreviation: "CIF",
@@ -91,6 +93,7 @@ const cif: Validator = {
     "código de identificación fiscal",
   ] as const,
   candidatePattern: "[A-HJNP-SUVW]\\d{7}[\\dA-J]",
+  scope: "country",
   country: "ES",
   entityType: "company",
   sourceUrl: "https://www.agenciatributaria.es/",

package/src/es/dni.ts

@@ -8,13 +8,16 @@
  * @see https://www.interior.gob.es/opencms/es/servicios-al-ciudadano/tramites-y-gestiones/dni/
  */
 
+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 CHECK_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE";
 
 const compact = (value: string): string =>
@@ -59,7 +62,7 @@ const generate = (): string => {
 };
 
 /** Spanish National Identity Document. */
-const dni: Validator = {
+const dni: CountryValidator<"ES"> = {
   name: "Spanish National ID",
   localName: "Documento Nacional de Identidad",
   abbreviation: "DNI",
@@ -69,6 +72,7 @@ const dni: Validator = {
     "documento nacional de identidad",
   ] as const,
   candidatePattern: "\\d{1,2}\\.?\\d{3}\\.?\\d{3}-?[A-Z]",
+  scope: "country",
   country: "ES",
   entityType: "person",
   sourceUrl:

package/src/es/nie.ts

@@ -8,14 +8,17 @@
  * @see https://www.interior.gob.es/opencms/es/servicios-al-ciudadano/tramites-y-gestiones/nie/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+import { CHECK_LETTERS } from "./dni";
+
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } 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";
-import { CHECK_LETTERS } from "./dni";
-
 const PREFIX_MAP: Record<string, string> = {
   X: "0",
   Y: "1",
@@ -66,18 +69,23 @@ const validate = (value: string): ValidateResult => {
 
 const format = (value: string): string => compact(value);
 
+const NIE_PREFIXES = ["X", "Y", "Z"] as const;
+const NIE_PREFIX_VALUES: Record<
+  (typeof NIE_PREFIXES)[number],
+  number
+> = { X: 0, Y: 1, Z: 2 };
+
 /** Generate a random valid Spanish NIE. */
 const generate = (): string => {
-  const prefixes = ["X", "Y", "Z"] as const;
-  const vals: Record<string, number> = { X: 0, Y: 1, Z: 2 };
-  const prefix = prefixes[randomInt(0, 2)]!;
+  const prefix = randomPick(NIE_PREFIXES);
   const digits = randomDigits(7);
-  const num = vals[prefix]! * 10000000 + Number(digits);
+  const num =
+    NIE_PREFIX_VALUES[prefix] * 10000000 + Number(digits);
   return prefix + digits + CHECK_LETTERS.charAt(num % 23);
 };
 
 /** Spanish Foreigner Identification Number. */
-const nie: Validator = {
+const nie: CountryValidator<"ES"> = {
   name: "Spanish Foreigner ID",
   localName: "Número de Identidad de Extranjero",
   abbreviation: "NIE",
@@ -87,6 +95,7 @@ const nie: Validator = {
     "número de identidad de extranjero",
   ] as const,
   candidatePattern: "[XYZ]-?\\d{7}-?[A-Z]",
+  scope: "country",
   country: "ES",
   entityType: "person",
   sourceUrl:

package/src/es/nss.ts

@@ -15,13 +15,16 @@
  * @see https://intervia.com/doc/validar-numeros-de-la-seguridad-social/
  */
 
+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, " -/.");
 
@@ -85,12 +88,13 @@ const generate = (): string => {
 };
 
 /** Spanish Social Security Number. */
-const nss: Validator = {
+const nss: CountryValidator<"ES"> = {
   name: "Spanish Social Security Number",
   localName: "Número de la Seguridad Social",
   abbreviation: "NSS",
   aliases: ["NSS", "número de seguridad social"] as const,
   candidatePattern: "\\d{12}",
+  scope: "country",
   country: "ES",
   entityType: "person",
   description:

package/src/es/vat.ts

@@ -8,13 +8,16 @@
  * @see https://www.agenciatributaria.es/
  */
 
+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 DNI_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE";
 const CIF_LETTERS = "JABCDEFGHI";
 
@@ -70,8 +73,12 @@ const validate = (value: string): ValidateResult => {
 
   // NIE: X/Y/Z + 7 digits + letter
   if (first === "X" || first === "Y" || first === "Z") {
-    const prefix =
-      first === "X" ? "0" : first === "Y" ? "1" : "2";
+    let prefix = "2";
+    if (first === "X") {
+      prefix = "0";
+    } else if (first === "Y") {
+      prefix = "1";
+    }
     const digits = prefix + v.slice(1, 8);
     if (!isdigits(digits) || !isdigits(v.slice(1, 8))) {
       return err(
@@ -154,7 +161,7 @@ const generate = (): string => {
 };
 
 /** Spanish VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"ES"> = {
   name: "Spanish VAT Number",
   localName: "Número de Identificación Fiscal",
   abbreviation: "NIF",
@@ -164,6 +171,7 @@ const vat: Validator = {
     "número de identificación fiscal",
   ] as const,
   candidatePattern: "ES[A-Z]\\d{7}[A-Z\\d]",
+  scope: "country",
   country: "ES",
   entityType: "any",
   sourceUrl: "https://www.agenciatributaria.es/",

package/src/eu/vat.ts

@@ -12,9 +12,6 @@
  * @see https://ec.europa.eu/taxation_customs/vies/
  */
 
-import { clean } from "#util/clean";
-import { err } from "#util/result";
-
 import atUid from "../at/uid";
 import beVat from "../be/vat";
 import bgVat from "../bg/vat";
@@ -43,7 +40,14 @@ import roVat from "../ro/vat";
 import seVat from "../se/vat";
 import siVat from "../si/vat";
 import skDic from "../sk/dic";
-import type { Validator, ValidateResult } from "../types";
+import type {
+  GlobalValidator,
+  ValidateResult,
+} from "../types";
+
+import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
 
 type CountryValidator = {
   compact: (value: string) => string;
@@ -152,8 +156,52 @@ const format = (value: string): string => {
   return `${parts.cc}${validator.compact(parts.rest)}`;
 };
 
+const GENERATORS = [
+  ["AT", atUid],
+  ["BE", beVat],
+  ["BG", bgVat],
+  ["CY", cyVat],
+  ["CZ", czDic],
+  ["DE", deVat],
+  ["DK", dkVat],
+  ["EE", eeVat],
+  ["ES", esVat],
+  ["FI", fiVat],
+  ["FR", frTva],
+  ["GR", grVat],
+  ["HR", hrVat],
+  ["HU", huVat],
+  ["IE", ieVat],
+  ["IT", itIva],
+  ["LT", ltVat],
+  ["LU", luVat],
+  ["LV", lvVat],
+  ["MT", mtVat],
+  ["NL", nlVat],
+  ["PL", plNip],
+  ["PT", ptVat],
+  ["RO", roVat],
+  ["SE", seVat],
+  ["SI", siVat],
+  ["SK", skDic],
+] as const;
+
+/** Generate a random EU VAT number from a member validator. */
+const generate = (): string => {
+  for (;;) {
+    const candidate =
+      GENERATORS[randomInt(0, GENERATORS.length - 1)];
+    if (!candidate) continue;
+
+    const [prefix, validator] = candidate;
+    if (validator.generate === undefined) continue;
+    return `${prefix}${validator.generate()}`;
+  }
+};
+
 /** European Union VAT Number. */
-const euVat: Validator = {
+const euVat: GlobalValidator = {
+  scope: "global",
   name: "EU VAT Number",
   localName: "EU VAT Number",
   abbreviation: "EU VAT",
@@ -165,7 +213,8 @@ const euVat: Validator = {
   compact,
   format,
   validate,
+  generate,
 };
 
 export default euVat;
-export { compact, format, validate };
+export { compact, format, generate, validate };