@stll/stdnum 0.0.1

package/src/it/codicefiscale.ts

@@ -0,0 +1,290 @@
+/**
+ * Codice Fiscale (Italian tax code).
+ *
+ * 16-character alphanumeric code encoding name,
+ * birth date, gender, and birthplace. The last
+ * character is a check letter computed using
+ * odd/even position value tables.
+ *
+ * Supports omocodia: when two people share the
+ * same code, the tax office replaces digit
+ * positions with letters from the set LMNPQRSTUV
+ * (L=0, M=1, N=2, P=3, Q=4, R=5, S=6, T=7,
+ * U=8, V=9). Only these 10 letters are valid
+ * substitutes at digit positions.
+ *
+ * Also accepts 11-digit numbers (delegates to
+ * Partita IVA validation).
+ *
+ * @see https://www.agenziaentrate.gov.it/
+ * @see https://it.wikipedia.org/wiki/Codice_fiscale#Omocodia
+ */
+
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  Validator,
+} from "../types";
+import { validate as validateIva } from "./iva";
+
+// Values for odd-positioned characters (0-based
+// index 0, 2, 4, ...)
+const ODD: Record<string, number> = {
+  "0": 1,
+  "1": 0,
+  "2": 5,
+  "3": 7,
+  "4": 9,
+  "5": 13,
+  "6": 15,
+  "7": 17,
+  "8": 19,
+  "9": 21,
+  A: 1,
+  B: 0,
+  C: 5,
+  D: 7,
+  E: 9,
+  F: 13,
+  G: 15,
+  H: 17,
+  I: 19,
+  J: 21,
+  K: 2,
+  L: 4,
+  M: 18,
+  N: 20,
+  O: 11,
+  P: 3,
+  Q: 6,
+  R: 8,
+  S: 12,
+  T: 14,
+  U: 16,
+  V: 10,
+  W: 22,
+  X: 25,
+  Y: 24,
+  Z: 23,
+};
+
+// Values for even-positioned characters (0-based
+// index 1, 3, 5, ...)
+const EVEN: Record<string, number> = {
+  "0": 0,
+  "1": 1,
+  "2": 2,
+  "3": 3,
+  "4": 4,
+  "5": 5,
+  "6": 6,
+  "7": 7,
+  "8": 8,
+  "9": 9,
+  A: 0,
+  B: 1,
+  C: 2,
+  D: 3,
+  E: 4,
+  F: 5,
+  G: 6,
+  H: 7,
+  I: 8,
+  J: 9,
+  K: 10,
+  L: 11,
+  M: 12,
+  N: 13,
+  O: 14,
+  P: 15,
+  Q: 16,
+  R: 17,
+  S: 18,
+  T: 19,
+  U: 20,
+  V: 21,
+  W: 22,
+  X: 23,
+  Y: 24,
+  Z: 25,
+};
+
+const CHECK_LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+/** Omocodia letter-to-digit mapping. */
+const OMOCODIA: Record<string, string> = {
+  L: "0",
+  M: "1",
+  N: "2",
+  P: "3",
+  Q: "4",
+  R: "5",
+  S: "6",
+  T: "7",
+  U: "8",
+  V: "9",
+};
+
+/** Month letter to 1-based month number. */
+const MONTH_LETTERS: Record<string, number> = {
+  A: 1,
+  B: 2,
+  C: 3,
+  D: 4,
+  E: 5,
+  H: 6,
+  L: 7,
+  M: 8,
+  P: 9,
+  R: 10,
+  S: 11,
+  T: 12,
+};
+
+const decodeCfDigit = (ch: string): number => {
+  const mapped = OMOCODIA[ch];
+  if (mapped !== undefined) return Number(mapped);
+  return Number(ch);
+};
+
+const compact = (value: string): string =>
+  clean(value, " -").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  // 11-digit: delegate to Partita IVA
+  if (v.length === 11 && isdigits(v)) {
+    return validateIva(v);
+  }
+
+  if (v.length !== 16) {
+    return err(
+      "INVALID_LENGTH",
+      "Codice Fiscale must be 16 characters",
+    );
+  }
+  // Structural format: 6 letters + 2 alphanumeric
+  // + 1 letter (month) + 2 alphanumeric + 1 letter
+  // (municipality) + 3 alphanumeric + 1 check letter
+  // The "alphanumeric" positions accept omocodia
+  // substitution letters (LMNPQRSTUV for 0-9)
+  if (
+    // Omocodia: digits can be replaced with
+    // LMNPQRSTUV only (not arbitrary letters)
+    !/^[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]$/.test(
+      v,
+    )
+  ) {
+    return err(
+      "INVALID_FORMAT",
+      "Codice Fiscale format is invalid",
+    );
+  }
+
+  // Compute check letter
+  let sum = 0;
+  for (let i = 0; i < 15; i++) {
+    const ch = v[i];
+    if (ch === undefined) continue;
+    if (i % 2 === 0) {
+      // Odd position (1-based) = even index
+      const val = ODD[ch];
+      if (val === undefined) {
+        return err(
+          "INVALID_FORMAT",
+          "Codice Fiscale contains invalid char",
+        );
+      }
+      sum += val;
+    } else {
+      const val = EVEN[ch];
+      if (val === undefined) {
+        return err(
+          "INVALID_FORMAT",
+          "Codice Fiscale contains invalid char",
+        );
+      }
+      sum += val;
+    }
+  }
+
+  const expected = CHECK_LETTERS[sum % 26];
+  if (expected !== v[15]) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Codice Fiscale check letter mismatch",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Extract birth date and gender from a Codice Fiscale.
+ * Returns null if the value is not valid or is an
+ * 11-digit Partita IVA (no personal data embedded).
+ */
+const parse = (value: string): ParsedPersonId | null => {
+  const result = validate(value);
+  if (!result.valid) return null;
+
+  const v = result.compact;
+  if (v.length !== 16) return null;
+
+  const yy =
+    decodeCfDigit(v.charAt(6)) * 10 +
+    decodeCfDigit(v.charAt(7));
+  const month = MONTH_LETTERS[v.charAt(8)];
+  if (month === undefined) return null;
+  let dd =
+    decodeCfDigit(v.charAt(9)) * 10 +
+    decodeCfDigit(v.charAt(10));
+
+  const gender = dd > 40 ? "female" : "male";
+  if (dd > 40) dd -= 40;
+
+  const currentYear = new Date().getFullYear();
+  let year = 2000 + yy;
+  if (year > currentYear) year -= 100;
+
+  return {
+    birthDate: new Date(year, month - 1, dd),
+    gender,
+  };
+};
+
+/** Italian Tax Code. */
+const codiceFiscale: Validator = {
+  name: "Italian Tax Code",
+  localName: "Codice Fiscale",
+  abbreviation: "CF",
+  aliases: [
+    "codice fiscale",
+    "C.F.",
+    "CF",
+    "cod. fisc.",
+    "fiscal code",
+  ] as const,
+  candidatePattern:
+    "[A-Z]{6}\\d{2}[A-Z]\\d{2}[A-Z]\\d{3}[A-Z]",
+  country: "IT",
+  entityType: "person",
+  description:
+    "Personal/company tax code (16-char personal, 11-digit company)",
+  sourceUrl: "https://www.agenziaentrate.gov.it/",
+  lengths: [11, 16] as const,
+  examples: ["RCCMNL83S18D969H"] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default codiceFiscale;
+export { compact, format, parse, validate };

package/src/it/iva.ts

@@ -0,0 +1,115 @@
+/**
+ * Partita IVA (Italian VAT number).
+ *
+ * 11 digits: 7-digit company ID + 3-digit
+ * province code + Luhn check digit.
+ *
+ * @see https://www.agenziaentrate.gov.it/
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+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 VALID_PROVINCES = new Set([
+  ...Array.from({ length: 100 }, (_, i) =>
+    String(i + 1).padStart(3, "0"),
+  ),
+  "120",
+  "121",
+  "888",
+  "999",
+]);
+
+const compact = (value: string): string => {
+  let v = clean(value, " -");
+  if (v.startsWith("IT") || v.startsWith("it")) {
+    v = v.slice(2);
+  }
+  return v;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "Partita IVA must be exactly 11 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Partita IVA must contain only digits",
+    );
+  }
+  // First 7 digits cannot all be zero
+  if (/^0{7}/.test(v)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Partita IVA company ID cannot be all zeros",
+    );
+  }
+  // Province code validation
+  const province = v.slice(7, 10);
+  if (!VALID_PROVINCES.has(province)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Partita IVA province code is invalid",
+    );
+  }
+  if (!luhnValidate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Partita IVA fails Luhn check",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `IT${compact(value)}`;
+
+/** Generate a random valid Italian Partita IVA. */
+const generate = (): string => {
+  const company = randomDigits(7);
+  const province = String(randomInt(1, 100)).padStart(
+    3,
+    "0",
+  );
+  const payload = company + province;
+  const cs = luhnChecksum(payload + "0");
+  return payload + String((10 - cs) % 10);
+};
+
+/** Italian VAT Number. */
+const iva: Validator = {
+  name: "Italian VAT Number",
+  localName: "Partita IVA",
+  abbreviation: "P.IVA",
+  aliases: [
+    "partita IVA",
+    "P.IVA",
+    "P. IVA",
+    "VAT IT",
+  ] as const,
+  candidatePattern: "IT\\d{11}",
+  country: "IT",
+  entityType: "company",
+  sourceUrl: "https://www.agenziaentrate.gov.it/",
+  examples: ["00743110157"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default iva;
+export { compact, format, validate, generate };

package/src/it/mod.ts

@@ -0,0 +1,2 @@
+export { default as codiceFiscale } from "./codicefiscale";
+export { default as iva } from "./iva";

package/src/jp/cn.ts

@@ -0,0 +1,91 @@
+/**
+ * CN (Corporate Number, 法人番号).
+ *
+ * Japanese Corporate Number. 13 digits with a
+ * check digit based on modulus 9. Assigned by the
+ * National Tax Agency.
+ *
+ * @see https://en.wikipedia.org/wiki/Corporate_Number_(Japan)
+ */
+
+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, " -");
+
+/**
+ * Compute the check digit for a 12-digit payload.
+ * Weights alternate [1,2,1,2,...] from the
+ * rightmost digit of the payload.
+ */
+const checkDigit = (payload: string): number => {
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    const digit = Number(payload[11 - i]);
+    const weight = i % 2 === 0 ? 1 : 2;
+    sum += digit * weight;
+  }
+  return 9 - (sum % 9);
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 13) {
+    return err(
+      "INVALID_LENGTH",
+      "Corporate Number must be exactly 13 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Corporate Number must contain only digits",
+    );
+  }
+  const expected = checkDigit(v.slice(1));
+  if (expected !== Number(v[0])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Corporate Number check digit does not match",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Corporate Number. */
+const generate = (): string => {
+  const payload = randomDigits(12);
+  const check = checkDigit(payload);
+  return `${String(check)}${payload}`;
+};
+
+/** Japanese Corporate Number. */
+const cn: Validator = {
+  name: "Japanese Corporate Number",
+  localName: "法人番号",
+  abbreviation: "CN",
+  aliases: ["法人番号", "Corporate Number"] as const,
+  candidatePattern: "\\d{13}",
+  country: "JP",
+  entityType: "company",
+  description:
+    "13-digit corporate identifier assigned by the National Tax Agency",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Corporate_Number_(Japan)",
+  lengths: [13] as const,
+  examples: ["5835678256246", "2021001052596"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default cn;
+export { compact, format, generate, validate };

package/src/jp/mod.ts

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

package/src/jp/mynumber.ts

@@ -0,0 +1,103 @@
+/**
+ * My Number (Individual Number, マイナンバー).
+ *
+ * Japanese Individual Number. 12 digits with a
+ * mod 11 check digit. Assigned to every resident
+ * of Japan for tax and social security purposes.
+ * Contains no encoded personal information.
+ *
+ * @see https://en.wikipedia.org/wiki/Individual_Number
+ */
+
+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 WEIGHTS = [6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+
+/**
+ * Compute the check digit for an 11-digit payload.
+ * remainder <= 1 yields 0; otherwise 11 - remainder.
+ */
+const checkDigit = (payload: string): number => {
+  let sum = 0;
+  for (let i = 0; i < 11; i++) {
+    sum += (WEIGHTS[i] ?? 0) * Number(payload.charAt(i));
+  }
+  const remainder = sum % 11;
+  return remainder <= 1 ? 0 : 11 - remainder;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "My Number must be exactly 12 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "My Number must contain only digits",
+    );
+  }
+  const expected = checkDigit(v.slice(0, 11));
+  if (expected !== Number(v[11])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "My Number check digit does not match",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 12) {
+    return `${v.slice(0, 4)} ${v.slice(4, 8)} ${v.slice(8)}`;
+  }
+  return v;
+};
+
+/** Generate a random valid My Number. */
+const generate = (): string => {
+  const payload = randomDigits(11);
+  const check = checkDigit(payload);
+  return `${payload}${String(check)}`;
+};
+
+/** Japanese Individual Number (My Number). */
+const mynumber: Validator = {
+  name: "Japanese Individual Number",
+  localName: "マイナンバー",
+  abbreviation: "My Number",
+  aliases: [
+    "My Number",
+    "マイナンバー",
+    "個人番号",
+  ] as const,
+  candidatePattern: "\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}",
+  country: "JP",
+  entityType: "person",
+  description:
+    "12-digit personal identifier for tax" +
+    " and social security",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Individual_Number",
+  lengths: [12] as const,
+  examples: ["123456789018", "000000000019"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default mynumber;
+export { compact, format, generate, validate };

package/src/kr/brn.ts

@@ -0,0 +1,101 @@
+/** Generate a random valid Korean BRN. */
+const generate = (): string => {
+  const office = String(randomInt(101, 999));
+  let bizType: string;
+  do {
+    bizType = randomDigits(2);
+  } while (bizType === "00");
+  let serial: string;
+  do {
+    serial = randomDigits(4);
+  } while (serial === "0000");
+  const last = randomDigits(1);
+  return `${office}${bizType}${serial}${last}`;
+};
+
+/**
+ * BRN (Business Registration Number, 사업자등록번호).
+ *
+ * Korean Business Registration Number. 10 digits
+ * formatted as XXX-XX-XXXXX. Validated by component
+ * checks (tax office, business type, serial).
+ *
+ * @see https://en.wikipedia.org/wiki/Business_registration_number_(South_Korea)
+ */
+
+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 =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "BRN must be exactly 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "BRN must contain only digits",
+    );
+  }
+  // Tax office number must be >= 101
+  if (v.slice(0, 3) < "101") {
+    return err(
+      "INVALID_COMPONENT",
+      "BRN tax office code must be >= 101",
+    );
+  }
+  // Business type must not be 00
+  if (v.slice(3, 5) === "00") {
+    return err(
+      "INVALID_COMPONENT",
+      "BRN business type must not be 00",
+    );
+  }
+  // Serial part must not be 0000
+  if (v.slice(5, 9) === "0000") {
+    return err(
+      "INVALID_COMPONENT",
+      "BRN serial must not be 0000",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 3)}-${v.slice(3, 5)}-${v.slice(5)}`;
+};
+
+/** Korean Business Registration Number. */
+const brn: Validator = {
+  name: "Korean Business Registration Number",
+  localName: "사업자등록번호",
+  abbreviation: "BRN",
+  aliases: ["사업자등록번호", "BRN"] as const,
+  candidatePattern: "\\d{3}-?\\d{2}-?\\d{5}",
+  country: "KR",
+  entityType: "company",
+  description:
+    "10-digit business identifier issued by the National Tax Service",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Business_registration_number_(South_Korea)",
+  lengths: [10] as const,
+  examples: ["1168200131", "2208162517"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default brn;
+export { compact, format, validate, generate };

package/src/kr/mod.ts

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