@stll/stdnum 0.0.1 → 2.0.0

package/src/sg/uen.ts

@@ -14,13 +14,16 @@
  * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Singapore-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";
-
 /** Check letter alphabet for "Other" format. */
 const OTHER_ALPHA = "ABCDEFGHJKLMNPQRSTUVWX0123456789";
 
@@ -72,6 +75,9 @@ const compact = (value: string): string =>
  * Validate Business (ROB) UEN (9 chars):
  * 8 digits + 1 check letter.
  */
+const BUSINESS_WEIGHTS = [10, 4, 9, 3, 8, 2, 7, 1] as const;
+const BUSINESS_CHECK_ALPHA = "XMKECAWLJDB";
+
 const validateBusiness = (v: string): ValidateResult => {
   if (!isdigits(v.slice(0, 8))) {
     return err(
@@ -79,6 +85,9 @@ const validateBusiness = (v: string): ValidateResult => {
       "Business UEN must start with 8 digits",
     );
   }
+  // SAFETY: caller routes to this only when
+  // v.length === 9.
+  // eslint-disable-next-line no-non-null-assertion
   if (!/^[A-Z]$/.test(v[8]!)) {
     return err(
       "INVALID_FORMAT",
@@ -86,13 +95,11 @@ const validateBusiness = (v: string): ValidateResult => {
     );
   }
 
-  const weights = [10, 4, 9, 3, 8, 2, 7, 1];
-  const checkAlpha = "XMKECAWLJDB";
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += Number(v[i]) * weights[i]!;
+  for (const [i, weight] of BUSINESS_WEIGHTS.entries()) {
+    sum += Number(v[i]) * weight;
   }
-  const expected = checkAlpha[sum % 11];
+  const expected = BUSINESS_CHECK_ALPHA[sum % 11];
   if (v[8] !== expected) {
     return err(
       "INVALID_CHECKSUM",
@@ -106,6 +113,9 @@ const validateBusiness = (v: string): ValidateResult => {
  * Validate Local Company (ROC) UEN (10 chars):
  * 9 digits (year prefix) + 1 check letter.
  */
+const LOCAL_WEIGHTS = [10, 8, 6, 4, 9, 7, 5, 3, 1] as const;
+const LOCAL_CHECK_ALPHA = "ZKCMDNERGWH";
+
 const validateLocalCompany = (
   v: string,
 ): ValidateResult => {
@@ -115,6 +125,9 @@ const validateLocalCompany = (
       "Company UEN must have 9 digits",
     );
   }
+  // SAFETY: caller routes to this only when
+  // v.length === 10.
+  // eslint-disable-next-line no-non-null-assertion
   if (!/^[A-Z]$/.test(v[9]!)) {
     return err(
       "INVALID_FORMAT",
@@ -122,13 +135,11 @@ const validateLocalCompany = (
     );
   }
 
-  const weights = [10, 8, 6, 4, 9, 7, 5, 3, 1];
-  const checkAlpha = "ZKCMDNERGWH";
   let sum = 0;
-  for (let i = 0; i < 9; i++) {
-    sum += Number(v[i]) * weights[i]!;
+  for (const [i, weight] of LOCAL_WEIGHTS.entries()) {
+    sum += Number(v[i]) * weight;
   }
-  const expected = checkAlpha[sum % 11];
+  const expected = LOCAL_CHECK_ALPHA[sum % 11];
   if (v[9] !== expected) {
     return err(
       "INVALID_CHECKSUM",
@@ -143,7 +154,12 @@ const validateLocalCompany = (
  * R/S/T + 2 digits + 2-letter type + 4 digits
  * + 1 check letter.
  */
+const OTHER_WEIGHTS = [4, 3, 5, 3, 10, 2, 2, 5, 7] as const;
+
 const validateOther = (v: string): ValidateResult => {
+  // SAFETY: caller routes to this only when
+  // v.length === 10.
+  // eslint-disable-next-line no-non-null-assertion
   const prefix = v[0]!;
   if (prefix !== "R" && prefix !== "S" && prefix !== "T") {
     return err(
@@ -171,17 +187,18 @@ const validateOther = (v: string): ValidateResult => {
     );
   }
 
-  const weights = [4, 3, 5, 3, 10, 2, 2, 5, 7];
   let sum = 0;
-  for (let i = 0; i < 9; i++) {
-    const idx = OTHER_ALPHA.indexOf(v[i]!);
+  for (const [i, weight] of OTHER_WEIGHTS.entries()) {
+    const ch = v[i];
+    if (ch === undefined) continue;
+    const idx = OTHER_ALPHA.indexOf(ch);
     if (idx === -1) {
       return err(
         "INVALID_FORMAT",
-        `Unexpected character at position ${i + 1}: ${v[i]}`,
+        `Unexpected character at position ${i + 1}: ${ch}`,
       );
     }
-    sum += idx * weights[i]!;
+    sum += idx * weight;
   }
   const expected =
     OTHER_ALPHA[(((sum - 5) % 11) + 11) % 11];
@@ -218,6 +235,8 @@ const validate = (value: string): ValidateResult => {
 
   // 10 chars: first char digit => local company,
   // otherwise "other" entity
+  // SAFETY: v.length === 10 here.
+  // eslint-disable-next-line no-non-null-assertion
   if (isdigits(v[0]!)) {
     return validateLocalCompany(v);
   }
@@ -228,24 +247,26 @@ const format = (value: string): string => compact(value);
 
 /** Generate a random valid Singapore UEN (business format). */
 const generate = (): string => {
-  const weights = [10, 4, 9, 3, 8, 2, 7, 1];
-  const checkAlpha = "XMKECAWLJDB";
   const body = randomDigits(8);
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += Number(body[i]) * weights[i]!;
+  for (const [i, weight] of BUSINESS_WEIGHTS.entries()) {
+    sum += Number(body[i]) * weight;
   }
-  const check = checkAlpha[sum % 11]!;
+  // SAFETY: sum % 11 is in 0..10 and BUSINESS_CHECK_ALPHA
+  // has 11 characters.
+  // eslint-disable-next-line no-non-null-assertion
+  const check = BUSINESS_CHECK_ALPHA[sum % 11]!;
   return body + check;
 };
 
 /** Singapore Unique Entity Number. */
-const uen: Validator = {
+const uen: CountryValidator<"SG"> = {
   name: "Singapore Unique Entity Number",
   localName: "Unique Entity Number",
   abbreviation: "UEN",
   aliases: ["UEN", "Unique Entity Number"] as const,
   candidatePattern: "[\\dSTR]\\d{7}[A-Z]",
+  scope: "country",
   country: "SG",
   entityType: "company",
   description:

package/src/si/emso.ts

@@ -5,10 +5,22 @@
  * encoding DDMMYYY (7-digit birth year), region code,
  * serial number, and a check digit.
  *
- * @see https://en.wikipedia.org/wiki/Unique_Master_Citizen_Number
- * @see https://www.gov.si/
+ * Canonical source:
+ * - Slovenia government registry overview
+ *
+ * This is the source behind the stricter register
+ * code check (50-59) and the decision to reject
+ * future birth dates in the embedded date field.
+ *
+ * @see https://www.gov.si/teme/registri-in-evidence-prebivalstva/
  */
 
+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 = [
   7, 6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2,
 ] as const;
@@ -75,6 +81,23 @@ const validate = (value: string): ValidateResult => {
       "EMŠO contains an invalid date",
     );
   }
+  const birthDate = new Date(yyyy, mm - 1, dd);
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  if (birthDate > today) {
+    return err(
+      "INVALID_COMPONENT",
+      "EMŠO cannot contain a future birth date",
+    );
+  }
+
+  const register = Number(v.slice(7, 9));
+  if (register < 50 || register > 59) {
+    return err(
+      "INVALID_COMPONENT",
+      "EMSO register code must be between 50 and 59",
+    );
+  }
 
   if (calcCheckDigit(v) !== Number(v[12])) {
     return err(
@@ -120,7 +143,7 @@ const generate = (): string => {
     const dd = String(randomInt(1, 28)).padStart(2, "0");
     const mm = String(randomInt(1, 12)).padStart(2, "0");
     const yyy = String(randomInt(900, 999));
-    const rr = String(randomInt(50, 99));
+    const rr = String(randomInt(50, 59));
     const sss = String(randomInt(0, 999)).padStart(3, "0");
     const partial = dd + mm + yyy + rr + sss;
     const c = partial + String(calcCheckDigit(partial));
@@ -129,7 +152,7 @@ const generate = (): string => {
 };
 
 /** Slovenian Unique Master Citizen Number. */
-const emso: Validator = {
+const emso: CountryValidator<"SI", ParsedPersonId> = {
   name: "Slovenian Personal ID",
   localName: "Enotna matična številka občana",
   abbreviation: "EMŠO",
@@ -138,12 +161,15 @@ const emso: Validator = {
     "enotna matična številka občana",
   ] as const,
   candidatePattern: "\\d{13}",
+  scope: "country",
   country: "SI",
   entityType: "person",
-  sourceUrl: "https://www.gov.si/",
+  sourceUrl:
+    "https://www.gov.si/teme/registri-in-evidence-prebivalstva/",
   examples: ["0101006500006"] as const,
   compact,
   format,
+  parse,
   validate,
   generate,
 };

package/src/si/vat.ts

@@ -10,14 +10,17 @@
  * @see https://spot.gov.si/en/info/taxes/value-added-tax-vat
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { weightedSum } from "#checksums/weighted-sum";
 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 = [8, 7, 6, 5, 4, 3, 2];
 
 const compact = (value: string): string => {
@@ -85,7 +88,7 @@ const generate = (): string => {
 };
 
 /** Slovenian VAT Number. */
-const vat: Validator = {
+const vat: CountryValidator<"SI"> = {
   name: "Slovenian VAT Number",
   localName: "Davčna številka",
   abbreviation: "DDV",
@@ -94,9 +97,11 @@ const vat: Validator = {
     "identifikacijska številka za DDV",
   ] as const,
   candidatePattern: "SI\\d{8}",
+  scope: "country",
   country: "SI",
   entityType: "company",
   sourceUrl: "https://www.fu.gov.si/",
+  lengths: [8] as const,
   examples: ["15012557"] as const,
   compact,
   format,

package/src/sk/dic.ts

@@ -9,14 +9,17 @@
  * @see https://www.financnasprava.sk/
  */
 
+import { validate as validateRc } from "../cz/rc";
+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 { validate as validateRc } from "../cz/rc";
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string => {
   const v = clean(value, " -");
   if (v.startsWith("SK") || v.startsWith("sk")) {
@@ -85,13 +88,14 @@ const generate = (): string => {
 };
 
 /** Slovak VAT Number. */
-const dic: Validator = {
+const dic: CountryValidator<"SK"> = {
   name: "Slovak VAT Number",
   localName:
     "Identifikačné číslo pre daň z pridanej hodnoty",
   abbreviation: "IČ DPH",
   aliases: ["DIČ", "daňové identifikačné číslo"] as const,
   candidatePattern: "SK\\d{10}",
+  scope: "country",
   country: "SK",
   entityType: "company",
   sourceUrl: "https://www.financnasprava.sk/",

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

@@ -8,24 +8,37 @@
  * @see https://www.minv.sk/
  */
 
-import { compact, format, parse, validate } from "../cz/rc";
-import type { Validator } from "../types";
+import {
+  compact,
+  format,
+  generate,
+  parse,
+  validate,
+} from "../cz/rc";
+import type {
+  ParsedPersonId,
+  CountryValidator,
+} from "../types";
 
 /** Slovak Birth Number. */
-const rc: Validator = {
+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/",
+  lengths: [9, 10] as const,
   examples: ["7103192745"] as const,
   compact,
   format,
+  generate,
+  parse,
   validate,
 };
 
 export default rc;
-export { compact, format, parse, validate };
+export { compact, format, generate, parse, validate };

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. */
@@ -48,8 +51,8 @@ const validate = (value: string): ValidateResult => {
   }
 
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += digitSum(Number(v[i]) * WEIGHTS[i]!);
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += digitSum(Number(v[i]) * weight);
   }
 
   const checksum = sum % 10;
@@ -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

@@ -116,24 +116,47 @@ export type ValidateResult =
   | { valid: false; error: StdnumError };
 
 /**
- * Structured data extracted from a personal ID number.
- * Returned by `parse()` on validators that encode
- * birth date and gender.
+ * Structured data extracted from an identifier that
+ * encodes a birth date.
  */
-export type ParsedPersonId = {
+export type ParsedBirthDate = {
   birthDate: Date;
+};
+
+/**
+ * Structured data extracted from a personal ID number
+ * that also encodes gender.
+ */
+export type ParsedPersonId = ParsedBirthDate & {
   gender: "male" | "female";
 };
 
-export type Validator = {
+export type ParsedIdentifier =
+  | ParsedBirthDate
+  | ParsedPersonId;
+
+/**
+ * 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. */
   name: string;
   /** Name in the local language. */
   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";
 
@@ -197,4 +220,43 @@ export type Validator = {
    * passed to validate() for confirmation.
    */
   candidatePattern?: string;
+
+  /**
+   * Extract structured data (e.g. birth date,
+   * gender) from a known-valid identifier.
+   * Available on personal IDs that encode such
+   * data. Returns null if the input cannot be
+   * parsed.
+   *
+   * On the base `Validator` type this is optional
+   * with a widened return; narrow it by typing the
+   * validator as `Validator<ParsedPersonId>` etc.
+   */
+  parse?: (value: string) => ParsedIdentifier | null;
+} & ([TParsed] extends [undefined]
+  ? 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>;