@stll/stdnum 0.0.1 → 1.0.0

package/src/bz/tin.ts

@@ -26,6 +26,7 @@
  */
 
 import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 
 import type { ValidateResult, Validator } from "../types";
@@ -79,6 +80,15 @@ const format = (value: string): string => {
   return `${v.slice(0, 6)}-${v.slice(6)}`;
 };
 
+/** Generate a random valid Belize TIN. */
+const generate = (): string => {
+  const base = randomDigits(6);
+  const suffixes = ["", ...SUFFIX_CODES] as const;
+  const suffix =
+    suffixes[randomInt(0, suffixes.length - 1)] ?? "";
+  return `${base}${suffix}`;
+};
+
 /**
  * Belize Tax Identification Number.
  *
@@ -97,6 +107,7 @@ const tin: Validator = {
   compact,
   format,
   validate,
+  generate,
   description:
     "Belize tax number issued by the Belize Tax Service Department",
   sourceUrl:
@@ -104,4 +115,4 @@ const tin: Validator = {
 };
 
 export default tin;
-export { compact, format, validate };
+export { compact, format, generate, validate };

package/src/cl/rut.ts

@@ -35,10 +35,12 @@ const compact = (value: string): string => {
  * 11 -> "0", 10 -> "K", else the digit as string.
  */
 const calcCheckDigit = (body: string): string => {
-  const weights = [2, 3, 4, 5, 6, 7];
+  const weights = [2, 3, 4, 5, 6, 7] as const;
   let sum = 0;
   for (let i = body.length - 1, w = 0; i >= 0; i--, w++) {
-    sum += Number(body[i]) * weights[w % 6]!;
+    // SAFETY: w % weights.length is a valid index.
+    // eslint-disable-next-line no-non-null-assertion
+    sum += Number(body[i]) * weights[w % weights.length]!;
   }
   const remainder = 11 - (sum % 11);
   if (remainder === 11) return "0";

package/src/cn/ric.ts

@@ -67,6 +67,8 @@ const validate = (value: string): ValidateResult => {
       "RIC must contain only digits (plus check char)",
     );
   }
+  // SAFETY: 18-character branch guarantees v[17] exists.
+  // eslint-disable-next-line no-non-null-assertion
   const lastChar = v[17]!;
   if (!isdigits(lastChar) && lastChar !== "X") {
     return err(
@@ -153,7 +155,7 @@ const generate = (): string => {
 };
 
 /** Chinese Resident Identity Card number. */
-const ric: Validator = {
+const ric: Validator<ParsedPersonId> = {
   name: "Chinese Resident Identity Card",
   localName: "居民身份证号码",
   abbreviation: "RIC",
@@ -172,6 +174,7 @@ const ric: Validator = {
   ] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/cn/uscc.ts

@@ -10,7 +10,11 @@
  */
 
 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";
 
@@ -28,10 +32,14 @@ const compact = (value: string): string =>
 
 const calcCheckChar = (value: string): string => {
   let total = 0;
-  for (let i = 0; i < 17; i++) {
-    const idx = ALPHABET.indexOf(value[i]!);
-    total += idx * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    const ch = value[i];
+    if (ch === undefined) continue;
+    total += ALPHABET.indexOf(ch) * weight;
   }
+  // SAFETY: (31 - total % 31) % 31 is in 0..30 and
+  // ALPHABET has 31 characters.
+  // eslint-disable-next-line no-non-null-assertion
   return ALPHABET[(31 - (total % 31)) % 31]!;
 };
 
@@ -45,8 +53,8 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
-  for (let i = 0; i < 18; i++) {
-    if (!ALPHABET.includes(v[i]!)) {
+  for (const ch of v) {
+    if (!ALPHABET.includes(ch)) {
       return err(
         "INVALID_FORMAT",
         "USCC contains invalid character",
@@ -75,12 +83,16 @@ const format = (value: string): string => compact(value);
 
 /** Generate a random valid USCC. */
 const generate = (): string => {
+  // SAFETY: indices 1..9 are within ALPHABET (31 chars).
+  // eslint-disable-next-line no-non-null-assertion
   const reg = ALPHABET[randomInt(1, 9)]!;
+  // eslint-disable-next-line no-non-null-assertion
   const etype = ALPHABET[randomInt(1, 9)]!;
   const region = randomDigits(6);
   let org = "";
-  for (let i = 0; i < 9; i++)
-    org += ALPHABET[randomInt(0, ALPHABET.length - 1)]!;
+  for (let i = 0; i < 9; i++) {
+    org += randomChar(ALPHABET);
+  }
   const payload = reg + etype + region + org;
   return payload + calcCheckChar(payload);
 };

package/src/co/nit.ts

@@ -30,9 +30,13 @@ const compact = (value: string): string =>
 const calcCheckDigit = (body: string): number => {
   let sum = 0;
   const len = body.length;
-  for (let i = 0; i < len; i++) {
-    sum += Number(body[len - 1 - i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    if (i >= len) break;
+    sum += Number(body[len - 1 - i]) * weight;
   }
+  // SAFETY: sum % 11 is in 0..10 and CHECK_DIGITS has
+  // 11 entries.
+  // eslint-disable-next-line no-non-null-assertion
   return CHECK_DIGITS[sum % 11]!;
 };
 

package/src/cr/cpf.ts

@@ -38,9 +38,10 @@ const compact = (value: string): string => {
 
   const parts = number.split("-");
   if (parts.length === 3) {
-    const p0 = parts[0]!.padStart(2, "0");
-    const p1 = parts[1]!.padStart(4, "0");
-    const p2 = parts[2]!.padStart(4, "0");
+    const [raw0, raw1, raw2] = parts;
+    const p0 = (raw0 ?? "").padStart(2, "0");
+    const p1 = (raw1 ?? "").padStart(4, "0");
+    const p2 = (raw2 ?? "").padStart(4, "0");
     number = p0 + p1 + p2;
   } else {
     number = number.replaceAll("-", "");

package/src/cu/ni.ts

@@ -17,6 +17,7 @@
 
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
+import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 
 import type {
@@ -58,6 +59,8 @@ const validate = (value: string): ValidateResult => {
   const yy = Number(v.slice(0, 2));
   const mm = Number(v.slice(2, 4));
   const dd = Number(v.slice(4, 6));
+  // SAFETY: regex check above guarantees v.length === 11.
+  // eslint-disable-next-line no-non-null-assertion
   const year = centuryOffset(v[6]!) + yy;
 
   if (!isValidDate(year, mm, dd)) {
@@ -84,6 +87,8 @@ const parse = (value: string): ParsedPersonId | null => {
   const yy = Number(v.slice(0, 2));
   const mm = Number(v.slice(2, 4));
   const dd = Number(v.slice(4, 6));
+  // SAFETY: regex check above guarantees v.length === 11.
+  // eslint-disable-next-line no-non-null-assertion
   const year = centuryOffset(v[6]!) + yy;
 
   const genderDigit = Number(v[9]);
@@ -96,12 +101,25 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+/** Generate a random valid Cuban NI. */
+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 yy = String(year % 100).padStart(2, "0");
+  const century =
+    year >= 2000
+      ? String(randomInt(6, 8))
+      : String(randomInt(0, 5));
+  return `${yy}${month}${day}${century}${randomDigits(4)}`;
+};
+
 /**
  * Cuban identity card number (NI).
  *
  * Examples sourced from python-stdnum test suite.
  */
-const ni: Validator = {
+const ni: Validator<ParsedPersonId> = {
   name: "Cuban Identity Card Number",
   localName: "Número de Identidad",
   abbreviation: "NI",
@@ -117,9 +135,11 @@ const ni: Validator = {
   examples: ["91021027775", "72062506561"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
   sourceUrl: "https://www.ecured.cu/Carnet_de_Identidad",
 };
 
 export default ni;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/cz/rc.ts

@@ -6,9 +6,19 @@
  * and gender. 10-digit numbers (post-1954) must
  * be divisible by 11.
  *
- * Women have 50 added to the month. Since 2004,
- * an extra +20 offset is used when the serial
- * range is exhausted.
+ * Women have 50 added to the month. For modern
+ * 10-digit numbers, an additional +20 offset may
+ * be used when the daily serial range is exhausted
+ * (+70 for women).
+ *
+ * Canonical source:
+ * - Czech Ministry of the Interior guidance on rodne
+ *   cislo, with the modern overflow-month rules
+ *
+ * We use this to keep the 9-digit historical form
+ * valid while rejecting modern +20/+70 month offsets
+ * on 9-digit numbers. Those overflow offsets are a
+ * modern rule for 10-digit values.
  *
  * @see https://www.mvcr.cz/mvcren/docDetail.aspx?docid=21975362&doctype=ART
  * @see Law 133/2000 Sb.
@@ -29,6 +39,24 @@ import type {
 const compact = (value: string): string =>
   clean(value, " /");
 
+const decodeMonth = (
+  rawMonth: number,
+  year: number,
+  length: number,
+): number | null => {
+  const candidates =
+    length === 10 && year >= 2004
+      ? [0, 50, 20, 70]
+      : [0, 50];
+  for (const offset of candidates) {
+    const month = rawMonth - offset;
+    if (month >= 1 && month <= 12) {
+      return month;
+    }
+  }
+  return null;
+};
+
 const validate = (value: string): ValidateResult => {
   const v = compact(value);
   if (v.length !== 9 && v.length !== 10) {
@@ -48,22 +76,6 @@ const validate = (value: string): ValidateResult => {
   const mm = Number(v.slice(2, 4));
   const dd = Number(v.slice(4, 6));
 
-  // Strip gender (+50) and overflow (+20) offsets
-  const month = (mm % 50) % 20 || mm % 50;
-  if (month < 1 || month > 12) {
-    return err(
-      "INVALID_COMPONENT",
-      "Birth number contains an invalid month",
-    );
-  }
-
-  if (dd < 1 || dd > 31) {
-    return err(
-      "INVALID_COMPONENT",
-      "Birth number contains an invalid day",
-    );
-  }
-
   // Resolve full year
   let year = yy + 1900;
   if (v.length === 9) {
@@ -80,6 +92,21 @@ const validate = (value: string): ValidateResult => {
     if (year < 1954) year += 100;
   }
 
+  const month = decodeMonth(mm, year, v.length);
+  if (month === null) {
+    return err(
+      "INVALID_COMPONENT",
+      "Birth number contains an invalid month",
+    );
+  }
+
+  if (dd < 1 || dd > 31) {
+    return err(
+      "INVALID_COMPONENT",
+      "Birth number contains an invalid day",
+    );
+  }
+
   // Validate the actual date
   if (!isValidDate(year, month, dd)) {
     return err(
@@ -122,13 +149,16 @@ const parse = (value: string): ParsedPersonId | null => {
   const mm = Number(v.slice(2, 4));
   const dd = Number(v.slice(4, 6));
 
-  const gender = mm > 50 ? "female" : "male";
-  const month = (mm % 50) % 20 || mm % 50;
-
+  const gender = mm >= 50 ? "female" : "male";
   let year = yy + 1900;
   if (v.length === 10 && year < 1954) year += 100;
   if (v.length === 9 && year >= 1980) year -= 100;
 
+  const month = decodeMonth(mm, year, v.length);
+  if (month === null) {
+    return null;
+  }
+
   return {
     birthDate: new Date(year, month - 1, dd),
     gender,
@@ -166,7 +196,7 @@ const generate = (): string => {
 };
 
 /** Czech/Slovak Birth Number. */
-const rc: Validator = {
+const rc: Validator<ParsedPersonId> = {
   name: "Czech Birth Number",
   localName: "Rodné číslo",
   abbreviation: "RČ",
@@ -182,6 +212,7 @@ const rc: Validator = {
   examples: ["7103192745"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/de/handelsreg.ts

@@ -1,7 +1,14 @@
+const GENERATE_TYPES = [
+  "HRA",
+  "HRB",
+  "GNR",
+  "PR",
+  "VR",
+] as const;
+
 /** Generate a random valid Handelsregisternummer. */
 const generate = (): string => {
-  const types = ["HRA", "HRB", "GNR", "PR", "VR"];
-  const type = types[randomInt(0, types.length - 1)]!;
+  const type = randomPick(GENERATE_TYPES);
   const number = randomDigits(5);
   return `${type} ${number}`;
 };
@@ -25,7 +32,7 @@ const generate = (): string => {
  */
 
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
+import { randomDigits, randomPick } from "#util/generate";
 import { err } from "#util/result";
 
 import type { ValidateResult, Validator } from "../types";
@@ -62,7 +69,11 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
+  // SAFETY: both capture groups are required, so a
+  // successful match always populates [1] and [2].
+  // eslint-disable-next-line no-non-null-assertion
   const type = match[1]!;
+  // eslint-disable-next-line no-non-null-assertion
   const number = match[2]!;
 
   if (!REGISTER_TYPES.has(type)) {

package/src/de/idnr.ts

@@ -103,6 +103,9 @@ const generate = (): string => {
     while (pool.length < 10) pool.push(randomInt(0, 9));
     for (let i = pool.length - 1; i > 0; i--) {
       const j = randomInt(0, i);
+      // SAFETY: i and j are valid indices of `pool`
+      // (i > 0, j ∈ [0, i]).
+      // eslint-disable-next-line no-non-null-assertion
       [pool[i], pool[j]] = [pool[j]!, pool[i]!];
     }
     if (pool[0] === 0) continue;

package/src/de/stnr.ts

@@ -166,9 +166,13 @@ const format = (value: string): string => {
     // category: literal digits, F, B, U, P
     const segments: string[] = [];
     let segStart = 0;
+    // SAFETY: fmt is a non-empty literal from COMPILED.
+    // eslint-disable-next-line no-non-null-assertion
     let prevCat = charCat(fmt[0]!);
 
     for (let i = 1; i < fmt.length; i++) {
+      // SAFETY: i < fmt.length.
+      // eslint-disable-next-line no-non-null-assertion
       const cat = charCat(fmt[i]!);
       if (cat !== prevCat) {
         segments.push(v.slice(segStart, i));

package/src/de/svnr.ts

@@ -39,6 +39,8 @@ const computeCheck = (v: string): number => {
     digits.push(Number(v[i]));
   }
 
+  // SAFETY: caller guarantees v.length === 12.
+  // eslint-disable-next-line no-non-null-assertion
   const lv = letterValue(v[8]!);
   digits.push(Math.floor(lv / 10));
   digits.push(lv % 10);
@@ -47,8 +49,11 @@ const computeCheck = (v: string): number => {
   digits.push(Number(v[10]));
 
   let sum = 0;
-  for (let i = 0; i < 12; i++) {
-    const product = digits[i]! * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    // SAFETY: WEIGHTS.length === 12 and we just pushed
+    // 12 entries onto `digits`.
+    // eslint-disable-next-line no-non-null-assertion
+    const product = digits[i]! * weight;
     if (product >= 10) {
       sum += Math.floor(product / 10) + (product % 10);
     } else {

package/src/dk/cpr.ts

@@ -10,6 +10,7 @@
 
 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";
 
@@ -102,8 +103,18 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+/** Generate a random valid Danish CPR. */
+const generate = (): string => {
+  const year = randomInt(1900, 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 serialPrefix = String(randomInt(0, 3));
+  return `${day}${month}${yy}${serialPrefix}${randomDigits(3)}`;
+};
+
 /** Danish Personal Identification Number. */
-const cpr: Validator = {
+const cpr: Validator<ParsedPersonId> = {
   name: "Danish Personal ID",
   localName: "Det Centrale Personregister",
   abbreviation: "CPR",
@@ -112,11 +123,14 @@ const cpr: Validator = {
   country: "DK",
   entityType: "person",
   sourceUrl: "https://cpr.dk/",
+  lengths: [10] as const,
   examples: ["2110625629"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default cpr;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/do/rnc.ts

@@ -38,8 +38,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);

package/src/ec/ruc.ts

@@ -46,8 +46,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;
 };

package/src/ee/ik.ts

@@ -5,7 +5,16 @@
  * 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 { weightedSum } from "#checksums/weighted-sum";
@@ -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,7 +144,7 @@ const generate = (): string => {
 };
 
 /** Estonian Personal Identification Code. */
-const ik: Validator = {
+const ik: Validator<ParsedPersonId> = {
   name: "Estonian Personal ID",
   localName: "Isikukood",
   abbreviation: "IK",
@@ -148,6 +157,7 @@ const ik: Validator = {
   examples: ["36805280109"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/ee/registrikood.ts

@@ -8,7 +8,7 @@
  */
 
 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";
 
@@ -52,10 +52,11 @@ 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));
 };

package/src/es/cif.ts

@@ -10,7 +10,7 @@
  */
 
 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";
 
@@ -72,8 +72,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))

package/src/es/nie.ts

@@ -9,7 +9,7 @@
  */
 
 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";
 
@@ -66,13 +66,18 @@ 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);
 };