@stll/stdnum 0.0.1 → 1.0.0

package/src/eu/vat.ts

@@ -13,6 +13,7 @@
  */
 
 import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 
 import atUid from "../at/uid";
@@ -152,6 +153,49 @@ const format = (value: string): string => {
   return `${parts.cc}${validator.compact(parts.rest)}`;
 };
 
+const GENERATORS = [
+  ["AT", atUid],
+  ["BE", beVat],
+  ["BG", bgVat],
+  ["CY", cyVat],
+  ["CZ", czDic],
+  ["DE", deVat],
+  ["DK", dkVat],
+  ["EE", eeVat],
+  ["ES", esVat],
+  ["FI", fiVat],
+  ["FR", frTva],
+  ["GR", grVat],
+  ["HR", hrVat],
+  ["HU", huVat],
+  ["IE", ieVat],
+  ["IT", itIva],
+  ["LT", ltVat],
+  ["LU", luVat],
+  ["LV", lvVat],
+  ["MT", mtVat],
+  ["NL", nlVat],
+  ["PL", plNip],
+  ["PT", ptVat],
+  ["RO", roVat],
+  ["SE", seVat],
+  ["SI", siVat],
+  ["SK", skDic],
+] as const;
+
+/** Generate a random EU VAT number from a member validator. */
+const generate = (): string => {
+  for (;;) {
+    const candidate =
+      GENERATORS[randomInt(0, GENERATORS.length - 1)];
+    if (!candidate) continue;
+
+    const [prefix, validator] = candidate;
+    if (validator.generate === undefined) continue;
+    return `${prefix}${validator.generate()}`;
+  }
+};
+
 /** European Union VAT Number. */
 const euVat: Validator = {
   name: "EU VAT Number",
@@ -165,7 +209,8 @@ const euVat: Validator = {
   compact,
   format,
   validate,
+  generate,
 };
 
 export default euVat;
-export { compact, format, validate };
+export { compact, format, generate, validate };

package/src/fi/hetu.ts

@@ -10,6 +10,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";
 
@@ -158,8 +159,21 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+/** Generate a random valid HETU. */
+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 separator = year >= 2000 ? "A" : "-";
+  const serial = String(randomInt(2, 899)).padStart(3, "0");
+  const checkNum = Number(`${day}${month}${yy}${serial}`);
+  const checkChar = CHECK_CHARS.charAt(checkNum % 31);
+  return `${day}${month}${yy}${separator}${serial}${checkChar}`;
+};
+
 /** Finnish Personal Identity Code. */
-const hetu: Validator = {
+const hetu: Validator<ParsedPersonId> = {
   name: "Finnish Personal ID",
   localName: "Henkilötunnus",
   abbreviation: "HETU",
@@ -172,11 +186,14 @@ const hetu: Validator = {
   country: "FI",
   entityType: "person",
   sourceUrl: "https://dvv.fi/en/personal-identity-code",
+  lengths: [11] as const,
   examples: ["131052-308T"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default hetu;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/fr/nir.ts

@@ -165,7 +165,7 @@ const generate = (): string => {
 };
 
 /** French Social Security Number. */
-const nir: Validator = {
+const nir: Validator<ParsedPersonId> = {
   name: "French Social Security Number",
   localName: "Numero d'Inscription au Repertoire",
   abbreviation: "NIR",
@@ -187,6 +187,7 @@ const nir: Validator = {
   examples: ["295117823456784"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/gb/nino.ts

@@ -1,21 +1,19 @@
+const NINO_VALID_FIRST = "ABCEGHJKLMNOPRSTWXYZ";
+const NINO_VALID_SECOND = "ABCEGHJKLMNPRSTWXYZ";
+const NINO_SUFFIXES = "ABCD";
+
 /** Generate a random valid UK NINO. */
 const generate = (): string => {
-  const validFirst = "ABCEGHJKLMNOPRSTWXYZ";
-  const validSecond = "ABCEGHJKLMNPRSTWXYZ";
-  const suffixes = "ABCD";
   let first: string;
   let second: string;
   let prefix: string;
   do {
-    first =
-      validFirst[randomInt(0, validFirst.length - 1)]!;
-    second =
-      validSecond[randomInt(0, validSecond.length - 1)]!;
+    first = randomChar(NINO_VALID_FIRST);
+    second = randomChar(NINO_VALID_SECOND);
     prefix = first + second;
   } while (INVALID_PREFIX.has(prefix));
   const digits = randomDigits(6);
-  const suffix =
-    suffixes[randomInt(0, suffixes.length - 1)]!;
+  const suffix = randomChar(NINO_SUFFIXES);
   return `${prefix}${digits}${suffix}`;
 };
 
@@ -31,7 +29,7 @@ const generate = (): string => {
  */
 
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
+import { randomChar, randomDigits } from "#util/generate";
 import { err } from "#util/result";
 
 import type { ValidateResult, Validator } from "../types";
@@ -85,7 +83,10 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
+  // SAFETY: regex above guarantees v.length === 9.
+  // eslint-disable-next-line no-non-null-assertion
   const first = v[0]!;
+  // eslint-disable-next-line no-non-null-assertion
   const second = v[1]!;
   const prefix = v.slice(0, 2);
 

package/src/gb/sedol.ts

@@ -11,7 +11,7 @@
  */
 
 import { clean } from "#util/clean";
-import { randomInt } from "#util/generate";
+import { randomChar } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
@@ -36,14 +36,14 @@ const calcCheckDigit = (number: string): string => {
     );
   }
   let sum = 0;
-  for (let i = 0; i < 6; i++) {
-    const ch = number[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    const ch = number[i];
+    if (ch === undefined) continue;
     const val = ALPHABET.indexOf(ch);
     if (val < 0) {
       throw new Error(`Invalid SEDOL character: ${ch}`);
     }
-    // SAFETY: weights length matches loop bound
-    sum += WEIGHTS[i]! * val;
+    sum += weight * val;
   }
   return String((10 - (sum % 10)) % 10);
 };
@@ -74,6 +74,8 @@ const validate = (value: string): ValidateResult => {
   // Old-style SEDOLs are fully numeric; new-style
   // SEDOLs start with a letter. A number that starts
   // with a digit but contains letters is invalid.
+  // SAFETY: v.length === 7 here.
+  // eslint-disable-next-line no-non-null-assertion
   if (isdigits(v[0]!) && !isdigits(v)) {
     return err(
       "INVALID_FORMAT",
@@ -94,15 +96,15 @@ const validate = (value: string): ValidateResult => {
 
 const format = (value: string): string => compact(value);
 
+const SEDOL_CONSONANTS = "BCDFGHJKLMNPQRSTVWXYZ";
+const SEDOL_CHARS = "0123456789BCDFGHJKLMNPQRSTVWXYZ";
+
 /** Generate a random valid SEDOL. */
 const generate = (): string => {
-  const consonants = "BCDFGHJKLMNPQRSTVWXYZ";
-  const chars = "0123456789BCDFGHJKLMNPQRSTVWXYZ";
-  const first =
-    consonants[randomInt(0, consonants.length - 1)]!;
-  let payload = first;
-  for (let i = 1; i < 6; i++)
-    payload += chars[randomInt(0, chars.length - 1)]!;
+  let payload = randomChar(SEDOL_CONSONANTS);
+  for (let i = 1; i < 6; i++) {
+    payload += randomChar(SEDOL_CHARS);
+  }
   return payload + calcCheckDigit(payload);
 };
 

package/src/gh/tin.ts

@@ -15,7 +15,7 @@
  */
 
 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";
@@ -65,11 +65,12 @@ const validate = (value: string): ValidateResult => {
 
 const format = (value: string): string => compact(value);
 
+const TIN_PREFIXES = ["P", "C", "G", "Q", "V"] as const;
+
 /** Generate a random valid Ghana TIN. */
 const generate = (): string => {
-  const prefixes = ["P", "C", "G", "Q", "V"] as const;
   for (;;) {
-    const p = prefixes[randomInt(0, 4)]!;
+    const p = randomPick(TIN_PREFIXES);
     const d = randomDigits(9);
     const partial = p + d;
     const c = partial + calcCheckDigit(partial);

package/src/gt/nit.ts

@@ -88,9 +88,12 @@ const format = (value: string): string => {
 
 /** Generate a random valid NIT (7 body digits). */
 const generate = (): string => {
-  const body = randomDigits(7);
-  const check = calcCheckChar(body);
-  return `${body}${check}`;
+  for (;;) {
+    const body = randomDigits(7);
+    if (body.startsWith("0")) continue;
+    const check = calcCheckChar(body);
+    return `${body}${check}`;
+  }
 };
 
 /** Guatemala tax identification number. */

package/src/hk/hkid.ts

@@ -32,7 +32,8 @@ const computeCheck = (body: string): string => {
 
   let sum = 0;
   for (let i = 0; i < 8; i++) {
-    const ch = padded[i]!;
+    const ch = padded[i];
+    if (ch === undefined) continue;
     let val: number;
     if (ch === " ") {
       val = 36;

package/src/in/gstin.ts

@@ -70,7 +70,9 @@ const luhn36Checksum = (value: string): number => {
   let sum = 0;
   let double = false;
   for (let i = value.length - 1; i >= 0; i--) {
-    let v = charValue(value[i]!);
+    const ch = value[i];
+    if (ch === undefined) continue;
+    let v = charValue(ch);
     if (double) {
       v *= 2;
       sum += Math.floor(v / BASE) + (v % BASE);

package/src/in/pan.ts

@@ -4,8 +4,7 @@ const generate = (): string => {
     String.fromCodePoint(65 + randomInt(0, 25));
   const first3 =
     randomLetter() + randomLetter() + randomLetter();
-  const holderType =
-    HOLDER_TYPES[randomInt(0, HOLDER_TYPES.length - 1)]!;
+  const holderType = randomChar(HOLDER_TYPES);
   const fifth = randomLetter();
   const digits = randomDigits(4);
   const last = randomLetter();
@@ -27,7 +26,11 @@ const generate = (): string => {
  */
 
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
+import {
+  randomChar,
+  randomDigits,
+  randomInt,
+} from "#util/generate";
 import { err } from "#util/result";
 
 import type { ValidateResult, Validator } from "../types";
@@ -53,6 +56,8 @@ const validate = (value: string): ValidateResult => {
       "PAN must be 5 letters + 4 digits + 1 letter",
     );
   }
+  // SAFETY: regex above guarantees v.length === 10.
+  // eslint-disable-next-line no-non-null-assertion
   if (!HOLDER_TYPES.includes(v[3]!)) {
     return err(
       "INVALID_COMPONENT",

package/src/index.ts

@@ -1,7 +1,10 @@
 export type {
   CountryCode,
   ErrorCode,
+  ParsedBirthDate,
+  ParsedIdentifier,
   ParsedPersonId,
+  ParsableValidator,
   StdnumError,
   ValidateResult,
   Validator,

package/src/isin.ts

@@ -12,7 +12,7 @@
 
 import { luhnChecksum } from "#checksums/luhn";
 import { clean } from "#util/clean";
-import { randomInt } from "#util/generate";
+import { randomInt, randomPick } from "#util/generate";
 import { err } from "#util/result";
 import { charValue, isalnum } from "#util/strings";
 
@@ -73,12 +73,18 @@ const format = (value: string): string => {
   return `${v.slice(0, 2)} ${v.slice(2, 6)} ${v.slice(6, 10)} ${v.slice(10)}`;
 };
 
+const ISIN_COUNTRIES = [
+  "US",
+  "GB",
+  "DE",
+  "FR",
+  "JP",
+] as const;
+
 /** Generate a random valid ISIN. */
 const generate = (): string => {
-  const countries = ["US", "GB", "DE", "FR", "JP"];
   for (;;) {
-    const cc =
-      countries[randomInt(0, countries.length - 1)]!;
+    const cc = randomPick(ISIN_COUNTRIES);
     let nsin = "";
     for (let i = 0; i < 9; i++)
       nsin += String(randomInt(0, 9));

package/src/it/codicefiscale.ts

@@ -21,6 +21,7 @@
  */
 
 import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
@@ -260,8 +261,43 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const MONTH_CODES = Object.keys(MONTH_LETTERS);
+
+const randomLetter = (): string =>
+  LETTERS.charAt(randomInt(0, LETTERS.length - 1));
+
+/** Generate a random valid 16-character Codice Fiscale. */
+const generate = (): string => {
+  let body = "";
+
+  for (let i = 0; i < 6; i++) {
+    body += randomLetter();
+  }
+
+  body += String(randomInt(0, 99)).padStart(2, "0");
+  body +=
+    MONTH_CODES[randomInt(0, MONTH_CODES.length - 1)] ??
+    "A";
+
+  const day =
+    randomInt(1, 28) + (randomInt(0, 1) === 0 ? 0 : 40);
+  body += String(day).padStart(2, "0");
+  body += randomLetter();
+  body += String(randomInt(0, 999)).padStart(3, "0");
+
+  let sum = 0;
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch === undefined) continue;
+    sum += i % 2 === 0 ? (ODD[ch] ?? 0) : (EVEN[ch] ?? 0);
+  }
+
+  return `${body}${CHECK_LETTERS.charAt(sum % 26)}`;
+};
+
 /** Italian Tax Code. */
-const codiceFiscale: Validator = {
+const codiceFiscale: Validator<ParsedPersonId> = {
   name: "Italian Tax Code",
   localName: "Codice Fiscale",
   abbreviation: "CF",
@@ -283,8 +319,10 @@ const codiceFiscale: Validator = {
   examples: ["RCCMNL83S18D969H"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default codiceFiscale;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/kr/rrn.ts

@@ -11,6 +11,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";
 
@@ -140,8 +141,23 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+/** Generate a random valid Korean RRN. */
+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 genderDigit =
+    year >= 2000
+      ? String(randomInt(3, 4))
+      : String(randomInt(1, 2));
+  const place = String(randomInt(0, 96)).padStart(2, "0");
+  const body = `${yy}${month}${day}${genderDigit}${place}${randomDigits(3)}`;
+  return `${body}${String(checkDigit(body))}`;
+};
+
 /** Korean Resident Registration Number. */
-const rrn: Validator = {
+const rrn: Validator<ParsedPersonId> = {
   name: "Korean Resident Registration Number",
   localName: "주민등록번호",
   abbreviation: "RRN",
@@ -163,8 +179,10 @@ const rrn: Validator = {
   examples: ["9710139019902", "9501011000109"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default rrn;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/kw/civil.ts

@@ -14,11 +14,12 @@
 
 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";
 
 import type {
-  ParsedPersonId,
+  ParsedBirthDate,
   ValidateResult,
   Validator,
 } from "../types";
@@ -35,9 +36,8 @@ const compact = (value: string): string =>
 
 const calcCheckDigit = (digits: string): number => {
   let sum = 0;
-  for (let i = 0; i < 11; i++) {
-    // SAFETY: loop bound guarantees valid index
-    sum += Number(digits[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += Number(digits[i]) * weight;
   }
   return (11 - (sum % 11)) % 11;
 };
@@ -101,9 +101,7 @@ const format = (value: string): string => {
  * Gender is not encoded in the number.
  * Returns null if the value is not valid.
  */
-const parse = (
-  value: string,
-): Omit<ParsedPersonId, "gender"> | null => {
+const parse = (value: string): ParsedBirthDate | null => {
   const result = validate(value);
   if (!result.valid) return null;
 
@@ -120,8 +118,24 @@ const parse = (
   };
 };
 
+/** Generate a random valid Kuwait civil number. */
+const generate = (): string => {
+  for (;;) {
+    const year = randomInt(1950, 2024);
+    const month = String(randomInt(1, 12)).padStart(2, "0");
+    const day = String(randomInt(1, 28)).padStart(2, "0");
+    const body =
+      `${year >= 2000 ? "3" : "2"}` +
+      `${String(year % 100).padStart(2, "0")}` +
+      `${month}${day}${randomDigits(4)}`;
+    const check = calcCheckDigit(body);
+    if (check > 9) continue;
+    return `${body}${String(check)}`;
+  }
+};
+
 /** Kuwait Civil Number (الرقم المدني). */
-const civil: Validator = {
+const civil: Validator<ParsedBirthDate> = {
   name: "Civil Number",
   localName: "الرقم المدني",
   abbreviation: "Civil ID",
@@ -137,8 +151,10 @@ const civil: Validator = {
     "https://kuwaitsexpat.com/kuwait-civil-id-format/",
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default civil;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/kz/iin.ts

@@ -155,7 +155,7 @@ const generate = (): string => {
  *
  * Examples sourced from identique/idnumbers test suite.
  */
-const iin: Validator = {
+const iin: Validator<ParsedPersonId> = {
   name: "Kazakhstan Individual ID",
   localName: "Жеке сәйкестендіру нөмірі",
   abbreviation: "IIN",
@@ -171,6 +171,7 @@ const iin: Validator = {
   examples: ["880515300120", "950101400012"] as const,
   compact,
   format,
+  parse,
   validate,
   sourceUrl:
     "https://www.oecd.org/tax/automatic-exchange/" +

package/src/lk/nic.ts

@@ -14,6 +14,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";
 
@@ -184,8 +185,27 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+/** Generate a random valid Sri Lankan NIC. */
+const generate = (): string => {
+  const year = randomInt(1950, 2024);
+  const start = new Date(year, 0, 1);
+  const end = new Date(year, 11, 31);
+  const maxDay =
+    Math.round(
+      (end.getTime() - start.getTime()) / 86_400_000,
+    ) + 1;
+  const dayOfYear = randomInt(1, maxDay);
+  const genderOffset = Math.random() < 0.5 ? 0 : 500;
+  const ddd = String(dayOfYear + genderOffset).padStart(
+    3,
+    "0",
+  );
+  const body = `${year}${ddd}0${randomDigits(3)}`;
+  return `${body}${String(checkDigit(body))}`;
+};
+
 /** Sri Lankan National Identity Card. */
-const nic: Validator = {
+const nic: Validator<ParsedPersonId> = {
   name: "National Identity Card",
   localName: "ජාතික හැඳුනුම්පත",
   abbreviation: "NIC",
@@ -203,8 +223,10 @@ const nic: Validator = {
   examples: ["197819202757", "862348753V"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default nic;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/luhn.ts

@@ -60,7 +60,10 @@ const luhn: Validator = {
   name: "Luhn",
   localName: "Luhn",
   abbreviation: "Luhn",
+  aliases: ["Luhn", "Luhn algorithm", "mod 10"] as const,
+  candidatePattern: "\\d{2,}",
   entityType: "any",
+  sourceUrl: "https://en.wikipedia.org/wiki/Luhn_algorithm",
   examples: ["4111111111111111", "18"] as const,
   compact,
   format,