@stll/stdnum 0.0.1 → 2.0.0

package/src/fi/hetu.ts

@@ -8,17 +8,18 @@
  * @see https://dvv.fi/en/personal-identity-code
  */
 
-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 { randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
 const CHECK_CHARS = "0123456789ABCDEFHJKLMNPRSTUVWXY";
 
 const SEPARATORS_1800 = new Set(["+"]);
@@ -158,8 +159,21 @@ const parse = (value: string): ParsedPersonId | null => {
   };
 };
 
+/** Generate a random valid HETU. */
+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 separator = year >= 2000 ? "A" : "-";
+  const serial = String(randomInt(2, 899)).padStart(3, "0");
+  const checkNum = Number(`${day}${month}${yy}${serial}`);
+  const checkChar = CHECK_CHARS.charAt(checkNum % 31);
+  return `${day}${month}${yy}${separator}${serial}${checkChar}`;
+};
+
 /** Finnish Personal Identity Code. */
-const hetu: Validator = {
+const hetu: CountryValidator<"FI", ParsedPersonId> = {
   name: "Finnish Personal ID",
   localName: "Henkilötunnus",
   abbreviation: "HETU",
@@ -169,14 +183,18 @@ const hetu: Validator = {
     "sosiaaliturvatunnus",
   ] as const,
   candidatePattern: "\\d{6}[-+A]\\d{3}[\\dA-Z]",
+  scope: "country",
   country: "FI",
   entityType: "person",
   sourceUrl: "https://dvv.fi/en/personal-identity-code",
+  lengths: [11] as const,
   examples: ["131052-308T"] as const,
   compact,
   format,
+  parse,
   validate,
+  generate,
 };
 
 export default hetu;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

package/src/fi/vat.ts

@@ -8,14 +8,17 @@
  * @see https://www.ytj.fi/en/index/businessid.html
  */
 
+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 = [7, 9, 10, 5, 8, 4, 2, 1];
 
 const compact = (value: string): string => {
@@ -62,15 +65,17 @@ const generate = (): string => {
 };
 
 /** Finnish VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"FI"> = {
   name: "Finnish VAT Number",
   localName: "Arvonlisäveronumero",
   abbreviation: "ALV nro",
   aliases: ["ALV-numero", "Y-tunnus"] as const,
   candidatePattern: "FI\\d{8}",
+  scope: "country",
   country: "FI",
   entityType: "company",
   sourceUrl: "https://www.ytj.fi/en/index/businessid.html",
+  lengths: [8] as const,
   examples: ["20774740"] as const,
   compact,
   format,

package/src/fi/ytunnus.ts

@@ -8,14 +8,17 @@
  * @see https://www.ytj.fi/en/index/businessid.html
  */
 
+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 = [7, 9, 10, 5, 8, 4, 2, 1];
 
 const compact = (value: string): string =>
@@ -59,7 +62,7 @@ const generate = (): string => {
 };
 
 /** Finnish Business ID. */
-const ytunnus: Validator = {
+const ytunnus: CountryValidator<"FI"> = {
   name: "Finnish Business ID",
   localName: "Y-tunnus",
   abbreviation: "Y-tunnus",
@@ -69,6 +72,7 @@ const ytunnus: Validator = {
     "FO-nummer",
   ] as const,
   candidatePattern: "\\d{7}-\\d",
+  scope: "country",
   country: "FI",
   entityType: "company",
   sourceUrl: "https://www.ytj.fi/en/index/businessid.html",

package/src/fr/nif.ts

@@ -8,13 +8,16 @@
  * @see https://www.impots.gouv.fr/
  */
 
+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, " -");
 
@@ -69,7 +72,7 @@ const generate = (): string => {
 };
 
 /** French Tax Identification Number. */
-const nif: Validator = {
+const nif: CountryValidator<"FR"> = {
   name: "French Tax ID",
   localName: "Numéro d'Identification Fiscale",
   abbreviation: "NIF",
@@ -79,6 +82,7 @@ const nif: Validator = {
     "numéro d'identification fiscale",
   ] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "FR",
   entityType: "person",
   sourceUrl: "https://www.impots.gouv.fr/",

package/src/fr/nir.ts

@@ -12,17 +12,17 @@
  * @see https://en.wikipedia.org/wiki/INSEE_code
  */
 
-import { clean } from "#util/clean";
-import { resolveTwoDigitYear } from "#util/date";
-import { randomInt } from "#util/generate";
-import { err } from "#util/result";
-
 import type {
   ParsedPersonId,
   ValidateResult,
-  Validator,
+  CountryValidator,
 } from "../types";
 
+import { clean } from "#util/clean";
+import { resolveTwoDigitYear } from "#util/date";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+
 const compact = (value: string): string =>
   clean(value, " -.");
 
@@ -165,7 +165,7 @@ const generate = (): string => {
 };
 
 /** French Social Security Number. */
-const nir: Validator = {
+const nir: CountryValidator<"FR", ParsedPersonId> = {
   name: "French Social Security Number",
   localName: "Numero d'Inscription au Repertoire",
   abbreviation: "NIR",
@@ -177,6 +177,7 @@ const nir: Validator = {
   ] as const,
   candidatePattern:
     "[12]\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\s?\\d{3}\\s?\\d{3}\\s?\\d{2}",
+  scope: "country",
   country: "FR",
   entityType: "person",
   description:
@@ -187,6 +188,7 @@ const nir: Validator = {
   examples: ["295117823456784"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/fr/siren.ts

@@ -8,6 +8,11 @@
  * @see https://www.insee.fr/fr/information/2549588
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -17,8 +22,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, " -.");
 
@@ -58,13 +61,14 @@ const generate = (): string => {
 };
 
 /** French Company Identification Number. */
-const siren: Validator = {
+const siren: CountryValidator<"FR"> = {
   name: "French Company ID",
   localName:
     "Système d'Identification du Répertoire des Entreprises",
   abbreviation: "SIREN",
   aliases: ["SIREN", "numéro SIREN"] as const,
   candidatePattern: "\\d{3}\\s?\\d{3}\\s?\\d{3}",
+  scope: "country",
   country: "FR",
   entityType: "company",
   sourceUrl: "https://www.insee.fr/fr/information/2549588",

package/src/fr/siret.ts

@@ -9,6 +9,11 @@
  * @see https://www.insee.fr/fr/information/2549588
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -18,8 +23,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, " -.");
 
@@ -101,13 +104,14 @@ const generate = (): string => {
 };
 
 /** French Establishment Identification Number. */
-const siret: Validator = {
+const siret: CountryValidator<"FR"> = {
   name: "French Establishment ID",
   localName:
     "Système d'Identification du Répertoire des Établissements",
   abbreviation: "SIRET",
   aliases: ["SIRET", "numéro SIRET"] as const,
   candidatePattern: "\\d{3}\\s?\\d{3}\\s?\\d{3}\\s?\\d{5}",
+  scope: "country",
   country: "FR",
   entityType: "company",
   sourceUrl: "https://www.insee.fr/fr/information/2549588",

package/src/fr/tva.ts

@@ -10,6 +10,11 @@
  * @see https://www.economie.gouv.fr/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import {
   luhnValidate,
   luhnChecksum,
@@ -19,8 +24,6 @@ import { randomDigits } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 const ALPHABET = "0123456789ABCDEFGHJKLMNPQRSTUVWXYZ";
 
 const compact = (value: string): string => {
@@ -122,7 +125,7 @@ const generate = (): string => {
 };
 
 /** French VAT Number. */
-const tva: Validator = {
+const tva: CountryValidator<"FR"> = {
   name: "French VAT Number",
   localName: "Numéro de TVA intracommunautaire",
   abbreviation: "TVA",
@@ -132,6 +135,7 @@ const tva: Validator = {
     "FR VAT",
   ] as const,
   candidatePattern: "FR[A-Z0-9]{2}\\d{9}",
+  scope: "country",
   country: "FR",
   entityType: "company",
   sourceUrl: "https://www.economie.gouv.fr/",

package/src/gb/nino.ts

@@ -1,21 +1,19 @@
+const NINO_VALID_FIRST = "ABCEGHJKLMNOPRSTWXYZ";
+const NINO_VALID_SECOND = "ABCEGHJKLMNPRSTWXYZ";
+const NINO_SUFFIXES = "ABCD";
+
 /** Generate a random valid UK NINO. */
 const generate = (): string => {
-  const validFirst = "ABCEGHJKLMNOPRSTWXYZ";
-  const validSecond = "ABCEGHJKLMNPRSTWXYZ";
-  const suffixes = "ABCD";
   let first: string;
   let second: string;
   let prefix: string;
   do {
-    first =
-      validFirst[randomInt(0, validFirst.length - 1)]!;
-    second =
-      validSecond[randomInt(0, validSecond.length - 1)]!;
+    first = randomChar(NINO_VALID_FIRST);
+    second = randomChar(NINO_VALID_SECOND);
     prefix = first + second;
   } while (INVALID_PREFIX.has(prefix));
   const digits = randomDigits(6);
-  const suffix =
-    suffixes[randomInt(0, suffixes.length - 1)]!;
+  const suffix = randomChar(NINO_SUFFIXES);
   return `${prefix}${digits}${suffix}`;
 };
 
@@ -30,12 +28,15 @@ const generate = (): string => {
  * @see https://www.gov.uk/hmrc-internal-manuals/national-insurance-manual/nim39110
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
+import { randomChar, randomDigits } from "#util/generate";
 import { err } from "#util/result";
 
-import type { ValidateResult, Validator } from "../types";
-
 const INVALID_FIRST = new Set([
   "D",
   "F",
@@ -85,7 +86,10 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
+  // SAFETY: regex above guarantees v.length === 9.
+  // eslint-disable-next-line no-non-null-assertion
   const first = v[0]!;
+  // eslint-disable-next-line no-non-null-assertion
   const second = v[1]!;
   const prefix = v.slice(0, 2);
 
@@ -123,7 +127,7 @@ const format = (value: string): string => {
 };
 
 /** UK National Insurance Number. */
-const nino: Validator = {
+const nino: CountryValidator<"GB"> = {
   name: "UK National Insurance Number",
   localName: "National Insurance Number",
   abbreviation: "NINO",
@@ -133,6 +137,7 @@ const nino: Validator = {
     "NI number",
   ] as const,
   candidatePattern: "[A-Z]{2}\\d{6}[A-Z]",
+  scope: "country",
   country: "GB",
   entityType: "person",
   description:

package/src/gb/sedol.ts

@@ -10,13 +10,16 @@
  * @see https://en.wikipedia.org/wiki/SEDOL
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
-import { randomInt } from "#util/generate";
+import { randomChar } from "#util/generate";
 import { err } from "#util/result";
 import { isdigits } from "#util/strings";
 
-import type { ValidateResult, Validator } from "../types";
-
 /**
  * Allowed characters in a SEDOL: digits and
  * consonants only (vowels are never used).
@@ -36,14 +39,14 @@ const calcCheckDigit = (number: string): string => {
     );
   }
   let sum = 0;
-  for (let i = 0; i < 6; i++) {
-    const ch = number[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    const ch = number[i];
+    if (ch === undefined) continue;
     const val = ALPHABET.indexOf(ch);
     if (val < 0) {
       throw new Error(`Invalid SEDOL character: ${ch}`);
     }
-    // SAFETY: weights length matches loop bound
-    sum += WEIGHTS[i]! * val;
+    sum += weight * val;
   }
   return String((10 - (sum % 10)) % 10);
 };
@@ -74,6 +77,8 @@ const validate = (value: string): ValidateResult => {
   // Old-style SEDOLs are fully numeric; new-style
   // SEDOLs start with a letter. A number that starts
   // with a digit but contains letters is invalid.
+  // SAFETY: v.length === 7 here.
+  // eslint-disable-next-line no-non-null-assertion
   if (isdigits(v[0]!) && !isdigits(v)) {
     return err(
       "INVALID_FORMAT",
@@ -94,20 +99,20 @@ const validate = (value: string): ValidateResult => {
 
 const format = (value: string): string => compact(value);
 
+const SEDOL_CONSONANTS = "BCDFGHJKLMNPQRSTVWXYZ";
+const SEDOL_CHARS = "0123456789BCDFGHJKLMNPQRSTVWXYZ";
+
 /** Generate a random valid SEDOL. */
 const generate = (): string => {
-  const consonants = "BCDFGHJKLMNPQRSTVWXYZ";
-  const chars = "0123456789BCDFGHJKLMNPQRSTVWXYZ";
-  const first =
-    consonants[randomInt(0, consonants.length - 1)]!;
-  let payload = first;
-  for (let i = 1; i < 6; i++)
-    payload += chars[randomInt(0, chars.length - 1)]!;
+  let payload = randomChar(SEDOL_CONSONANTS);
+  for (let i = 1; i < 6; i++) {
+    payload += randomChar(SEDOL_CHARS);
+  }
   return payload + calcCheckDigit(payload);
 };
 
 /** Stock Exchange Daily Official List number. */
-const sedol: Validator = {
+const sedol: CountryValidator<"GB"> = {
   name: "Stock Exchange Daily Official List number",
   localName: "Stock Exchange Daily Official List number",
   abbreviation: "SEDOL",
@@ -116,6 +121,7 @@ const sedol: Validator = {
     "Stock Exchange Daily Official List",
   ] as const,
   candidatePattern: "[B-DF-HJ-NP-TV-Z0-9]{6}\\d",
+  scope: "country",
   country: "GB",
   entityType: "any",
   sourceUrl: "https://en.wikipedia.org/wiki/SEDOL",

package/src/gb/utr.ts

@@ -8,14 +8,17 @@
  * @see https://www.gov.uk/find-utr-number
  */
 
+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, 7, 8, 9, 10, 5, 4, 3, 2] as const;
 const CHECK_LOOKUP = "21987654321";
 
@@ -61,12 +64,13 @@ const generate = (): string => {
 };
 
 /** UK Unique Taxpayer Reference. */
-const utr: Validator = {
+const utr: CountryValidator<"GB"> = {
   name: "UK Unique Taxpayer Reference",
   localName: "Unique Taxpayer Reference",
   abbreviation: "UTR",
   aliases: ["Unique Taxpayer Reference", "UTR"] as const,
   candidatePattern: "\\d{10}",
+  scope: "country",
   country: "GB",
   entityType: "any",
   sourceUrl: "https://www.gov.uk/find-utr-number",

package/src/gb/vat.ts

@@ -9,14 +9,17 @@
  * @see https://www.gov.uk/vat-registration
  */
 
+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 = [8, 7, 6, 5, 4, 3, 2] as const;
 
 const compact = (value: string): string => {
@@ -135,7 +138,7 @@ const generate = (): string => {
 };
 
 /** UK VAT Registration Number. */
-const vat: Validator = {
+const vat: CountryValidator<"GB"> = {
   name: "UK VAT Number",
   localName: "VAT Registration Number",
   abbreviation: "VAT",
@@ -144,6 +147,7 @@ const vat: Validator = {
     "VAT number",
   ] as const,
   candidatePattern: "GB\\d{9,12}",
+  scope: "country",
   country: "GB",
   entityType: "company",
   sourceUrl: "https://www.gov.uk/vat-registration",

package/src/ge/pin.ts

@@ -14,13 +14,16 @@ const generate = (): string => randomDigits(11);
  * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Georgia-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 =>
   clean(value, " -").trim();
 
@@ -47,12 +50,13 @@ const validate = (value: string): ValidateResult => {
 const format = (value: string): string => compact(value);
 
 /** Georgian Personal Identification Number. */
-const pin: Validator = {
+const pin: CountryValidator<"GE"> = {
   name: "Georgian Personal ID",
   localName: "პირადი ნომერი",
   abbreviation: "PIN",
   aliases: ["პირადი ნომერი", "PIN"] as const,
   candidatePattern: "\\d{11}",
+  scope: "country",
   country: "GE",
   entityType: "any",
   lengths: [9, 11] as const,

package/src/gh/tin.ts

@@ -14,12 +14,15 @@
  * @see https://gra.gov.gh/
  */
 
+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 type { ValidateResult, Validator } from "../types";
-
 const FORMAT_RE = /^[PCGQV]00[0-9]{7}[0-9X]$/;
 
 const compact = (value: string): string =>
@@ -65,11 +68,12 @@ const validate = (value: string): ValidateResult => {
 
 const format = (value: string): string => compact(value);
 
+const TIN_PREFIXES = ["P", "C", "G", "Q", "V"] as const;
+
 /** Generate a random valid Ghana TIN. */
 const generate = (): string => {
-  const prefixes = ["P", "C", "G", "Q", "V"] as const;
   for (;;) {
-    const p = prefixes[randomInt(0, 4)]!;
+    const p = randomPick(TIN_PREFIXES);
     const d = randomDigits(9);
     const partial = p + d;
     const c = partial + calcCheckDigit(partial);
@@ -78,12 +82,13 @@ const generate = (): string => {
 };
 
 /** Ghanaian Tax Identification Number. */
-const tin: Validator = {
+const tin: CountryValidator<"GH"> = {
   name: "Ghanaian Tax Identification Number",
   localName: "Tax Identification Number",
   abbreviation: "TIN",
   aliases: ["TIN", "Tax Identification Number"] as const,
   candidatePattern: "[A-Z]\\d{9,10}",
+  scope: "country",
   country: "GH",
   entityType: "any",
   compact,