@stll/stdnum 1.0.0 → 2.0.1

package/src/sk/ico.ts

@@ -13,10 +13,10 @@ import {
   generate,
   validate,
 } from "../cz/ico";
-import type { Validator } from "../types";
+import type { CountryValidator } from "../types";
 
 /** Slovak Company Identification Number. */
-const ico: Validator = {
+const ico: CountryValidator<"SK"> = {
   name: "Slovak Company ID",
   localName: "Identifikačné číslo organizácie",
   abbreviation: "IČO",
@@ -25,6 +25,7 @@ const ico: Validator = {
     "identifikačné číslo organizácie",
   ] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "SK",
   entityType: "company",
   sourceUrl: "https://www.statistics.sk/",

package/src/sk/rc.ts

@@ -15,15 +15,19 @@ import {
   parse,
   validate,
 } from "../cz/rc";
-import type { ParsedPersonId, Validator } from "../types";
+import type {
+  ParsedPersonId,
+  CountryValidator,
+} from "../types";
 
 /** Slovak Birth Number. */
-const rc: Validator<ParsedPersonId> = {
+const rc: CountryValidator<"SK", ParsedPersonId> = {
   name: "Slovak Birth Number",
   localName: "Rodné číslo",
   abbreviation: "RČ",
   aliases: ["rodné číslo", "RČ"] as const,
   candidatePattern: "\\d{6}/\\d{3,4}",
+  scope: "country",
   country: "SK",
   entityType: "person",
   sourceUrl: "https://www.minv.sk/",

package/src/th/tin.ts

@@ -10,13 +10,16 @@
  * @see https://en.wikipedia.org/wiki/Thai_identity_card
  */
 
+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, " -");
 
@@ -79,12 +82,13 @@ const generate = (): string => {
 };
 
 /** Thai Tax Identification Number. */
-const tin: Validator = {
+const tin: CountryValidator<"TH"> = {
   name: "Thai Tax Identification Number",
   localName: "เลขประจำตัวผู้เสียภาษี",
   abbreviation: "TIN",
   aliases: ["เลขประจำตัวผู้เสียภาษี", "TIN"] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "TH",
   entityType: "any",
   description:

package/src/tr/tckimlik.ts

@@ -19,13 +19,16 @@
  * @see https://www.turkiye.gov.tr/nvi-tckn-dogrulama
  */
 
+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, " -./");
 
@@ -88,7 +91,7 @@ const generate = (): string => {
 };
 
 /** Turkish Personal Identification Number. */
-const tckimlik: Validator = {
+const tckimlik: CountryValidator<"TR"> = {
   name: "Turkish Personal ID",
   localName: "T.C. Kimlik Numarası",
   abbreviation: "T.C. Kimlik",
@@ -97,6 +100,7 @@ const tckimlik: Validator = {
     "T.C. Kimlik Numarası",
   ] as const,
   candidatePattern: "[1-9]\\d{10}",
+  scope: "country",
   country: "TR",
   entityType: "person",
   sourceUrl: "https://www.nvi.gov.tr/",

package/src/tr/vkn.ts

@@ -19,13 +19,16 @@
  * @see https://www.gib.gov.tr/
  */
 
+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, " -./");
 
@@ -77,12 +80,13 @@ const generate = (): string => {
 };
 
 /** Turkish Tax Identification Number. */
-const vkn: Validator = {
+const vkn: CountryValidator<"TR"> = {
   name: "Turkish Tax ID",
   localName: "Vergi Kimlik Numarası",
   abbreviation: "VKN",
   aliases: ["VKN", "Vergi Kimlik Numarası"] as const,
   candidatePattern: "\\d{10}",
+  scope: "country",
   country: "TR",
   entityType: "company",
   sourceUrl: "https://www.gib.gov.tr/",

package/src/tw/ubn.ts

@@ -10,13 +10,16 @@
  * @see https://zh.wikipedia.org/wiki/統一編號
  */
 
+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, 2, 1, 2, 1, 2, 4, 1] as const;
 
 /** Sum the individual digits of a number. */
@@ -84,12 +87,13 @@ const generate = (): string => {
 };
 
 /** Taiwanese Unified Business Number. */
-const ubn: Validator = {
+const ubn: CountryValidator<"TW"> = {
   name: "Unified Business Number",
   localName: "統一編號",
   abbreviation: "UBN",
   aliases: ["統一編號", "UBN"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "TW",
   entityType: "company",
   description:

package/src/types.ts

@@ -135,7 +135,20 @@ export type ParsedIdentifier =
   | ParsedBirthDate
   | ParsedPersonId;
 
-export type Validator<
+/**
+ * Whether an identifier is scoped to a single
+ * country (e.g. Czech IČO) or is cross-border by
+ * design (e.g. IBAN, ISIN, BIC, LEI, EU VAT).
+ *
+ * Modeled as a discriminated union so consumers
+ * can group, filter, and exhaustively switch
+ * without null-checking `country`.
+ */
+export type ValidatorScope =
+  | { scope: "country"; country: CountryCode }
+  | { scope: "global" };
+
+type ValidatorBase<
   TParsed extends ParsedIdentifier | undefined = undefined,
 > = {
   /** English name. */
@@ -144,8 +157,6 @@ export type Validator<
   localName: string;
   /** Common abbreviation (e.g. "IČO"). */
   abbreviation: string;
-  /** Country this identifier belongs to. */
-  country?: CountryCode;
   /** What kind of entity this identifies. */
   entityType: "person" | "company" | "any";
 
@@ -226,6 +237,26 @@ export type Validator<
   ? unknown
   : { parse: (value: string) => TParsed | null });
 
+export type CountryValidator<
+  TCountry extends CountryCode = CountryCode,
+  TParsed extends ParsedIdentifier | undefined = undefined,
+> = ValidatorBase<TParsed> & {
+  scope: "country";
+  country: TCountry;
+};
+
+export type GlobalValidator<
+  TParsed extends ParsedIdentifier | undefined = undefined,
+> = ValidatorBase<TParsed> & {
+  scope: "global";
+};
+
+export type Validator<
+  TParsed extends ParsedIdentifier | undefined = undefined,
+> =
+  | CountryValidator<CountryCode, TParsed>
+  | GlobalValidator<TParsed>;
+
 export type ParsableValidator<
   TParsed extends ParsedIdentifier = ParsedIdentifier,
 > = Validator<TParsed>;

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;
@@ -83,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

@@ -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, 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

@@ -23,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, 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. */
@@ -99,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",
@@ -108,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,14 +7,19 @@
  * [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,
@@ -24,8 +29,6 @@ import {
 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] as const;
 
 const compact = (value: string): string =>
@@ -48,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;
@@ -78,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],
@@ -103,7 +110,7 @@ const generate = (): string => {
 };
 
 /** U.S. Routing Transit Number. */
-const rtn: Validator = {
+const rtn: CountryValidator<"US"> = {
   name: "Routing Transit Number",
   localName: "Routing Transit Number",
   abbreviation: "RTN",
@@ -115,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 => {
@@ -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, 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.
@@ -110,9 +113,7 @@ const GENERATE_TYPES = ["V", "E", "J", "P", "G"] as const;
 const generate = (): string => {
   const prefix = randomPick(GENERATE_TYPES);
   const body = randomDigits(8);
-  return (
-    prefix + body + String(calcCheckDigit(prefix, body))
-  );
+  return prefix + body + calcCheckDigit(prefix, body);
 };
 
 /**
@@ -120,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",
@@ -129,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,12 +132,13 @@ const generate = (): string => {
 };
 
 /** South African Identity Number. */
-const idnr: Validator<ParsedPersonId> = {
+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,