@stll/stdnum 0.0.1

package/src/cy/vat.ts

@@ -0,0 +1,130 @@
+/**
+ * ΦΠΑ (Cypriot VAT number).
+ *
+ * 8 digits + 1 check letter. Cannot start with "12".
+ *
+ * @see https://www.vatify.eu/cyprus-vat-number.html
+ * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/cyprus-tin.pdf
+ */
+
+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 ODD_MAP: Record<number, number> = {
+  0: 1,
+  1: 0,
+  2: 5,
+  3: 7,
+  4: 9,
+  5: 13,
+  6: 15,
+  7: 17,
+  8: 19,
+  9: 21,
+};
+
+const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+const compact = (value: string): string => {
+  let v = clean(value, " -/.");
+  if (v.startsWith("CY") || v.startsWith("cy")) {
+    v = v.slice(2);
+  }
+  return v.toUpperCase();
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Cypriot VAT number must be 8 digits + 1 letter",
+    );
+  }
+  const digits = v.slice(0, 8);
+  const checkLetter = v[8];
+  if (!isdigits(digits)) {
+    return err(
+      "INVALID_FORMAT",
+      "Cypriot VAT number must start with 8 digits",
+    );
+  }
+  if (
+    checkLetter === undefined ||
+    !LETTERS.includes(checkLetter)
+  ) {
+    return err(
+      "INVALID_FORMAT",
+      "Cypriot VAT number must end with a letter",
+    );
+  }
+  if (v.startsWith("12")) {
+    return err(
+      "INVALID_COMPONENT",
+      "Cypriot VAT number cannot start with 12",
+    );
+  }
+  let odd = 0;
+  let even = 0;
+  for (let i = 0; i < 8; i++) {
+    const d = Number(digits.charAt(i));
+    if (i % 2 === 0) {
+      // Odd position (1-indexed: 1,3,5,7)
+      odd += ODD_MAP[d] ?? 0;
+    } else {
+      // Even position (1-indexed: 2,4,6,8)
+      even += d;
+    }
+  }
+  const expected = LETTERS.charAt((odd + even) % 26);
+  if (checkLetter !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Cypriot VAT number check letter mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `CY${compact(value)}`;
+
+/** Generate a random valid Cypriot VAT number. */
+const generate = (): string => {
+  for (;;) {
+    const digits = randomDigits(8);
+    if (digits.startsWith("12")) continue;
+    let odd = 0;
+    let even = 0;
+    for (let i = 0; i < 8; i++) {
+      const d = Number(digits.charAt(i));
+      if (i % 2 === 0) odd += ODD_MAP[d] ?? 0;
+      else even += d;
+    }
+    return digits + LETTERS.charAt((odd + even) % 26);
+  }
+};
+
+/** Cypriot VAT Number. */
+const vat: Validator = {
+  name: "Cypriot VAT Number",
+  localName: "Αριθμός Εγγραφής Φ.Π.Α.",
+  abbreviation: "ΦΠΑ",
+  aliases: ["ΦΠΑ", "VAT CY"] as const,
+  candidatePattern: "CY\\d{8}[A-Z]",
+  country: "CY",
+  entityType: "company",
+  sourceUrl: "https://www.mof.gov.cy/",
+  examples: ["10259033P"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, validate, generate };

package/src/cz/dic.ts

@@ -0,0 +1,135 @@
+/**
+ * DIČ (Daňové identifikační číslo).
+ *
+ * Czech tax identification number / VAT number.
+ * Format: "CZ" prefix + 8, 9, or 10 digits.
+ * - 8 digits: company (same checksum as IČO,
+ *   but first digit cannot be 9)
+ * - 9 digits starting with 6: special entity
+ * - 9-10 digits: individual (birth number)
+ *
+ * @see https://adisspr.mfcr.cz/dpr/DphReg
+ */
+
+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";
+import { validate as validateRc } from "./rc";
+
+const ICO_WEIGHTS = [8, 7, 6, 5, 4, 3, 2] as const;
+
+const compact = (value: string): string => {
+  const v = clean(value, " -");
+  if (v.startsWith("CZ") || v.startsWith("cz")) {
+    return v.slice(2);
+  }
+  return v;
+};
+
+const checkLegal = (value: string): boolean => {
+  const sum = weightedSum(
+    value.slice(0, 7),
+    ICO_WEIGHTS,
+    11,
+  );
+  const v11 = (11 - sum) % 11;
+  const check = v11 === 0 ? 1 : v11 % 10;
+  return check === Number(value[7]);
+};
+
+const checkSpecial = (value: string): boolean => {
+  // Skip the leading "6"; check digits 1..7
+  const sum = weightedSum(
+    value.slice(1, 8),
+    [8, 7, 6, 5, 4, 3, 2],
+    11,
+  );
+  const check =
+    (((8 - ((((10 - sum) % 11) + 11) % 11)) % 10) + 10) %
+    10;
+  return check === Number(value[8]);
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < 8 || v.length > 10) {
+    return err(
+      "INVALID_LENGTH",
+      "DIČ must be 8-10 digits (without CZ prefix)",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "DIČ must contain only digits",
+    );
+  }
+
+  // 8-digit: legal entity (IČO-like checksum)
+  if (v.length === 8) {
+    if (v[0] === "9") {
+      return err(
+        "INVALID_COMPONENT",
+        "8-digit DIČ cannot start with 9",
+      );
+    }
+    if (!checkLegal(v)) {
+      return err(
+        "INVALID_CHECKSUM",
+        "DIČ check digit does not match",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // 9-digit starting with 6: special entity
+  if (v.length === 9 && v[0] === "6") {
+    if (!checkSpecial(v)) {
+      return err(
+        "INVALID_CHECKSUM",
+        "DIČ special entity check digit mismatch",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // 9-10 digit: birth number
+  return validateRc(v);
+};
+
+const format = (value: string): string =>
+  `CZ${compact(value)}`;
+
+/** Generate a random valid 8-digit DIČ. */
+const generate = (): string => {
+  const first = String(randomInt(1, 8));
+  const payload = first + randomDigits(6);
+  const sum = weightedSum(payload, ICO_WEIGHTS, 11);
+  const v11 = (11 - sum) % 11;
+  const check = v11 === 0 ? 1 : v11 % 10;
+  return payload + String(check);
+};
+
+/** Czech VAT Number. */
+const dic: Validator = {
+  name: "Czech VAT Number",
+  localName: "Daňové identifikační číslo",
+  abbreviation: "DIČ",
+  aliases: ["DIČ", "daňové identifikační číslo"] as const,
+  candidatePattern: "CZ\\d{8,10}",
+  country: "CZ",
+  entityType: "any",
+  sourceUrl: "https://adisspr.mfcr.cz/dpr/DphReg",
+  examples: ["25123891", "7103192745"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default dic;
+export { compact, format, validate, generate };

package/src/cz/ico.ts

@@ -0,0 +1,82 @@
+/**
+ * IČO (Identifikační číslo osoby).
+ *
+ * Czech company identification number. 8 digits
+ * with a weighted checksum. Assigned by the Czech
+ * Statistical Office.
+ *
+ * @see https://www.czso.cz/
+ */
+
+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 =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 8) {
+    return err(
+      "INVALID_LENGTH",
+      "IČO must be exactly 8 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "IČO must contain only digits",
+    );
+  }
+  const sum = weightedSum(v.slice(0, 7), WEIGHTS, 11);
+  const v11 = (11 - sum) % 11;
+  const check = v11 === 0 ? 1 : v11 % 10;
+  if (check !== Number(v[7])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "IČO check digit does not match",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid ICO. */
+const generate = (): string => {
+  const payload = randomDigits(7);
+  const sum = weightedSum(payload, WEIGHTS, 11);
+  const v11 = (11 - sum) % 11;
+  const check = v11 === 0 ? 1 : v11 % 10;
+  return `${payload}${String(check)}`;
+};
+
+/** Czech Company Identification Number. */
+const ico: Validator = {
+  name: "Czech Company ID",
+  localName: "Identifikační číslo osoby",
+  abbreviation: "IČO",
+  aliases: ["IČO", "IČ", "identifikační číslo"] as const,
+  candidatePattern: "\\d{8}",
+  country: "CZ",
+  entityType: "company",
+  description:
+    "8-digit company ID assigned by the Czech Statistical Office",
+  sourceUrl: "https://www.czso.cz/",
+  lengths: [8] as const,
+  examples: ["25123891", "27074358"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default ico;
+export { compact, format, generate, validate };

package/src/cz/mod.ts

@@ -0,0 +1,3 @@
+export { default as dic } from "./dic";
+export { default as ico } from "./ico";
+export { default as rc } from "./rc";

package/src/cz/rc.ts

@@ -0,0 +1,190 @@
+/**
+ * RČ (Rodné číslo).
+ *
+ * Czech and Slovak national identifier (birth
+ * number). 9 or 10 digits encoding date of birth
+ * and gender. 10-digit numbers (post-1954) must
+ * be divisible by 11.
+ *
+ * Women have 50 added to the month. Since 2004,
+ * an extra +20 offset is used when the serial
+ * range is exhausted.
+ *
+ * @see https://www.mvcr.cz/mvcren/docDetail.aspx?docid=21975362&doctype=ART
+ * @see Law 133/2000 Sb.
+ */
+
+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 compact = (value: string): string =>
+  clean(value, " /");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9 && v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "Birth number must be 9 or 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Birth number must contain only digits",
+    );
+  }
+
+  const yy = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+
+  // Strip gender (+50) and overflow (+20) offsets
+  const month = (mm % 50) % 20 || mm % 50;
+  if (month < 1 || month > 12) {
+    return err(
+      "INVALID_COMPONENT",
+      "Birth number contains an invalid month",
+    );
+  }
+
+  if (dd < 1 || dd > 31) {
+    return err(
+      "INVALID_COMPONENT",
+      "Birth number contains an invalid day",
+    );
+  }
+
+  // Resolve full year
+  let year = yy + 1900;
+  if (v.length === 9) {
+    // 9-digit: pre-1954 only
+    if (year >= 1980) year -= 100;
+    if (year > 1953) {
+      return err(
+        "INVALID_COMPONENT",
+        "9-digit birth numbers are pre-1954 only",
+      );
+    }
+  } else {
+    // 10-digit: if year < 1954, it's 2000s
+    if (year < 1954) year += 100;
+  }
+
+  // Validate the actual date
+  if (!isValidDate(year, month, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Birth number contains an invalid date",
+    );
+  }
+
+  // 10-digit: check digit is first 9 digits
+  // mod 11 mod 10
+  if (v.length === 10) {
+    const front = Number(v.slice(0, 9));
+    const check = (front % 11) % 10;
+    if (String(check) !== v[9]) {
+      return err(
+        "INVALID_CHECKSUM",
+        "Birth number is not divisible by 11",
+      );
+    }
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 6)}/${v.slice(6)}`;
+};
+
+/**
+ * Extract birth date and gender from a birth number.
+ * 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 yy = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+
+  const gender = mm > 50 ? "female" : "male";
+  const month = (mm % 50) % 20 || mm % 50;
+
+  let year = yy + 1900;
+  if (v.length === 10 && year < 1954) year += 100;
+  if (v.length === 9 && year >= 1980) year -= 100;
+
+  return {
+    birthDate: new Date(year, month - 1, dd),
+    gender,
+  };
+};
+
+/**
+ * Generate a random valid 10-digit birth number.
+ * Uses a random date between 1954 and 2024.
+ */
+const generate = (): string => {
+  const year = randomInt(1954, 2024);
+  const month = randomInt(1, 12);
+  const day = randomInt(1, 28);
+  const isFemale = Math.random() < 0.5;
+  const mm = isFemale ? month + 50 : month;
+
+  const yy = String(year % 100).padStart(2, "0");
+  const mmStr = String(mm).padStart(2, "0");
+  const dd = String(day).padStart(2, "0");
+
+  const datePart = `${yy}${mmStr}${dd}`;
+  for (let seq = 0; seq < 1000; seq++) {
+    const seqStr = String(seq).padStart(3, "0");
+    const front = `${datePart}${seqStr}`;
+    const num = Number(front);
+    const check = (num % 11) % 10;
+    const result = `${front}${String(check)}`;
+    if (validate(result).valid) {
+      return result;
+    }
+  }
+
+  throw new Error("Failed to generate valid birth number");
+};
+
+/** Czech/Slovak Birth Number. */
+const rc: Validator = {
+  name: "Czech Birth Number",
+  localName: "Rodné číslo",
+  abbreviation: "RČ",
+  aliases: ["rodné číslo", "RČ", "birth number"] as const,
+  candidatePattern: "\\d{6}/\\d{3,4}",
+  country: "CZ",
+  entityType: "person",
+  description:
+    "Czech/Slovak national identifier encoding birth date and gender",
+  sourceUrl:
+    "https://www.mvcr.cz/mvcren/docDetail.aspx?docid=21975362&doctype=ART",
+  lengths: [9, 10] as const,
+  examples: ["7103192745"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default rc;
+export { compact, format, generate, parse, validate };

package/src/de/handelsreg.ts

@@ -0,0 +1,107 @@
+/** Generate a random valid Handelsregisternummer. */
+const generate = (): string => {
+  const types = ["HRA", "HRB", "GNR", "PR", "VR"];
+  const type = types[randomInt(0, types.length - 1)]!;
+  const number = randomDigits(5);
+  return `${type} ${number}`;
+};
+
+/**
+ * Handelsregisternummer (German Company Register Number).
+ *
+ * German commercial register number assigned by the
+ * local court (Amtsgericht). Format: register type
+ * (HRA, HRB, GnR, PR, VR) + number.
+ *
+ * HRA = Handelsregister Abteilung A (partnerships,
+ * sole proprietors). HRB = Abteilung B (corporations).
+ * GnR = Genossenschaftsregister.
+ * PR = Partnerschaftsregister.
+ * VR = Vereinsregister.
+ *
+ * No check digit; validation is structural only.
+ *
+ * @see https://de.wikipedia.org/wiki/Handelsregister_(Deutschland)
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+const REGISTER_TYPES = new Set([
+  "HRA",
+  "HRB",
+  "GNR",
+  "PR",
+  "VR",
+]);
+
+/**
+ * Strip separators and normalize to canonical form.
+ * Accepts "HRB 12345", "HRB12345", "hrb 12345".
+ */
+const compact = (value: string): string => {
+  const v = clean(value, " -.").trim().toUpperCase();
+  const match = v.match(/^(HRA|HRB|GNR|PR|VR)(\d{1,7})$/);
+  if (!match) return v;
+  return `${match[1]} ${match[2]}`;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = clean(value, " -.").trim().toUpperCase();
+
+  const match = v.match(/^([A-Z]{2,3})(\d{1,7})$/);
+  if (!match) {
+    return err(
+      "INVALID_FORMAT",
+      "Handelsregisternummer must be a register type " +
+        "(HRA, HRB, GnR, PR, VR) followed by " +
+        "1-7 digits",
+    );
+  }
+
+  const type = match[1]!;
+  const number = match[2]!;
+
+  if (!REGISTER_TYPES.has(type)) {
+    return err(
+      "INVALID_COMPONENT",
+      `Unrecognised register type "${type}"`,
+    );
+  }
+
+  return {
+    valid: true,
+    compact: `${type} ${number}`,
+  };
+};
+
+const format = (value: string): string => compact(value);
+
+/** German Company Register Number. */
+const handelsreg: Validator = {
+  name: "German Company Register Number",
+  localName: "Handelsregisternummer",
+  abbreviation: "HReg",
+  aliases: [
+    "Handelsregisternummer",
+    "Handelsregister",
+    "HRB",
+    "HRA",
+  ] as const,
+  candidatePattern: "(?:HRA|HRB|GnR|PR|VR)\\s*\\d{1,7}",
+  country: "DE",
+  entityType: "company",
+  sourceUrl:
+    "https://de.wikipedia.org/wiki/Handelsregister_(Deutschland)",
+  examples: ["HRB 12345"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default handelsreg;
+export { compact, format, validate, generate };