@stll/stdnum 0.0.1

package/src/fr/siren.ts

@@ -0,0 +1,79 @@
+/**
+ * SIREN (Système d'Identification du Répertoire
+ * des Entreprises).
+ *
+ * French company identification number. 9 digits
+ * validated with standard Luhn algorithm.
+ *
+ * @see https://www.insee.fr/fr/information/2549588
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+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 !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "SIREN must be exactly 9 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "SIREN must contain only digits",
+    );
+  }
+  if (!luhnValidate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "SIREN fails Luhn check",
+    );
+  }
+  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)}`;
+};
+
+/** Generate a random valid French SIREN. */
+const generate = (): string => {
+  const payload = randomDigits(8);
+  const cs = luhnChecksum(payload + "0");
+  return payload + String((10 - cs) % 10);
+};
+
+/** French Company Identification Number. */
+const siren: Validator = {
+  name: "French Company ID",
+  localName:
+    "Système d'Identification du Répertoire des Entreprises",
+  abbreviation: "SIREN",
+  aliases: ["SIREN", "numéro SIREN"] as const,
+  candidatePattern: "\\d{3}\\s?\\d{3}\\s?\\d{3}",
+  country: "FR",
+  entityType: "company",
+  sourceUrl: "https://www.insee.fr/fr/information/2549588",
+  examples: ["552008443"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default siren;
+export { compact, format, validate, generate };

package/src/fr/siret.ts

@@ -0,0 +1,122 @@
+/**
+ * SIRET (Système d'Identification du Répertoire
+ * des Établissements).
+ *
+ * French establishment identification number.
+ * 14 digits: SIREN (9) + NIC (5). Validated
+ * with Luhn, with a special case for La Poste.
+ *
+ * @see https://www.insee.fr/fr/information/2549588
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+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, " -.");
+
+/**
+ * La Poste SIRET uses digit sum % 5 instead of
+ * Luhn, EXCEPT the head office (35600000000048)
+ * which uses standard Luhn.
+ */
+const isLaPoste = (v: string): boolean =>
+  v.startsWith("356000000") && v !== "35600000000048";
+
+const digitSum = (v: string): number => {
+  let sum = 0;
+  for (let i = 0; i < v.length; i++) {
+    sum += Number(v[i]);
+  }
+  return sum;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 14) {
+    return err(
+      "INVALID_LENGTH",
+      "SIRET must be exactly 14 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "SIRET must contain only digits",
+    );
+  }
+
+  // Validate SIREN part (first 9 digits)
+  const siren = v.slice(0, 9);
+  if (!luhnValidate(siren) && !isLaPoste(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "SIRET SIREN part fails Luhn check",
+    );
+  }
+
+  // La Poste: digit sum mod 5
+  if (isLaPoste(v)) {
+    if (digitSum(v) % 5 !== 0) {
+      return err(
+        "INVALID_CHECKSUM",
+        "SIRET La Poste digit sum check failed",
+      );
+    }
+  } else {
+    // Standard: full 14-digit Luhn
+    if (!luhnValidate(v)) {
+      return err(
+        "INVALID_CHECKSUM",
+        "SIRET fails Luhn check",
+      );
+    }
+  }
+
+  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, 9)} ${v.slice(9)}`;
+};
+
+/** Generate a random valid French SIRET. */
+const generate = (): string => {
+  const sp = randomDigits(8);
+  const sc = luhnChecksum(sp + "0");
+  const siren = sp + String((10 - sc) % 10);
+  const nic = randomDigits(4);
+  const payload = siren + nic;
+  const cs = luhnChecksum(payload + "0");
+  return payload + String((10 - cs) % 10);
+};
+
+/** French Establishment Identification Number. */
+const siret: Validator = {
+  name: "French Establishment ID",
+  localName:
+    "Système d'Identification du Répertoire des Établissements",
+  abbreviation: "SIRET",
+  aliases: ["SIRET", "numéro SIRET"] as const,
+  candidatePattern: "\\d{3}\\s?\\d{3}\\s?\\d{3}\\s?\\d{5}",
+  country: "FR",
+  entityType: "company",
+  sourceUrl: "https://www.insee.fr/fr/information/2549588",
+  examples: ["73282932000074"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default siret;
+export { compact, format, validate, generate };

package/src/fr/tva.ts

@@ -0,0 +1,146 @@
+/**
+ * n° TVA (Numéro de TVA intracommunautaire).
+ *
+ * French VAT number. 11 characters: 2-char
+ * check prefix + 9-digit SIREN. The prefix
+ * can be numeric (old style) or alphanumeric
+ * (new style, letters from a restricted
+ * alphabet excluding I and O).
+ *
+ * @see https://www.economie.gouv.fr/
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+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 ALPHABET = "0123456789ABCDEFGHJKLMNPQRSTUVWXYZ";
+
+const compact = (value: string): string => {
+  let v = clean(value, " -.");
+  if (v.startsWith("FR") || v.startsWith("fr")) {
+    v = v.slice(2);
+  }
+  return v.toUpperCase();
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "French TVA must be 11 characters",
+    );
+  }
+
+  const prefix = v.slice(0, 2);
+  const siren = v.slice(2);
+
+  if (!isdigits(siren)) {
+    return err(
+      "INVALID_FORMAT",
+      "French TVA SIREN part must be digits",
+    );
+  }
+
+  // Validate prefix characters are in alphabet
+  const p0 = prefix[0] ?? "";
+  const p1 = prefix[1] ?? "";
+  if (
+    ALPHABET.indexOf(p0) < 0 ||
+    ALPHABET.indexOf(p1) < 0
+  ) {
+    return err(
+      "INVALID_FORMAT",
+      "French TVA prefix contains invalid chars",
+    );
+  }
+
+  // SIREN validation (skip Monaco: starts with 000)
+  if (!siren.startsWith("000") && !luhnValidate(siren)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "French TVA SIREN part fails Luhn check",
+    );
+  }
+
+  const c0 = ALPHABET.indexOf(p0);
+  const c1 = ALPHABET.indexOf(p1);
+
+  if (c0 < 10 && c1 < 10) {
+    // Old-style: both digits numeric
+    const check = Number(prefix);
+    const expected = Number(siren + "12") % 97;
+    if (check !== expected) {
+      return err(
+        "INVALID_CHECKSUM",
+        "French TVA check digits mismatch",
+      );
+    }
+  } else {
+    // New-style: at least one letter
+    let cvalue: number;
+    if (c0 < 10) {
+      cvalue = c0 * 24 + c1 - 10;
+    } else {
+      cvalue = c0 * 34 + c1 - 100;
+    }
+    const sirenNum = Number(siren);
+    if (
+      (sirenNum + 1 + Math.floor(cvalue / 11)) % 11 !==
+      cvalue % 11
+    ) {
+      return err(
+        "INVALID_CHECKSUM",
+        "French TVA check digits mismatch",
+      );
+    }
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `FR${compact(value)}`;
+
+/** Generate a random valid French TVA. */
+const generate = (): string => {
+  const sp = randomDigits(8);
+  const cs = luhnChecksum(sp + "0");
+  const siren = sp + String((10 - cs) % 10);
+  const prefix = String(
+    (12 + 3 * (Number(siren) % 97)) % 97,
+  ).padStart(2, "0");
+  return prefix + siren;
+};
+
+/** French VAT Number. */
+const tva: Validator = {
+  name: "French VAT Number",
+  localName: "Numéro de TVA intracommunautaire",
+  abbreviation: "TVA",
+  aliases: [
+    "numéro de TVA",
+    "TVA intracommunautaire",
+    "FR VAT",
+  ] as const,
+  candidatePattern: "FR[A-Z0-9]{2}\\d{9}",
+  country: "FR",
+  entityType: "company",
+  sourceUrl: "https://www.economie.gouv.fr/",
+  examples: ["40303265045", "K7399859412"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default tva;
+export { compact, format, validate, generate };

package/src/gb/mod.ts

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

package/src/gb/nino.ts

@@ -0,0 +1,153 @@
+/** Generate a random valid UK NINO. */
+const generate = (): string => {
+  const validFirst = "ABCEGHJKLMNOPRSTWXYZ";
+  const validSecond = "ABCEGHJKLMNPRSTWXYZ";
+  const suffixes = "ABCD";
+  let first: string;
+  let second: string;
+  let prefix: string;
+  do {
+    first =
+      validFirst[randomInt(0, validFirst.length - 1)]!;
+    second =
+      validSecond[randomInt(0, validSecond.length - 1)]!;
+    prefix = first + second;
+  } while (INVALID_PREFIX.has(prefix));
+  const digits = randomDigits(6);
+  const suffix =
+    suffixes[randomInt(0, suffixes.length - 1)]!;
+  return `${prefix}${digits}${suffix}`;
+};
+
+/**
+ * NINO (National Insurance Number).
+ *
+ * UK National Insurance Number. Format: 2 letters
+ * + 6 digits + 1 suffix letter (A, B, C, or D).
+ * Validated by format and prefix rules only; there
+ * is no checksum.
+ *
+ * @see https://www.gov.uk/hmrc-internal-manuals/national-insurance-manual/nim39110
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+const INVALID_FIRST = new Set([
+  "D",
+  "F",
+  "I",
+  "Q",
+  "U",
+  "V",
+]);
+
+const INVALID_SECOND = new Set([
+  "D",
+  "F",
+  "I",
+  "O",
+  "Q",
+  "U",
+  "V",
+]);
+
+const INVALID_PREFIX = new Set([
+  "BG",
+  "GB",
+  "NK",
+  "KN",
+  "TN",
+  "NT",
+  "ZZ",
+]);
+
+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",
+      "UK NINO must be 9 characters",
+    );
+  }
+
+  if (!/^[A-Z]{2}\d{6}[A-D]$/.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "UK NINO must be 2 letters, 6 digits, " +
+        "then A/B/C/D",
+    );
+  }
+
+  const first = v[0]!;
+  const second = v[1]!;
+  const prefix = v.slice(0, 2);
+
+  if (INVALID_FIRST.has(first)) {
+    return err(
+      "INVALID_COMPONENT",
+      `UK NINO first letter cannot be ${first}`,
+    );
+  }
+
+  if (INVALID_SECOND.has(second)) {
+    return err(
+      "INVALID_COMPONENT",
+      `UK NINO second letter cannot be ${second}`,
+    );
+  }
+
+  if (INVALID_PREFIX.has(prefix)) {
+    return err(
+      "INVALID_COMPONENT",
+      `UK NINO prefix ${prefix} is not allowed`,
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return (
+    `${v.slice(0, 2)} ${v.slice(2, 4)}` +
+    ` ${v.slice(4, 6)} ${v.slice(6, 8)}` +
+    ` ${v.slice(8)}`
+  );
+};
+
+/** UK National Insurance Number. */
+const nino: Validator = {
+  name: "UK National Insurance Number",
+  localName: "National Insurance Number",
+  abbreviation: "NINO",
+  aliases: [
+    "National Insurance number",
+    "NINO",
+    "NI number",
+  ] as const,
+  candidatePattern: "[A-Z]{2}\\d{6}[A-Z]",
+  country: "GB",
+  entityType: "person",
+  description:
+    "UK National Insurance Number for tax " +
+    "and benefits",
+  sourceUrl:
+    "https://www.gov.uk/hmrc-internal-manuals/" +
+    "national-insurance-manual/nim39110",
+  lengths: [9] as const,
+  examples: ["AB123456C"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nino;
+export { compact, format, validate, generate };

package/src/gb/sedol.ts

@@ -0,0 +1,137 @@
+/**
+ * SEDOL (Stock Exchange Daily Official List number).
+ *
+ * 7-character security identifier used in the UK and
+ * Ireland, assigned by the London Stock Exchange.
+ * Consists of 6 alphanumeric characters (vowels
+ * excluded) followed by a weighted mod-10 check
+ * digit.
+ *
+ * @see https://en.wikipedia.org/wiki/SEDOL
+ */
+
+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";
+
+/**
+ * Allowed characters in a SEDOL: digits and
+ * consonants only (vowels are never used).
+ * Spaces occupy vowel positions (A=10, E=14,
+ * I=18, O=24, U=30) so that indexOf returns
+ * the correct SEDOL weight for each consonant.
+ */
+const ALPHABET = "0123456789 BCD FGH JKLMN PQRST VWXYZ";
+
+const WEIGHTS = [1, 3, 1, 7, 3, 9] as const;
+
+const calcCheckDigit = (number: string): string => {
+  if (number.length !== 6) {
+    throw new Error(
+      "calcCheckDigit requires a 6-character " +
+        "SEDOL prefix",
+    );
+  }
+  let sum = 0;
+  for (let i = 0; i < 6; i++) {
+    const ch = number[i]!;
+    const val = ALPHABET.indexOf(ch);
+    if (val < 0) {
+      throw new Error(`Invalid SEDOL character: ${ch}`);
+    }
+    // SAFETY: weights length matches loop bound
+    sum += WEIGHTS[i]! * val;
+  }
+  return String((10 - (sum % 10)) % 10);
+};
+
+const compact = (value: string): string =>
+  clean(value, " ").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 7) {
+    return err(
+      "INVALID_LENGTH",
+      "SEDOL must be exactly 7 characters",
+    );
+  }
+
+  for (const ch of v) {
+    if (!ALPHABET.includes(ch)) {
+      return err(
+        "INVALID_FORMAT",
+        "SEDOL contains invalid character: " +
+          "vowels are not allowed",
+      );
+    }
+  }
+
+  // Old-style SEDOLs are fully numeric; new-style
+  // SEDOLs start with a letter. A number that starts
+  // with a digit but contains letters is invalid.
+  if (isdigits(v[0]!) && !isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Numeric-prefix SEDOL must be fully " +
+        "numeric (old-style)",
+    );
+  }
+
+  if (calcCheckDigit(v.slice(0, 6)) !== v[6]) {
+    return err(
+      "INVALID_CHECKSUM",
+      "SEDOL check digit mismatch",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid SEDOL. */
+const generate = (): string => {
+  const consonants = "BCDFGHJKLMNPQRSTVWXYZ";
+  const chars = "0123456789BCDFGHJKLMNPQRSTVWXYZ";
+  const first =
+    consonants[randomInt(0, consonants.length - 1)]!;
+  let payload = first;
+  for (let i = 1; i < 6; i++)
+    payload += chars[randomInt(0, chars.length - 1)]!;
+  return payload + calcCheckDigit(payload);
+};
+
+/** Stock Exchange Daily Official List number. */
+const sedol: Validator = {
+  name: "Stock Exchange Daily Official List number",
+  localName: "Stock Exchange Daily Official List number",
+  abbreviation: "SEDOL",
+  aliases: [
+    "SEDOL",
+    "Stock Exchange Daily Official List",
+  ] as const,
+  candidatePattern: "[B-DF-HJ-NP-TV-Z0-9]{6}\\d",
+  country: "GB",
+  entityType: "any",
+  sourceUrl: "https://en.wikipedia.org/wiki/SEDOL",
+  lengths: [7] as const,
+  examples: ["B15KXQ8"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default sedol;
+export {
+  calcCheckDigit,
+  compact,
+  format,
+  validate,
+  generate,
+};