@stll/stdnum 0.0.1 → 2.0.0

package/src/is/vsk.ts

@@ -12,13 +12,16 @@ const generate = (): string => {
  * @see https://www.rsk.is/
  */
 
+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 compact = (value: string): string =>
   clean(value, " -");
 
@@ -43,12 +46,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Icelandic VAT Number. */
-const vsk: Validator = {
+const vsk: CountryValidator<"IS"> = {
   name: "Icelandic VAT Number",
   localName: "Virðisaukaskattur",
   abbreviation: "VSK",
   aliases: ["VSK-númer", "virðisaukaskattur"] as const,
   candidatePattern: "IS\\d{5,6}",
+  scope: "country",
   country: "IS",
   entityType: "company",
   sourceUrl: "https://www.rsk.is/",

package/src/isin.ts

@@ -10,14 +10,17 @@
  * @see https://www.isin.org/
  */
 
+import type {
+  ValidateResult,
+  GlobalValidator,
+} from "./types";
+
 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";
 
-import type { ValidateResult, Validator } from "./types";
-
 const ISIN_RE = /^[A-Z]{2}[0-9A-Z]{9}[0-9]$/;
 
 const compact = (value: string): string =>
@@ -73,12 +76,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));
@@ -91,7 +100,8 @@ const generate = (): string => {
 };
 
 /** International Securities Identification Number. */
-const isin: Validator = {
+const isin: GlobalValidator = {
+  scope: "global",
   name: "International Securities Identification Number",
   localName:
     "International Securities Identification Number",

package/src/it/codicefiscale.ts

@@ -20,17 +20,18 @@
  * @see https://it.wikipedia.org/wiki/Codice_fiscale#Omocodia
  */
 
-import { clean } from "#util/clean";
-import { err } from "#util/result";
-import { isdigits } from "#util/strings";
-
 import type {
   ParsedPersonId,
   ValidateResult,
-  Validator,
+  CountryValidator,
 } from "../types";
 import { validate as validateIva } from "./iva";
 
+import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
 // Values for odd-positioned characters (0-based
 // index 0, 2, 4, ...)
 const ODD: Record<string, number> = {
@@ -260,8 +261,46 @@ 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: CountryValidator<
+  "IT",
+  ParsedPersonId
+> = {
   name: "Italian Tax Code",
   localName: "Codice Fiscale",
   abbreviation: "CF",
@@ -274,6 +313,7 @@ const codiceFiscale: Validator = {
   ] as const,
   candidatePattern:
     "[A-Z]{6}\\d{2}[A-Z]\\d{2}[A-Z]\\d{3}[A-Z]",
+  scope: "country",
   country: "IT",
   entityType: "person",
   description:
@@ -283,8 +323,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/it/iva.ts

@@ -7,6 +7,11 @@
  * @see https://www.agenziaentrate.gov.it/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -16,8 +21,6 @@ import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const VALID_PROVINCES = new Set([
   ...Array.from({ length: 100 }, (_, i) =>
     String(i + 1).padStart(3, "0"),
@@ -90,7 +93,7 @@ const generate = (): string => {
 };
 
 /** Italian VAT Number. */
-const iva: Validator = {
+const iva: CountryValidator<"IT"> = {
   name: "Italian VAT Number",
   localName: "Partita IVA",
   abbreviation: "P.IVA",
@@ -101,6 +104,7 @@ const iva: Validator = {
     "VAT IT",
   ] as const,
   candidatePattern: "IT\\d{11}",
+  scope: "country",
   country: "IT",
   entityType: "company",
   sourceUrl: "https://www.agenziaentrate.gov.it/",

package/src/jp/cn.ts

@@ -8,13 +8,16 @@
  * @see https://en.wikipedia.org/wiki/Corporate_Number_(Japan)
  */
 
+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, " -");
 
@@ -67,12 +70,13 @@ const generate = (): string => {
 };
 
 /** Japanese Corporate Number. */
-const cn: Validator = {
+const cn: CountryValidator<"JP"> = {
   name: "Japanese Corporate Number",
   localName: "法人番号",
   abbreviation: "CN",
   aliases: ["法人番号", "Corporate Number"] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "JP",
   entityType: "company",
   description:

package/src/jp/mynumber.ts

@@ -9,13 +9,16 @@
  * @see https://en.wikipedia.org/wiki/Individual_Number
  */
 
+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, " -");
 
@@ -74,7 +77,7 @@ const generate = (): string => {
 };
 
 /** Japanese Individual Number (My Number). */
-const mynumber: Validator = {
+const mynumber: CountryValidator<"JP"> = {
   name: "Japanese Individual Number",
   localName: "マイナンバー",
   abbreviation: "My Number",
@@ -84,6 +87,7 @@ const mynumber: Validator = {
     "個人番号",
   ] as const,
   candidatePattern: "\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}",
+  scope: "country",
   country: "JP",
   entityType: "person",
   description:

package/src/kr/brn.ts

@@ -23,13 +23,16 @@ const generate = (): string => {
  * @see https://en.wikipedia.org/wiki/Business_registration_number_(South_Korea)
  */
 
+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 compact = (value: string): string =>
   clean(value, " -");
 
@@ -77,12 +80,13 @@ const format = (value: string): string => {
 };
 
 /** Korean Business Registration Number. */
-const brn: Validator = {
+const brn: CountryValidator<"KR"> = {
   name: "Korean Business Registration Number",
   localName: "사업자등록번호",
   abbreviation: "BRN",
   aliases: ["사업자등록번호", "BRN"] as const,
   candidatePattern: "\\d{3}-?\\d{2}-?\\d{5}",
+  scope: "country",
   country: "KR",
   entityType: "company",
   description:

package/src/kr/rrn.ts

@@ -9,17 +9,18 @@
  * @see https://en.wikipedia.org/wiki/Resident_registration_number
  */
 
-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, " -/");
 
@@ -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: CountryValidator<"KR", ParsedPersonId> = {
   name: "Korean Resident Registration Number",
   localName: "주민등록번호",
   abbreviation: "RRN",
@@ -151,6 +167,7 @@ const rrn: Validator = {
     "Resident Registration Number",
   ] as const,
   candidatePattern: "\\d{6}[\\s-]?\\d{7}",
+  scope: "country",
   country: "KR",
   entityType: "person",
   description:
@@ -163,8 +180,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

@@ -12,17 +12,18 @@
  * @see https://kuwaitsexpat.com/kuwait-civil-id-format/
  */
 
+import type {
+  ParsedBirthDate,
+  ValidateResult,
+  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";
 
-import type {
-  ParsedPersonId,
-  ValidateResult,
-  Validator,
-} from "../types";
-
 const WEIGHTS = [2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2] as const;
 
 const centuryMap: Record<number, number> = {
@@ -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,13 +118,30 @@ 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: CountryValidator<"KW", ParsedBirthDate> = {
   name: "Civil Number",
   localName: "الرقم المدني",
   abbreviation: "Civil ID",
   aliases: ["Civil ID", "الرقم المدني"] as const,
   candidatePattern: "\\d{12}",
+  scope: "country",
   country: "KW",
   entityType: "person",
   lengths: [12] as const,
@@ -137,8 +152,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

@@ -14,6 +14,12 @@
  * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Kazakhstan-TIN.pdf
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
@@ -21,12 +27,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 WEIGHTS_1 = [
   1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
 ] as const;
@@ -144,7 +144,6 @@ const generate = (): string => {
     const serial = randomDigits(4);
     const payload = yy + mm + dd + gender + serial;
     const check = calcCheckDigit(payload);
-    if (check === null) continue;
     const c = payload + String(check);
     if (validate(c).valid) return c;
   }
@@ -155,7 +154,7 @@ const generate = (): string => {
  *
  * Examples sourced from identique/idnumbers test suite.
  */
-const iin: Validator = {
+const iin: CountryValidator<"KZ", ParsedPersonId> = {
   name: "Kazakhstan Individual ID",
   localName: "Жеке сәйкестендіру нөмірі",
   abbreviation: "IIN",
@@ -165,12 +164,14 @@ const iin: Validator = {
     "индивидуальный идентификационный номер",
   ] as const,
   candidatePattern: "\\d{12}",
+  scope: "country",
   country: "KZ",
   entityType: "person",
   lengths: [12] as const,
   examples: ["880515300120", "950101400012"] as const,
   compact,
   format,
+  parse,
   validate,
   sourceUrl:
     "https://www.oecd.org/tax/automatic-exchange/" +

package/src/lei.ts

@@ -9,14 +9,17 @@
  * @see https://www.gleif.org/
  */
 
+import type {
+  ValidateResult,
+  GlobalValidator,
+} from "./types";
+
 import { mod97 } from "#checksums/mod97";
 import { clean } from "#util/clean";
 import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { charValue, isalnum } from "#util/strings";
 
-import type { ValidateResult, Validator } from "./types";
-
 const compact = (value: string): string =>
   clean(value, " -").toUpperCase();
 
@@ -79,7 +82,8 @@ const generate = (): string => {
 };
 
 /** Legal Entity Identifier. */
-const lei: Validator = {
+const lei: GlobalValidator = {
+  scope: "global",
   name: "Legal Entity Identifier",
   localName: "Legal Entity Identifier",
   abbreviation: "LEI",

package/src/li/peid.ts

@@ -15,13 +15,16 @@ const generate = (): string => {
  * @see https://www.oera.li/
  */
 
+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 compact = (value: string): string =>
   clean(value, " .").replace(/^0+/, "");
 
@@ -45,12 +48,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Liechtenstein Person Identification Number. */
-const peid: Validator = {
+const peid: CountryValidator<"LI"> = {
   name: "Liechtenstein Person Identification Number",
   localName: "Personenidentifikationsnummer",
   abbreviation: "PEID",
   aliases: ["PEID", "Personenidentifikation"] as const,
   candidatePattern: "\\d{6}",
+  scope: "country",
   country: "LI",
   entityType: "any",
   lengths: [4, 5, 6, 7, 8, 9, 10, 11, 12] as const,

package/src/lk/nic.ts

@@ -12,17 +12,18 @@
  * @see https://drp.gov.lk/Templates/Artical%20-%20English%20new%20number.html
  */
 
-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";
+
 /** Old format: 9 digits + V or X (case-insensitive). */
 const OLD_RE = /^\d{9}[VvXx]$/;
 
@@ -184,13 +185,33 @@ 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: CountryValidator<"LK", ParsedPersonId> = {
   name: "National Identity Card",
   localName: "ජාතික හැඳුනුම්පත",
   abbreviation: "NIC",
   aliases: ["NIC", "ජාතික හැඳුනුම්පත"] as const,
   candidatePattern: "\\d{9}[VXvx]|\\d{12}",
+  scope: "country",
   country: "LK",
   entityType: "person",
   description:
@@ -203,8 +224,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 };