@stll/stdnum 1.0.0 → 2.0.0

package/src/my/nric.ts

@@ -12,18 +12,18 @@
  * @see https://en.wikipedia.org/wiki/Malaysian_identity_card
  */
 
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 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";
 
-import type {
-  ParsedPersonId,
-  ValidateResult,
-  Validator,
-} from "../types";
-
 /**
  * Valid place-of-birth codes (2-digit).
  * Codes 01-16 are states, 21-59 are pre-2000
@@ -234,12 +234,13 @@ const generate = (): string => {
 };
 
 /** Malaysian National Registration Identity Card. */
-const nric: Validator<ParsedPersonId> = {
+const nric: CountryValidator<"MY", ParsedPersonId> = {
   name: "Malaysian National Registration Identity Card Number",
   localName: "Nombor Kad Pengenalan",
   abbreviation: "NRIC",
   aliases: ["NRIC", "MyKad", "kad pengenalan"] as const,
   candidatePattern: "\\d{6}-?\\d{2}-?\\d{4}",
+  scope: "country",
   country: "MY",
   entityType: "person",
   description:

package/src/ng/nin.ts

@@ -13,13 +13,16 @@ const generate = (): string => randomDigits(11);
  * @see https://nimc.gov.ng/about-nin/
  */
 
+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, " -");
 
@@ -46,7 +49,7 @@ const format = (value: string): string => {
 };
 
 /** Nigerian National Identification Number. */
-const nin: Validator = {
+const nin: CountryValidator<"NG"> = {
   name: "National Identification Number",
   localName: "National Identification Number",
   abbreviation: "NIN",
@@ -55,6 +58,7 @@ const nin: Validator = {
     "National Identification Number",
   ] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "NG",
   entityType: "person",
   lengths: [11] as const,

package/src/ni/ruc.ts

@@ -22,13 +22,16 @@
  * @see https://www.dgi.gob.ni/
  */
 
+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";
-
 /**
  * Check letter alphabet (mod 23). Excludes I, O, Z
  * to prevent transcription errors.
@@ -154,12 +157,13 @@ const format = (value: string): string => {
 const generate = (): string => "J" + randomDigits(13);
 
 /** Nicaragua tax identification number. */
-const ruc: Validator = {
+const ruc: CountryValidator<"NI"> = {
   name: "Tax Identification Number",
   localName: "Registro Único de Contribuyente",
   abbreviation: "RUC",
   aliases: ["RUC"] as const,
   candidatePattern: "[JKME]\\d{13}",
+  scope: "country",
   country: "NI",
   entityType: "any",
   description: "Tax identifier issued by Nicaragua's DGI",

package/src/nl/bsn.ts

@@ -8,14 +8,17 @@
  * @see https://www.government.nl/topics/personal-data/citizen-service-number-bsn
  */
 
+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 WEIGHTS = [9, 8, 7, 6, 5, 4, 3, 2, -1] as const;
 
 const compact = (value: string): string =>
@@ -62,7 +65,7 @@ const generate = (): string => {
 };
 
 /** Dutch Citizen Service Number. */
-const bsn: Validator = {
+const bsn: CountryValidator<"NL"> = {
   name: "Dutch Citizen Service Number",
   localName: "Burgerservicenummer",
   abbreviation: "BSN",
@@ -72,6 +75,7 @@ const bsn: Validator = {
     "sofinummer",
   ] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "NL",
   entityType: "person",
   sourceUrl:

package/src/nl/kvk.ts

@@ -9,13 +9,16 @@ const generate = (): string => randomDigits(8);
  * @see https://www.kvk.nl/
  */
 
+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, " -/.");
 
@@ -39,12 +42,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Dutch Chamber of Commerce Number. */
-const kvk: Validator = {
+const kvk: CountryValidator<"NL"> = {
   name: "Dutch Chamber of Commerce Number",
   localName: "KvK-nummer",
   abbreviation: "KvK",
   aliases: ["KVK-nummer", "Kamer van Koophandel"] as const,
   candidatePattern: "\\d{8}",
+  scope: "country",
   country: "NL",
   entityType: "company",
   sourceUrl: "https://www.kvk.nl/",

package/src/nl/vat.ts

@@ -12,13 +12,16 @@
  * @see https://business.gov.nl/regulations/using-checking-vat-numbers/
  */
 
+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("NL") || v.startsWith("nl")) {
@@ -70,12 +73,13 @@ const generate = (): string =>
   `${randomDigits(9)}B${randomDigits(2)}`;
 
 /** Dutch VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"NL"> = {
   name: "Dutch VAT Number",
   localName: "BTW-identificatienummer",
   abbreviation: "BTW",
   aliases: ["BTW-nummer", "BTW-id"] as const,
   candidatePattern: "NL\\d{9}B\\d{2}",
+  scope: "country",
   country: "NL",
   entityType: "company",
   sourceUrl:

package/src/no/fodselsnummer.ts

@@ -8,18 +8,18 @@
  * @see https://www.skatteetaten.no/
  */
 
+import type {
+  ParsedPersonId,
+  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_D1 = [3, 7, 6, 1, 8, 9, 4, 5, 2] as const;
 const WEIGHTS_D2 = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2] as const;
 
@@ -172,12 +172,16 @@ const generate = (): string => {
 };
 
 /** Norwegian Birth Number. */
-const fodselsnummer: Validator<ParsedPersonId> = {
+const fodselsnummer: CountryValidator<
+  "NO",
+  ParsedPersonId
+> = {
   name: "Norwegian Birth Number",
   localName: "Fødselsnummer",
   abbreviation: "Fødselsnr",
   aliases: ["fødselsnummer", "personnummer"] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "NO",
   entityType: "person",
   sourceUrl: "https://www.skatteetaten.no/",

package/src/no/mva.ts

@@ -7,15 +7,18 @@
  * @see https://www.skatteetaten.no/
  */
 
-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 validateOrgnr,
   generate as generateOrgnr,
 } from "./orgnr";
 
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
 const compact = (value: string): string => {
   let v = clean(value, " -").toUpperCase();
   if (v.startsWith("NO")) {
@@ -53,12 +56,13 @@ const format = (value: string): string => {
 const generate = (): string => generateOrgnr() + "MVA";
 
 /** Norwegian VAT Number. */
-const mva: Validator = {
+const mva: CountryValidator<"NO"> = {
   name: "Norwegian VAT Number",
   localName: "Merverdiavgift",
   abbreviation: "MVA",
   aliases: ["MVA-nummer", "organisasjonsnummer"] as const,
   candidatePattern: "NO\\d{9}MVA",
+  scope: "country",
   country: "NO",
   entityType: "company",
   sourceUrl: "https://www.skatteetaten.no/",

package/src/no/orgnr.ts

@@ -6,14 +6,17 @@
  * @see https://www.brreg.no/
  */
 
+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 WEIGHTS = [3, 2, 7, 6, 5, 4, 3, 2, 1] as const;
 
 const compact = (value: string): string =>
@@ -59,12 +62,13 @@ const generate = (): string => {
 };
 
 /** Norwegian Organization Number. */
-const orgnr: Validator = {
+const orgnr: CountryValidator<"NO"> = {
   name: "Norwegian Organization Number",
   localName: "Organisasjonsnummer",
   abbreviation: "Orgnr",
   aliases: ["organisasjonsnummer", "org.nr"] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "NO",
   entityType: "company",
   sourceUrl: "https://www.brreg.no/",

package/src/nz/ird.ts

@@ -9,13 +9,16 @@
  * @see https://www.ird.govt.nz/
  */
 
+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 PRIMARY_WEIGHTS = [3, 2, 7, 6, 5, 4, 3, 2] as const;
 
 const SECONDARY_WEIGHTS = [7, 4, 3, 2, 5, 2, 7, 6] as const;
@@ -80,7 +83,7 @@ const validate = (value: string): ValidateResult => {
       "IRD number cannot have a valid check digit",
     );
   }
-  if (expected !== Number(v[v.length - 1])) {
+  if (expected !== Number(v.at(-1))) {
     return err(
       "INVALID_CHECKSUM",
       "IRD check digit does not match",
@@ -105,12 +108,13 @@ const generate = (): string => {
 };
 
 /** New Zealand IRD Number. */
-const ird: Validator = {
+const ird: CountryValidator<"NZ"> = {
   name: "IRD Number",
   localName: "IRD Number",
   abbreviation: "IRD",
   aliases: ["IRD number", "tax number NZ"] as const,
   candidatePattern: "\\d{8,9}",
+  scope: "country",
   country: "NZ",
   entityType: "any",
   compact,

package/src/pa/ruc.ts

@@ -17,12 +17,15 @@
  * @see https://dgi.mef.gob.pa/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomInt } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 /**
  * Legacy cross-reference table: maps two-digit codes
  * at positions 5–6 of old-format juridical RUCs.
@@ -359,12 +362,13 @@ const generate = (): string => {
 };
 
 /** Panama tax identification number. */
-const ruc: Validator = {
+const ruc: CountryValidator<"PA"> = {
   name: "Tax Identification Number",
   localName: "Registro Único de Contribuyente",
   abbreviation: "RUC",
   aliases: ["RUC"] as const,
   candidatePattern: "\\d{1,2}-?\\d{1,4}-?\\d{1,6}",
+  scope: "country",
   country: "PA",
   entityType: "any",
   description: "Tax identifier issued by Panama's DGI",

package/src/patterns.ts

@@ -27,13 +27,19 @@
  * ```
  */
 
-import type { CountryCode, Validator } from "./types";
+import type {
+  CountryCode,
+  CountryValidator,
+  Validator,
+} from "./types";
 
 // ─── Pattern type ─────────────────────────────
 
-export type ValidatorPattern = {
+export type ValidatorPattern<
+  TValidator extends Validator = Validator,
+> = {
   /** The validator this pattern was derived from. */
-  validator: Validator;
+  validator: TValidator;
   /** Loose regex matching candidates in text. */
   regex: RegExp;
 };
@@ -314,9 +320,9 @@ export const toRegex = (v: Validator): RegExp => {
 /**
  * Build patterns for a list of validators.
  */
-export const toPatterns = (
-  validators: readonly Validator[],
-): ValidatorPattern[] =>
+export const toPatterns = <TValidator extends Validator>(
+  validators: readonly TValidator[],
+): ValidatorPattern<TValidator>[] =>
   validators.map((v) => ({
     validator: v,
     regex: toRegex(v),
@@ -326,22 +332,47 @@ export const toPatterns = (
  * Filter validators by country code and build
  * patterns.
  */
-export const byCountry = (
-  country: CountryCode,
-  validators: readonly Validator[],
-): ValidatorPattern[] =>
-  toPatterns(
-    validators.filter((v) => v.country === country),
+type CountryScopedValidator<
+  TValidator extends Validator,
+  TCountry extends CountryCode,
+> =
+  TValidator extends CountryValidator<
+    infer TValidatorCountry,
+    infer TParsed
+  >
+    ? TCountry extends TValidatorCountry
+      ? TValidator & CountryValidator<TCountry, TParsed>
+      : TValidatorCountry extends TCountry
+        ? TValidator
+        : never
+    : never;
+
+export const byCountry = <
+  TCountry extends CountryCode,
+  TValidator extends Validator,
+>(
+  country: TCountry,
+  validators: readonly TValidator[],
+): ValidatorPattern<
+  CountryScopedValidator<TValidator, TCountry>
+>[] => {
+  const countryValidators = validators.filter(
+    (
+      v,
+    ): v is CountryScopedValidator<TValidator, TCountry> =>
+      v.scope === "country" && v.country === country,
   );
+  return toPatterns(countryValidators);
+};
 
 /**
  * Filter validators by entity type and build
  * patterns.
  */
-export const byEntityType = (
+export const byEntityType = <TValidator extends Validator>(
   entityType: "person" | "company" | "any",
-  validators: readonly Validator[],
-): ValidatorPattern[] =>
+  validators: readonly TValidator[],
+): ValidatorPattern<TValidator>[] =>
   toPatterns(
     validators.filter(
       (v) =>
@@ -354,6 +385,6 @@ export const byEntityType = (
 /**
  * Build patterns for ALL provided validators.
  */
-export const allPatterns = (
-  validators: readonly Validator[],
-): ValidatorPattern[] => toPatterns(validators);
+export const allPatterns = <TValidator extends Validator>(
+  validators: readonly TValidator[],
+): ValidatorPattern<TValidator>[] => toPatterns(validators);

package/src/pe/ruc.ts

@@ -14,13 +14,16 @@
  * @see https://en.wikipedia.org/wiki/Tax_identification_number#Peru
  */
 
+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 type prefixes for RUC numbers.
  * 10 = natural person, 15 = non-domiciled without RUC,
@@ -99,12 +102,13 @@ const generate = (): string => {
  * Examples sourced from python-stdnum test suite
  * (pe.ruc module).
  */
-const ruc: Validator = {
+const ruc: CountryValidator<"PE"> = {
   name: "Peruvian Tax ID",
   localName: "Registro Único de Contribuyentes",
   abbreviation: "RUC",
   aliases: ["RUC"] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "PE",
   entityType: "any",
   compact,

package/src/ph/philid.ts

@@ -14,13 +14,16 @@ const generate = (): string => randomDigits(12);
  * @see https://philsys.gov.ph/
  */
 
+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, " -");
 
@@ -50,12 +53,13 @@ const format = (value: string): string => {
 };
 
 /** Philippine Identification System Number. */
-const philid: Validator = {
+const philid: CountryValidator<"PH"> = {
   name: "Philippine Identification System Number",
   localName: "PhilSys Card Number",
   abbreviation: "PhilID",
   aliases: ["PhilID", "PhilSys", "Philippine ID"] as const,
   candidatePattern: "\\d{4}-\\d{4}-\\d{4}-\\d{4}",
+  scope: "country",
   country: "PH",
   entityType: "person",
   description:

package/src/pk/cnic.ts

@@ -20,13 +20,16 @@ const generate = (): string => {
  * @see https://en.wikipedia.org/wiki/CNIC_(Pakistan)
  */
 
+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, " -");
 
@@ -81,12 +84,13 @@ const format = (value: string): string => {
 };
 
 /** Pakistan Computerized National Identity Card. */
-const cnic: Validator = {
+const cnic: CountryValidator<"PK"> = {
   name: "Computerized National Identity Card",
   localName: "Computerized National Identity Card",
   abbreviation: "CNIC",
   aliases: ["CNIC", "شناختی کارڈ"] as const,
   candidatePattern: "\\d{5}-?\\d{7}-?\\d",
+  scope: "country",
   country: "PK",
   entityType: "person",
   lengths: [13],

package/src/pl/nip.ts

@@ -8,14 +8,17 @@
  * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/poland-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 WEIGHTS = [6, 5, 7, 2, 3, 4, 5, 6, 7] as const;
 
 const compact = (value: string): string => {
@@ -73,7 +76,7 @@ const generate = (): string => {
 };
 
 /** Polish VAT Number. */
-const nip: Validator = {
+const nip: CountryValidator<"PL"> = {
   name: "Polish VAT Number",
   localName: "Numer Identyfikacji Podatkowej",
   abbreviation: "NIP",
@@ -82,6 +85,7 @@ const nip: Validator = {
     "numer identyfikacji podatkowej",
   ] as const,
   candidatePattern: "\\d{3}-?\\d{3}-?\\d{2}-?\\d{2}",
+  scope: "country",
   country: "PL",
   entityType: "company",
   sourceUrl: "https://www.biznes.gov.pl/en/portal/004124",