@stll/stdnum 0.0.1 → 1.0.0

package/src/lv/vat.ts

@@ -1,12 +1,29 @@
 /**
  * PVN (Latvian VAT number).
  *
- * 11 digits. Legal entities (first digit > 3):
- * weights [9,1,4,8,3,10,2,5,7,6,1], sum % 11 === 3.
- * Personal (first digit <= 3): 11-digit format only.
+ * 11 digits.
  *
- * @see https://www.vatify.eu/latvia-vat-number.html
- * @see https://www.vid.gov.lv/en
+ * Individuals:
+ * - legacy personal codes: DDMMYY + century digit 0/1/2 + 4 digits
+ * - since 1 July 2017: codes start with 3, the second digit is 2-9,
+ *   and the remaining digits are random
+ *
+ * Entities:
+ * - tax administration issued: 9XXXXXXXXXX
+ * - enterprise register issued: 4XXXXXXXXXX / 5XXXXXXXXXX
+ *
+ * Canonical sources:
+ * - OECD Latvia TIN sheet for the tax-facing formats
+ * - PMLP page documenting the post-2017 personal code
+ *
+ * These are the reasons we accept the new personal
+ * code shape (`3` + second digit `2-9`) without the
+ * legacy birth-date checksum, and why we reject
+ * legacy personal codes with century digits outside
+ * 0/1/2.
+ *
+ * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Latvia-TIN.pdf
+ * @see https://www.pmlp.gov.lv/en/change-personal-identity-number
  */
 
 import { weightedSum } from "#checksums/weighted-sum";
@@ -46,6 +63,9 @@ const validateBirthDate = (v: string): boolean => {
   const month = Number(v.slice(2, 4));
   const year2 = Number(v.slice(4, 6));
   const century = Number(v[6]);
+  if (century < 0 || century > 2) {
+    return false;
+  }
   const fullYear = 1800 + century * 100 + year2;
   const date = new Date(fullYear, month - 1, day);
   return (
@@ -69,9 +89,19 @@ const validate = (value: string): ValidateResult => {
       "Latvian VAT number must contain only digits",
     );
   }
-  const first = Number(v[0]);
-  // Legal entity: first digit > 3
-  if (first > 3) {
+  if (
+    v[0] === "3" &&
+    v[1] !== undefined &&
+    v[1] >= "2" &&
+    v[1] <= "9"
+  ) {
+    // Since 1 July 2017, new personal codes start with 3
+    // and are syntactic identifiers only.
+    return { valid: true, compact: v };
+  }
+
+  const first = v[0];
+  if (first === "4" || first === "5" || first === "9") {
     const sum = weightedSum(v, WEIGHTS, 11);
     if (sum !== 3) {
       return err(
@@ -79,15 +109,6 @@ const validate = (value: string): ValidateResult => {
         "Latvian VAT number check digit mismatch",
       );
     }
-  } else if (v.startsWith("32")) {
-    // New-format personal code (from July 2017),
-    // no birth date; checksum only
-    if (!checkPersonal(v)) {
-      return err(
-        "INVALID_CHECKSUM",
-        "Latvian personal code check digit mismatch",
-      );
-    }
   } else {
     // Old-format personal code: first 6 digits encode
     // birth date as DDMMYY, digit 7 encodes century
@@ -112,8 +133,12 @@ const format = (value: string): string =>
 
 /** Generate a random valid Latvian VAT number. */
 const generate = (): string => {
+  const entityPrefixes = ["4", "5", "9"] as const;
   for (;;) {
-    const c = String(randomInt(4, 9)) + randomDigits(10);
+    const c =
+      randomInt(0, 1) === 0
+        ? `3${randomInt(2, 9)}${randomDigits(9)}`
+        : `${entityPrefixes[randomInt(0, entityPrefixes.length - 1)] ?? "4"}${randomDigits(10)}`;
     if (validate(c).valid) return c;
   }
 };
@@ -127,8 +152,9 @@ const vat: Validator = {
   candidatePattern: "LV\\d{11}",
   country: "LV",
   entityType: "any",
-  sourceUrl: "https://www.vid.gov.lv/en",
-  examples: ["40003521600"] as const,
+  sourceUrl:
+    "https://www.pmlp.gov.lv/en/change-personal-identity-number",
+  examples: ["40003521600", "32999999999"] as const,
   compact,
   format,
   validate,

package/src/mx/curp.ts

@@ -16,6 +16,7 @@
 
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
+import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 
 import type {
@@ -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].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: Validator<ParsedPersonId> = {
   name: "Mexican Personal ID",
   localName: "Clave Única de Registro de Población",
   abbreviation: "CURP",
@@ -202,9 +236,11 @@ const curp: Validator = {
   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

@@ -18,6 +18,7 @@
 
 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";
@@ -26,8 +27,8 @@ import type { ValidateResult, Validator } from "../types";
 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].entries()) {
+  CHAR_MAP.set(ch, i);
 }
 
 const compact = (value: string): string =>
@@ -48,7 +49,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 +62,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,6 +119,32 @@ 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).
  *
@@ -136,9 +166,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

@@ -14,6 +14,7 @@
 
 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";
 
@@ -211,8 +212,29 @@ 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: Validator<ParsedPersonId> = {
   name: "Malaysian National Registration Identity Card Number",
   localName: "Nombor Kad Pengenalan",
   abbreviation: "NRIC",
@@ -228,8 +250,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/nl/vat.ts

@@ -2,10 +2,13 @@
  * 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/
  */
 
@@ -30,42 +33,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 +59,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,12 +66,8 @@ 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 = {
@@ -134,8 +78,9 @@ const vat: Validator = {
   candidatePattern: "NL\\d{9}B\\d{2}",
   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

@@ -172,7 +172,7 @@ const generate = (): string => {
 };
 
 /** Norwegian Birth Number. */
-const fodselsnummer: Validator = {
+const fodselsnummer: Validator<ParsedPersonId> = {
   name: "Norwegian Birth Number",
   localName: "Fødselsnummer",
   abbreviation: "Fødselsnr",
@@ -184,6 +184,7 @@ const fodselsnummer: Validator = {
   examples: ["15108695088"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/nz/ird.ts

@@ -28,15 +28,15 @@ const SECONDARY_WEIGHTS = [7, 4, 3, 2, 5, 2, 7, 6] as const;
 const calcCheckDigit = (payload: string): number | null => {
   const padded = payload.padStart(8, "0");
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += PRIMARY_WEIGHTS[i]! * Number(padded[i]);
+  for (const [i, weight] of PRIMARY_WEIGHTS.entries()) {
+    sum += weight * Number(padded[i]);
   }
   let remainder = ((-sum % 11) + 11) % 11;
   if (remainder !== 10) return remainder;
 
   sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += SECONDARY_WEIGHTS[i]! * Number(padded[i]);
+  for (const [i, weight] of SECONDARY_WEIGHTS.entries()) {
+    sum += weight * Number(padded[i]);
   }
   remainder = ((-sum % 11) + 11) % 11;
   if (remainder === 10) return null;

package/src/pa/ruc.ts

@@ -111,19 +111,26 @@ const computeDV = (
 ): string | null => {
   const len = segments.length;
 
-  if (
-    len < 3 ||
-    len > 4 ||
-    (len === 4 && segments[1] !== "NT")
-  ) {
+  if (len < 3 || len > 4) {
+    return null;
+  }
+  // The NT designation requires exactly 4 segments
+  // (xxNT-NT-xxx-xxx); any other 4-segment shape is
+  // unrecognized, and a 3-segment "NT" in position 1
+  // is malformed.
+  if ((len === 4) !== (segments[1] === "NT")) {
     return null;
   }
 
   let buf: string;
   let isOld = false;
 
+  // SAFETY: length check above ensures 3..4 segments.
+  // eslint-disable-next-line no-non-null-assertion
   const s0 = segments[0]!;
+  // eslint-disable-next-line no-non-null-assertion
   const s1 = segments[1]!;
+  // eslint-disable-next-line no-non-null-assertion
   const s2 = segments[2]!;
 
   if (raw[0] === "E") {
@@ -138,7 +145,9 @@ const computeDV = (
       z(5 - s2.length) +
       s2;
   } else if (s1 === "NT") {
-    // NT designation (xxNT-xxx-xxx)
+    // NT designation (xxNT-NT-xxx-xxx)
+    // SAFETY: NT branch implies len === 4 (checked above).
+    // eslint-disable-next-line no-non-null-assertion
     const s3 = segments[3]!;
     const prefix = s0.slice(0, -2);
     buf =
@@ -220,8 +229,14 @@ const computeDV = (
       s1 +
       z(6 - s2.length) +
       s2;
+    // SAFETY: juridical branch zero-pads s0 to at least
+    // 10 chars (z(10 - s0.length)), so buf[3..6] are
+    // always defined.
     isOld =
-      buf[3] === "0" && buf[4] === "0" && buf[5]! < "5";
+      buf[3] === "0" &&
+      buf[4] === "0" &&
+      // eslint-disable-next-line no-non-null-assertion
+      buf[5]! < "5";
   }
 
   // Apply legacy cross-reference for old format
@@ -270,7 +285,10 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
+  // SAFETY: both DV regex capture groups are required.
+  // eslint-disable-next-line no-non-null-assertion
   const rucPart = dvMatch[1]!;
+  // eslint-disable-next-line no-non-null-assertion
   const dvPart = dvMatch[2]!;
 
   // The RUC part should be hyphen-separated segments
@@ -318,7 +336,10 @@ const format = (value: string): string => {
   const dvMatch = v.match(/^(.+?)-?\s*DV[:\s]*(\d{2})$/);
   if (!dvMatch) return v;
 
+  // SAFETY: both DV regex capture groups are required.
+  // eslint-disable-next-line no-non-null-assertion
   const rucPart = dvMatch[1]!.replace(/-+$/, "");
+  // eslint-disable-next-line no-non-null-assertion
   const dvPart = dvMatch[2]!;
   const segments = rucPart.split("-");
   return `${segments.join("-")} DV ${dvPart}`;
@@ -330,7 +351,10 @@ const generate = (): string => {
   const volume = String(randomInt(1, 9999));
   const folio = String(randomInt(1, 99999));
   const segments = [province, volume, folio];
-  const dv = computeDV(segments, segments.join("-"))!;
+  const dv = computeDV(segments, segments.join("-"));
+  if (dv === null) {
+    throw new Error("Failed to compute Panama RUC DV");
+  }
   return `${segments.join("-")} DV${dv}`;
 };