@stll/stdnum 0.0.1

package/src/uy/rut.ts

@@ -0,0 +1,146 @@
+/**
+ * RUT (Registro Único Tributario).
+ *
+ * Uruguayan tax identification number issued by the
+ * DGI (Dirección General Impositiva). The number is
+ * 12 digits: 2-digit document type (01-22), 6-digit
+ * sequence, fixed "001" suffix, and a check digit
+ * computed via weighted sum mod 11 (Python-style
+ * modulo of the negated sum).
+ *
+ * Format: ############  (12 digits compact)
+ *
+ * @see https://www.agesic.gub.uy/
+ */
+
+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 WEIGHTS = [4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2] as const;
+
+const compact = (value: string): string => {
+  let v = clean(value, " -").trim();
+  if (v.toUpperCase().startsWith("UY")) {
+    v = v.slice(2);
+  }
+  return v;
+};
+
+/**
+ * Python-style modulo: always returns a non-negative
+ * result for a positive divisor.
+ */
+const pymod = (a: number, b: number): number =>
+  ((a % b) + b) % b;
+
+const calcCheckDigit = (value: string): string | null => {
+  let sum = 0;
+  for (let i = 0; i < 11; i++) {
+    sum += Number(value[i]) * WEIGHTS[i]!;
+  }
+  const result = pymod(-sum, 11);
+  // A result of 10 means no valid single-digit check
+  // digit exists; the DGI does not issue such numbers.
+  if (result === 10) return null;
+  return String(result);
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 12) {
+    return err("INVALID_LENGTH", "RUT must be 12 digits");
+  }
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "RUT must contain only digits",
+    );
+  }
+
+  // First 2 digits: document type (01-22)
+  const docType = Number.parseInt(v.slice(0, 2), 10);
+  if (docType < 1 || docType > 22) {
+    return err(
+      "INVALID_COMPONENT",
+      "RUT document type must be between 01 and 22",
+    );
+  }
+
+  // Digits 2-8: sequence (must not be all zeros)
+  if (v.slice(2, 8) === "000000") {
+    return err(
+      "INVALID_COMPONENT",
+      "RUT sequence must not be all zeros",
+    );
+  }
+
+  // Digits 8-11: must be "001"
+  if (v.slice(8, 11) !== "001") {
+    return err(
+      "INVALID_COMPONENT",
+      "RUT branch code must be 001",
+    );
+  }
+
+  const expected = calcCheckDigit(v);
+  if (expected === null || 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);
+  return `${v.slice(0, 2)}-${v.slice(2, 8)}-${v.slice(8, 11)}-${v.slice(11)}`;
+};
+
+/** Generate a random valid Uruguayan RUT. */
+const generate = (): string => {
+  for (;;) {
+    const docType = String(randomInt(1, 22)).padStart(
+      2,
+      "0",
+    );
+    const seq = randomDigits(6);
+    if (seq === "000000") continue;
+    const partial = `${docType}${seq}001`;
+    const check = calcCheckDigit(partial);
+    if (check === null) continue;
+    return `${partial}${check}`;
+  }
+};
+
+/**
+ * Uruguayan RUT (tax identification number).
+ *
+ * Examples sourced from python-stdnum test suite.
+ */
+const rut: Validator = {
+  name: "Uruguayan Tax ID",
+  localName: "Registro Único Tributario",
+  abbreviation: "RUT",
+  aliases: ["RUT", "Registro Único Tributario"] as const,
+  candidatePattern: "\\d{12}",
+  country: "UY",
+  entityType: "any",
+  lengths: [12] as const,
+  examples: ["010100010013", "102000010017"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl: "https://www.agesic.gub.uy/",
+  generate,
+};
+
+export default rut;
+export { compact, format, validate, generate };

package/src/ve/mod.ts

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

package/src/ve/rif.ts

@@ -0,0 +1,140 @@
+/**
+ * RIF (Registro de Información Fiscal).
+ *
+ * Venezuelan tax identification number issued by the
+ * SENIAT. The number consists of 1 letter indicating
+ * the entity type (J=juridical, G=government,
+ * V=natural/Venezuelan, E=foreign, P=passport)
+ * followed by 8 digits and a check digit computed
+ * via weighted sum mod 11.
+ *
+ * Format: X-########-# or X######### (10 chars compact)
+ *
+ * @see https://en.wikipedia.org/wiki/Tax_Identification_Number#Venezuela
+ */
+
+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";
+
+/**
+ * Map prefix letter to its numeric offset used
+ * in the check digit computation.
+ */
+const PREFIX_VALUES: Record<string, number> = {
+  V: 4,
+  E: 8,
+  J: 12,
+  P: 16,
+  G: 20,
+};
+
+/** Weights applied to the 8-digit body. */
+const WEIGHTS = [3, 2, 7, 6, 5, 4, 3, 2] as const;
+
+/**
+ * Lookup table for converting the mod 11 result
+ * to the check character.
+ */
+const CHECK_LOOKUP = "00987654321";
+
+const compact = (value: string): string =>
+  clean(value, " -.").trim().toUpperCase();
+
+const calcCheckDigit = (
+  prefix: string,
+  body: string,
+): string => {
+  const pv = PREFIX_VALUES[prefix]!;
+  let sum = 0;
+  for (let i = 0; i < 8; i++) {
+    sum += Number(body[i]) * WEIGHTS[i]!;
+  }
+  const digit = (pv + (sum % 11)) % 11;
+  return CHECK_LOOKUP[digit]!;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "RIF must be 10 characters",
+    );
+  }
+
+  const prefix = v[0]!;
+  if (!(prefix in PREFIX_VALUES)) {
+    return err(
+      "INVALID_COMPONENT",
+      "RIF must start with V, E, J, P, or G",
+    );
+  }
+
+  const body = v.slice(1, 9);
+  const check = v.slice(9);
+  if (!isdigits(v.slice(1))) {
+    return err(
+      "INVALID_FORMAT",
+      "RIF body must contain only digits",
+    );
+  }
+
+  const expected = calcCheckDigit(prefix, body);
+  if (check !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "RIF check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v[0]}-${v.slice(1, 9)}-${v.slice(9)}`;
+};
+
+/** Generate a random valid Venezuelan RIF. */
+const generate = (): string => {
+  const types = ["V", "E", "J", "P", "G"] as const;
+  const prefix = types[randomInt(0, types.length - 1)]!;
+  const body = randomDigits(8);
+  return (
+    prefix + body + String(calcCheckDigit(prefix, body))
+  );
+};
+
+/**
+ * Venezuelan RIF (tax identification number).
+ *
+ * Examples sourced from python-stdnum test suite.
+ */
+const rif: Validator = {
+  name: "Venezuelan Tax ID",
+  localName: "Registro de Información Fiscal",
+  abbreviation: "RIF",
+  aliases: [
+    "RIF",
+    "Registro de Información Fiscal",
+  ] as const,
+  candidatePattern: "[VEJPG]-?\\d{8}-?\\d",
+  country: "VE",
+  entityType: "any",
+  lengths: [10] as const,
+  examples: ["V309876543", "J309876546"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Tax_Identification_Number#Venezuela",
+  generate,
+};
+
+export default rif;
+export { compact, format, validate, generate };

package/src/vn/mod.ts

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

package/src/vn/mst.ts

@@ -0,0 +1,128 @@
+/**
+ * MST (Mã số thuế, Vietnam tax number).
+ *
+ * 10 or 13 digits. The first two digits encode the province
+ * where the business was registered. Digits 3-9 are a
+ * sequential number (0000001-9999999). Digit 10 is a
+ * weighted mod-11 check digit. An optional 3-digit branch
+ * suffix (001-999) may follow, separated by a dash.
+ *
+ * @see https://vi.wikipedia.org/wiki/Thuế_Việt_Nam#Mã_số_thuế_(MST)_của_doanh_nghiệp
+ * @see https://easyinvoice.vn/ma-so-thue/
+ */
+
+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 WEIGHTS = [31, 29, 23, 19, 17, 13, 7, 5, 3] as const;
+
+const calcCheckDigit = (number: string): string => {
+  let total = 0;
+  for (let i = 0; i < 9; i++) {
+    total += (WEIGHTS[i] ?? 0) * Number(number.charAt(i));
+  }
+  const remainder = 10 - (total % 11);
+  // When remainder is 10, the sequential part is
+  // never issued by GDT. Returning "0" keeps the
+  // function correct as a digit calculator (mod 10
+  // wrap) while still rejecting these numbers since
+  // no real MST will have this combination.
+  return String(
+    remainder >= 10 ? remainder - 10 : remainder,
+  );
+};
+
+const compact = (value: string): string =>
+  clean(value, " -.");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 10 && v.length !== 13) {
+    return err(
+      "INVALID_LENGTH",
+      "MST must be 10 or 13 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "MST must contain only digits",
+    );
+  }
+
+  // Sequential part (digits 3-9) must not be all zeros
+  if (v.slice(2, 9) === "0000000") {
+    return err(
+      "INVALID_COMPONENT",
+      "MST sequential part must not be 0000000",
+    );
+  }
+
+  // Branch suffix (last 3 digits) must not be 000
+  if (v.length === 13 && v.slice(10) === "000") {
+    return err(
+      "INVALID_COMPONENT",
+      "MST branch suffix must not be 000",
+    );
+  }
+
+  // Check digit (position 10, index 9)
+  if (v[9] !== calcCheckDigit(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "MST check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 13) {
+    return `${v.slice(0, 10)}-${v.slice(10)}`;
+  }
+  return v;
+};
+
+/** Generate a random valid Vietnamese MST. */
+const generate = (): string => {
+  for (;;) {
+    const province = String(randomInt(1, 99)).padStart(
+      2,
+      "0",
+    );
+    const payload = province + randomDigits(7);
+    const c = payload + calcCheckDigit(payload);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Vietnamese Tax Number. */
+const mst: Validator = {
+  name: "Vietnamese Tax Number",
+  localName: "Mã số thuế",
+  abbreviation: "MST",
+  aliases: ["MST", "mã số thuế"] as const,
+  candidatePattern: "\\d{10}(-\\d{3})?",
+  country: "VN",
+  entityType: "company",
+  description:
+    "10- or 13-digit tax identifier for enterprises",
+  sourceUrl:
+    "https://vi.wikipedia.org/wiki/Thu%E1%BA%BF_Vi%E1%BB%87t_Nam#M%C3%A3_s%E1%BB%91_thu%E1%BA%BF_(MST)_c%E1%BB%A7a_doanh_nghi%E1%BB%87p",
+  lengths: [10, 13] as const,
+  examples: ["0100233488", "0314409058002"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default mst;
+export { compact, format, validate, generate };

package/src/za/idnr.ts

@@ -0,0 +1,157 @@
+/**
+ * South African Identity Number.
+ *
+ * 13-digit number encoding date of birth, gender,
+ * citizenship, and a Luhn check digit.
+ * Format: YYMMDD SSSS C A Z
+ *   - YYMMDD: date of birth
+ *   - SSSS: sequence (0000-4999 female, 5000-9999 male)
+ *   - C: citizenship (0 = citizen, 1 = permanent resident)
+ *   - A: was used for race (now always 8 or 9)
+ *   - Z: Luhn check digit
+ *
+ * @see https://en.wikipedia.org/wiki/South_African_identity_document
+ */
+
+import {
+  luhnValidate,
+  luhnChecksum,
+} from "#checksums/luhn";
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { randomDigits, 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, " ");
+
+/**
+ * Resolve the birth date from the 2-digit year.
+ * Years after the current year are assumed to be
+ * in the previous century.
+ */
+const resolveBirthDate = (
+  v: string,
+): { year: number; month: number; day: number } | null => {
+  const today = new Date();
+  const century = Math.floor(today.getFullYear() / 100);
+  let year = century * 100 + Number(v.slice(0, 2));
+  const month = Number(v.slice(2, 4));
+  const day = Number(v.slice(4, 6));
+  if (year > today.getFullYear()) {
+    year -= 100;
+  }
+  if (!isValidDate(year, month, day)) return null;
+  return { year, month, day };
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 13) {
+    return err(
+      "INVALID_LENGTH",
+      "SA ID must be exactly 13 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "SA ID must contain only digits",
+    );
+  }
+  if (resolveBirthDate(v) === null) {
+    return err(
+      "INVALID_COMPONENT",
+      "SA ID contains an invalid date of birth",
+    );
+  }
+  const citizenship = v[10];
+  if (citizenship !== "0" && citizenship !== "1") {
+    return err(
+      "INVALID_COMPONENT",
+      "SA ID citizenship digit must be 0 or 1",
+    );
+  }
+  if (!luhnValidate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "SA ID Luhn check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 13) {
+    return `${v.slice(0, 6)} ${v.slice(6, 10)} ${v.slice(10, 12)} ${v.slice(12)}`;
+  }
+  return v;
+};
+
+/**
+ * Extract birth date and gender from a South African
+ * ID 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 bd = resolveBirthDate(v);
+  if (bd === null) return null;
+
+  const sequence = Number(v.slice(6, 10));
+
+  return {
+    birthDate: new Date(bd.year, bd.month - 1, bd.day),
+    gender: sequence < 5000 ? "female" : "male",
+  };
+};
+
+/** Generate a random valid South African ID. */
+const generate = (): string => {
+  for (;;) {
+    const yy = String(randomInt(50, 99)).padStart(2, "0");
+    const mm = String(randomInt(1, 12)).padStart(2, "0");
+    const dd = String(randomInt(1, 28)).padStart(2, "0");
+    const serial = randomDigits(4);
+    const citizen = String(randomInt(0, 1));
+    const payload = yy + mm + dd + serial + citizen + "8";
+    const cs = luhnChecksum(payload + "0");
+    const c = payload + String((10 - cs) % 10);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** South African Identity Number. */
+const idnr: Validator = {
+  name: "South African Identity Number",
+  localName: "South African Identity Number",
+  abbreviation: "SA ID",
+  aliases: ["ID number", "RSA ID"] as const,
+  candidatePattern: "\\d{13}",
+  country: "ZA",
+  entityType: "person",
+  compact,
+  format,
+  validate,
+  description:
+    "South African personal identification number",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/" +
+    "South_African_identity_document",
+  lengths: [13] as const,
+  examples: ["7503305044089", "8001015009087"] as const,
+  generate,
+};
+
+export default idnr;
+export { compact, format, parse, validate, generate };

package/src/za/mod.ts

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