@stll/stdnum 0.0.1

package/src/ee/ik.ts

@@ -0,0 +1,156 @@
+/**
+ * Isikukood (IK).
+ *
+ * Estonian personal identification code. 11 digits:
+ * gender/century digit, YYMMDD, 3-digit serial, and
+ * a check digit computed with two-pass weighted sums.
+ *
+ * @see https://www.riigiteataja.ee/en/eli/512012015003/consolide
+ */
+
+import { weightedSum } from "#checksums/weighted-sum";
+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 {
+  ParsedPersonId,
+  ValidateResult,
+  Validator,
+} from "../types";
+
+const WEIGHTS_1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 1] as const;
+const WEIGHTS_2 = [3, 4, 5, 6, 7, 8, 9, 1, 2, 3] as const;
+
+const centuryMap: Record<number, number> = {
+  1: 1800,
+  2: 1800,
+  3: 1900,
+  4: 1900,
+  5: 2000,
+  6: 2000,
+  7: 2100,
+  8: 2100,
+};
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+/**
+ * Compute the two-pass check digit used by both
+ * Estonian IK and Lithuanian Asmens kodas.
+ */
+export const twoPassCheck = (digits: string): number => {
+  let remainder = weightedSum(digits, WEIGHTS_1, 11);
+  if (remainder !== 10) return remainder;
+  remainder = weightedSum(digits, WEIGHTS_2, 11);
+  return remainder === 10 ? 0 : remainder;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "Isikukood must be exactly 11 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Isikukood must contain only digits",
+    );
+  }
+
+  const g = Number(v[0]);
+  if (g < 1 || g > 8) {
+    return err(
+      "INVALID_COMPONENT",
+      "Isikukood gender/century digit is invalid",
+    );
+  }
+
+  const century = centuryMap[g] ?? 1900;
+  const yy = Number(v.slice(1, 3));
+  const mm = Number(v.slice(3, 5));
+  const dd = Number(v.slice(5, 7));
+  const year = century + yy;
+
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Isikukood contains an invalid date",
+    );
+  }
+
+  const check = twoPassCheck(v.slice(0, 10));
+  if (check !== Number(v[10])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Isikukood check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Extract birth date and gender from an Isikukood.
+ * Returns null if the value is not valid.
+ */
+const parse = (value: string): ParsedPersonId | null => {
+  const result = validate(value);
+  if (!result.valid) return null;
+
+  const v = result.compact;
+  const g = Number(v[0]);
+  const century = centuryMap[g] ?? 1900;
+  const yy = Number(v.slice(1, 3));
+  const mm = Number(v.slice(3, 5));
+  const dd = Number(v.slice(5, 7));
+  const year = century + yy;
+
+  return {
+    birthDate: new Date(year, mm - 1, dd),
+    gender: g % 2 === 1 ? "male" : "female",
+  };
+};
+
+/** Generate a random valid Estonian IK. */
+const generate = (): string => {
+  for (;;) {
+    const g = String(randomInt(3, 6));
+    const yy = String(randomInt(0, 99)).padStart(2, "0");
+    const mm = String(randomInt(1, 12)).padStart(2, "0");
+    const dd = String(randomInt(1, 28)).padStart(2, "0");
+    const s = String(randomInt(0, 999)).padStart(3, "0");
+    const payload = g + yy + mm + dd + s;
+    const c = payload + String(twoPassCheck(payload));
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Estonian Personal Identification Code. */
+const ik: Validator = {
+  name: "Estonian Personal ID",
+  localName: "Isikukood",
+  abbreviation: "IK",
+  aliases: ["isikukood", "IK"] as const,
+  candidatePattern: "[1-6]\\d{10}",
+  country: "EE",
+  entityType: "person",
+  sourceUrl:
+    "https://www.riigiteataja.ee/en/eli/512012015003/consolide",
+  examples: ["36805280109"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default ik;
+export { compact, format, parse, validate, generate };

package/src/ee/mod.ts

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

package/src/ee/registrikood.ts

@@ -0,0 +1,81 @@
+/**
+ * Registrikood (Estonian company registration code).
+ *
+ * 8 digits. First digit must be 1, 7, 8, or 9.
+ * Two-pass checksum (same algorithm as EE IK).
+ *
+ * @see https://www.rik.ee/
+ */
+
+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 { twoPassCheck } from "./ik";
+
+const VALID_FIRST = new Set(["1", "7", "8", "9"]);
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 8) {
+    return err(
+      "INVALID_LENGTH",
+      "Estonian Registrikood must be 8 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Estonian Registrikood must contain only digits",
+    );
+  }
+  if (!VALID_FIRST.has(v.charAt(0))) {
+    return err(
+      "INVALID_COMPONENT",
+      "Estonian Registrikood must start with 1, 7, 8, or 9",
+    );
+  }
+  const check = twoPassCheck(v.slice(0, 7));
+  if (check !== Number(v[7])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Estonian Registrikood check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Estonian Registrikood. */
+const generate = (): string => {
+  const firsts = [1, 7, 8, 9];
+  const first = String(firsts[randomInt(0, 3)]!);
+  const payload = first + randomDigits(6);
+  return payload + String(twoPassCheck(payload));
+};
+
+/** Estonian Company Registration Code. */
+const registrikood: Validator = {
+  name: "Estonian Company Registration Code",
+  localName: "Registrikood",
+  abbreviation: "Registrikood",
+  aliases: ["registrikood"] as const,
+  candidatePattern: "\\d{8}",
+  country: "EE",
+  entityType: "company",
+  sourceUrl: "https://www.rik.ee/",
+  examples: ["12345678"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default registrikood;
+export { compact, format, validate, generate };

package/src/ee/vat.ts

@@ -0,0 +1,85 @@
+/**
+ * KMKR (Estonian VAT number).
+ *
+ * 9 digits. Weights [3,7,1,3,7,1,3,7,1],
+ * sum % 10 === 0.
+ *
+ * @see https://www.vatify.eu/estonia-vat-number.html
+ * @see https://www.emta.ee/en
+ */
+
+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 = [3, 7, 1, 3, 7, 1, 3, 7, 1];
+
+const compact = (value: string): string => {
+  let v = clean(value, " -/.");
+  if (v.startsWith("EE") || v.startsWith("ee")) {
+    v = v.slice(2);
+  }
+  return v;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Estonian VAT number must be 9 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Estonian VAT number must contain only digits",
+    );
+  }
+  const sum = weightedSum(v, WEIGHTS, 10);
+  if (sum !== 0) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Estonian VAT number check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `EE${compact(value)}`;
+
+/** Generate a random valid Estonian VAT number. */
+const generate = (): string => {
+  for (;;) {
+    const c = randomDigits(9);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Estonian VAT Number. */
+const vat: Validator = {
+  name: "Estonian VAT Number",
+  localName: "Käibemaksukohustuslase number",
+  abbreviation: "KMKR",
+  aliases: [
+    "käibemaksukohustuslase number",
+    "KMKR",
+  ] as const,
+  candidatePattern: "EE\\d{9}",
+  country: "EE",
+  entityType: "company",
+  sourceUrl: "https://www.emta.ee/en",
+  examples: ["100931558"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, validate, generate };

package/src/eg/mod.ts

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

package/src/eg/tn.ts

@@ -0,0 +1,103 @@
+/** Generate a random valid Egyptian TN. */
+const generate = (): string => randomDigits(9);
+
+/**
+ * TN (Tax Registration Number, الرقم الضريبي).
+ *
+ * Egyptian tax number. 9 digits, no checksum.
+ * Displayed as XXX-XXX-XXX. Accepts both
+ * Arabic-Indic and Extended Arabic-Indic digits.
+ *
+ * @see https://www.eta.gov.eg/
+ */
+
+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";
+
+/**
+ * Arabic-Indic and Extended Arabic-Indic digit map.
+ * Converts Arabic numeral characters to ASCII digits.
+ */
+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", // ۹
+};
+
+const ARABIC_REGEX = new RegExp(
+  `[${Object.keys(ARABIC_DIGITS).join("")}]`,
+  "g",
+);
+
+const compact = (value: string): string => {
+  const cleaned = clean(value, " -/");
+  return cleaned.replace(
+    ARABIC_REGEX,
+    (ch) => ARABIC_DIGITS[ch] ?? ch,
+  );
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Egyptian TN must be exactly 9 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Egyptian TN must contain only digits",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 3)}-${v.slice(3, 6)}-${v.slice(6)}`;
+};
+
+/** Egyptian Tax Registration Number. */
+const tn: Validator = {
+  name: "Egyptian Tax Registration Number",
+  localName: "الرقم الضريبي",
+  abbreviation: "TN",
+  aliases: ["الرقم الضريبي", "tax number"] as const,
+  candidatePattern: "\\d{9}",
+  country: "EG",
+  entityType: "any",
+  compact,
+  format,
+  validate,
+  description: "Egyptian tax identification number",
+  sourceUrl: "https://www.eta.gov.eg/",
+  lengths: [9] as const,
+  examples: ["100531385", "331105268"] as const,
+  generate,
+};
+
+export default tn;
+export { compact, format, validate, generate };

package/src/es/cif.ts

@@ -0,0 +1,105 @@
+/**
+ * CIF (Código de Identificación Fiscal).
+ *
+ * Spanish company tax identification number.
+ * Letter prefix (ABCDEFGHJNPQRSUVW) + 7 digits +
+ * check digit or letter. Delegates to the CIF
+ * branch of es/vat validation.
+ *
+ * @see https://www.agenciatributaria.es/
+ */
+
+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 { cifChecksum } from "./vat";
+
+const CIF_PREFIXES = "ABCDEFGHJNPQRSUVW";
+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 validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Spanish CIF must be 9 characters",
+    );
+  }
+
+  const first = v.charAt(0);
+  if (!CIF_PREFIXES.includes(first)) {
+    return err(
+      "INVALID_FORMAT",
+      "Spanish CIF must start with a valid prefix letter",
+    );
+  }
+
+  if (!isdigits(v.slice(1, 8))) {
+    return err(
+      "INVALID_FORMAT",
+      "Spanish CIF must have 7 digits after prefix",
+    );
+  }
+
+  const last = v.charAt(8);
+  const check = cifChecksum(v.slice(1, 8));
+
+  if (
+    last !== String(check) &&
+    last !== CIF_LETTERS.charAt(check)
+  ) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Spanish CIF check digit/letter mismatch",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Spanish CIF. */
+const generate = (): string => {
+  const letter =
+    CIF_PREFIXES[randomInt(0, CIF_PREFIXES.length - 1)]!;
+  const payload = randomDigits(7);
+  const check = cifChecksum(payload);
+  if ("KPQS".includes(letter))
+    return letter + payload + CIF_LETTERS.charAt(check);
+  return letter + payload + String(check);
+};
+
+/** Spanish Company Tax ID (CIF). */
+const cif: Validator = {
+  name: "Spanish Company Tax ID",
+  localName: "Código de Identificación Fiscal",
+  abbreviation: "CIF",
+  aliases: [
+    "CIF",
+    "código de identificación fiscal",
+  ] as const,
+  candidatePattern: "[A-HJNP-SUVW]\\d{7}[\\dA-J]",
+  country: "ES",
+  entityType: "company",
+  sourceUrl: "https://www.agenciatributaria.es/",
+  examples: ["A13585625"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default cif;
+export { compact, format, validate, generate };

package/src/es/dni.ts

@@ -0,0 +1,90 @@
+/**
+ * DNI (Documento Nacional de Identidad).
+ *
+ * Spanish national identity document number.
+ * 8 digits followed by a check letter determined
+ * by the remainder of dividing the number by 23.
+ *
+ * @see https://www.interior.gob.es/opencms/es/servicios-al-ciudadano/tramites-y-gestiones/dni/
+ */
+
+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 CHECK_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE";
+
+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",
+      "DNI must be 8 digits and 1 letter",
+    );
+  }
+
+  const digits = v.slice(0, 8);
+  const letter = v[8];
+
+  if (!isdigits(digits)) {
+    return err(
+      "INVALID_FORMAT",
+      "DNI must start with 8 digits",
+    );
+  }
+
+  const expected = CHECK_LETTERS[Number(digits) % 23];
+  if (letter !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "DNI check letter does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Spanish DNI. */
+const generate = (): string => {
+  const num = randomDigits(8);
+  return num + CHECK_LETTERS[Number(num) % 23];
+};
+
+/** Spanish National Identity Document. */
+const dni: Validator = {
+  name: "Spanish National ID",
+  localName: "Documento Nacional de Identidad",
+  abbreviation: "DNI",
+  aliases: [
+    "D.N.I.",
+    "DNI",
+    "documento nacional de identidad",
+  ] as const,
+  candidatePattern: "\\d{1,2}\\.?\\d{3}\\.?\\d{3}-?[A-Z]",
+  country: "ES",
+  entityType: "person",
+  sourceUrl:
+    "https://www.interior.gob.es/opencms/es/servicios-al-ciudadano/tramites-y-gestiones/dni/",
+  examples: ["54362315K"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default dni;
+export {
+  CHECK_LETTERS,
+  compact,
+  format,
+  validate,
+  generate,
+};

package/src/es/mod.ts

@@ -0,0 +1,5 @@
+export { default as cif } from "./cif";
+export { default as dni } from "./dni";
+export { default as nie } from "./nie";
+export { default as nss } from "./nss";
+export { default as vat } from "./vat";