@stll/stdnum 0.0.1 → 2.0.0

package/src/cu/ni.ts

@@ -15,16 +15,17 @@
  * @see https://www.ecured.cu/Carnet_de_Identidad
  */
 
-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 { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+
 const compact = (value: string): string =>
   clean(value, " -").trim();
 
@@ -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: CountryValidator<"CU", ParsedPersonId> = {
   name: "Cuban Identity Card Number",
   localName: "Número de Identidad",
   abbreviation: "NI",
@@ -111,15 +129,18 @@ const ni: Validator = {
     "carnet de identidad",
   ] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "CU",
   entityType: "person",
   lengths: [11] as const,
   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/cy/vat.ts

@@ -7,13 +7,16 @@
  * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/cyprus-tin.pdf
  */
 
+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 ODD_MAP: Record<number, number> = {
   0: 1,
   1: 0,
@@ -110,12 +113,13 @@ const generate = (): string => {
 };
 
 /** Cypriot VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"CY"> = {
   name: "Cypriot VAT Number",
   localName: "Αριθμός Εγγραφής Φ.Π.Α.",
   abbreviation: "ΦΠΑ",
   aliases: ["ΦΠΑ", "VAT CY"] as const,
   candidatePattern: "CY\\d{8}[A-Z]",
+  scope: "country",
   country: "CY",
   entityType: "company",
   sourceUrl: "https://www.mof.gov.cy/",

package/src/cz/dic.ts

@@ -11,15 +11,18 @@
  * @see https://adisspr.mfcr.cz/dpr/DphReg
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+import { validate as validateRc } from "./rc";
+
 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";
-import { validate as validateRc } from "./rc";
-
 const ICO_WEIGHTS = [8, 7, 6, 5, 4, 3, 2] as const;
 
 const compact = (value: string): string => {
@@ -115,15 +118,17 @@ const generate = (): string => {
 };
 
 /** Czech VAT Number. */
-const dic: Validator = {
+const dic: CountryValidator<"CZ"> = {
   name: "Czech VAT Number",
   localName: "Daňové identifikační číslo",
   abbreviation: "DIČ",
   aliases: ["DIČ", "daňové identifikační číslo"] as const,
   candidatePattern: "CZ\\d{8,10}",
+  scope: "country",
   country: "CZ",
   entityType: "any",
   sourceUrl: "https://adisspr.mfcr.cz/dpr/DphReg",
+  lengths: [8, 9, 10] as const,
   examples: ["25123891", "7103192745"] as const,
   compact,
   format,

package/src/cz/ico.ts

@@ -8,14 +8,17 @@
  * @see https://www.czso.cz/
  */
 
+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 = [8, 7, 6, 5, 4, 3, 2] as const;
 
 const compact = (value: string): string =>
@@ -59,12 +62,13 @@ const generate = (): string => {
 };
 
 /** Czech Company Identification Number. */
-const ico: Validator = {
+const ico: CountryValidator<"CZ"> = {
   name: "Czech Company ID",
   localName: "Identifikační číslo osoby",
   abbreviation: "IČO",
   aliases: ["IČO", "IČ", "identifikační číslo"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "CZ",
   entityType: "company",
   description:

package/src/cz/rc.ts

@@ -6,29 +6,57 @@
  * 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.
  */
 
+import type {
+  ParsedPersonId,
+  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 { isdigits } from "#util/strings";
 
-import type {
-  ParsedPersonId,
-  ValidateResult,
-  Validator,
-} from "../types";
-
 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,12 +196,13 @@ const generate = (): string => {
 };
 
 /** Czech/Slovak Birth Number. */
-const rc: Validator = {
+const rc: CountryValidator<"CZ", ParsedPersonId> = {
   name: "Czech Birth Number",
   localName: "Rodné číslo",
   abbreviation: "RČ",
   aliases: ["rodné číslo", "RČ", "birth number"] as const,
   candidatePattern: "\\d{6}/\\d{3,4}",
+  scope: "country",
   country: "CZ",
   entityType: "person",
   description:
@@ -182,6 +213,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}`;
 };
@@ -24,12 +31,15 @@ const generate = (): string => {
  * @see https://de.wikipedia.org/wiki/Handelsregister_(Deutschland)
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 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";
-
 const REGISTER_TYPES = new Set([
   "HRA",
   "HRB",
@@ -62,7 +72,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)) {
@@ -81,7 +95,7 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** German Company Register Number. */
-const handelsreg: Validator = {
+const handelsreg: CountryValidator<"DE"> = {
   name: "German Company Register Number",
   localName: "Handelsregisternummer",
   abbreviation: "HReg",
@@ -92,6 +106,7 @@ const handelsreg: Validator = {
     "HRA",
   ] as const,
   candidatePattern: "(?:HRA|HRB|GnR|PR|VR)\\s*\\d{1,7}",
+  scope: "country",
   country: "DE",
   entityType: "company",
   sourceUrl:

package/src/de/idnr.ts

@@ -10,6 +10,11 @@
  * @see https://www.bzst.de/DE/Privatpersonen/SteuerlicheIdentifikationsnummer/steuerlicheidentifikationsnummer_node.html
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   mod1110validate,
   mod1110checkDigit,
@@ -19,8 +24,6 @@ import { 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, " -/");
 
@@ -103,6 +106,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;
@@ -115,7 +121,7 @@ const generate = (): string => {
 };
 
 /** German Personal Tax ID. */
-const idnr: Validator = {
+const idnr: CountryValidator<"DE"> = {
   name: "German Tax ID",
   localName: "Steuerliche Identifikationsnummer",
   abbreviation: "IdNr",
@@ -125,6 +131,7 @@ const idnr: Validator = {
     "Steuer-ID",
   ] as const,
   candidatePattern: "\\d{2}\\s?\\d{3}\\s?\\d{3}\\s?\\d{3}",
+  scope: "country",
   country: "DE",
   entityType: "person",
   sourceUrl:

package/src/de/stnr.ts

@@ -26,13 +26,16 @@ const generate = (): string => {
  * @see https://de.wikipedia.org/wiki/Steuernummer
  */
 
+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";
-
 /**
  * Format patterns per federal state.
  * [0] = regional format, [1] = unified (federal) format.
@@ -166,9 +169,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));
@@ -190,12 +197,13 @@ const charCat = (ch: string): string => {
 };
 
 /** German Tax Number (Steuernummer). */
-const stnr: Validator = {
+const stnr: CountryValidator<"DE"> = {
   name: "German Tax Number",
   localName: "Steuernummer",
   abbreviation: "StNr",
   aliases: ["Steuernummer", "St.Nr."] as const,
   candidatePattern: "\\d{2,4}/\\d{3,4}/\\d{4,5}",
+  scope: "country",
   country: "DE",
   entityType: "any",
   description:

package/src/de/svnr.ts

@@ -9,6 +9,11 @@
  * @see https://de.wikipedia.org/wiki/Sozialversicherungsnummer
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import {
   isValidDate,
@@ -17,8 +22,6 @@ import {
 import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 const letterValue = (ch: string): number => {
   const code = ch.charCodeAt(0);
   if (code >= 65 && code <= 90) return code - 64;
@@ -39,6 +42,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 +52,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 {
@@ -132,7 +140,7 @@ const generate = (): string => {
 };
 
 /** German Social Insurance Number. */
-const svnr: Validator = {
+const svnr: CountryValidator<"DE"> = {
   name: "German Social Insurance Number",
   localName: "Sozialversicherungsnummer",
   abbreviation: "SVNR",
@@ -142,6 +150,7 @@ const svnr: Validator = {
     "Versicherungsnummer",
   ] as const,
   candidatePattern: "\\d{2}\\s?\\d{6}\\s?[A-Z]\\s?\\d{3}",
+  scope: "country",
   country: "DE",
   entityType: "person",
   description:

package/src/de/vat.ts

@@ -9,6 +9,11 @@
  * @see https://www.bzst.de/SharedDocs/Downloads/DE/Merkblaetter/ust_idnr_aufbau.pdf
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   mod1110checkDigit,
   mod1110validate,
@@ -18,8 +23,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 => {
   const v = clean(value, " -/");
   if (v.startsWith("DE") || v.startsWith("de")) {
@@ -70,7 +73,7 @@ const generate = (): string => {
 };
 
 /** German VAT Identification Number. */
-const vat: Validator = {
+const vat: CountryValidator<"DE"> = {
   name: "German VAT Number",
   localName: "Umsatzsteuer-Identifikationsnummer",
   abbreviation: "USt-IdNr.",
@@ -80,6 +83,7 @@ const vat: Validator = {
     "VAT DE",
   ] as const,
   candidatePattern: "DE\\d{9}",
+  scope: "country",
   country: "DE",
   entityType: "company",
   description:

package/src/dk/cpr.ts

@@ -8,17 +8,18 @@
  * @see https://cpr.dk/
  */
 
-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 { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
 const compact = (value: string): string =>
   clean(value, " -");
 
@@ -102,21 +103,35 @@ 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: CountryValidator<"DK", ParsedPersonId> = {
   name: "Danish Personal ID",
   localName: "Det Centrale Personregister",
   abbreviation: "CPR",
   aliases: ["CPR-nummer", "personnummer", "CPR"] as const,
   candidatePattern: "\\d{6}-?\\d{4}",
+  scope: "country",
   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 };