@stll/stdnum 0.0.1

package/src/ca/sin.ts

@@ -0,0 +1,91 @@
+/**
+ * SIN (Canadian Social Insurance Number).
+ *
+ * 9-digit identifier with Luhn checksum. First
+ * digit cannot be 0 or 8.
+ *
+ * @see https://www.canada.ca/en/employment-social-development/services/sin.html
+ * @see https://en.wikipedia.org/wiki/Social_Insurance_Number
+ */
+
+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 compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "SIN must contain only digits",
+    );
+  }
+  if (v.length !== 9) {
+    return err("INVALID_LENGTH", "SIN must be 9 digits");
+  }
+  if (v[0] === "0" || v[0] === "8") {
+    return err(
+      "INVALID_COMPONENT",
+      "SIN cannot start with 0 or 8",
+    );
+  }
+  if (!luhnValidate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "SIN Luhn check digit mismatch",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 9) {
+    return `${v.slice(0, 3)}-${v.slice(3, 6)}-${v.slice(6)}`;
+  }
+  return v;
+};
+
+/** Generate a random valid Canadian SIN. */
+const generate = (): string => {
+  const first = String(randomInt(1, 7));
+  const payload = first + randomDigits(7);
+  const cs = luhnChecksum(payload + "0");
+  return payload + String((10 - cs) % 10);
+};
+
+/** Canadian Social Insurance Number. */
+const sin: Validator = {
+  name: "Social Insurance Number",
+  localName: "Social Insurance Number",
+  abbreviation: "SIN",
+  aliases: [
+    "SIN",
+    "Social Insurance Number",
+    "NAS",
+  ] as const,
+  candidatePattern: "\\d{3}-?\\d{3}-?\\d{3}",
+  country: "CA",
+  entityType: "person",
+  sourceUrl:
+    "https://www.canada.ca/en/employment-social-development/services/sin.html",
+  examples: ["123456782"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default sin;
+export { compact, format, validate, generate };

package/src/ch/mod.ts

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

package/src/ch/ssn.ts

@@ -0,0 +1,95 @@
+/**
+ * Swiss Social Security Number (AHV/AVS).
+ *
+ * 13 digits starting with 756. Uses EAN-13 checksum:
+ * alternating weights (1, 3) from left, check digit
+ * is (10 - sum % 10) % 10.
+ *
+ * @see https://www.bsv.admin.ch/
+ */
+
+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 !== 13) {
+    return err(
+      "INVALID_LENGTH",
+      "Swiss SSN must be 13 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Swiss SSN must contain only digits",
+    );
+  }
+  if (!v.startsWith("756")) {
+    return err(
+      "INVALID_COMPONENT",
+      "Swiss SSN must start with 756",
+    );
+  }
+
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    const weight = i % 2 === 0 ? 1 : 3;
+    sum += Number(v[i]) * weight;
+  }
+  const check = (10 - (sum % 10)) % 10;
+  if (check !== Number(v[12])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Swiss SSN check digit mismatch",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 3)}.${v.slice(3, 7)}.${v.slice(7, 11)}.${v.slice(11)}`;
+};
+
+/** Generate a random valid Swiss SSN. */
+const generate = (): string => {
+  const payload = "756" + randomDigits(9);
+  let sum = 0;
+  for (let i = 0; i < 12; i++)
+    sum += Number(payload[i]) * (i % 2 === 0 ? 1 : 3);
+  return payload + String((10 - (sum % 10)) % 10);
+};
+
+/** Swiss Social Security Number. */
+const ssn: Validator = {
+  name: "Swiss Social Security Number",
+  localName: "AHV-Versichertennummer",
+  abbreviation: "AHV",
+  aliases: [
+    "AHV-Nummer",
+    "numéro AVS",
+    "AVS",
+    "AHV",
+  ] as const,
+  candidatePattern: "756\\.?\\d{4}\\.?\\d{4}\\.?\\d{2}",
+  country: "CH",
+  entityType: "person",
+  sourceUrl: "https://www.bsv.admin.ch/",
+  examples: ["7561234567897"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default ssn;
+export { compact, format, validate, generate };

package/src/ch/uid.ts

@@ -0,0 +1,108 @@
+/**
+ * UID (Unternehmens-Identifikationsnummer).
+ *
+ * Swiss business identification number. 12 characters:
+ * "CHE" prefix + 9 digits. Check digit uses weights
+ * [5,4,3,2,7,6,5,4] on the first 8 digits.
+ *
+ * @see https://www.uid.admin.ch/
+ */
+
+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 = [5, 4, 3, 2, 7, 6, 5, 4] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -./").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "Swiss UID must be CHE + 9 digits",
+    );
+  }
+  if (!v.startsWith("CHE")) {
+    return err(
+      "INVALID_COMPONENT",
+      "Swiss UID must start with CHE",
+    );
+  }
+  const digits = v.slice(3);
+  if (!isdigits(digits)) {
+    return err(
+      "INVALID_FORMAT",
+      "Swiss UID must be CHE + 9 digits",
+    );
+  }
+
+  let sum = 0;
+  for (let i = 0; i < 8; i++) {
+    sum += Number(digits.charAt(i)) * (WEIGHTS[i] ?? 0);
+  }
+  const check = (11 - (sum % 11)) % 11;
+  if (check === 10) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Swiss UID check digit is invalid",
+    );
+  }
+  if (check !== Number(digits[8])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Swiss UID check digit mismatch",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  const d = v.slice(3);
+  return `CHE-${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6)}`;
+};
+
+/** Generate a random valid Swiss UID. */
+const generate = (): string => {
+  for (let i = 0; i < 100; i++) {
+    const payload = randomDigits(8);
+    let sum = 0;
+    for (let j = 0; j < 8; j++)
+      sum += Number(payload.charAt(j)) * (WEIGHTS[j] ?? 0);
+    const check = (11 - (sum % 11)) % 11;
+    if (check === 10) continue;
+    return "CHE" + payload + String(check);
+  }
+  throw new Error("Failed to generate valid Swiss UID");
+};
+
+/** Swiss Business Identification Number. */
+const uid: Validator = {
+  name: "Swiss Business ID",
+  localName: "Unternehmens-Identifikationsnummer",
+  abbreviation: "UID",
+  aliases: [
+    "Unternehmens-Identifikationsnummer",
+    "UID",
+    "IDE",
+  ] as const,
+  candidatePattern: "CHE-?\\d{3}\\.?\\d{3}\\.?\\d{3}",
+  country: "CH",
+  entityType: "company",
+  sourceUrl: "https://www.uid.admin.ch/",
+  examples: ["CHE100155212"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default uid;
+export { compact, format, validate, generate };

package/src/ch/vat.ts

@@ -0,0 +1,85 @@
+/**
+ * Swiss VAT number.
+ *
+ * Format: CHE + 9 digits + suffix (MWST|TVA|IVA|TPV).
+ * The numeric part is validated as a UID.
+ *
+ * @see https://www.ch.ch/en/value-added-tax-number-und-business-identification-number/
+ * @see https://www.estv.admin.ch/
+ */
+
+import { clean } from "#util/clean";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+import {
+  validate as validateUid,
+  generate as generateUid,
+} from "./uid";
+
+const SUFFIXES = ["MWST", "TVA", "IVA", "TPV"] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -./").toUpperCase();
+
+const extractParts = (
+  v: string,
+): { uid: string; suffix: string } | undefined => {
+  for (const s of SUFFIXES) {
+    if (v.endsWith(s)) {
+      return { uid: v.slice(0, -s.length), suffix: s };
+    }
+  }
+  return undefined;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  const parts = extractParts(v);
+  if (!parts) {
+    return err(
+      "INVALID_FORMAT",
+      "Swiss VAT must end with MWST, TVA, IVA, or TPV",
+    );
+  }
+
+  const uidResult = validateUid(parts.uid);
+  if (!uidResult.valid) {
+    return uidResult;
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  const parts = extractParts(v);
+  if (!parts) return v;
+  const d = parts.uid.slice(3);
+  return `CHE-${d.slice(0, 3)}.${d.slice(3, 6)}.${d.slice(6)} ${parts.suffix}`;
+};
+
+/** Generate a random valid Swiss VAT number. */
+const generate = (): string => generateUid() + "MWST";
+
+/** Swiss VAT Number. */
+const vat: Validator = {
+  name: "Swiss VAT Number",
+  localName: "Mehrwertsteuernummer",
+  abbreviation: "MWST",
+  aliases: ["MWST", "TVA", "IVA"] as const,
+  candidatePattern:
+    "CHE-?\\d{3}\\.?\\d{3}\\.?\\d{3}\\s?(?:MWST|TVA|IVA)",
+  country: "CH",
+  entityType: "company",
+  sourceUrl: "https://www.estv.admin.ch/",
+  examples: ["CHE107787577IVA"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, validate, generate };

package/src/cl/mod.ts

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

package/src/cl/rut.ts

@@ -0,0 +1,118 @@
+/**
+ * RUT (Rol Único Tributario).
+ *
+ * Chilean tax identification number assigned by the SII
+ * (Servicio de Impuestos Internos). The number consists
+ * of 7 or 8 digits followed by a check digit (0-9 or K),
+ * computed using a modulo 11 algorithm with weights
+ * [2, 3, 4, 5, 6, 7] cycling right-to-left.
+ *
+ * Format: XX.XXX.XXX-C (7-8 digits + check digit).
+ *
+ * @see https://www.sii.cl/
+ * @see https://en.wikipedia.org/wiki/Rol_%C3%9Anico_Tributario
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+const RUT_RE = /^\d{7,8}[\dK]$/;
+
+const compact = (value: string): string => {
+  let v = clean(value, " -.").trim().toUpperCase();
+  if (v.startsWith("CL")) v = v.slice(2);
+  return v;
+};
+
+/**
+ * Compute the RUT check digit using mod 11 with
+ * weights [2, 3, 4, 5, 6, 7] cycling right-to-left.
+ *
+ * remainder = 11 - (weighted sum % 11)
+ * 11 -> "0", 10 -> "K", else the digit as string.
+ */
+const calcCheckDigit = (body: string): string => {
+  const weights = [2, 3, 4, 5, 6, 7];
+  let sum = 0;
+  for (let i = body.length - 1, w = 0; i >= 0; i--, w++) {
+    sum += Number(body[i]) * weights[w % 6]!;
+  }
+  const remainder = 11 - (sum % 11);
+  if (remainder === 11) return "0";
+  if (remainder === 10) return "K";
+  return String(remainder);
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 8 && v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "RUT must be 8 or 9 characters",
+    );
+  }
+
+  if (!RUT_RE.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "RUT must contain only digits and optionally K",
+    );
+  }
+
+  const body = v.slice(0, -1);
+  const expected = calcCheckDigit(body);
+  if (v.at(-1) !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "RUT check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  const check = v.at(-1);
+  const body = v.slice(0, -1);
+  return (
+    `${body.slice(0, -6)}.${body.slice(-6, -3)}` +
+    `.${body.slice(-3)}-${check}`
+  );
+};
+
+/** Generate a random valid Chilean RUT. */
+const generate = (): string => {
+  const body = randomDigits(8);
+  return body + calcCheckDigit(body);
+};
+
+/**
+ * Chilean RUT (tax identification number).
+ *
+ * Examples sourced from python-stdnum test suite
+ * (cl.rut module).
+ */
+const rut: Validator = {
+  name: "Chilean Tax ID",
+  localName: "Rol Único Tributario",
+  abbreviation: "RUT",
+  aliases: ["RUT", "Rol Único Tributario"] as const,
+  candidatePattern: "\\d{1,2}\\.?\\d{3}\\.?\\d{3}-?[\\dkK]",
+  country: "CL",
+  entityType: "any",
+  compact,
+  format,
+  validate,
+  sourceUrl: "https://www.sii.cl/",
+  lengths: [8, 9] as const,
+  examples: ["760864285", "125319092"] as const,
+  generate,
+};
+
+export default rut;
+export { compact, format, validate, generate };

package/src/cn/mod.ts

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

package/src/cn/ric.ts

@@ -0,0 +1,180 @@
+/**
+ * RIC (Resident Identity Card number, 居民身份证号码).
+ *
+ * Chinese national identifier. 18 characters:
+ * 6 (area code) + 8 (YYYYMMDD birth) + 3 (sequence,
+ * odd = male) + 1 (check, 0-9 or X).
+ *
+ * Also accepts the legacy 15-digit format (no check
+ * digit, 2-digit year).
+ *
+ * @see https://en.wikipedia.org/wiki/Resident_Identity_Card
+ */
+
+import {
+  mod112checkChar,
+  mod112validate,
+} from "#checksums/mod112";
+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, " -").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 15 && v.length !== 18) {
+    return err(
+      "INVALID_LENGTH",
+      "RIC must be 15 or 18 characters",
+    );
+  }
+
+  if (v.length === 15) {
+    if (!isdigits(v)) {
+      return err(
+        "INVALID_FORMAT",
+        "15-digit RIC must contain only digits",
+      );
+    }
+    // Validate date: digits 6-11 are YYMMDD
+    const year = 1900 + Number(v.slice(6, 8));
+    const month = Number(v.slice(8, 10));
+    const day = Number(v.slice(10, 12));
+    if (!isValidDate(year, month, day)) {
+      return err(
+        "INVALID_COMPONENT",
+        "RIC contains an invalid birth date",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // 18-character format
+  if (!isdigits(v.slice(0, 17))) {
+    return err(
+      "INVALID_FORMAT",
+      "RIC must contain only digits (plus check char)",
+    );
+  }
+  const lastChar = v[17]!;
+  if (!isdigits(lastChar) && lastChar !== "X") {
+    return err(
+      "INVALID_FORMAT",
+      "RIC check character must be 0-9 or X",
+    );
+  }
+
+  // Validate date: digits 6-13 are YYYYMMDD
+  const year = Number(v.slice(6, 10));
+  const month = Number(v.slice(10, 12));
+  const day = Number(v.slice(12, 14));
+  if (!isValidDate(year, month, day)) {
+    return err(
+      "INVALID_COMPONENT",
+      "RIC contains an invalid birth date",
+    );
+  }
+
+  if (!mod112validate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "RIC check character does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Extract birth date and gender from an RIC 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;
+
+  let year: number;
+  let month: number;
+  let day: number;
+  let seq: number;
+
+  if (v.length === 15) {
+    year = 1900 + Number(v.slice(6, 8));
+    month = Number(v.slice(8, 10));
+    day = Number(v.slice(10, 12));
+    seq = Number(v.slice(12, 15));
+  } else {
+    year = Number(v.slice(6, 10));
+    month = Number(v.slice(10, 12));
+    day = Number(v.slice(12, 14));
+    seq = Number(v.slice(14, 17));
+  }
+
+  const gender = seq % 2 === 1 ? "male" : "female";
+
+  return {
+    birthDate: new Date(year, month - 1, day),
+    gender,
+  };
+};
+
+/** Generate a random valid 18-digit RIC. */
+const generate = (): string => {
+  // Use a simple area code prefix
+  const area = String(randomInt(110000, 659999));
+  const year = randomInt(1950, 2005);
+  const month = randomInt(1, 12);
+  const day = randomInt(1, 28);
+  const seqNum = randomInt(1, 999);
+  const seq = String(seqNum).padStart(3, "0");
+
+  const yStr = String(year);
+  const mStr = String(month).padStart(2, "0");
+  const dStr = String(day).padStart(2, "0");
+
+  const payload = `${area}${yStr}${mStr}${dStr}${seq}`;
+  const check = mod112checkChar(payload);
+  return `${payload}${check}`;
+};
+
+/** Chinese Resident Identity Card number. */
+const ric: Validator = {
+  name: "Chinese Resident Identity Card",
+  localName: "居民身份证号码",
+  abbreviation: "RIC",
+  aliases: ["身份证", "居民身份证号码", "RIC"] as const,
+  candidatePattern: "\\d{17}[\\dX]",
+  country: "CN",
+  entityType: "person",
+  description:
+    "18-character national ID encoding area, birth date, gender, and check digit",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Resident_Identity_Card",
+  lengths: [15, 18] as const,
+  examples: [
+    "11010519491231002X",
+    "440524188001010014",
+  ] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default ric;
+export { compact, format, generate, parse, validate };