@stll/stdnum 0.0.1 → 2.0.0

package/src/gr/amka.ts

@@ -8,6 +8,11 @@
  * @see https://www.amka.gr/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -18,8 +23,6 @@ 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, " -");
 
@@ -80,7 +83,7 @@ const generate = (): string => {
 };
 
 /** Greek Social Security Number. */
-const amka: Validator = {
+const amka: CountryValidator<"GR"> = {
   name: "Greek Social Security Number",
   localName: "Αριθμός Μητρώου Κοινωνικής Ασφάλισης",
   abbreviation: "ΑΜΚΑ",
@@ -90,6 +93,7 @@ const amka: Validator = {
     "AMKA",
   ] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "GR",
   entityType: "person",
   sourceUrl: "https://www.amka.gr/",

package/src/gr/vat.ts

@@ -9,13 +9,16 @@
  * @see https://www.aade.gr/
  */
 
+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("EL") || v.startsWith("el")) {
@@ -72,7 +75,7 @@ const generate = (): string => {
 };
 
 /** Greek VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"GR"> = {
   name: "Greek VAT Number",
   localName: "Αριθμός Φορολογικού Μητρώου",
   abbreviation: "ΑΦΜ",
@@ -82,6 +85,7 @@ const vat: Validator = {
     "AFM",
   ] as const,
   candidatePattern: "EL\\d{9}",
+  scope: "country",
   country: "GR",
   entityType: "any",
   sourceUrl: "https://www.aade.gr/",

package/src/gt/nit.ts

@@ -11,13 +11,16 @@
  * @see https://portal.sat.gob.gt/portal/
  */
 
+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";
-
 /**
  * Compact: strip spaces, hyphens, leading zeros,
  * and uppercase.
@@ -88,18 +91,22 @@ 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. */
-const nit: Validator = {
+const nit: CountryValidator<"GT"> = {
   name: "Tax Identification Number",
   localName: "Número de Identificación Tributaria",
   abbreviation: "NIT",
   aliases: ["NIT"] as const,
   candidatePattern: "\\d{7,8}-?\\d",
+  scope: "country",
   country: "GT",
   entityType: "any",
   description: "Tax identifier issued by Guatemala's SAT",

package/src/hk/hkid.ts

@@ -9,12 +9,15 @@
  * @see https://en.wikipedia.org/wiki/Hong_Kong_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 type { ValidateResult, Validator } from "../types";
-
 /** Strip spaces, parentheses, and dashes. */
 const compact = (value: string): string =>
   clean(value, " -()").toUpperCase();
@@ -32,7 +35,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;
@@ -105,12 +109,13 @@ const generate = (): string => {
 };
 
 /** Hong Kong Identity Card number. */
-const hkid: Validator = {
+const hkid: CountryValidator<"HK"> = {
   name: "Hong Kong Identity Card Number",
   localName: "Hong Kong Identity Card Number",
   abbreviation: "HKID",
   aliases: ["HKID", "香港身份證"] as const,
   candidatePattern: "[A-Z]{1,2}\\d{6}[\\dA]",
+  scope: "country",
   country: "HK",
   entityType: "person",
   lengths: [8, 9],

package/src/hr/vat.ts

@@ -7,6 +7,11 @@
  * @see https://www.porezna-uprava.hr/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   mod1110validate,
   mod1110checkDigit,
@@ -16,8 +21,6 @@ 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("HR") || v.startsWith("hr")) {
@@ -59,12 +62,13 @@ const generate = (): string => {
 };
 
 /** Croatian VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"HR"> = {
   name: "Croatian VAT Number",
   localName: "Osobni identifikacijski broj",
   abbreviation: "OIB",
   aliases: ["OIB", "osobni identifikacijski broj"] as const,
   candidatePattern: "HR\\d{11}",
+  scope: "country",
   country: "HR",
   entityType: "any",
   sourceUrl: "https://www.porezna-uprava.hr/",

package/src/hu/vat.ts

@@ -8,14 +8,17 @@
  * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/hungary-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 = [9, 7, 3, 1, 9, 7, 3, 1];
 
 const compact = (value: string): string => {
@@ -62,15 +65,17 @@ const generate = (): string => {
 };
 
 /** Hungarian VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"HU"> = {
   name: "Hungarian VAT Number",
   localName: "Adószám",
   abbreviation: "ANUM",
   aliases: ["adószám", "adóazonosító jel"] as const,
   candidatePattern: "\\d{8}-\\d-\\d{2}",
+  scope: "country",
   country: "HU",
   entityType: "company",
   sourceUrl: "https://nav.gov.hu/",
+  lengths: [8] as const,
   examples: ["12892312"] as const,
   compact,
   format,

package/src/iban.ts

@@ -6,14 +6,17 @@
  * characters. Validated using ISO 7064 Mod 97-10.
  */
 
+import type {
+  ValidateResult,
+  GlobalValidator,
+} from "./types";
+
 import { mod97 } from "#checksums/mod97";
 import { clean } from "#util/clean";
 import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { charValue, isalnum } from "#util/strings";
 
-import type { ValidateResult, Validator } from "./types";
-
 /**
  * BBAN format regex by country code.
  * Sourced from SWIFT IBAN Registry.
@@ -314,7 +317,8 @@ const generate = (): string => {
 };
 
 /** International Bank Account Number. */
-const iban: Validator = {
+const iban: GlobalValidator = {
+  scope: "global",
   name: "IBAN",
   localName: "IBAN",
   abbreviation: "IBAN",

package/src/id/npwp.ts

@@ -10,6 +10,11 @@
  * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Indonesia-TIN.pdf
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -20,8 +25,6 @@ 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, " .-");
 
@@ -160,13 +163,14 @@ const generate = (): string => {
 };
 
 /** Indonesian Taxpayer Identification Number. */
-const npwp: Validator = {
+const npwp: CountryValidator<"ID"> = {
   name: "Indonesian Taxpayer Identification Number",
   localName: "Nomor Pokok Wajib Pajak",
   abbreviation: "NPWP",
   aliases: ["NPWP", "Nomor Pokok Wajib Pajak"] as const,
   candidatePattern:
     "\\d{2}\\.?\\d{3}\\.?\\d{3}\\.?\\d-?\\d{3}\\.?\\d{3}",
+  scope: "country",
   country: "ID",
   entityType: "any",
   lengths: [15, 16],

package/src/ie/pps.ts

@@ -9,13 +9,16 @@
  * @see https://www.gov.ie/en/service/12e6de-get-a-personal-public-service-pps-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 ALPHABET = "WABCDEFGHIJKLMNOPQRSTUV";
 
 const compact = (value: string): string =>
@@ -84,12 +87,13 @@ const generate = (): string => {
 };
 
 /** Irish Personal Public Service Number. */
-const pps: Validator = {
+const pps: CountryValidator<"IE"> = {
   name: "Irish Personal ID",
   localName: "Personal Public Service Number",
   abbreviation: "PPS",
   aliases: ["PPS number", "PPSN", "RSI number"] as const,
   candidatePattern: "\\d{7}[A-Z]{1,2}",
+  scope: "country",
   country: "IE",
   entityType: "person",
   sourceUrl:

package/src/ie/vat.ts

@@ -8,13 +8,16 @@
  * @see https://www.revenue.ie/
  */
 
+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 ALPHABET = "WABCDEFGHIJKLMNOPQRSTUV";
 
 const compact = (value: string): string => {
@@ -118,12 +121,13 @@ const generate = (): string => {
 };
 
 /** Irish VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"IE"> = {
   name: "Irish VAT Number",
   localName: "Value Added Tax Number",
   abbreviation: "VAT",
   aliases: ["VAT number IE"] as const,
   candidatePattern: "IE\\d[A-Z+*]\\d{5}[A-Z]",
+  scope: "country",
   country: "IE",
   entityType: "any",
   sourceUrl: "https://www.revenue.ie/",

package/src/il/idnr.ts

@@ -7,6 +7,11 @@
  * @see https://en.wikipedia.org/wiki/Israeli_identity_card
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -16,8 +21,6 @@ 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, " -").padStart(9, "0");
 
@@ -58,7 +61,7 @@ const generate = (): string => {
 };
 
 /** Israeli Identity Number (Mispar Zehut). */
-const idnr: Validator = {
+const idnr: CountryValidator<"IL"> = {
   name: "Israeli Identity Number",
   localName: "מספר זהות",
   abbreviation: "ת.ז.",
@@ -68,6 +71,7 @@ const idnr: Validator = {
     "ID number",
   ] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "IL",
   entityType: "person",
   compact,

package/src/in/aadhaar.ts

@@ -10,6 +10,11 @@
  * @see https://uidai.gov.in/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   verhoeffValidate,
   verhoeffCheckDigit,
@@ -19,8 +24,6 @@ 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, " -");
 
@@ -73,12 +76,13 @@ const generate = (): string => {
 };
 
 /** Indian Unique Identity Number. */
-const aadhaar: Validator = {
+const aadhaar: CountryValidator<"IN"> = {
   name: "Indian Unique Identity Number",
   localName: "Aadhaar",
   abbreviation: "Aadhaar",
   aliases: ["Aadhaar", "आधार"] as const,
   candidatePattern: "\\d{4}\\s?\\d{4}\\s?\\d{4}",
+  scope: "country",
   country: "IN",
   entityType: "person",
   lengths: [12],

package/src/in/gstin.ts

@@ -9,13 +9,16 @@
  * @see https://en.wikipedia.org/wiki/Goods_and_Services_Tax_Identification_Number
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
 import { randomDigits, randomInt } from "#util/generate";
 import { err } from "#util/result";
 import { charValue } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const GSTIN_RE =
   /^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z]$/;
 
@@ -70,7 +73,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);
@@ -144,13 +149,14 @@ const generate = (): string => {
 };
 
 /** Indian Goods and Services Tax ID. */
-const gstin: Validator = {
+const gstin: CountryValidator<"IN"> = {
   name: "Indian Goods and Services Tax ID",
   localName: "Goods and Services Tax Identification Number",
   abbreviation: "GSTIN",
   aliases: ["GSTIN", "GST number"] as const,
   candidatePattern:
     "\\d{2}[A-Z]{5}\\d{4}[A-Z][A-Z\\d][Z][A-Z\\d]",
+  scope: "country",
   country: "IN",
   entityType: "company",
   lengths: [15],

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();
@@ -26,12 +25,19 @@ const generate = (): string => {
  * @see https://en.wikipedia.org/wiki/Permanent_account_number
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 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";
-
 const PAN_RE = /^[A-Z]{5}\d{4}[A-Z]$/;
 
 const HOLDER_TYPES = "ABCFGHJLPT";
@@ -53,6 +59,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",
@@ -65,12 +73,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Indian Permanent Account Number. */
-const pan: Validator = {
+const pan: CountryValidator<"IN"> = {
   name: "Indian Permanent Account Number",
   localName: "Permanent Account Number",
   abbreviation: "PAN",
   aliases: ["PAN", "Permanent Account Number"] as const,
   candidatePattern: "[A-Z]{5}\\d{4}[A-Z]",
+  scope: "country",
   country: "IN",
   entityType: "any",
   lengths: [10],

package/src/index.ts

@@ -1,10 +1,16 @@
 export type {
+  CountryValidator,
   CountryCode,
   ErrorCode,
+  GlobalValidator,
+  ParsedBirthDate,
+  ParsedIdentifier,
   ParsedPersonId,
+  ParsableValidator,
   StdnumError,
   ValidateResult,
   Validator,
+  ValidatorScope,
 } from "./types";
 export { default as bic } from "./bic";
 export {

package/src/iq/nid.ts

@@ -16,14 +16,17 @@ const generate = (): string => randomDigits(12);
  * @see https://mofa.gov.iq/the-civil-status-id/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { normalizeArabicDigits } from "#util/arabic";
 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 =>
   normalizeArabicDigits(clean(value, " -./"));
 
@@ -48,12 +51,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Iraqi National Identification Number. */
-const nid: Validator = {
+const nid: CountryValidator<"IQ"> = {
   name: "Iraqi National ID",
   localName: "البطاقة الوطنية الموحدة",
   abbreviation: "NID",
   aliases: ["NID", "البطاقة الوطنية الموحدة"] as const,
   candidatePattern: "\\d{12}",
+  scope: "country",
   country: "IQ",
   entityType: "person",
   sourceUrl: "https://mofa.gov.iq/the-civil-status-id/",

package/src/ir/nid.ts

@@ -22,14 +22,17 @@
  * @see https://persian-tools.js.org/functions/verifyIranianNationalId.html
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { normalizeArabicDigits } from "#util/arabic";
 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";
-
 /** All-same-digit patterns (0000000000 .. 9999999999). */
 const ALL_SAME = new Set(
   Array.from({ length: 10 }, (_, i) =>
@@ -97,12 +100,13 @@ const generate = (): string => {
 };
 
 /** Iranian National Identification Number. */
-const nid: Validator = {
+const nid: CountryValidator<"IR"> = {
   name: "Iranian National ID",
   localName: "کد ملی",
   abbreviation: "NID",
   aliases: ["NID", "کد ملی", "national code"] as const,
   candidatePattern: "\\d{10}",
+  scope: "country",
   country: "IR",
   entityType: "person",
   sourceUrl: "https://www.sabteahval.ir/",

package/src/is/kennitala.ts

@@ -11,14 +11,17 @@
  * @see https://www.skra.is/
  */
 
+import type {
+  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 { ValidateResult, Validator } from "../types";
-
 const WEIGHTS = [3, 2, 7, 6, 5, 4, 3, 2, 0, 0] as const;
 
 const compact = (value: string): string =>
@@ -105,12 +108,13 @@ const generate = (): string => {
 };
 
 /** Icelandic Identification Number. */
-const kennitala: Validator = {
+const kennitala: CountryValidator<"IS"> = {
   name: "Icelandic ID Number",
   localName: "Kennitala",
   abbreviation: "kt.",
   aliases: ["kennitala", "kt."] as const,
   candidatePattern: "\\d{6}-?\\d{4}",
+  scope: "country",
   country: "IS",
   entityType: "any",
   sourceUrl: "https://www.skra.is/",