@stll/stdnum 0.0.1 → 2.0.0

package/src/mx/curp.ts

@@ -14,16 +14,17 @@
  * @see https://en.wikipedia.org/wiki/CURP
  */
 
-import { clean } from "#util/clean";
-import { isValidDate } from "#util/date";
-import { err } from "#util/result";
-
 import type {
   ParsedPersonId,
   ValidateResult,
-  Validator,
+  CountryValidator,
 } from "../types";
 
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+
 /** Valid Mexican state codes (2-letter). */
 const STATE_CODES = new Set([
   "AS",
@@ -60,6 +61,8 @@ const STATE_CODES = new Set([
   "ZS",
   "NE", // Born abroad
 ]);
+const STATE_CODE_LIST = [...STATE_CODES];
+const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 
 /**
  * Alphabet for CURP check digit computation.
@@ -69,8 +72,8 @@ const STATE_CODES = new Set([
 const ALPHABET = "0123456789ABCDEFGHIJKLMN&OPQRSTUVWXYZ";
 
 const CHAR_MAP = new Map<string, number>();
-for (let i = 0; i < ALPHABET.length; i++) {
-  CHAR_MAP.set(ALPHABET[i]!, i);
+for (const [i, ch] of ALPHABET.split("").entries()) {
+  CHAR_MAP.set(ch, i);
 }
 
 const compact = (value: string): string =>
@@ -84,7 +87,9 @@ const compact = (value: string): string =>
 const calcCheckDigit = (value: string): string => {
   let sum = 0;
   for (let i = 0; i < 17; i++) {
-    sum += (CHAR_MAP.get(value[i]!) ?? 0) * (18 - i);
+    const ch = value[i];
+    if (ch === undefined) continue;
+    sum += (CHAR_MAP.get(ch) ?? 0) * (18 - i);
   }
   return String((10 - (sum % 10)) % 10);
 };
@@ -126,6 +131,8 @@ const validate = (value: string): ValidateResult => {
   const mm = Number(v.slice(6, 8));
   const dd = Number(v.slice(8, 10));
 
+  // SAFETY: regex validation ensures v.length === 18.
+  // eslint-disable-next-line no-non-null-assertion
   const year = resolveCurpYear(yy, v[16]!);
   if (!isValidDate(year, mm, dd)) {
     return err(
@@ -170,6 +177,8 @@ const parse = (value: string): ParsedPersonId | null => {
   const mm = Number(v.slice(6, 8));
   const dd = Number(v.slice(8, 10));
 
+  // SAFETY: regex validation ensures v.length === 18.
+  // eslint-disable-next-line no-non-null-assertion
   const year = resolveCurpYear(yy, v[16]!);
 
   const genderChar = v[10];
@@ -182,12 +191,37 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+const randomLetter = (): string =>
+  LETTERS.charAt(randomInt(0, LETTERS.length - 1));
+
+/** Generate a random valid CURP. */
+const generate = (): string => {
+  const year = randomInt(1980, 2024);
+  const month = String(randomInt(1, 12)).padStart(2, "0");
+  const day = String(randomInt(1, 28)).padStart(2, "0");
+  const yy = String(year % 100).padStart(2, "0");
+  const gender = Math.random() < 0.5 ? "H" : "M";
+  const state =
+    STATE_CODE_LIST[
+      randomInt(0, STATE_CODE_LIST.length - 1)
+    ] ?? "NE";
+  const centuryChar =
+    year >= 2000 ? randomLetter() : String(randomInt(0, 9));
+  const body =
+    `${randomLetter()}${randomLetter()}` +
+    `${randomLetter()}${randomLetter()}` +
+    `${yy}${month}${day}${gender}${state}` +
+    `${randomLetter()}${randomLetter()}${randomLetter()}` +
+    `${centuryChar}`;
+  return `${body}${calcCheckDigit(body)}`;
+};
+
 /**
  * Mexican CURP (personal identification number).
  *
  * Example sourced from python-stdnum test suite.
  */
-const curp: Validator = {
+const curp: CountryValidator<"MX", ParsedPersonId> = {
   name: "Mexican Personal ID",
   localName: "Clave Única de Registro de Población",
   abbreviation: "CURP",
@@ -196,15 +230,18 @@ const curp: Validator = {
     "Clave Única de Registro de Población",
   ] as const,
   candidatePattern: "[A-Z]{4}\\d{6}[HM][A-Z]{5}[A-Z\\d]\\d",
+  scope: "country",
   country: "MX",
   entityType: "person",
   lengths: [18] as const,
   examples: ["BOXW310820HNERXN09"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
   sourceUrl: "https://en.wikipedia.org/wiki/CURP",
 };
 
 export default curp;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/mx/rfc.ts

@@ -16,18 +16,22 @@
  * @see https://en.wikipedia.org/wiki/Tax_Identification_Number_(Mexico)
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
+import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 /** Alphabet for RFC check digit computation. */
 const ALPHABET = "0123456789ABCDEFGHIJKLMN&OPQRSTUVWXYZ Ñ";
 
 const CHAR_MAP = new Map<string, number>();
-for (let i = 0; i < ALPHABET.length; i++) {
-  CHAR_MAP.set(ALPHABET[i]!, i);
+for (const [i, ch] of ALPHABET.split("").entries()) {
+  CHAR_MAP.set(ch, i);
 }
 
 const compact = (value: string): string =>
@@ -48,7 +52,8 @@ const calcCheckDigit = (value: string): string => {
   const padded = value.length === 11 ? ` ${value}` : value;
   let sum = 0;
   for (let i = 0; i < 12; i++) {
-    const ch = padded[i]!;
+    const ch = padded[i];
+    if (ch === undefined) continue;
     const v = CHAR_MAP.get(ch) ?? 0;
     sum += v * (13 - i);
   }
@@ -60,6 +65,8 @@ const calcCheckDigit = (value: string): string => {
 
 const PERSON_RE = /^[A-ZÑ&]{4}\d{6}[A-Z\d]{3}$/;
 const COMPANY_RE = /^[A-ZÑ&]{3}\d{6}[A-Z\d]{3}$/;
+const PREFIX_ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZÑ&";
+const RFC_ALNUM = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 
 const validate = (value: string): ValidateResult => {
   const v = compact(value);
@@ -115,12 +122,38 @@ const validate = (value: string): ValidateResult => {
 
 const format = (value: string): string => compact(value);
 
+const randomCharFrom = (chars: string): string =>
+  chars.charAt(randomInt(0, chars.length - 1));
+
+/** Generate a random valid RFC. */
+const generate = (): string => {
+  const isPerson = Math.random() < 0.5;
+  const prefixLength = isPerson ? 4 : 3;
+  let prefix = "";
+  for (let i = 0; i < prefixLength; i++) {
+    prefix += randomCharFrom(PREFIX_ALPHA);
+  }
+
+  const year = randomInt(2000, 2099);
+  const month = String(randomInt(1, 12)).padStart(2, "0");
+  const day = String(randomInt(1, 28)).padStart(2, "0");
+  let homoclave = "";
+  for (let i = 0; i < 2; i++) {
+    homoclave += randomCharFrom(RFC_ALNUM);
+  }
+
+  const body =
+    `${prefix}${String(year % 100).padStart(2, "0")}` +
+    `${month}${day}${homoclave}`;
+  return `${body}${calcCheckDigit(body)}`;
+};
+
 /**
  * Mexican RFC (tax identification number).
  *
  * Examples sourced from python-stdnum test suite.
  */
-const rfc: Validator = {
+const rfc: CountryValidator<"MX"> = {
   name: "Mexican Tax ID",
   localName: "Registro Federal de Contribuyentes",
   abbreviation: "RFC",
@@ -129,6 +162,7 @@ const rfc: Validator = {
     "Registro Federal de Contribuyentes",
   ] as const,
   candidatePattern: "[A-ZÑ&]{3,4}\\d{6}[A-Z\\d]{3}",
+  scope: "country",
   country: "MX",
   entityType: "any",
   lengths: [12, 13] as const,
@@ -136,9 +170,10 @@ const rfc: Validator = {
   compact,
   format,
   validate,
+  generate,
   sourceUrl:
     "https://en.wikipedia.org/wiki/Tax_Identification_Number_(Mexico)",
 };
 
 export default rfc;
-export { compact, format, validate };
+export { compact, format, generate, validate };

package/src/my/nric.ts

@@ -12,17 +12,18 @@
  * @see https://en.wikipedia.org/wiki/Malaysian_identity_card
  */
 
-import { clean } from "#util/clean";
-import { isValidDate } from "#util/date";
-import { err } from "#util/result";
-import { isdigits } from "#util/strings";
-
 import type {
   ParsedPersonId,
   ValidateResult,
-  Validator,
+  CountryValidator,
 } from "../types";
 
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
 /**
  * Valid place-of-birth codes (2-digit).
  * Codes 01-16 are states, 21-59 are pre-2000
@@ -211,13 +212,35 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+const PB_CODES = [...VALID_PB_CODES];
+
+/** Generate a random valid Malaysian NRIC. */
+const generate = (): string => {
+  const year = randomInt(1950, 2024);
+  const month = String(randomInt(1, 12)).padStart(2, "0");
+  const day = String(randomInt(1, 28)).padStart(2, "0");
+  const pb =
+    PB_CODES[randomInt(0, PB_CODES.length - 1)] ?? "01";
+  const serial = String(randomInt(0, 999)).padStart(3, "0");
+  const isMale = Math.random() < 0.5;
+  const lastDigit = isMale
+    ? String(randomInt(0, 4) * 2 + 1)
+    : String(randomInt(0, 4) * 2);
+
+  return (
+    `${String(year % 100).padStart(2, "0")}` +
+    `${month}${day}${pb}${serial}${lastDigit}`
+  );
+};
+
 /** Malaysian National Registration Identity Card. */
-const nric: Validator = {
+const nric: CountryValidator<"MY", ParsedPersonId> = {
   name: "Malaysian National Registration Identity Card Number",
   localName: "Nombor Kad Pengenalan",
   abbreviation: "NRIC",
   aliases: ["NRIC", "MyKad", "kad pengenalan"] as const,
   candidatePattern: "\\d{6}-?\\d{2}-?\\d{4}",
+  scope: "country",
   country: "MY",
   entityType: "person",
   description:
@@ -228,8 +251,10 @@ const nric: Validator = {
   examples: ["770305021234", "880715141234"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default nric;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/ng/nin.ts

@@ -13,13 +13,16 @@ const generate = (): string => randomDigits(11);
  * @see https://nimc.gov.ng/about-nin/
  */
 
+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, " -");
 
@@ -46,7 +49,7 @@ const format = (value: string): string => {
 };
 
 /** Nigerian National Identification Number. */
-const nin: Validator = {
+const nin: CountryValidator<"NG"> = {
   name: "National Identification Number",
   localName: "National Identification Number",
   abbreviation: "NIN",
@@ -55,6 +58,7 @@ const nin: Validator = {
     "National Identification Number",
   ] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "NG",
   entityType: "person",
   lengths: [11] as const,

package/src/ni/ruc.ts

@@ -22,13 +22,16 @@
  * @see https://www.dgi.gob.ni/
  */
 
+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";
-
 /**
  * Check letter alphabet (mod 23). Excludes I, O, Z
  * to prevent transcription errors.
@@ -154,12 +157,13 @@ const format = (value: string): string => {
 const generate = (): string => "J" + randomDigits(13);
 
 /** Nicaragua tax identification number. */
-const ruc: Validator = {
+const ruc: CountryValidator<"NI"> = {
   name: "Tax Identification Number",
   localName: "Registro Único de Contribuyente",
   abbreviation: "RUC",
   aliases: ["RUC"] as const,
   candidatePattern: "[JKME]\\d{13}",
+  scope: "country",
   country: "NI",
   entityType: "any",
   description: "Tax identifier issued by Nicaragua's DGI",

package/src/nl/bsn.ts

@@ -8,14 +8,17 @@
  * @see https://www.government.nl/topics/personal-data/citizen-service-number-bsn
  */
 
+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 = [9, 8, 7, 6, 5, 4, 3, 2, -1] as const;
 
 const compact = (value: string): string =>
@@ -62,7 +65,7 @@ const generate = (): string => {
 };
 
 /** Dutch Citizen Service Number. */
-const bsn: Validator = {
+const bsn: CountryValidator<"NL"> = {
   name: "Dutch Citizen Service Number",
   localName: "Burgerservicenummer",
   abbreviation: "BSN",
@@ -72,6 +75,7 @@ const bsn: Validator = {
     "sofinummer",
   ] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "NL",
   entityType: "person",
   sourceUrl:

package/src/nl/kvk.ts

@@ -9,13 +9,16 @@ const generate = (): string => randomDigits(8);
  * @see https://www.kvk.nl/
  */
 
+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, " -/.");
 
@@ -39,12 +42,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Dutch Chamber of Commerce Number. */
-const kvk: Validator = {
+const kvk: CountryValidator<"NL"> = {
   name: "Dutch Chamber of Commerce Number",
   localName: "KvK-nummer",
   abbreviation: "KvK",
   aliases: ["KVK-nummer", "Kamer van Koophandel"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "NL",
   entityType: "company",
   sourceUrl: "https://www.kvk.nl/",

package/src/nl/vat.ts

@@ -2,20 +2,26 @@
  * BTW (Dutch VAT number).
  *
  * 12 characters: 9 digits + "B" + 2 digits.
- * Mod 97 check: convert "NL" + number to numeric
- * (N=23, L=21, B=11), mod 97 === 1.
  *
- * @see https://www.vatify.eu/netherlands-vat-number.html
+ * The current Dutch VAT identification number
+ * (btw-id) format is structural: `NL` + 9 digits
+ * + `B` + 2 digits. The official guidance explicitly
+ * states that the 9 digits are not derived from BSN
+ * and the final 2 digits are random.
+ *
  * @see https://business.gov.nl/regulations/using-checking-vat-numbers/
  */
 
+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 => {
   let v = clean(value, " -/.");
   if (v.startsWith("NL") || v.startsWith("nl")) {
@@ -30,42 +36,6 @@ const compact = (value: string): string => {
   return v;
 };
 
-/**
- * Compute mod 97 of a string containing digits and
- * uppercase letters (A=10, B=11, ..., Z=35).
- */
-const mod97 = (value: string): number => {
-  let remainder = 0;
-  for (const ch of value) {
-    const code = ch.charCodeAt(0);
-    if (code >= 48 && code <= 57) {
-      // Digit
-      remainder = (remainder * 10 + (code - 48)) % 97;
-    } else if (code >= 65 && code <= 90) {
-      // Letter: two decimal digits (A=10, ..., Z=35)
-      const num = code - 55;
-      remainder = (remainder * 100 + num) % 97;
-    }
-  }
-  return remainder;
-};
-
-/**
- * Check if a 9-digit string is a valid BSN (Dutch citizen
- * identification number). Weights [9,8,7,6,5,4,3,2,-1],
- * sum % 11 === 0.
- */
-const bsnValid = (num: string): boolean => {
-  if (!isdigits(num) || num.length !== 9) return false;
-  if (Number.parseInt(num, 10) <= 0) return false;
-  let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += (9 - i) * Number(num[i]);
-  }
-  sum -= Number(num[8]);
-  return sum % 11 === 0;
-};
-
 const validate = (value: string): ValidateResult => {
   const v = compact(value);
   if (v.length !== 12) {
@@ -92,25 +62,6 @@ const validate = (value: string): ValidateResult => {
       "Dutch VAT number must end with 2 digits",
     );
   }
-  if (Number.parseInt(v.slice(0, 9), 10) <= 0) {
-    return err(
-      "INVALID_FORMAT",
-      "Dutch VAT number first 9 digits must be > 0",
-    );
-  }
-  if (Number.parseInt(v.slice(10, 12), 10) <= 0) {
-    return err(
-      "INVALID_FORMAT",
-      "Dutch VAT number last 2 digits must be > 0",
-    );
-  }
-  // Valid if BSN check passes OR mod 97 check passes
-  if (!bsnValid(v.slice(0, 9)) && mod97(`NL${v}`) !== 1) {
-    return err(
-      "INVALID_CHECKSUM",
-      "Dutch VAT number checksum failed",
-    );
-  }
   return { valid: true, compact: v };
 };
 
@@ -118,24 +69,22 @@ const format = (value: string): string =>
   `NL${compact(value)}`;
 
 /** Generate a random valid Dutch VAT number. */
-const generate = (): string => {
-  for (;;) {
-    const c = randomDigits(9) + "B" + randomDigits(2);
-    if (validate(c).valid) return c;
-  }
-};
+const generate = (): string =>
+  `${randomDigits(9)}B${randomDigits(2)}`;
 
 /** Dutch VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"NL"> = {
   name: "Dutch VAT Number",
   localName: "BTW-identificatienummer",
   abbreviation: "BTW",
   aliases: ["BTW-nummer", "BTW-id"] as const,
   candidatePattern: "NL\\d{9}B\\d{2}",
+  scope: "country",
   country: "NL",
   entityType: "company",
-  sourceUrl: "https://www.belastingdienst.nl/",
-  examples: ["123456789B13"] as const,
+  sourceUrl:
+    "https://business.gov.nl/regulations/using-checking-vat-numbers/",
+  examples: ["000099998B57"] as const,
   compact,
   format,
   validate,

package/src/no/fodselsnummer.ts

@@ -8,18 +8,18 @@
  * @see https://www.skatteetaten.no/
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
 import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type {
-  ParsedPersonId,
-  ValidateResult,
-  Validator,
-} from "../types";
-
 const WEIGHTS_D1 = [3, 7, 6, 1, 8, 9, 4, 5, 2] as const;
 const WEIGHTS_D2 = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2] as const;
 
@@ -172,18 +172,23 @@ const generate = (): string => {
 };
 
 /** Norwegian Birth Number. */
-const fodselsnummer: Validator = {
+const fodselsnummer: CountryValidator<
+  "NO",
+  ParsedPersonId
+> = {
   name: "Norwegian Birth Number",
   localName: "Fødselsnummer",
   abbreviation: "Fødselsnr",
   aliases: ["fødselsnummer", "personnummer"] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "NO",
   entityType: "person",
   sourceUrl: "https://www.skatteetaten.no/",
   examples: ["15108695088"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/no/mva.ts

@@ -7,15 +7,18 @@
  * @see https://www.skatteetaten.no/
  */
 
-import { clean } from "#util/clean";
-import { err } from "#util/result";
-
-import type { ValidateResult, Validator } from "../types";
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
 import {
   validate as validateOrgnr,
   generate as generateOrgnr,
 } from "./orgnr";
 
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
 const compact = (value: string): string => {
   let v = clean(value, " -").toUpperCase();
   if (v.startsWith("NO")) {
@@ -53,12 +56,13 @@ const format = (value: string): string => {
 const generate = (): string => generateOrgnr() + "MVA";
 
 /** Norwegian VAT Number. */
-const mva: Validator = {
+const mva: CountryValidator<"NO"> = {
   name: "Norwegian VAT Number",
   localName: "Merverdiavgift",
   abbreviation: "MVA",
   aliases: ["MVA-nummer", "organisasjonsnummer"] as const,
   candidatePattern: "NO\\d{9}MVA",
+  scope: "country",
   country: "NO",
   entityType: "company",
   sourceUrl: "https://www.skatteetaten.no/",