@stll/stdnum 0.0.1

package/src/de/idnr.ts

@@ -0,0 +1,140 @@
+/**
+ * IdNr (Steuerliche Identifikationsnummer).
+ *
+ * German personal tax identification number.
+ * 11 digits; the last digit is a check digit
+ * (ISO 7064 Mod 11,10). Exactly one digit
+ * appears twice or three times; the rest are
+ * unique. The first digit cannot be 0.
+ *
+ * @see https://www.bzst.de/DE/Privatpersonen/SteuerlicheIdentifikationsnummer/steuerlicheidentifikationsnummer_node.html
+ */
+
+import {
+  mod1110validate,
+  mod1110checkDigit,
+} from "#checksums/mod1110";
+import { clean } from "#util/clean";
+import { 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, " -/");
+
+/**
+ * Validate digit distribution: in the first 10
+ * digits, exactly one digit appears 2 or 3
+ * times; all others appear exactly once.
+ */
+const validDistribution = (value: string): boolean => {
+  const counts = Array.from<number>({ length: 10 }).fill(0);
+  for (let i = 0; i < 10; i++) {
+    const idx = Number(value.charAt(i));
+    const prev = counts[idx];
+    if (prev !== undefined) counts[idx] = prev + 1;
+  }
+  let doubles = 0;
+  let triples = 0;
+  for (const c of counts) {
+    if (c === 2) doubles++;
+    if (c === 3) triples++;
+    if (c > 3) return false;
+  }
+  // Exactly one digit repeated (2 or 3 times)
+  return (
+    (doubles === 1 && triples === 0) ||
+    (doubles === 0 && triples === 1)
+  );
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "German IdNr must be 11 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "German IdNr must contain only digits",
+    );
+  }
+  if (v[0] === "0") {
+    return err(
+      "INVALID_COMPONENT",
+      "German IdNr cannot start with 0",
+    );
+  }
+  if (!validDistribution(v)) {
+    return err(
+      "INVALID_COMPONENT",
+      "German IdNr digit distribution invalid",
+    );
+  }
+  if (!mod1110validate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "German IdNr check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 2)} ${v.slice(2, 5)} ${v.slice(5, 8)} ${v.slice(8)}`;
+};
+
+/** Generate a random valid German IdNr. */
+const generate = (): string => {
+  for (;;) {
+    const repeated = randomInt(0, 9);
+    const times = Math.random() < 0.8 ? 2 : 3;
+    const pool: number[] = [];
+    for (let d = 0; d < 10; d++) {
+      const count = d === repeated ? times : 1;
+      for (let t = 0; t < count; t++) pool.push(d);
+    }
+    while (pool.length < 10) pool.push(randomInt(0, 9));
+    for (let i = pool.length - 1; i > 0; i--) {
+      const j = randomInt(0, i);
+      [pool[i], pool[j]] = [pool[j]!, pool[i]!];
+    }
+    if (pool[0] === 0) continue;
+    const payload = pool.slice(0, 10).join("");
+    if (!validDistribution(payload)) continue;
+    const check = mod1110checkDigit(payload);
+    const c = payload + String(check);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** German Personal Tax ID. */
+const idnr: Validator = {
+  name: "German Tax ID",
+  localName: "Steuerliche Identifikationsnummer",
+  abbreviation: "IdNr",
+  aliases: [
+    "Steuerliche Identifikationsnummer",
+    "IdNr",
+    "Steuer-ID",
+  ] as const,
+  candidatePattern: "\\d{2}\\s?\\d{3}\\s?\\d{3}\\s?\\d{3}",
+  country: "DE",
+  entityType: "person",
+  sourceUrl:
+    "https://www.bzst.de/DE/Privatpersonen/SteuerlicheIdentifikationsnummer/steuerlicheidentifikationsnummer_node.html",
+  examples: ["36574261809"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default idnr;
+export { compact, format, validate, generate };

package/src/de/mod.ts

@@ -0,0 +1,5 @@
+export { default as handelsreg } from "./handelsreg";
+export { default as idnr } from "./idnr";
+export { default as stnr } from "./stnr";
+export { default as svnr } from "./svnr";
+export { default as vat } from "./vat";

package/src/de/stnr.ts

@@ -0,0 +1,214 @@
+/**
+ * Generate a random valid Steuernummer.
+ * Uses Berlin regional format (FFBBBUUUUP, 10 digits).
+ */
+const generate = (): string => {
+  const ff = randomDigits(2);
+  const bbb = randomDigits(3);
+  const uuuu = randomDigits(4);
+  const p = randomDigits(1);
+  return `${ff}${bbb}${uuuu}${p}`;
+};
+
+/**
+ * StNr (Steuernummer).
+ *
+ * German tax number assigned by the local tax office.
+ * Regional format: 10 or 11 digits. Unified federal
+ * format: 13 digits (prefixed with a 2–4 digit BUFA
+ * code). Structure varies by federal state.
+ *
+ * The number encodes: BUFA (Bundesfinanzamtsnummer),
+ * district code, serial number, and check digit. No
+ * algorithmic check digit validation is standardised
+ * across all states; validation is format-only.
+ *
+ * @see https://de.wikipedia.org/wiki/Steuernummer
+ */
+
+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";
+
+/**
+ * Format patterns per federal state.
+ * [0] = regional format, [1] = unified (federal) format.
+ *
+ * Legend: F = finance office, B = district,
+ *         U = serial, P = check digit,
+ *         leading digits are literal.
+ */
+const STATES = {
+  "Baden-Württemberg": ["FFBBBUUUUP", "28FF0BBBUUUUP"],
+  Bayern: ["FFFBBBUUUUP", "9FFF0BBBUUUUP"],
+  Berlin: ["FFBBBUUUUP", "11FF0BBBUUUUP"],
+  Brandenburg: ["0FFBBBUUUUP", "30FF0BBBUUUUP"],
+  Bremen: ["FFBBBUUUUP", "24FF0BBBUUUUP"],
+  Hamburg: ["FFBBBUUUUP", "22FF0BBBUUUUP"],
+  Hessen: ["0FFBBBUUUUP", "26FF0BBBUUUUP"],
+  "Mecklenburg-Vorpommern": [
+    "0FFBBBUUUUP",
+    "40FF0BBBUUUUP",
+  ],
+  Niedersachsen: ["FFBBBUUUUP", "23FF0BBBUUUUP"],
+  "Nordrhein-Westfalen": ["FFFBBBBUUUP", "5FFF0BBBBUUUP"],
+  "Rheinland-Pfalz": ["FFBBBUUUUP", "27FF0BBBUUUUP"],
+  Saarland: ["0FFBBBUUUUP", "10FF0BBBUUUUP"],
+  Sachsen: ["2FFBBBUUUUP", "32FF0BBBUUUUP"],
+  "Sachsen-Anhalt": ["1FFBBBUUUUP", "31FF0BBBUUUUP"],
+  "Schleswig-Holstein": ["FFBBBUUUUP", "21FF0BBBUUUUP"],
+  Thüringen: ["1FFBBBUUUUP", "41FF0BBBUUUUP"],
+} as const;
+
+type StateName = keyof typeof STATES;
+
+/**
+ * Convert a format pattern to a regex.
+ * Literal digits match themselves; F/B/U match any
+ * digit; P (check digit) matches any digit.
+ */
+const patternToRegex = (pattern: string): RegExp => {
+  let re = "^";
+  for (const ch of pattern) {
+    if (ch >= "0" && ch <= "9") {
+      re += ch;
+    } else {
+      re += "\\d";
+    }
+  }
+  re += "$";
+  return new RegExp(re);
+};
+
+/** Pre-compiled regexes for each state + format. */
+const COMPILED: Array<{
+  state: StateName;
+  regional: RegExp;
+  regionalFmt: string;
+  federal: RegExp;
+  federalFmt: string;
+}> = (
+  Object.entries(STATES) as Array<
+    [StateName, readonly [string, string]]
+  >
+).map(([state, [regionalFmt, federalFmt]]) => ({
+  state,
+  regional: patternToRegex(regionalFmt),
+  regionalFmt,
+  federal: patternToRegex(federalFmt),
+  federalFmt,
+}));
+
+const compact = (value: string): string =>
+  clean(value, " -/.");
+
+const matchesAnyPattern = (v: string): boolean => {
+  for (const { regional, federal } of COMPILED) {
+    if (regional.test(v) || federal.test(v)) return true;
+  }
+  return false;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "German Steuernummer must contain only digits",
+    );
+  }
+
+  if (
+    v.length !== 10 &&
+    v.length !== 11 &&
+    v.length !== 13
+  ) {
+    return err(
+      "INVALID_LENGTH",
+      "German Steuernummer must be 10, 11, or 13 digits",
+    );
+  }
+
+  if (!matchesAnyPattern(v)) {
+    return err(
+      "INVALID_COMPONENT",
+      "German Steuernummer does not match any " +
+        "known state format",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+/**
+ * Format with slashes at segment boundaries.
+ * Uses the first matching state pattern to determine
+ * segment positions.
+ */
+const format = (value: string): string => {
+  const v = compact(value);
+
+  for (const entry of COMPILED) {
+    const pattern =
+      v.length === 13 ? entry.federal : entry.regional;
+    if (!pattern.test(v)) continue;
+
+    const fmt =
+      v.length === 13
+        ? entry.federalFmt
+        : entry.regionalFmt;
+
+    // Group by consecutive runs of the same letter
+    // category: literal digits, F, B, U, P
+    const segments: string[] = [];
+    let segStart = 0;
+    let prevCat = charCat(fmt[0]!);
+
+    for (let i = 1; i < fmt.length; i++) {
+      const cat = charCat(fmt[i]!);
+      if (cat !== prevCat) {
+        segments.push(v.slice(segStart, i));
+        segStart = i;
+        prevCat = cat;
+      }
+    }
+    segments.push(v.slice(segStart));
+
+    return segments.join("/");
+  }
+
+  return v;
+};
+
+const charCat = (ch: string): string => {
+  if (ch >= "0" && ch <= "9") return "L"; // literal
+  return ch; // F, B, U, P
+};
+
+/** German Tax Number (Steuernummer). */
+const stnr: Validator = {
+  name: "German Tax Number",
+  localName: "Steuernummer",
+  abbreviation: "StNr",
+  aliases: ["Steuernummer", "St.Nr."] as const,
+  candidatePattern: "\\d{2,4}/\\d{3,4}/\\d{4,5}",
+  country: "DE",
+  entityType: "any",
+  description:
+    "German tax number assigned by the local " +
+    "tax office, varies by federal state",
+  sourceUrl: "https://de.wikipedia.org/wiki/Steuernummer",
+  lengths: [10, 11, 13] as const,
+  examples: ["2181508150", "18181508155"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default stnr;
+export { compact, format, validate, generate };

package/src/de/svnr.ts

@@ -0,0 +1,162 @@
+/**
+ * SVNR (Sozialversicherungsnummer).
+ *
+ * German social insurance number. 12 characters:
+ * area number (2 digits) + date of birth (DDMMYY)
+ * + initial letter of birth name (1 letter) +
+ * serial number (2 digits) + check digit (1 digit).
+ *
+ * @see https://de.wikipedia.org/wiki/Sozialversicherungsnummer
+ */
+
+import { clean } from "#util/clean";
+import {
+  isValidDate,
+  resolveTwoDigitYear,
+} from "#util/date";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+const letterValue = (ch: string): number => {
+  const code = ch.charCodeAt(0);
+  if (code >= 65 && code <= 90) return code - 64;
+  return -1;
+};
+
+const WEIGHTS = [
+  2, 1, 2, 5, 7, 1, 2, 1, 2, 1, 2, 1,
+] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -/").toUpperCase();
+
+const computeCheck = (v: string): number => {
+  const digits: number[] = [];
+
+  for (let i = 0; i < 8; i++) {
+    digits.push(Number(v[i]));
+  }
+
+  const lv = letterValue(v[8]!);
+  digits.push(Math.floor(lv / 10));
+  digits.push(lv % 10);
+
+  digits.push(Number(v[9]));
+  digits.push(Number(v[10]));
+
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    const product = digits[i]! * WEIGHTS[i]!;
+    if (product >= 10) {
+      sum += Math.floor(product / 10) + (product % 10);
+    } else {
+      sum += product;
+    }
+  }
+
+  return sum % 10;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "German SVNR must be 12 characters",
+    );
+  }
+
+  if (!/^\d{8}[A-Z]\d{3}$/.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "German SVNR must be 8 digits, 1 letter, " +
+        "3 digits",
+    );
+  }
+
+  const dd = Number(v.slice(2, 4));
+  const mm = Number(v.slice(4, 6));
+  const yy = Number(v.slice(6, 8));
+
+  const year = resolveTwoDigitYear(yy);
+
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "German SVNR contains an invalid birth date",
+    );
+  }
+
+  const expected = computeCheck(v);
+  const actual = Number(v[11]);
+
+  if (expected !== actual) {
+    return err(
+      "INVALID_CHECKSUM",
+      "German SVNR check digit mismatch",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return (
+    `${v.slice(0, 2)} ${v.slice(2, 8)}` +
+    ` ${v.slice(8, 9)} ${v.slice(9, 11)}` +
+    ` ${v.slice(11)}`
+  );
+};
+
+/** Generate a random valid German SVNR. */
+const generate = (): string => {
+  for (;;) {
+    const area = String(randomInt(1, 99)).padStart(2, "0");
+    const dd = String(randomInt(1, 28)).padStart(2, "0");
+    const mm = String(randomInt(1, 12)).padStart(2, "0");
+    const yy = String(randomInt(40, 99)).padStart(2, "0");
+    const letter = String.fromCharCode(
+      65 + randomInt(0, 25),
+    );
+    const serial = String(randomInt(0, 49)).padStart(
+      2,
+      "0",
+    );
+    const partial = area + dd + mm + yy + letter + serial;
+    const c = partial + String(computeCheck(partial));
+    if (validate(c).valid) return c;
+  }
+};
+
+/** German Social Insurance Number. */
+const svnr: Validator = {
+  name: "German Social Insurance Number",
+  localName: "Sozialversicherungsnummer",
+  abbreviation: "SVNR",
+  aliases: [
+    "Sozialversicherungsnummer",
+    "SVNR",
+    "Versicherungsnummer",
+  ] as const,
+  candidatePattern: "\\d{2}\\s?\\d{6}\\s?[A-Z]\\s?\\d{3}",
+  country: "DE",
+  entityType: "person",
+  description:
+    "German social insurance number encoding " +
+    "birth date and name initial",
+  sourceUrl:
+    "https://de.wikipedia.org/wiki/" +
+    "Sozialversicherungsnummer",
+  lengths: [12] as const,
+  examples: ["12010188M011"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default svnr;
+export { compact, format, validate, generate };

package/src/de/vat.ts

@@ -0,0 +1,98 @@
+/**
+ * USt-IdNr. (Umsatzsteuer-Identifikationsnummer).
+ *
+ * German VAT identification number. Format:
+ * "DE" + 9 digits. The last digit is a check
+ * digit computed using ISO 7064 Mod 11,10.
+ *
+ * @see https://www.bzst.de/DE/Unternehmen/Identifikationsnummern/Umsatzsteuer-Identifikationsnummer/umsatzsteuer-identifikationsnummer_node.html
+ * @see https://www.bzst.de/SharedDocs/Downloads/DE/Merkblaetter/ust_idnr_aufbau.pdf
+ */
+
+import {
+  mod1110checkDigit,
+  mod1110validate,
+} from "#checksums/mod1110";
+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 => {
+  const v = clean(value, " -/");
+  if (v.startsWith("DE") || v.startsWith("de")) {
+    return v.slice(2);
+  }
+  return v;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "German VAT number must be 9 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "German VAT number must contain only digits",
+    );
+  }
+  if (v[0] === "0") {
+    return err(
+      "INVALID_COMPONENT",
+      "German VAT number cannot start with 0",
+    );
+  }
+  if (!mod1110validate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "German VAT number check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `DE${compact(value)}`;
+
+/** Generate a random valid German VAT number. */
+const generate = (): string => {
+  const first = String(randomInt(1, 9));
+  const rest = randomDigits(7);
+  const payload = `${first}${rest}`;
+  const check = mod1110checkDigit(payload);
+  return `${payload}${String(check)}`;
+};
+
+/** German VAT Identification Number. */
+const vat: Validator = {
+  name: "German VAT Number",
+  localName: "Umsatzsteuer-Identifikationsnummer",
+  abbreviation: "USt-IdNr.",
+  aliases: [
+    "USt-IdNr",
+    "Umsatzsteuer-Identifikationsnummer",
+    "VAT DE",
+  ] as const,
+  candidatePattern: "DE\\d{9}",
+  country: "DE",
+  entityType: "company",
+  description:
+    "German VAT ID issued by the Federal Tax Office (BZSt)",
+  sourceUrl:
+    "https://www.bzst.de/DE/Unternehmen/Identifikationsnummern/Umsatzsteuer-Identifikationsnummer/umsatzsteuer-identifikationsnummer_node.html",
+  lengths: [9] as const,
+  examples: ["136695976"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, generate, validate };