@stll/stdnum 0.0.1 → 2.0.0

package/src/ua/edrpou.ts

@@ -10,13 +10,16 @@
  * @see https://usr.minjust.gov.ua/
  */
 
+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 WEIGHTS_A = [1, 2, 3, 4, 5, 6, 7] as const;
 const WEIGHTS_B = [7, 1, 2, 3, 4, 5, 6] as const;
 const WEIGHTS_A2 = [3, 4, 5, 6, 7, 8, 9] as const;
@@ -27,8 +30,9 @@ const calcCheck = (
   weights: readonly number[],
 ): number => {
   let sum = 0;
-  for (let i = 0; i < 7; i++) {
-    sum += Number(value[i]) * weights[i]!;
+  for (const [i, weight] of weights.entries()) {
+    if (i >= 7) break;
+    sum += Number(value[i]) * weight;
   }
   return sum % 11;
 };
@@ -82,12 +86,13 @@ const generate = (): string => {
 };
 
 /** Ukrainian Company Register Number. */
-const edrpou: Validator = {
+const edrpou: CountryValidator<"UA"> = {
   name: "Ukrainian Company Register Number",
   localName: "ЄДРПОУ",
   abbreviation: "ЄДРПОУ",
   aliases: ["ЄДРПОУ", "EDRPOU"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "UA",
   entityType: "company",
   lengths: [8] as const,

package/src/us/ein.ts

@@ -1,92 +1,92 @@
+const EIN_PREFIXES = [
+  "01",
+  "02",
+  "03",
+  "04",
+  "05",
+  "06",
+  "10",
+  "11",
+  "12",
+  "13",
+  "14",
+  "15",
+  "16",
+  "20",
+  "21",
+  "22",
+  "23",
+  "24",
+  "25",
+  "26",
+  "27",
+  "30",
+  "31",
+  "32",
+  "33",
+  "34",
+  "35",
+  "36",
+  "37",
+  "38",
+  "39",
+  "40",
+  "41",
+  "42",
+  "43",
+  "44",
+  "45",
+  "46",
+  "47",
+  "48",
+  "50",
+  "51",
+  "52",
+  "53",
+  "54",
+  "55",
+  "56",
+  "57",
+  "58",
+  "59",
+  "60",
+  "61",
+  "62",
+  "63",
+  "64",
+  "65",
+  "66",
+  "67",
+  "68",
+  "71",
+  "72",
+  "73",
+  "74",
+  "75",
+  "76",
+  "77",
+  "80",
+  "81",
+  "82",
+  "83",
+  "84",
+  "85",
+  "86",
+  "87",
+  "88",
+  "90",
+  "91",
+  "92",
+  "93",
+  "94",
+  "95",
+  "98",
+  "99",
+] as const;
+
 /** Generate a random valid U.S. EIN. */
 const generate = (): string => {
-  const prefixes = [
-    "01",
-    "02",
-    "03",
-    "04",
-    "05",
-    "06",
-    "10",
-    "11",
-    "12",
-    "13",
-    "14",
-    "15",
-    "16",
-    "20",
-    "21",
-    "22",
-    "23",
-    "24",
-    "25",
-    "26",
-    "27",
-    "30",
-    "31",
-    "32",
-    "33",
-    "34",
-    "35",
-    "36",
-    "37",
-    "38",
-    "39",
-    "40",
-    "41",
-    "42",
-    "43",
-    "44",
-    "45",
-    "46",
-    "47",
-    "48",
-    "50",
-    "51",
-    "52",
-    "53",
-    "54",
-    "55",
-    "56",
-    "57",
-    "58",
-    "59",
-    "60",
-    "61",
-    "62",
-    "63",
-    "64",
-    "65",
-    "66",
-    "67",
-    "68",
-    "71",
-    "72",
-    "73",
-    "74",
-    "75",
-    "76",
-    "77",
-    "80",
-    "81",
-    "82",
-    "83",
-    "84",
-    "85",
-    "86",
-    "87",
-    "88",
-    "90",
-    "91",
-    "92",
-    "93",
-    "94",
-    "95",
-    "98",
-    "99",
-  ];
-  const prefix =
-    prefixes[randomInt(0, prefixes.length - 1)]!;
+  const prefix = randomPick(EIN_PREFIXES);
   return prefix + randomDigits(7);
 };
 
@@ -101,13 +101,16 @@ const generate = (): string => {
  * @see https://www.irs.gov/businesses/small-businesses-self-employed/how-eins-are-assigned-and-valid-ein-prefixes
  */
 
+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 { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 /**
  * Valid EIN campus prefixes. Sourced from IRS
  * documentation and python-stdnum's numdb.
@@ -232,7 +235,7 @@ const format = (value: string): string => {
 };
 
 /** U.S. Employer Identification Number. */
-const ein: Validator = {
+const ein: CountryValidator<"US"> = {
   name: "Employer Identification Number",
   localName: "Employer Identification Number",
   abbreviation: "EIN",
@@ -242,6 +245,7 @@ const ein: Validator = {
     "Federal Tax ID",
   ] as const,
   candidatePattern: "\\d{2}-?\\d{7}",
+  scope: "country",
   country: "US",
   entityType: "company",
   sourceUrl:

package/src/us/itin.ts

@@ -1,13 +1,12 @@
+const ITIN_ALLOWED_GROUPS = Array.from(
+  { length: 30 },
+  (_, i) => i + 70,
+).filter((g) => g !== 89 && g !== 93);
+
 /** Generate a random valid U.S. ITIN. */
 const generate = (): string => {
   const area = "9" + randomDigits(2);
-  const allowed = Array.from(
-    { length: 30 },
-    (_, i) => i + 70,
-  ).filter((g) => g !== 89 && g !== 93);
-  const group = String(
-    allowed[randomInt(0, allowed.length - 1)]!,
-  );
+  const group = String(randomPick(ITIN_ALLOWED_GROUPS));
   const serial = randomDigits(4);
   return `${area}${group}${serial}`;
 };
@@ -24,13 +23,16 @@ const generate = (): string => {
  * @see https://www.irs.gov/individuals/individual-taxpayer-identification-number
  */
 
+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 { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const ITIN_RE = /^(?<area>\d{3})-?(?<group>\d{2})-?\d{4}$/;
 
 /** Groups 70-99 excluding 89 and 93. */
@@ -100,7 +102,7 @@ const format = (value: string): string => {
 /**
  * U.S. Individual Taxpayer Identification Number.
  */
-const itin: Validator = {
+const itin: CountryValidator<"US"> = {
   name: "Individual Taxpayer Identification Number",
   localName: "Individual Taxpayer Identification Number",
   abbreviation: "ITIN",
@@ -109,6 +111,7 @@ const itin: Validator = {
     "Individual Taxpayer Identification Number",
   ] as const,
   candidatePattern: "9\\d{2}[\\s-]?\\d{2}[\\s-]?\\d{4}",
+  scope: "country",
   country: "US",
   entityType: "person",
   sourceUrl:

package/src/us/rtn.ts

@@ -7,22 +7,29 @@
  * [3, 7, 1] repeated three times.
  *
  * The first two digits identify the Federal Reserve
- * district (01-12) or special ranges (21-32 for
- * thrifts, 61-72 for electronic, 80 for traveler's
- * cheques).
+ * district (01-12) or special ranges (00 for U.S.
+ * Government, 21-32 for thrifts, 61-72 for electronic,
+ * 80 for traveler's cheques).
  *
  * @see https://en.wikipedia.org/wiki/ABA_routing_transit_number
  * @see https://www.frbservices.org/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
+import {
+  randomDigits,
+  randomInt,
+  randomPick,
+} 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 WEIGHTS = [3, 7, 1, 3, 7, 1, 3, 7, 1] as const;
 
 const compact = (value: string): string =>
   clean(value, " -").trim();
@@ -44,7 +51,11 @@ const validate = (value: string): ValidateResult => {
   // Validate Federal Reserve prefix (first 2 digits)
   const prefix = Number(v.slice(0, 2));
   const validPrefixRanges =
-    (prefix >= 1 && prefix <= 12) ||
+    // 00 is reserved for U.S. Government and federal
+    // agencies per the ABA Routing Number Policy;
+    // 01-12 are the 12 Federal Reserve districts.
+    // @see https://en.wikipedia.org/wiki/ABA_routing_transit_number
+    (prefix >= 0 && prefix <= 12) ||
     (prefix >= 21 && prefix <= 32) ||
     (prefix >= 61 && prefix <= 72) ||
     prefix === 80;
@@ -57,8 +68,8 @@ const validate = (value: string): ValidateResult => {
 
   // Weighted checksum must be divisible by 10
   let sum = 0;
-  for (let i = 0; i < 9; i++) {
-    sum += Number(v[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += Number(v[i]) * weight;
   }
   if (sum % 10 !== 0) {
     return err(
@@ -74,7 +85,7 @@ const format = (value: string): string => compact(value);
 
 /** All valid Federal Reserve prefix ranges. */
 const PREFIX_RANGES: readonly [number, number][] = [
-  [1, 12],
+  [0, 12],
   [21, 32],
   [61, 72],
   [80, 80],
@@ -82,23 +93,24 @@ const PREFIX_RANGES: readonly [number, number][] = [
 
 /** Generate a random valid U.S. RTN. */
 const generate = (): string => {
-  const range =
-    PREFIX_RANGES[randomInt(0, PREFIX_RANGES.length - 1)]!;
-  const prefix = String(
-    randomInt(range[0], range[1]),
-  ).padStart(2, "0");
+  const [low, high] = randomPick(PREFIX_RANGES);
+  const prefix = String(randomInt(low, high)).padStart(
+    2,
+    "0",
+  );
   const mid = randomDigits(6);
   const body = prefix + mid;
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += Number(body[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    if (i >= 8) break;
+    sum += Number(body[i]) * weight;
   }
   const check = (10 - (sum % 10)) % 10;
   return body + String(check);
 };
 
 /** U.S. Routing Transit Number. */
-const rtn: Validator = {
+const rtn: CountryValidator<"US"> = {
   name: "Routing Transit Number",
   localName: "Routing Transit Number",
   abbreviation: "RTN",
@@ -110,6 +122,7 @@ const rtn: Validator = {
     "Routing Transit Number",
   ] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "US",
   entityType: "company",
   sourceUrl:

package/src/us/ssn.ts

@@ -27,13 +27,16 @@ const generate = (): string => {
  * @see https://www.ssa.gov/employer/verifySSN.htm
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 /** Known-invalid SSNs used in advertisements. */
 const BLACKLIST = new Set([
   "078051120",
@@ -97,12 +100,13 @@ const format = (value: string): string => {
 };
 
 /** U.S. Social Security Number. */
-const ssn: Validator = {
+const ssn: CountryValidator<"US"> = {
   name: "Social Security Number",
   localName: "Social Security Number",
   abbreviation: "SSN",
   aliases: ["SSN", "Social Security Number"] as const,
   candidatePattern: "\\d{3}-?\\d{2}-?\\d{4}",
+  scope: "country",
   country: "US",
   entityType: "person",
   sourceUrl: "https://www.ssa.gov/employer/verifySSN.htm",

package/src/uy/rut.ts

@@ -13,13 +13,16 @@
  * @see https://www.agesic.gub.uy/
  */
 
+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 WEIGHTS = [4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2] as const;
 
 const compact = (value: string): string => {
@@ -39,8 +42,8 @@ const pymod = (a: number, b: number): number =>
 
 const calcCheckDigit = (value: string): string | null => {
   let sum = 0;
-  for (let i = 0; i < 11; i++) {
-    sum += Number(value[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += Number(value[i]) * weight;
   }
   const result = pymod(-sum, 11);
   // A result of 10 means no valid single-digit check
@@ -125,12 +128,13 @@ const generate = (): string => {
  *
  * Examples sourced from python-stdnum test suite.
  */
-const rut: Validator = {
+const rut: CountryValidator<"UY"> = {
   name: "Uruguayan Tax ID",
   localName: "Registro Único Tributario",
   abbreviation: "RUT",
   aliases: ["RUT", "Registro Único Tributario"] as const,
   candidatePattern: "\\d{12}",
+  scope: "country",
   country: "UY",
   entityType: "any",
   lengths: [12] as const,

package/src/ve/rif.ts

@@ -13,13 +13,16 @@
  * @see https://en.wikipedia.org/wiki/Tax_Identification_Number#Venezuela
  */
 
+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 { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 /**
  * Map prefix letter to its numeric offset used
  * in the check digit computation.
@@ -48,12 +51,14 @@ const calcCheckDigit = (
   prefix: string,
   body: string,
 ): string => {
-  const pv = PREFIX_VALUES[prefix]!;
+  const pv = PREFIX_VALUES[prefix] ?? 0;
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += Number(body[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += Number(body[i]) * weight;
   }
   const digit = (pv + (sum % 11)) % 11;
+  // SAFETY: digit ∈ [0, 10] and CHECK_LOOKUP has 11 chars.
+  // eslint-disable-next-line no-non-null-assertion
   return CHECK_LOOKUP[digit]!;
 };
 
@@ -67,6 +72,8 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
+  // SAFETY: length check above guarantees v[0] exists.
+  // eslint-disable-next-line no-non-null-assertion
   const prefix = v[0]!;
   if (!(prefix in PREFIX_VALUES)) {
     return err(
@@ -100,14 +107,13 @@ const format = (value: string): string => {
   return `${v[0]}-${v.slice(1, 9)}-${v.slice(9)}`;
 };
 
+const GENERATE_TYPES = ["V", "E", "J", "P", "G"] as const;
+
 /** Generate a random valid Venezuelan RIF. */
 const generate = (): string => {
-  const types = ["V", "E", "J", "P", "G"] as const;
-  const prefix = types[randomInt(0, types.length - 1)]!;
+  const prefix = randomPick(GENERATE_TYPES);
   const body = randomDigits(8);
-  return (
-    prefix + body + String(calcCheckDigit(prefix, body))
-  );
+  return prefix + body + calcCheckDigit(prefix, body);
 };
 
 /**
@@ -115,7 +121,7 @@ const generate = (): string => {
  *
  * Examples sourced from python-stdnum test suite.
  */
-const rif: Validator = {
+const rif: CountryValidator<"VE"> = {
   name: "Venezuelan Tax ID",
   localName: "Registro de Información Fiscal",
   abbreviation: "RIF",
@@ -124,6 +130,7 @@ const rif: Validator = {
     "Registro de Información Fiscal",
   ] as const,
   candidatePattern: "[VEJPG]-?\\d{8}-?\\d",
+  scope: "country",
   country: "VE",
   entityType: "any",
   lengths: [10] as const,

package/src/vn/mst.ts

@@ -11,13 +11,16 @@
  * @see https://easyinvoice.vn/ma-so-thue/
  */
 
+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 WEIGHTS = [31, 29, 23, 19, 17, 13, 7, 5, 3] as const;
 
 const calcCheckDigit = (number: string): string => {
@@ -104,12 +107,13 @@ const generate = (): string => {
 };
 
 /** Vietnamese Tax Number. */
-const mst: Validator = {
+const mst: CountryValidator<"VN"> = {
   name: "Vietnamese Tax Number",
   localName: "Mã số thuế",
   abbreviation: "MST",
   aliases: ["MST", "mã số thuế"] as const,
   candidatePattern: "\\d{10}(-\\d{3})?",
+  scope: "country",
   country: "VN",
   entityType: "company",
   description:

package/src/za/idnr.ts

@@ -13,6 +13,12 @@
  * @see https://en.wikipedia.org/wiki/South_African_identity_document
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -23,12 +29,6 @@ import { randomDigits, 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, " ");
 
@@ -132,16 +132,18 @@ const generate = (): string => {
 };
 
 /** South African Identity Number. */
-const idnr: Validator = {
+const idnr: CountryValidator<"ZA", ParsedPersonId> = {
   name: "South African Identity Number",
   localName: "South African Identity Number",
   abbreviation: "SA ID",
   aliases: ["ID number", "RSA ID"] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "ZA",
   entityType: "person",
   compact,
   format,
+  parse,
   validate,
   description:
     "South African personal identification number",