@stll/stdnum 0.0.1

package/src/es/nie.ts

@@ -0,0 +1,102 @@
+/**
+ * NIE (Número de Identidad de Extranjero).
+ *
+ * Spanish foreigner identification number. Starts
+ * with X, Y, or Z, followed by 7 digits and a check
+ * letter computed using the DNI algorithm.
+ *
+ * @see https://www.interior.gob.es/opencms/es/servicios-al-ciudadano/tramites-y-gestiones/nie/
+ */
+
+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";
+import { CHECK_LETTERS } from "./dni";
+
+const PREFIX_MAP: Record<string, string> = {
+  X: "0",
+  Y: "1",
+  Z: "2",
+};
+
+const compact = (value: string): string =>
+  clean(value, " -").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "NIE must be 9 characters",
+    );
+  }
+
+  const prefix = v.charAt(0);
+  const replacement = PREFIX_MAP[prefix];
+  if (replacement === undefined) {
+    return err(
+      "INVALID_FORMAT",
+      "NIE must start with X, Y, or Z",
+    );
+  }
+
+  const digits = v.slice(1, 8);
+  if (!isdigits(digits)) {
+    return err(
+      "INVALID_FORMAT",
+      "NIE must have 7 digits after prefix",
+    );
+  }
+
+  const letter = v.charAt(8);
+  const num = Number(replacement + digits);
+  const expected = CHECK_LETTERS.charAt(num % 23);
+  if (letter !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "NIE check letter does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Spanish NIE. */
+const generate = (): string => {
+  const prefixes = ["X", "Y", "Z"] as const;
+  const vals: Record<string, number> = { X: 0, Y: 1, Z: 2 };
+  const prefix = prefixes[randomInt(0, 2)]!;
+  const digits = randomDigits(7);
+  const num = vals[prefix]! * 10000000 + Number(digits);
+  return prefix + digits + CHECK_LETTERS.charAt(num % 23);
+};
+
+/** Spanish Foreigner Identification Number. */
+const nie: Validator = {
+  name: "Spanish Foreigner ID",
+  localName: "Número de Identidad de Extranjero",
+  abbreviation: "NIE",
+  aliases: [
+    "N.I.E.",
+    "NIE",
+    "número de identidad de extranjero",
+  ] as const,
+  candidatePattern: "[XYZ]-?\\d{7}-?[A-Z]",
+  country: "ES",
+  entityType: "person",
+  sourceUrl:
+    "https://www.interior.gob.es/opencms/es/servicios-al-ciudadano/tramites-y-gestiones/nie/",
+  examples: ["X5253868R"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nie;
+export { compact, format, validate, generate };

package/src/es/nss.ts

@@ -0,0 +1,109 @@
+/**
+ * NSS (Número de la Seguridad Social).
+ *
+ * Spanish Social Security Number. 12 digits:
+ * 2-digit province code (01–52) + 8-digit affiliate
+ * number + 2-digit check digits.
+ *
+ * Check digits are computed as:
+ *   if affiliate < 10_000_000:
+ *     (affiliate + province × 10_000_000) mod 97
+ *   else:
+ *     parseInt(province + affiliate) mod 97
+ *
+ * @see https://www.seg-social.es/
+ * @see https://intervia.com/doc/validar-numeros-de-la-seguridad-social/
+ */
+
+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, " -/.");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "Spanish NSS must be 12 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Spanish NSS must contain only digits",
+    );
+  }
+
+  const province = Number(v.slice(0, 2));
+  if (province < 1 || province > 52) {
+    return err(
+      "INVALID_COMPONENT",
+      "Spanish NSS province code must be 01–52",
+    );
+  }
+
+  const affiliate = Number(v.slice(2, 10));
+  const check = Number(v.slice(10, 12));
+
+  let base: number;
+  if (affiliate < 10_000_000) {
+    base = affiliate + province * 10_000_000;
+  } else {
+    // Concatenate province and affiliate as a number
+    base = Number(`${province}${v.slice(2, 10)}`);
+  }
+
+  const expected = base % 97;
+
+  if (expected !== check) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Spanish NSS check digits do not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 2)}/${v.slice(2, 10)}/${v.slice(10)}`;
+};
+
+/** Generate a random valid Spanish NSS. */
+const generate = (): string => {
+  for (;;) {
+    const c = randomDigits(12);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Spanish Social Security Number. */
+const nss: Validator = {
+  name: "Spanish Social Security Number",
+  localName: "Número de la Seguridad Social",
+  abbreviation: "NSS",
+  aliases: ["NSS", "número de seguridad social"] as const,
+  candidatePattern: "\\d{12}",
+  country: "ES",
+  entityType: "person",
+  description:
+    "Spanish Social Security affiliation number " +
+    "with mod-97 check digits",
+  sourceUrl: "https://www.seg-social.es/",
+  lengths: [12] as const,
+  examples: ["281234567840"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nss;
+export { compact, format, validate, generate };

package/src/es/vat.ts

@@ -0,0 +1,178 @@
+/**
+ * NIF/CIF (Spanish VAT number).
+ *
+ * 9 characters with 4 subtypes: DNI, NIE, CIF,
+ * and K/L/M personal numbers.
+ *
+ * @see https://www.vatify.eu/spain-vat-number.html
+ * @see https://www.agenciatributaria.es/
+ */
+
+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 DNI_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE";
+const CIF_LETTERS = "JABCDEFGHI";
+
+const compact = (value: string): string => {
+  let v = clean(value, " -/.");
+  if (v.startsWith("ES") || v.startsWith("es")) {
+    v = v.slice(2);
+  }
+  return v.toUpperCase();
+};
+
+const cifChecksum = (digits: string): number => {
+  let even = 0;
+  let odd = 0;
+  for (let i = 0; i < 7; i++) {
+    const d = Number(digits.charAt(i));
+    if (i % 2 === 0) {
+      // Odd positions (1-indexed): double and sum digits
+      const doubled = d * 2;
+      odd += Math.floor(doubled / 10) + (doubled % 10);
+    } else {
+      even += d;
+    }
+  }
+  return (10 - ((even + odd) % 10)) % 10;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Spanish VAT number must be 9 characters",
+    );
+  }
+
+  const first = v.charAt(0);
+  const last = v.charAt(8);
+
+  // DNI: 8 digits + letter
+  if (isdigits(v.slice(0, 8))) {
+    const expected = DNI_LETTERS.charAt(
+      Number.parseInt(v.slice(0, 8), 10) % 23,
+    );
+    if (last !== expected) {
+      return err(
+        "INVALID_CHECKSUM",
+        "Spanish DNI check letter mismatch",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // NIE: X/Y/Z + 7 digits + letter
+  if (first === "X" || first === "Y" || first === "Z") {
+    const prefix =
+      first === "X" ? "0" : first === "Y" ? "1" : "2";
+    const digits = prefix + v.slice(1, 8);
+    if (!isdigits(digits) || !isdigits(v.slice(1, 8))) {
+      return err(
+        "INVALID_FORMAT",
+        "Spanish NIE must have 7 digits after prefix",
+      );
+    }
+    const expected = DNI_LETTERS.charAt(
+      Number.parseInt(digits, 10) % 23,
+    );
+    if (last !== expected) {
+      return err(
+        "INVALID_CHECKSUM",
+        "Spanish NIE check letter mismatch",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // K, L, M: personal number, letter + 7 digits +
+  // check letter
+  if (first === "K" || first === "L" || first === "M") {
+    if (!isdigits(v.slice(1, 8))) {
+      return err(
+        "INVALID_FORMAT",
+        "Spanish K/L/M number must have 7 digits",
+      );
+    }
+    const expected = DNI_LETTERS.charAt(
+      Number.parseInt(v.slice(1, 8), 10) % 23,
+    );
+    if (last !== expected) {
+      return err(
+        "INVALID_CHECKSUM",
+        "Spanish K/L/M check letter mismatch",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // CIF: letter + 7 digits + check digit/letter
+  const CIF_PREFIXES = "ABCDEFGHJNPQRSUVW";
+  if (CIF_PREFIXES.includes(first)) {
+    if (!isdigits(v.slice(1, 8))) {
+      return err(
+        "INVALID_FORMAT",
+        "Spanish CIF must have 7 digits after prefix",
+      );
+    }
+    const check = cifChecksum(v.slice(1, 8));
+    // Accept either numeric or alphabetic check digit
+    // for all CIF prefixes (sources conflict on which
+    // prefixes require which type)
+    if (
+      last !== String(check) &&
+      last !== CIF_LETTERS.charAt(check)
+    ) {
+      return err(
+        "INVALID_CHECKSUM",
+        "Spanish CIF check digit/letter mismatch",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  return err(
+    "INVALID_FORMAT",
+    "Spanish VAT number has invalid format",
+  );
+};
+
+const format = (value: string): string =>
+  `ES${compact(value)}`;
+
+/** Generate a random valid Spanish VAT (DNI form). */
+const generate = (): string => {
+  const letters = "TRWAGMYFPDXBNJZSQVHLCKE";
+  const num = randomDigits(8);
+  return num + letters.charAt(Number(num) % 23);
+};
+
+/** Spanish VAT Number. */
+const vat: Validator = {
+  name: "Spanish VAT Number",
+  localName: "Número de Identificación Fiscal",
+  abbreviation: "NIF",
+  aliases: [
+    "NIF",
+    "CIF",
+    "número de identificación fiscal",
+  ] as const,
+  candidatePattern: "ES[A-Z]\\d{7}[A-Z\\d]",
+  country: "ES",
+  entityType: "any",
+  sourceUrl: "https://www.agenciatributaria.es/",
+  examples: ["12345678Z", "A78304516"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { cifChecksum, compact, format, validate, generate };

package/src/eu/mod.ts

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

package/src/eu/vat.ts

@@ -0,0 +1,171 @@
+/**
+ * EU VAT (European Union VAT Number).
+ *
+ * Dispatcher that routes to per-country VAT
+ * validators. Extracts the 2-letter country prefix
+ * and delegates to the matching country module.
+ *
+ * Special cases:
+ *   - EL → Greece (gr.vat)
+ *   - XI → Northern Ireland (gb.vat)
+ *
+ * @see https://ec.europa.eu/taxation_customs/vies/
+ */
+
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+import atUid from "../at/uid";
+import beVat from "../be/vat";
+import bgVat from "../bg/vat";
+import cyVat from "../cy/vat";
+import czDic from "../cz/dic";
+import deVat from "../de/vat";
+import dkVat from "../dk/vat";
+import eeVat from "../ee/vat";
+import esVat from "../es/vat";
+import fiVat from "../fi/vat";
+import frTva from "../fr/tva";
+import gbVat from "../gb/vat";
+import grVat from "../gr/vat";
+import hrVat from "../hr/vat";
+import huVat from "../hu/vat";
+import ieVat from "../ie/vat";
+import itIva from "../it/iva";
+import ltVat from "../lt/vat";
+import luVat from "../lu/vat";
+import lvVat from "../lv/vat";
+import mtVat from "../mt/vat";
+import nlVat from "../nl/vat";
+import plNip from "../pl/nip";
+import ptVat from "../pt/vat";
+import roVat from "../ro/vat";
+import seVat from "../se/vat";
+import siVat from "../si/vat";
+import skDic from "../sk/dic";
+import type { Validator, ValidateResult } from "../types";
+
+type CountryValidator = {
+  compact: (value: string) => string;
+  validate: (value: string) => ValidateResult;
+  format: (value: string) => string;
+};
+
+/**
+ * Map of EU VAT country prefixes to their
+ * country-specific validators.
+ */
+const VALIDATORS: Record<string, CountryValidator> = {
+  AT: atUid,
+  BE: beVat,
+  BG: bgVat,
+  CY: cyVat,
+  CZ: czDic,
+  DE: deVat,
+  DK: dkVat,
+  EE: eeVat,
+  EL: grVat, // Greece uses EL prefix in EU VAT
+  ES: esVat,
+  FI: fiVat,
+  FR: frTva,
+  GR: grVat,
+  HR: hrVat,
+  HU: huVat,
+  IE: ieVat,
+  IT: itIva,
+  LT: ltVat,
+  LU: luVat,
+  LV: lvVat,
+  MT: mtVat,
+  NL: nlVat,
+  PL: plNip,
+  PT: ptVat,
+  RO: roVat,
+  SE: seVat,
+  SI: siVat,
+  SK: skDic,
+  XI: gbVat, // Northern Ireland
+};
+
+/**
+ * Extract the 2-letter country prefix and the
+ * remaining number from an EU VAT string.
+ */
+const splitPrefix = (
+  value: string,
+): { cc: string; rest: string } | undefined => {
+  const v = clean(value, " -").toUpperCase();
+  if (v.length < 3) return undefined;
+  const cc = v.slice(0, 2);
+  if (!/^[A-Z]{2}$/.test(cc)) return undefined;
+  return { cc, rest: v.slice(2) };
+};
+
+const compact = (value: string): string => {
+  const parts = splitPrefix(value);
+  if (parts === undefined) {
+    return clean(value, " -").toUpperCase();
+  }
+  const validator = VALIDATORS[parts.cc];
+  if (validator === undefined) {
+    return clean(value, " -").toUpperCase();
+  }
+  return `${parts.cc}${validator.compact(parts.rest)}`;
+};
+
+const validate = (value: string): ValidateResult => {
+  const parts = splitPrefix(value);
+  if (parts === undefined) {
+    return err(
+      "INVALID_FORMAT",
+      "EU VAT must start with a 2-letter country code",
+    );
+  }
+  const validator = VALIDATORS[parts.cc];
+  if (validator === undefined) {
+    return err(
+      "INVALID_COMPONENT",
+      `Unsupported EU VAT country: ${parts.cc}`,
+    );
+  }
+  const result = validator.validate(parts.rest);
+  if (!result.valid) return result;
+  return {
+    valid: true,
+    compact: `${parts.cc}${result.compact}`,
+  };
+};
+
+/**
+ * Format returns the compact EU VAT form:
+ * `CC` + country-compacted number. Equivalent to
+ * compact() because country format() methods
+ * prepend their own prefix (e.g., AT UID format
+ * returns "ATU..."), which would cause double-
+ * prefixing if used here.
+ */
+const format = (value: string): string => {
+  const parts = splitPrefix(value);
+  if (parts === undefined) return value;
+  const validator = VALIDATORS[parts.cc];
+  if (validator === undefined) return value;
+  return `${parts.cc}${validator.compact(parts.rest)}`;
+};
+
+/** European Union VAT Number. */
+const euVat: Validator = {
+  name: "EU VAT Number",
+  localName: "EU VAT Number",
+  abbreviation: "EU VAT",
+  aliases: ["EU VAT", "VAT identification number"] as const,
+  candidatePattern: "[A-Z]{2}\\d{8,12}",
+  entityType: "company",
+  sourceUrl: "https://ec.europa.eu/taxation_customs/vies/",
+  examples: ["ATU13585627", "DE136695976"] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default euVat;
+export { compact, format, validate };