@stll/stdnum 0.0.1 → 2.0.0

package/src/au/acn.ts

@@ -9,13 +9,16 @@
  * @see https://asic.gov.au/
  */
 
+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 = [8, 7, 6, 5, 4, 3, 2, 1] as const;
 
 const compact = (value: string): string =>
@@ -66,12 +69,13 @@ const generate = (): string => {
 };
 
 /** Australian Company Number. */
-const acn: Validator = {
+const acn: CountryValidator<"AU"> = {
   name: "Australian Company Number",
   localName: "Australian Company Number",
   abbreviation: "ACN",
   aliases: ["ACN", "Australian Company Number"] as const,
   candidatePattern: "\\d{3}\\s?\\d{3}\\s?\\d{3}",
+  scope: "country",
   country: "AU",
   entityType: "company",
   sourceUrl: "https://asic.gov.au/",

package/src/au/tfn.ts

@@ -9,13 +9,16 @@
  * @see https://www.ato.gov.au/Individuals/Tax-file-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 WEIGHTS = [1, 4, 3, 7, 5, 8, 6, 9, 10] as const;
 
 const compact = (value: string): string =>
@@ -64,12 +67,13 @@ const generate = (): string => {
 };
 
 /** Australian Tax File Number. */
-const tfn: Validator = {
+const tfn: CountryValidator<"AU"> = {
   name: "Tax File Number",
   localName: "Tax File Number",
   abbreviation: "TFN",
   aliases: ["TFN", "Tax File Number"] as const,
   candidatePattern: "\\d{8,9}",
+  scope: "country",
   country: "AU",
   entityType: "person",
   sourceUrl:

package/src/az/voen.ts

@@ -13,12 +13,15 @@
  * @see https://www.taxes.gov.az/
  */
 
+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";
-
 /** Weights for check digit computation (positions 0-7). */
 const WEIGHTS = [4, 1, 8, 6, 2, 7, 5, 3] as const;
 
@@ -63,6 +66,8 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
+  // SAFETY: regex above guarantees length === 10.
+  // eslint-disable-next-line no-non-null-assertion
   const lastDigit = v[9]!;
   if (lastDigit !== "1" && lastDigit !== "2") {
     return err(
@@ -104,12 +109,13 @@ const generate = (): string => {
  *
  * Examples sourced from python-stdnum test suite.
  */
-const voen: Validator = {
+const voen: CountryValidator<"AZ"> = {
   name: "Azerbaijani Tax ID",
   localName: "Vergi Ödəyicisinin Eyniləşdirmə Nömrəsi",
   abbreviation: "VÖEN",
   aliases: ["VÖEN"] as const,
   candidatePattern: "\\d{10}",
+  scope: "country",
   country: "AZ",
   entityType: "any",
   lengths: [10] as const,

package/src/ba/jmbg.ts

@@ -8,6 +8,12 @@
  * @see https://en.wikipedia.org/wiki/Unique_Master_Citizen_Number
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
@@ -15,12 +21,6 @@ import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type {
-  ParsedPersonId,
-  ValidateResult,
-  Validator,
-} from "../types";
-
 const WEIGHTS = [
   7, 6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2,
 ] as const;
@@ -106,12 +106,13 @@ const generate = (): string => {
 };
 
 /** Bosnian Unique Master Citizen Number. */
-const jmbg: Validator = {
+const jmbg: CountryValidator<"BA", ParsedPersonId> = {
   name: "Bosnian Personal ID",
   localName: "Jedinstveni matični broj građana",
   abbreviation: "JMBG",
   aliases: ["JMBG", "matični broj"] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "BA",
   entityType: "person",
   lengths: [13] as const,
@@ -120,6 +121,7 @@ const jmbg: Validator = {
   examples: ["0101006500006"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/bd/nid.ts

@@ -1,9 +1,9 @@
+const RMO_VALUES = ["1", "2", "3", "4", "5", "9"] as const;
+
 /** Generate a random valid Bangladesh NID (13-digit). */
 const generate = (): string => {
   const district = randomDigits(2);
-  const rmoValues = ["1", "2", "3", "4", "5", "9"];
-  const rmo =
-    rmoValues[randomInt(0, rmoValues.length - 1)]!;
+  const rmo = randomPick(RMO_VALUES);
   const rest = randomDigits(10);
   return `${district}${rmo}${rest}`;
 };
@@ -30,13 +30,16 @@ const generate = (): string => {
  * @see https://www.nidw.gov.bd/
  */
 
+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 RMO (residential/municipal/other) codes.
  * 1 = Rural, 2 = Municipality, 3 = City,
@@ -106,7 +109,7 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Bangladesh National Identity Number. */
-const nid: Validator = {
+const nid: CountryValidator<"BD"> = {
   name: "National Identity Number",
   localName: "জাতীয় পরিচয়পত্র",
   abbreviation: "NID",
@@ -116,6 +119,7 @@ const nid: Validator = {
     "National ID Card",
   ] as const,
   candidatePattern: "\\d{10,17}",
+  scope: "country",
   country: "BD",
   entityType: "person",
   lengths: [10, 13, 17],

package/src/be/bis.ts

@@ -10,14 +10,17 @@
  * @see https://nl.wikipedia.org/wiki/Rijksregisternummer
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+import { checksum, format as nnFormat } from "./nn";
+
 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";
-import { checksum, format as nnFormat } from "./nn";
-
 const compact = (value: string): string =>
   clean(value, " .-");
 
@@ -83,13 +86,14 @@ const generate = (): string => {
 };
 
 /** Belgian BIS Number. */
-const bis: Validator = {
+const bis: CountryValidator<"BE"> = {
   name: "Belgian BIS Number",
   localName: "BIS-nummer",
   abbreviation: "BIS",
   aliases: ["BIS-nummer", "numéro BIS"] as const,
   candidatePattern:
     "\\d{2}\\.?\\d{2}\\.?\\d{2}-?\\d{3}\\.?\\d{2}",
+  scope: "country",
   country: "BE",
   entityType: "person",
   sourceUrl:

package/src/be/nn.ts

@@ -10,13 +10,16 @@
  * @see https://www.ibz.rrn.fgov.be/
  */
 
+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";
-
 const compact = (value: string): string =>
   clean(value, " .-");
 
@@ -100,7 +103,7 @@ const generate = (): string => {
 };
 
 /** Belgian National Number. */
-const nn: Validator = {
+const nn: CountryValidator<"BE"> = {
   name: "Belgian National Number",
   localName: "Numéro national",
   abbreviation: "NN",
@@ -111,6 +114,7 @@ const nn: Validator = {
   ] as const,
   candidatePattern:
     "\\d{2}\\.?\\d{2}\\.?\\d{2}-?\\d{3}\\.?\\d{2}",
+  scope: "country",
   country: "BE",
   entityType: "person",
   sourceUrl: "https://www.ibz.rrn.fgov.be/",

package/src/be/vat.ts

@@ -8,13 +8,16 @@
  * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/belgium-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 compact = (value: string): string => {
   let v = clean(value, " -/.");
   if (v.startsWith("BE") || v.startsWith("be")) {
@@ -82,7 +85,7 @@ const generate = (): string => {
 };
 
 /** Belgian VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"BE"> = {
   name: "Belgian VAT Number",
   localName: "BTW-identificatienummer",
   abbreviation: "BTW",
@@ -93,6 +96,7 @@ const vat: Validator = {
     "ondernemingsnummer",
   ] as const,
   candidatePattern: "BE0?\\d{9,10}",
+  scope: "country",
   country: "BE",
   entityType: "company",
   sourceUrl: "https://finances.belgium.be/",

package/src/bg/egn.ts

@@ -5,10 +5,22 @@
  * 10 digits encoding date of birth, serial number,
  * and a check digit.
  *
- * @see https://en.wikipedia.org/wiki/Unique_citizenship_number
- * @see https://www.grao.bg/
+ * Canonical source:
+ * - GRAO regulation PDF describing the EGN structure.
+ *
+ * We treat this as authoritative over third-party
+ * oracle libraries when the checksum or date rules
+ * disagree.
+ *
+ * @see https://www.grao.bg/normact/NaredbaFunkcESGR.pdf
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 import { clean } from "#util/clean";
 import { isValidDate } from "#util/date";
@@ -16,12 +28,6 @@ import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type {
-  ParsedPersonId,
-  ValidateResult,
-  Validator,
-} from "../types";
-
 const WEIGHTS = [2, 4, 8, 5, 10, 9, 7, 3, 6] as const;
 
 const compact = (value: string): string =>
@@ -131,7 +137,7 @@ const generate = (): string => {
 };
 
 /** Bulgarian Personal Identification Number. */
-const egn: Validator = {
+const egn: CountryValidator<"BG", ParsedPersonId> = {
   name: "Bulgarian Personal ID",
   localName: "Единен граждански номер",
   abbreviation: "ЕГН",
@@ -141,12 +147,15 @@ const egn: Validator = {
     "EGN",
   ] as const,
   candidatePattern: "\\d{10}",
+  scope: "country",
   country: "BG",
   entityType: "person",
-  sourceUrl: "https://www.grao.bg/",
+  sourceUrl:
+    "https://www.grao.bg/normact/NaredbaFunkcESGR.pdf",
   examples: ["7523169263"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/bg/pnf.ts

@@ -7,13 +7,16 @@
  * @see https://en.wikipedia.org/wiki/Unique_citizenship_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 WEIGHTS = [21, 19, 17, 13, 11, 9, 7, 3, 1] as const;
 
 const compact = (value: string): string =>
@@ -61,7 +64,7 @@ const generate = (): string => {
 };
 
 /** Bulgarian Personal Number of a Foreigner. */
-const pnf: Validator = {
+const pnf: CountryValidator<"BG"> = {
   name: "Bulgarian Foreigner Number",
   localName: "Личен номер на чужденец",
   abbreviation: "ЛНЧ",
@@ -71,6 +74,7 @@ const pnf: Validator = {
     "PNF",
   ] as const,
   candidatePattern: "\\d{10}",
+  scope: "country",
   country: "BG",
   entityType: "person",
   sourceUrl:

package/src/bg/vat.ts

@@ -7,14 +7,17 @@
  * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/bulgaria-tin.pdf
  */
 
+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 compact = (value: string): string => {
   let v = clean(value, " -/.");
   if (v.startsWith("BG") || v.startsWith("bg")) {
@@ -132,7 +135,7 @@ const generate = (): string => {
 };
 
 /** Bulgarian VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"BG"> = {
   name: "Bulgarian VAT Number",
   localName: "ИН по ДДС",
   abbreviation: "ИН по ДДС",
@@ -141,9 +144,11 @@ const vat: Validator = {
     "идентификационен номер по ДДС",
   ] as const,
   candidatePattern: "BG\\d{9,10}",
+  scope: "country",
   country: "BG",
   entityType: "any",
   sourceUrl: "https://www.nra.bg/",
+  lengths: [9, 10] as const,
   examples: ["175074752"] as const,
   compact,
   format,

package/src/bh/cpr.ts

@@ -16,12 +16,16 @@
  * @see https://www.bahrain.bh/wps/portal/IDInfo_en
  */
 
+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, " -");
 
@@ -59,13 +63,21 @@ const format = (value: string): string => {
   return `${v.slice(0, 2)}-${v.slice(2, 4)}-${v.slice(4)}`;
 };
 
+/** Generate a random structurally valid Bahrain CPR. */
+const generate = (): string => {
+  const yy = String(randomInt(0, 99)).padStart(2, "0");
+  const mm = String(randomInt(1, 12)).padStart(2, "0");
+  return `${yy}${mm}${randomDigits(5)}`;
+};
+
 /** Bahrain Central Population Registration number. */
-const cpr: Validator = {
+const cpr: CountryValidator<"BH"> = {
   name: "Central Population Registration Number",
   localName: "الرقم السكاني",
   abbreviation: "CPR",
   aliases: ["CPR", "الرقم السكاني"] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "BH",
   entityType: "person",
   lengths: [9] as const,
@@ -75,7 +87,8 @@ const cpr: Validator = {
   compact,
   format,
   validate,
+  generate,
 };
 
 export default cpr;
-export { compact, format, validate };
+export { compact, format, generate, validate };

package/src/bic.ts

@@ -1,28 +1,26 @@
+const BIC_ALPHANUM = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+const BIC_COUNTRIES = [
+  "DE",
+  "GB",
+  "US",
+  "FR",
+  "CH",
+  "NL",
+  "AT",
+] as const;
+
 /** Generate a random valid BIC (8-character). */
 const generate = (): string => {
   const randomLetter = (): string =>
     String.fromCodePoint(65 + randomInt(0, 25));
-  const randomAlphaNum = (): string => {
-    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
-    return chars[randomInt(0, chars.length - 1)]!;
-  };
-  const countries = [
-    "DE",
-    "GB",
-    "US",
-    "FR",
-    "CH",
-    "NL",
-    "AT",
-  ];
-  const country =
-    countries[randomInt(0, countries.length - 1)]!;
+  const country = randomPick(BIC_COUNTRIES);
   const bank =
     randomLetter() +
     randomLetter() +
     randomLetter() +
     randomLetter();
-  const location = randomAlphaNum() + randomAlphaNum();
+  const location =
+    randomChar(BIC_ALPHANUM) + randomChar(BIC_ALPHANUM);
   return `${bank}${country}${location}`;
 };
 
@@ -38,12 +36,19 @@ const generate = (): string => {
  * @see https://www.swift.com/
  */
 
+import type {
+  ValidateResult,
+  GlobalValidator,
+} from "./types";
+
 import { clean } from "#util/clean";
-import { randomInt } from "#util/generate";
+import {
+  randomChar,
+  randomInt,
+  randomPick,
+} from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "./types";
-
 const BIC_RE =
   /^[A-Z]{4}[A-Z]{2}[0-9A-Z]{2}([0-9A-Z]{3})?$/;
 
@@ -80,7 +85,8 @@ const format = (value: string): string => {
 };
 
 /** Business Identifier Code (SWIFT/BIC). */
-const bic: Validator = {
+const bic: GlobalValidator = {
+  scope: "global",
   name: "Business Identifier Code",
   localName: "Business Identifier Code",
   abbreviation: "BIC",

package/src/br/cnpj.ts

@@ -19,12 +19,15 @@
  * @see https://en.wikipedia.org/wiki/CNPJ
  */
 
+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 CNPJ_RE = /^[\dA-Z]+$/;
 
 const compact = (value: string): string =>
@@ -128,7 +131,7 @@ const generate = (): string => {
  * - Petrobras: 33.000.167/0001-01
  * - Banco do Brasil: 00.000.000/0001-91
  */
-const cnpj: Validator = {
+const cnpj: CountryValidator<"BR"> = {
   name: "Brazilian CNPJ",
   localName: "Cadastro Nacional da Pessoa Jurídica",
   abbreviation: "CNPJ",
@@ -138,6 +141,7 @@ const cnpj: Validator = {
   ] as const,
   candidatePattern:
     "\\d{2}\\.?\\d{3}\\.?\\d{3}/?\\d{4}-?\\d{2}",
+  scope: "country",
   country: "BR",
   entityType: "company",
   sourceUrl: "https://www.gov.br/receitafederal/",

package/src/br/cpf.ts

@@ -13,13 +13,16 @@
  * @see https://en.wikipedia.org/wiki/CPF_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, " -.").trim();
 
@@ -94,12 +97,13 @@ const generate = (): string => {
 };
 
 /** Brazilian CPF (personal tax ID). */
-const cpf: Validator = {
+const cpf: CountryValidator<"BR"> = {
   name: "Brazilian CPF",
   localName: "Cadastro de Pessoas Físicas",
   abbreviation: "CPF",
   aliases: ["CPF", "Cadastro de Pessoas Físicas"] as const,
   candidatePattern: "\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}",
+  scope: "country",
   country: "BR",
   entityType: "person",
   sourceUrl: "https://www.gov.br/receitafederal/",