@stll/stdnum 0.0.1 → 2.0.0

package/src/by/unp.ts

@@ -11,13 +11,16 @@
  * @see https://www.nalog.gov.by/
  */
 
+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";
-
 /** Cyrillic to Latin mapping for the letter positions. */
 const CYRILLIC_TO_LATIN: Record<string, string> = {
   А: "A",
@@ -44,7 +47,8 @@ const compact = (value: string): string => {
   } else if (v.startsWith("UNP")) {
     v = v.slice(3);
   }
-  return [...v]
+  return v
+    .split("")
     .map((ch) => CYRILLIC_TO_LATIN[ch] ?? ch)
     .join("");
 };
@@ -52,16 +56,19 @@ const compact = (value: string): string => {
 const calcCheckDigit = (number: string): number | null => {
   let work = number;
   if (!isdigits(number)) {
-    const idx = ALPHA_SET.indexOf(number[1]!);
+    const second = number[1];
+    if (second === undefined) return null;
+    const idx = ALPHA_SET.indexOf(second);
     if (idx === -1) return null;
     work = number[0] + String(idx) + number.slice(2);
   }
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    const ch = work[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    const ch = work[i];
+    if (ch === undefined) return null;
     const val = ALPHABET.indexOf(ch);
     if (val === -1) return null;
-    sum += (WEIGHTS[i] ?? 0) * val;
+    sum += weight * val;
   }
   const remainder = sum % 11;
   if (remainder > 9) return null;
@@ -85,7 +92,7 @@ const validate = (value: string): ValidateResult => {
   const first2 = v.slice(0, 2);
   if (
     !isdigits(first2) &&
-    ![...first2].every((ch) => ALPHA_SET.includes(ch))
+    !first2.split("").every((ch) => ALPHA_SET.includes(ch))
   ) {
     return err(
       "INVALID_FORMAT",
@@ -93,6 +100,8 @@ const validate = (value: string): ValidateResult => {
         " digits or letters from ABCEHKMOPT",
     );
   }
+  // SAFETY: v.length === 9 guarantees v[0] exists.
+  // eslint-disable-next-line no-non-null-assertion
   if (!VALID_FIRST.includes(v[0]!)) {
     return err(
       "INVALID_COMPONENT",
@@ -133,12 +142,13 @@ const generate = (): string => {
 };
 
 /** Belarus UNP (Учётный номер плательщика). */
-const unp: Validator = {
+const unp: CountryValidator<"BY"> = {
   name: "Belarus Tax Number",
   localName: "Учётный номер плательщика",
   abbreviation: "УНП",
   aliases: ["УНП", "UNP"] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "BY",
   entityType: "any",
   sourceUrl: "https://www.nalog.gov.by/",

package/src/bz/tin.ts

@@ -25,11 +25,15 @@
  * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Belize-TIN.pdf
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 /** Valid 2-digit suffix codes. */
 const SUFFIX_CODES = ["10", "13", "66"] as const;
 
@@ -79,17 +83,27 @@ 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.
  *
  * Examples derived from stdnum-js test suite.
  */
-const tin: Validator = {
+const tin: CountryValidator<"BZ"> = {
   name: "Belize Tax Identification Number",
   localName: "Tax Identification Number",
   abbreviation: "TIN",
   aliases: ["TIN"] as const,
   candidatePattern: "\\d{6}",
+  scope: "country",
   country: "BZ",
   entityType: "any",
   lengths: [6, 8] as const,
@@ -97,6 +111,7 @@ const tin: Validator = {
   compact,
   format,
   validate,
+  generate,
   description:
     "Belize tax number issued by the Belize Tax Service Department",
   sourceUrl:
@@ -104,4 +119,4 @@ const tin: Validator = {
 };
 
 export default tin;
-export { compact, format, validate };
+export { compact, format, generate, validate };

package/src/ca/bn.ts

@@ -8,6 +8,11 @@
  * @see https://www.canada.ca/en/services/taxes/business-number.html
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -17,8 +22,6 @@ import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const VALID_PROGRAMS = new Set(["RC", "RM", "RP", "RT"]);
 
 const compact = (value: string): string =>
@@ -82,7 +85,7 @@ const generate = (): string => {
 };
 
 /** Canadian Business Number. */
-const bn: Validator = {
+const bn: CountryValidator<"CA"> = {
   name: "Business Number",
   localName: "Business Number",
   abbreviation: "BN",
@@ -92,6 +95,7 @@ const bn: Validator = {
     "numéro d'entreprise",
   ] as const,
   candidatePattern: "\\d{9}\\s?[A-Z]{2}\\s?\\d{4}",
+  scope: "country",
   country: "CA",
   entityType: "company",
   sourceUrl:

package/src/ca/sin.ts

@@ -8,6 +8,11 @@
  * @see https://en.wikipedia.org/wiki/Social_Insurance_Number
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -17,8 +22,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 =>
   clean(value, " -");
 
@@ -66,7 +69,7 @@ const generate = (): string => {
 };
 
 /** Canadian Social Insurance Number. */
-const sin: Validator = {
+const sin: CountryValidator<"CA"> = {
   name: "Social Insurance Number",
   localName: "Social Insurance Number",
   abbreviation: "SIN",
@@ -76,6 +79,7 @@ const sin: Validator = {
     "NAS",
   ] as const,
   candidatePattern: "\\d{3}-?\\d{3}-?\\d{3}",
+  scope: "country",
   country: "CA",
   entityType: "person",
   sourceUrl:

package/src/ch/ssn.ts

@@ -8,13 +8,16 @@
  * @see https://www.bsv.admin.ch/
  */
 
+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, " -.");
 
@@ -70,7 +73,7 @@ const generate = (): string => {
 };
 
 /** Swiss Social Security Number. */
-const ssn: Validator = {
+const ssn: CountryValidator<"CH"> = {
   name: "Swiss Social Security Number",
   localName: "AHV-Versichertennummer",
   abbreviation: "AHV",
@@ -81,6 +84,7 @@ const ssn: Validator = {
     "AHV",
   ] as const,
   candidatePattern: "756\\.?\\d{4}\\.?\\d{4}\\.?\\d{2}",
+  scope: "country",
   country: "CH",
   entityType: "person",
   sourceUrl: "https://www.bsv.admin.ch/",

package/src/ch/uid.ts

@@ -8,13 +8,16 @@
  * @see https://www.uid.admin.ch/
  */
 
+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 = [5, 4, 3, 2, 7, 6, 5, 4] as const;
 
 const compact = (value: string): string =>
@@ -84,7 +87,7 @@ const generate = (): string => {
 };
 
 /** Swiss Business Identification Number. */
-const uid: Validator = {
+const uid: CountryValidator<"CH"> = {
   name: "Swiss Business ID",
   localName: "Unternehmens-Identifikationsnummer",
   abbreviation: "UID",
@@ -94,6 +97,7 @@ const uid: Validator = {
     "IDE",
   ] as const,
   candidatePattern: "CHE-?\\d{3}\\.?\\d{3}\\.?\\d{3}",
+  scope: "country",
   country: "CH",
   entityType: "company",
   sourceUrl: "https://www.uid.admin.ch/",

package/src/ch/vat.ts

@@ -8,15 +8,18 @@
  * @see https://www.estv.admin.ch/
  */
 
-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 validateUid,
   generate as generateUid,
 } from "./uid";
 
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
 const SUFFIXES = ["MWST", "TVA", "IVA", "TPV"] as const;
 
 const compact = (value: string): string =>
@@ -64,13 +67,14 @@ const format = (value: string): string => {
 const generate = (): string => generateUid() + "MWST";
 
 /** Swiss VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"CH"> = {
   name: "Swiss VAT Number",
   localName: "Mehrwertsteuernummer",
   abbreviation: "MWST",
   aliases: ["MWST", "TVA", "IVA"] as const,
   candidatePattern:
     "CHE-?\\d{3}\\.?\\d{3}\\.?\\d{3}\\s?(?:MWST|TVA|IVA)",
+  scope: "country",
   country: "CH",
   entityType: "company",
   sourceUrl: "https://www.estv.admin.ch/",

package/src/cl/rut.ts

@@ -13,12 +13,15 @@
  * @see https://en.wikipedia.org/wiki/Rol_%C3%9Anico_Tributario
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 const RUT_RE = /^\d{7,8}[\dK]$/;
 
 const compact = (value: string): string => {
@@ -35,10 +38,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";
@@ -97,12 +102,13 @@ const generate = (): string => {
  * Examples sourced from python-stdnum test suite
  * (cl.rut module).
  */
-const rut: Validator = {
+const rut: CountryValidator<"CL"> = {
   name: "Chilean Tax ID",
   localName: "Rol Único Tributario",
   abbreviation: "RUT",
   aliases: ["RUT", "Rol Único Tributario"] as const,
   candidatePattern: "\\d{1,2}\\.?\\d{3}\\.?\\d{3}-?[\\dkK]",
+  scope: "country",
   country: "CL",
   entityType: "any",
   compact,

package/src/cn/ric.ts

@@ -11,6 +11,12 @@
  * @see https://en.wikipedia.org/wiki/Resident_Identity_Card
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   mod112checkChar,
   mod112validate,
@@ -21,12 +27,6 @@ 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, " -").toUpperCase();
 
@@ -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,12 +155,13 @@ const generate = (): string => {
 };
 
 /** Chinese Resident Identity Card number. */
-const ric: Validator = {
+const ric: CountryValidator<"CN", ParsedPersonId> = {
   name: "Chinese Resident Identity Card",
   localName: "居民身份证号码",
   abbreviation: "RIC",
   aliases: ["身份证", "居民身份证号码", "RIC"] as const,
   candidatePattern: "\\d{17}[\\dX]",
+  scope: "country",
   country: "CN",
   entityType: "person",
   description:
@@ -172,6 +175,7 @@ const ric: Validator = {
   ] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/cn/uscc.ts

@@ -9,13 +9,20 @@
  * @see https://zh.wikipedia.org/wiki/统一社会信用代码
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 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";
 
-import type { ValidateResult, Validator } from "../types";
-
 const ALPHABET = "0123456789ABCDEFGHJKLMNPQRTUWXY";
 
 const WEIGHTS = [
@@ -28,10 +35,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 +56,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,24 +86,29 @@ 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);
 };
 
 /** Chinese Unified Social Credit Code. */
-const uscc: Validator = {
+const uscc: CountryValidator<"CN"> = {
   name: "Unified Social Credit Code",
   localName: "统一社会信用代码",
   abbreviation: "USCC",
   aliases: ["统一社会信用代码", "USCC"] as const,
   candidatePattern:
     "[0-9A-HJ-NP-RTUW-Y]{2}\\d{6}[0-9A-HJ-NP-RTUW-Y]{10}",
+  scope: "country",
   country: "CN",
   entityType: "company",
   description:

package/src/co/nit.ts

@@ -10,13 +10,16 @@
  * @see https://es.wikipedia.org/wiki/Número_de_identificación_tributaria
  */
 
+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 = [
   3, 7, 13, 17, 19, 23, 29, 37, 41, 43, 47, 53, 59, 67, 71,
 ] as const;
@@ -30,9 +33,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]!;
 };
 
@@ -53,7 +60,7 @@ const validate = (value: string): ValidateResult => {
 
   const body = v.slice(0, -1);
   const check = calcCheckDigit(body);
-  if (check !== Number(v[v.length - 1])) {
+  if (check !== Number(v.at(-1))) {
     return err(
       "INVALID_CHECKSUM",
       "NIT check digit does not match",
@@ -82,7 +89,7 @@ const generate = (): string => {
 };
 
 /** Colombian tax identification number. */
-const nit: Validator = {
+const nit: CountryValidator<"CO"> = {
   name: "Número de Identificación Tributaria",
   localName: "Número de Identificación Tributaria",
   abbreviation: "NIT",
@@ -91,6 +98,7 @@ const nit: Validator = {
     "Número de Identificación Tributaria",
   ] as const,
   candidatePattern: "\\d{9,10}-?\\d",
+  scope: "country",
   country: "CO",
   entityType: "any",
   description: "Tax identifier issued by the DIAN",

package/src/cr/cpf.ts

@@ -23,12 +23,15 @@ const generate = (): string => {
  * @see https://www.tse.go.cr/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 /**
  * Compact: strip spaces, pad hyphen-separated parts
  * (2-4-4), join, and prepend '0' if 9 digits.
@@ -38,9 +41,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("-", "");
@@ -90,12 +94,13 @@ const format = (value: string): string => {
  *
  * Examples sourced from python-stdnum test suite.
  */
-const cpf: Validator = {
+const cpf: CountryValidator<"CR"> = {
   name: "Costa Rican Physical Person ID",
   localName: "Cédula de Persona Física",
   abbreviation: "CPF",
   aliases: ["CPF", "cédula de persona física"] as const,
   candidatePattern: "\\d{9,12}",
+  scope: "country",
   country: "CR",
   entityType: "person",
   lengths: [10] as const,

package/src/creditcard.ts

@@ -9,6 +9,11 @@
  * @see https://www.iso.org/standard/70484.html
  */
 
+import type {
+  ValidateResult,
+  GlobalValidator,
+} from "./types";
+
 import {
   luhnChecksum,
   luhnValidate,
@@ -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";
-
 /**
  * Card network identifiers returned by
  * {@link detectNetwork}.
@@ -74,9 +77,9 @@ const format = (value: string): string => {
   return groups.join(" ");
 };
 
-const MAESTRO_PREFIXES: readonly number[] = [
+const MAESTRO_PREFIXES = new Set([
   5018, 5020, 5038, 5893, 6304, 6759, 6761, 6762, 6763,
-];
+]);
 
 /**
  * Detect the card network from the BIN/IIN prefix.
@@ -112,7 +115,7 @@ const detectNetwork = (
 
   // Maestro (check before Mastercard; some share
   // the 50xx prefix space)
-  if (MAESTRO_PREFIXES.includes(d4)) return "maestro";
+  if (MAESTRO_PREFIXES.has(d4)) return "maestro";
 
   // Mastercard: 51-55 or 2221-2720
   if (d2 >= 51 && d2 <= 55) return "mastercard";
@@ -162,7 +165,8 @@ const generate = (): string => {
 };
 
 /** Credit Card Number (Luhn). */
-const creditCard: Validator = {
+const creditCard: GlobalValidator = {
+  scope: "global",
   name: "Credit Card Number",
   localName: "Credit Card Number",
   abbreviation: "CC",