@stll/stdnum 0.0.1

package/src/_checksums/luhn.ts

@@ -0,0 +1,24 @@
+/**
+ * Luhn checksum algorithm (ISO/IEC 7812-1).
+ * Used by credit cards, IMEI, Canadian SIN, etc.
+ */
+
+/** Compute the Luhn checksum of a digit string. */
+export const luhnChecksum = (value: string): number => {
+  let sum = 0;
+  let double = false;
+  for (let i = value.length - 1; i >= 0; i--) {
+    let d = Number(value[i]);
+    if (double) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    double = !double;
+  }
+  return sum % 10;
+};
+
+/** Validate a digit string using Luhn. */
+export const luhnValidate = (value: string): boolean =>
+  luhnChecksum(value) === 0;

package/src/_checksums/mod1110.ts

@@ -0,0 +1,24 @@
+/**
+ * ISO 7064 Mod 11,10 check digit algorithm.
+ * Used by DE VAT, DE IdNr, HR OIB.
+ */
+
+/** Compute the Mod 11,10 check digit for a payload. */
+export const mod1110checkDigit = (
+  payload: string,
+): number => {
+  let product = 10;
+  for (let i = 0; i < payload.length; i++) {
+    let sum = (Number(payload[i]) + product) % 10;
+    if (sum === 0) sum = 10;
+    product = (sum * 2) % 11;
+  }
+  return (11 - product) % 10;
+};
+
+/** Validate a string with a Mod 11,10 check digit. */
+export const mod1110validate = (value: string): boolean => {
+  const payload = value.slice(0, -1);
+  const check = Number(value[value.length - 1]);
+  return mod1110checkDigit(payload) === check;
+};

package/src/_checksums/mod112.ts

@@ -0,0 +1,40 @@
+/**
+ * ISO 7064 Mod 11,2 check character algorithm.
+ * Used by CN RIC (Resident Identity Card).
+ *
+ * Weights are powers of 2 modulo 11
+ * (2^17 mod 11 ... 2^1 mod 11), applied
+ * left-to-right across the 17-character payload.
+ * The check character is looked up from
+ * "10X98765432".
+ */
+
+const WEIGHTS = [
+  7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2,
+] as const;
+
+const CHECK_CHARS = "10X98765432";
+
+/**
+ * Compute the ISO 7064 Mod 11,2 check character
+ * for a 17-character payload.
+ */
+export const mod112checkChar = (
+  payload: string,
+): string => {
+  let sum = 0;
+  for (let i = 0; i < 17; i++) {
+    sum += Number(payload[i]) * WEIGHTS[i]!;
+  }
+  return CHECK_CHARS[sum % 11]!;
+};
+
+/**
+ * Validate an 18-character string with a Mod 11,2
+ * check character (last char is 0-9 or X).
+ */
+export const mod112validate = (value: string): boolean => {
+  const payload = value.slice(0, 17);
+  const check = value[17]!.toUpperCase();
+  return mod112checkChar(payload) === check;
+};

package/src/_checksums/mod97.ts

@@ -0,0 +1,28 @@
+/**
+ * ISO 7064 Mod 97-10 checksum.
+ * Used by IBAN and LEI.
+ *
+ * Processes one digit at a time to avoid BigInt.
+ */
+
+/**
+ * Compute mod 97 of a numeric string.
+ * Letters must already be converted to digits.
+ */
+export const mod97 = (value: string): number => {
+  let remainder = 0;
+  for (let i = 0; i < value.length; i++) {
+    remainder = (remainder * 10 + Number(value[i])) % 97;
+  }
+  return remainder;
+};
+
+/**
+ * Validate a string using ISO 7064 Mod 97-10.
+ * The remainder must equal 1.
+ *
+ * @param value - Numeric string (letters already
+ *   converted via charValue)
+ */
+export const mod97validate = (value: string): boolean =>
+  mod97(value) === 1;

package/src/_checksums/verhoeff.ts

@@ -0,0 +1,71 @@
+/**
+ * Verhoeff checksum algorithm.
+ *
+ * Uses three tables (d, p, inv) to detect all
+ * single-digit and adjacent-transposition errors.
+ * Used by Indian Aadhaar numbers.
+ *
+ * @see https://en.wikipedia.org/wiki/Verhoeff_algorithm
+ */
+
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+
+// Dihedral group D5 multiplication table
+const D: readonly (readonly number[])[] = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+  [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+  [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+  [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
+  [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+  [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
+  [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+  [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+  [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+];
+
+// Permutation table
+const P: readonly (readonly number[])[] = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+  [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+  [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+  [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
+  [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+  [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
+  [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+];
+
+// Inverse table
+const INV = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9] as const;
+
+/** Compute the Verhoeff checksum of a digit string. */
+export const verhoeffChecksum = (value: string): number => {
+  let c = 0;
+  for (let i = value.length - 1; i >= 0; i--) {
+    const pos = (value.length - 1 - i) % 8;
+    const digit = Number(value[i]);
+    c = D[c]![P[pos]![digit]!]!;
+  }
+  return c;
+};
+
+/** Validate a digit string using Verhoeff. */
+export const verhoeffValidate = (value: string): boolean =>
+  verhoeffChecksum(value) === 0;
+
+/**
+ * Calculate the Verhoeff check digit for a
+ * digit string (without the check digit).
+ */
+export const verhoeffCheckDigit = (
+  value: string,
+): number => {
+  let c = 0;
+  for (let i = value.length - 1; i >= 0; i--) {
+    const pos = (value.length - i) % 8;
+    const digit = Number(value[i]);
+    c = D[c]![P[pos]![digit]!]!;
+  }
+  return INV[c]!;
+};

package/src/_checksums/weighted-sum.ts

@@ -0,0 +1,23 @@
+/**
+ * Compute a weighted sum of digits.
+ *
+ * @param value - String of digits
+ * @param weights - Array of weights (cycled if
+ *   shorter than value)
+ * @param modulus - Modulus for the result
+ */
+export const weightedSum = (
+  value: string,
+  weights: readonly number[],
+  modulus: number,
+): number => {
+  let sum = 0;
+  for (let i = 0; i < value.length; i++) {
+    const digit = Number(value[i]);
+    // SAFETY: modulo guarantees valid index
+    // eslint-disable-next-line no-non-null-assertion
+    const weight = weights[i % weights.length]!;
+    sum += digit * weight;
+  }
+  return ((sum % modulus) + modulus) % modulus;
+};

package/src/_util/arabic.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared Arabic-Indic and Extended Arabic-Indic digit
+ * normalization utilities.
+ *
+ * Arabic-Indic (U+0660..U+0669) and Extended Arabic-Indic
+ * (U+06F0..U+06F9, used for Persian/Dari) digits are
+ * mapped to ASCII 0-9.
+ */
+
+export const ARABIC_DIGITS: Record<string, string> = {
+  "\u0660": "0", // ٠
+  "\u0661": "1", // ١
+  "\u0662": "2", // ٢
+  "\u0663": "3", // ٣
+  "\u0664": "4", // ٤
+  "\u0665": "5", // ٥
+  "\u0666": "6", // ٦
+  "\u0667": "7", // ٧
+  "\u0668": "8", // ٨
+  "\u0669": "9", // ٩
+  "\u06F0": "0", // ۰
+  "\u06F1": "1", // ۱
+  "\u06F2": "2", // ۲
+  "\u06F3": "3", // ۳
+  "\u06F4": "4", // ۴
+  "\u06F5": "5", // ۵
+  "\u06F6": "6", // ۶
+  "\u06F7": "7", // ۷
+  "\u06F8": "8", // ۸
+  "\u06F9": "9", // ۹
+};
+
+export const ARABIC_REGEX = new RegExp(
+  `[${Object.keys(ARABIC_DIGITS).join("")}]`,
+  "g",
+);
+
+/**
+ * Replace Arabic-Indic and Extended Arabic-Indic digits
+ * with their ASCII equivalents.
+ */
+export const normalizeArabicDigits = (
+  value: string,
+): string =>
+  value.replace(
+    ARABIC_REGEX,
+    (ch) => ARABIC_DIGITS[ch] ?? ch,
+  );

package/src/_util/clean.ts

@@ -0,0 +1,86 @@
+/**
+ * Unicode normalization map for common OCR, PDF
+ * extraction, and copy-paste artifacts.
+ *
+ * Maps fullwidth digits, various dashes, dots,
+ * spaces, and quotes to their ASCII equivalents.
+ * Ported from python-stdnum's util.py _char_map.
+ */
+const CHAR_MAP: Record<string, string> = {
+  // Fullwidth digits
+  "\uFF10": "0",
+  "\uFF11": "1",
+  "\uFF12": "2",
+  "\uFF13": "3",
+  "\uFF14": "4",
+  "\uFF15": "5",
+  "\uFF16": "6",
+  "\uFF17": "7",
+  "\uFF18": "8",
+  "\uFF19": "9",
+  // Dashes and hyphens
+  "\u2010": "-", // hyphen
+  "\u2011": "-", // non-breaking hyphen
+  "\u2012": "-", // figure dash
+  "\u2013": "-", // en dash
+  "\u2014": "-", // em dash
+  "\u2015": "-", // horizontal bar
+  "\u2212": "-", // minus sign
+  "\uFE58": "-", // small em dash
+  "\uFE63": "-", // small hyphen-minus
+  "\uFF0D": "-", // fullwidth hyphen-minus
+  // Dots and periods
+  "\u2024": ".", // one dot leader
+  "\uFE52": ".", // small full stop
+  "\uFF0E": ".", // fullwidth full stop
+  // Spaces
+  "\u00A0": " ", // non-breaking space
+  "\u2000": " ", // en quad
+  "\u2001": " ", // em quad
+  "\u2002": " ", // en space
+  "\u2003": " ", // em space
+  "\u2004": " ", // three-per-em space
+  "\u2005": " ", // four-per-em space
+  "\u2006": " ", // six-per-em space
+  "\u2007": " ", // figure space
+  "\u2008": " ", // punctuation space
+  "\u2009": " ", // thin space
+  "\u200A": " ", // hair space
+  "\u200B": "", // zero-width space (remove)
+  "\u202F": " ", // narrow no-break space
+  "\u205F": " ", // medium mathematical space
+  "\u3000": " ", // ideographic space
+  "\uFEFF": "", // BOM / zero-width no-break
+  // Slashes
+  "\uFF0F": "/", // fullwidth solidus
+  "\u2044": "/", // fraction slash
+};
+
+const CHAR_REGEX = new RegExp(
+  `[${Object.keys(CHAR_MAP).join("")}]`,
+  "g",
+);
+
+/**
+ * Normalize Unicode artifacts to ASCII
+ * equivalents and strip the given characters.
+ *
+ * @param value - The input string
+ * @param strip - Characters to remove
+ *   (e.g. " -/" to strip spaces, dashes, slashes)
+ */
+export const clean = (
+  value: string,
+  strip: string = "",
+): string => {
+  let result = value.replace(
+    CHAR_REGEX,
+    (ch) => CHAR_MAP[ch] ?? ch,
+  );
+  if (strip) {
+    for (const ch of strip) {
+      result = result.replaceAll(ch, "");
+    }
+  }
+  return result;
+};

package/src/_util/date.ts

@@ -0,0 +1,23 @@
+/** Validate a calendar date via Date round-trip. */
+export const isValidDate = (
+  year: number,
+  month: number,
+  day: number,
+): boolean => {
+  const d = new Date(year, month - 1, day);
+  return (
+    d.getFullYear() === year &&
+    d.getMonth() === month - 1 &&
+    d.getDate() === day
+  );
+};
+
+/**
+ * Resolve a 2-digit year to a 4-digit year using a
+ * rolling pivot: years after the current year are
+ * assumed to be in the previous century.
+ */
+export const resolveTwoDigitYear = (yy: number): number => {
+  const y = 2000 + yy;
+  return y > new Date().getFullYear() ? y - 100 : y;
+};

package/src/_util/generate.ts

@@ -0,0 +1,24 @@
+/**
+ * Helpers for generating random valid identifiers.
+ * NOT cryptographically secure; use only for
+ * testing, demos, and form placeholders.
+ */
+
+/** Generate a string of n random decimal digits. */
+export const randomDigits = (n: number): string => {
+  let result = "";
+  for (let i = 0; i < n; i++) {
+    result += String(Math.floor(Math.random() * 10));
+  }
+  return result;
+};
+
+/**
+ * Generate a random integer in [min, max]
+ * (inclusive).
+ */
+export const randomInt = (
+  min: number,
+  max: number,
+): number =>
+  min + Math.floor(Math.random() * (max - min + 1));

package/src/_util/result.ts

@@ -0,0 +1,10 @@
+import type { StdnumError, ValidateResult } from "../types";
+
+/** Create an error ValidateResult. */
+export const err = (
+  code: StdnumError["code"],
+  message: string,
+): ValidateResult => ({
+  valid: false,
+  error: { code, message },
+});

package/src/_util/strings.ts

@@ -0,0 +1,32 @@
+/** Check if the string contains only digits. */
+export const isdigits = (value: string): boolean =>
+  value.length > 0 && /^\d+$/.test(value);
+
+/**
+ * Check if the string contains only ASCII
+ * letters (a-z, A-Z).
+ */
+export const isalpha = (value: string): boolean =>
+  value.length > 0 && /^[a-zA-Z]+$/.test(value);
+
+/**
+ * Check if the string contains only ASCII
+ * letters and digits.
+ */
+export const isalnum = (value: string): boolean =>
+  value.length > 0 && /^[a-zA-Z0-9]+$/.test(value);
+
+/**
+ * Convert a single character to its numeric
+ * value (0-9 for digits, 10-35 for A-Z).
+ */
+export const charValue = (ch: string): number => {
+  const code = ch.charCodeAt(0);
+  // 0-9
+  if (code >= 48 && code <= 57) return code - 48;
+  // A-Z
+  if (code >= 65 && code <= 90) return code - 55;
+  // a-z
+  if (code >= 97 && code <= 122) return code - 87;
+  return 0;
+};

package/src/ad/mod.ts

@@ -0,0 +1 @@
+export { default as nrt } from "./nrt";

package/src/ad/nrt.ts

@@ -0,0 +1,111 @@
+/** Generate a random valid Andorra NRT. */
+const generate = (): string => {
+  const prefixes = "CDEGOPU";
+  const prefix =
+    prefixes[randomInt(0, prefixes.length - 1)]!;
+  const digits = randomDigits(6);
+  const suffix = String.fromCodePoint(
+    65 + randomInt(0, 25),
+  );
+  return `${prefix}${digits}${suffix}`;
+};
+
+/**
+ * NRT (Número de Registre Tributari, Andorra tax number).
+ *
+ * The NRT identifies legal and natural entities for tax
+ * purposes. It consists of one letter indicating entity
+ * type, six digits, and a check letter.
+ *
+ * Entity type prefixes:
+ *   F      — companies (digits <= 699999)
+ *   A, L   — other entities (digits 700000-799999)
+ *   C, D, E, G, O, P, U — other types
+ *
+ * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Andorra-TIN.pdf
+ */
+
+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 VALID_PREFIXES = "ACDEFGLOPU";
+
+const compact = (value: string): string =>
+  clean(value, " -.").toUpperCase().trim();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 8) {
+    return err(
+      "INVALID_LENGTH",
+      "Andorra NRT must be 8 characters",
+    );
+  }
+  const prefix = v[0]!;
+  const tail = v[7]!;
+  const digits = v.slice(1, 7);
+  if (!/^[A-Z]$/.test(prefix) || !/^[A-Z]$/.test(tail)) {
+    return err(
+      "INVALID_FORMAT",
+      "Andorra NRT must start and end with a letter",
+    );
+  }
+  if (!isdigits(digits)) {
+    return err(
+      "INVALID_FORMAT",
+      "Andorra NRT must have 6 digits in the middle",
+    );
+  }
+  if (!VALID_PREFIXES.includes(prefix)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Andorra NRT has an invalid entity type prefix",
+    );
+  }
+  if (prefix === "F" && digits > "699999") {
+    return err(
+      "INVALID_COMPONENT",
+      "Andorra NRT F-type digits must be <= 699999",
+    );
+  }
+  if (
+    (prefix === "A" || prefix === "L") &&
+    !("699999" < digits && digits < "800000")
+  ) {
+    return err(
+      "INVALID_COMPONENT",
+      "Andorra NRT A/L-type digits must be 700000-799999",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v[0]}-${v.slice(1, 7)}-${v[7]}`;
+};
+
+/** Andorra NRT (Número de Registre Tributari). */
+const nrt: Validator = {
+  name: "Andorra Tax Number",
+  localName: "Número de Registre Tributari",
+  abbreviation: "NRT",
+  aliases: ["NRT", "Número de Registre Tributari"] as const,
+  candidatePattern: "[A-Z]-?\\d{6}-?[A-Z]",
+  country: "AD",
+  entityType: "any",
+  sourceUrl:
+    "https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Andorra-TIN.pdf",
+  examples: ["U132950X", "D059888N", "F123456M"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nrt;
+export { compact, format, validate, generate };

package/src/ae/eid.ts

@@ -0,0 +1,106 @@
+/**
+ * Emirates ID (رقم الهوية, UAE).
+ *
+ * 15 digits: 784-YYYY-NNNNNNN-C where 784 is the
+ * ISO 3166-1 numeric code for the UAE, YYYY is the
+ * year of birth, NNNNNNN is a serial number, and C
+ * is a Luhn check digit.
+ *
+ * @see https://en.wikipedia.org/wiki/National_identification_number#United_Arab_Emirates
+ * @see https://u.ae/en/information-and-services/visa-and-emirates-id/emirates-id
+ */
+
+import {
+  luhnChecksum,
+  luhnValidate,
+} from "#checksums/luhn";
+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, " -/");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 15) {
+    return err(
+      "INVALID_LENGTH",
+      "Emirates ID must be 15 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Emirates ID must contain only digits",
+    );
+  }
+  if (!v.startsWith("784")) {
+    return err(
+      "INVALID_COMPONENT",
+      "Emirates ID must start with 784",
+    );
+  }
+  if (!luhnValidate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Emirates ID Luhn check digit is invalid",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return [
+    v.slice(0, 3),
+    v.slice(3, 7),
+    v.slice(7, 14),
+    v.slice(14),
+  ].join("-");
+};
+
+/**
+ * Generate a random valid Emirates ID in compact
+ * form. NOT cryptographically secure.
+ */
+const generate = (): string => {
+  const yyyy = String(randomInt(1950, 2010));
+  const serial = randomDigits(7);
+  const partial = `784${yyyy}${serial}0`;
+  const remainder = luhnChecksum(partial);
+  const check = (10 - remainder) % 10;
+  return `784${yyyy}${serial}${String(check)}`;
+};
+
+/** UAE Emirates ID. */
+const eid: Validator = {
+  name: "Emirates ID",
+  localName: "رقم الهوية",
+  abbreviation: "EID",
+  aliases: ["EID", "Emirates ID", "رقم الهوية"] as const,
+  candidatePattern: "784-\\d{4}-\\d{7}-\\d",
+  country: "AE",
+  entityType: "person",
+  lengths: [15],
+  examples: [
+    "784198012345678",
+    "784197912345671",
+    "784195204640486",
+    "784196865703050",
+  ] as const,
+  description:
+    "15-digit identity number issued to UAE residents",
+  sourceUrl:
+    "https://u.ae/en/information-and-services/visa-and-emirates-id/emirates-id",
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default eid;
+export { compact, format, generate, validate };

package/src/ae/mod.ts

@@ -0,0 +1 @@
+export { default as eid } from "./eid";

package/src/ai/mod.ts

@@ -0,0 +1 @@
+export { default as tin } from "./tin";