@stll/stdnum 0.0.1

package/src/mu/brn.ts

@@ -0,0 +1,102 @@
+/** Generate a random valid Mauritius BRN (entity). */
+const generate = (): string => {
+  const letter = String.fromCodePoint(
+    65 + randomInt(0, 25),
+  );
+  const digits = randomDigits(8);
+  return `${letter}${digits}`;
+};
+
+/**
+ * BRN (Business Registration Number, Mauritius).
+ *
+ * Issued by the Corporate and Business Registration
+ * Department (CBRD). Used to identify entities and
+ * individuals carrying out business activities.
+ *
+ * Entity BRN: 1 letter prefix + 8 digits (9 chars).
+ *   - Letter indicates entity type (e.g. C = company,
+ *     F = foreign company).
+ *   - Digits 2-3 encode the registration year
+ *     (e.g. 07 = 2007).
+ *   - Digits 4-9 are a sequential number.
+ *
+ * Individual BRN: 8 digits, first digit 0-3.
+ *
+ * No public check digit algorithm is documented.
+ *
+ * @see https://companies.govmu.org/
+ * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/mauritius-tin.pdf
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+/** Entity BRN: letter + 8 digits. */
+const ENTITY_RE = /^[A-Z]\d{8}$/;
+
+/** Individual BRN: 8 digits, starts with 0-3. */
+const INDIVIDUAL_RE = /^[0-3]\d{7}$/;
+
+const compact = (value: string): string =>
+  clean(value, " -/").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 8 && v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Mauritius BRN must be 8 or 9 characters",
+    );
+  }
+
+  if (v.length === 9) {
+    if (!ENTITY_RE.test(v)) {
+      return err(
+        "INVALID_FORMAT",
+        "Mauritius entity BRN must be " +
+          "1 letter followed by 8 digits",
+      );
+    }
+  } else {
+    if (!INDIVIDUAL_RE.test(v)) {
+      return err(
+        "INVALID_FORMAT",
+        "Mauritius individual BRN must be " +
+          "8 digits starting with 0-3",
+      );
+    }
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Mauritius Business Registration Number. */
+const brn: Validator = {
+  name: "Mauritius Business Registration Number",
+  localName: "Business Registration Number",
+  abbreviation: "BRN",
+  aliases: ["BRN", "Business Registration Number"] as const,
+  candidatePattern: "[A-Z]\\d{8}",
+  country: "MU",
+  entityType: "any",
+  compact,
+  format,
+  validate,
+  description:
+    "Mauritius business registration number " +
+    "issued by the CBRD",
+  sourceUrl: "https://companies.govmu.org/",
+  lengths: [8, 9] as const,
+  examples: ["C07015330", "C16135302"] as const,
+  generate,
+};
+
+export default brn;
+export { compact, format, validate, generate };

package/src/mu/mod.ts

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

package/src/mx/clabe.ts

@@ -0,0 +1,111 @@
+/**
+ * CLABE (Clave Bancaria Estandarizada).
+ *
+ * Mexican standardized bank account number used for
+ * interbank electronic fund transfers. 18 digits:
+ * 3 (bank code) + 3 (branch) + 11 (account number)
+ * + 1 (check digit).
+ *
+ * The check digit is computed using a weighted sum with
+ * repeating weights [3, 7, 1] modulo 10:
+ * check = (10 - sum % 10) % 10.
+ *
+ * @see https://en.wikipedia.org/wiki/CLABE
+ */
+
+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 = [3, 7, 1] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -").trim();
+
+/**
+ * Compute the CLABE check digit.
+ *
+ * For each of the first 17 digits, multiply by the
+ * corresponding weight [3, 7, 1, 3, 7, 1, ...], take
+ * the result mod 10, sum all remainders, then
+ * check = (10 - sum % 10) % 10.
+ */
+const calcCheckDigit = (value: string): string => {
+  let sum = 0;
+  for (let i = 0; i < 17; i++) {
+    const digit = Number(value[i]);
+    // SAFETY: modulo guarantees valid index
+    // eslint-disable-next-line no-non-null-assertion
+    const weight = WEIGHTS[i % WEIGHTS.length]!;
+    sum += (digit * weight) % 10;
+  }
+  return String((10 - (sum % 10)) % 10);
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 18) {
+    return err("INVALID_LENGTH", "CLABE must be 18 digits");
+  }
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "CLABE must contain only digits",
+    );
+  }
+
+  // Verify check digit (last digit).
+  const expected = calcCheckDigit(v);
+  if (v[17] !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "CLABE check digit does not match",
+    );
+  }
+
+  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, 17)} ${v.slice(17)}`;
+};
+
+/** Generate a random valid Mexican CLABE. */
+const generate = (): string => {
+  const payload = randomDigits(17);
+  return payload + calcCheckDigit(payload);
+};
+
+/**
+ * Mexican CLABE (standardized bank account number).
+ *
+ * Example sourced from Wikipedia CLABE article.
+ */
+const clabe: Validator = {
+  name: "Mexican Bank Account",
+  localName: "Clave Bancaria Estandarizada",
+  abbreviation: "CLABE",
+  aliases: [
+    "CLABE",
+    "Clave Bancaria Estandarizada",
+  ] as const,
+  candidatePattern: "\\d{18}",
+  country: "MX",
+  entityType: "any",
+  lengths: [18] as const,
+  examples: ["032180000118359719"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl: "https://en.wikipedia.org/wiki/CLABE",
+  generate,
+};
+
+export default clabe;
+export { compact, format, validate, generate };

package/src/mx/curp.ts

@@ -0,0 +1,210 @@
+/**
+ * CURP (Clave Única de Registro de Población).
+ *
+ * Mexican personal identification number. 18 characters:
+ * 4 letters (name encoding) + 6 digits (YYMMDD birth
+ * date) + 1 letter (gender: H=male, M=female) + 2
+ * letters (state code) + 3 consonants (name
+ * disambiguation) + 1 digit (century discriminator) +
+ * 1 check digit.
+ *
+ * The check digit is computed as a weighted sum mod 10
+ * using an alphabet mapping (0-9, A-N, &, O-Z).
+ *
+ * @see https://en.wikipedia.org/wiki/CURP
+ */
+
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { err } from "#util/result";
+
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  Validator,
+} from "../types";
+
+/** Valid Mexican state codes (2-letter). */
+const STATE_CODES = new Set([
+  "AS",
+  "BC",
+  "BS",
+  "CC",
+  "CL",
+  "CM",
+  "CS",
+  "CH",
+  "DF",
+  "DG",
+  "GT",
+  "GR",
+  "HG",
+  "JC",
+  "MC",
+  "MN",
+  "MS",
+  "NT",
+  "NL",
+  "OC",
+  "PL",
+  "QT",
+  "QR",
+  "SP",
+  "SL",
+  "SR",
+  "TC",
+  "TS",
+  "TL",
+  "VZ",
+  "YN",
+  "ZS",
+  "NE", // Born abroad
+]);
+
+/**
+ * Alphabet for CURP check digit computation.
+ * Matches python-stdnum: digits 0-9, then A-N,
+ * ampersand, O-Z.
+ */
+const ALPHABET = "0123456789ABCDEFGHIJKLMN&OPQRSTUVWXYZ";
+
+const CHAR_MAP = new Map<string, number>();
+for (let i = 0; i < ALPHABET.length; i++) {
+  CHAR_MAP.set(ALPHABET[i]!, i);
+}
+
+const compact = (value: string): string =>
+  clean(value, " -").trim().toUpperCase();
+
+/**
+ * Compute the CURP check digit. Sum each of the first
+ * 17 characters multiplied by weight (18 - position),
+ * then check = (10 - sum % 10) % 10.
+ */
+const calcCheckDigit = (value: string): string => {
+  let sum = 0;
+  for (let i = 0; i < 17; i++) {
+    sum += (CHAR_MAP.get(value[i]!) ?? 0) * (18 - i);
+  }
+  return String((10 - (sum % 10)) % 10);
+};
+
+/**
+ * Resolve full year from 2-digit year and century
+ * discriminator: 0-9 = 1900s, letter = 2000s.
+ */
+const resolveCurpYear = (
+  yy: number,
+  centuryChar: string,
+): number =>
+  centuryChar >= "0" && centuryChar <= "9"
+    ? 1900 + yy
+    : 2000 + yy;
+
+const CURP_RE =
+  /^[A-Z]{4}\d{6}[HM][A-Z]{2}[A-Z]{3}[0-9A-Z]\d$/;
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 18) {
+    return err(
+      "INVALID_LENGTH",
+      "CURP must be 18 characters",
+    );
+  }
+
+  if (!CURP_RE.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "CURP has an invalid format",
+    );
+  }
+
+  // Validate the embedded date (YYMMDD at positions 4-9).
+  const yy = Number(v.slice(4, 6));
+  const mm = Number(v.slice(6, 8));
+  const dd = Number(v.slice(8, 10));
+
+  const year = resolveCurpYear(yy, v[16]!);
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "CURP contains an invalid birth date",
+    );
+  }
+
+  // Validate state code at positions 11-12.
+  const state = v.slice(11, 13);
+  if (!STATE_CODES.has(state)) {
+    return err(
+      "INVALID_COMPONENT",
+      "CURP contains an invalid state code",
+    );
+  }
+
+  // Verify check digit (last character).
+  const expected = calcCheckDigit(v);
+  if (v[17] !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "CURP check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Extract birth date and gender from a CURP.
+ * 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 yy = Number(v.slice(4, 6));
+  const mm = Number(v.slice(6, 8));
+  const dd = Number(v.slice(8, 10));
+
+  const year = resolveCurpYear(yy, v[16]!);
+
+  const genderChar = v[10];
+  const gender: "male" | "female" =
+    genderChar === "H" ? "male" : "female";
+
+  return {
+    birthDate: new Date(year, mm - 1, dd),
+    gender,
+  };
+};
+
+/**
+ * Mexican CURP (personal identification number).
+ *
+ * Example sourced from python-stdnum test suite.
+ */
+const curp: Validator = {
+  name: "Mexican Personal ID",
+  localName: "Clave Única de Registro de Población",
+  abbreviation: "CURP",
+  aliases: [
+    "CURP",
+    "Clave Única de Registro de Población",
+  ] as const,
+  candidatePattern: "[A-Z]{4}\\d{6}[HM][A-Z]{5}[A-Z\\d]\\d",
+  country: "MX",
+  entityType: "person",
+  lengths: [18] as const,
+  examples: ["BOXW310820HNERXN09"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl: "https://en.wikipedia.org/wiki/CURP",
+};
+
+export default curp;
+export { compact, format, parse, validate };

package/src/mx/mod.ts

@@ -0,0 +1,3 @@
+export { default as clabe } from "./clabe";
+export { default as curp } from "./curp";
+export { default as rfc } from "./rfc";

package/src/mx/rfc.ts

@@ -0,0 +1,144 @@
+/**
+ * RFC (Registro Federal de Contribuyentes).
+ *
+ * Mexican tax identification number issued by the SAT
+ * (Servicio de Administración Tributaria). The number is
+ * 13 characters for individuals (4 letters + 6 digits
+ * YYMMDD + 3 alphanumeric) or 12 characters for
+ * companies (3 letters + 6 digits YYMMDD + 3
+ * alphanumeric). The last character is a check digit
+ * computed with a mod 11 algorithm over a specific
+ * alphabet mapping.
+ *
+ * Format: AAAA######XXX (persons, 13 chars)
+ *         AAA######XXX  (companies, 12 chars)
+ *
+ * @see https://en.wikipedia.org/wiki/Tax_Identification_Number_(Mexico)
+ */
+
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+/** Alphabet for RFC check digit computation. */
+const ALPHABET = "0123456789ABCDEFGHIJKLMN&OPQRSTUVWXYZ Ñ";
+
+const CHAR_MAP = new Map<string, number>();
+for (let i = 0; i < ALPHABET.length; i++) {
+  CHAR_MAP.set(ALPHABET[i]!, i);
+}
+
+const compact = (value: string): string =>
+  clean(value, " -.").trim().toUpperCase();
+
+/**
+ * Compute the RFC check digit using mod 11 with
+ * the SAT alphabet mapping.
+ *
+ * Each character is mapped to its position in the
+ * ALPHABET, then multiplied by a weight that starts
+ * at (len + 1) and decreases by 1. The check digit
+ * is (11 - sum % 11) % 11, mapped to 0-9 or "A".
+ */
+const calcCheckDigit = (value: string): string => {
+  // Pad 12-char company RFCs with a leading space
+  // to align weights with the 13-char algorithm.
+  const padded = value.length === 11 ? ` ${value}` : value;
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    const ch = padded[i]!;
+    const v = CHAR_MAP.get(ch) ?? 0;
+    sum += v * (13 - i);
+  }
+  const remainder = sum % 11;
+  if (remainder === 0) return "0";
+  const digit = 11 - remainder;
+  return digit === 10 ? "A" : String(digit);
+};
+
+const PERSON_RE = /^[A-ZÑ&]{4}\d{6}[A-Z\d]{3}$/;
+const COMPANY_RE = /^[A-ZÑ&]{3}\d{6}[A-Z\d]{3}$/;
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 12 && v.length !== 13) {
+    return err(
+      "INVALID_LENGTH",
+      "RFC must be 12 or 13 characters",
+    );
+  }
+
+  const isPerson = v.length === 13;
+  const re = isPerson ? PERSON_RE : COMPANY_RE;
+  if (!re.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "RFC has an invalid format",
+    );
+  }
+
+  // Validate the embedded date (YYMMDD).
+  const dateOffset = isPerson ? 4 : 3;
+  const yy = Number(v.slice(dateOffset, dateOffset + 2));
+  const mm = Number(
+    v.slice(dateOffset + 2, dateOffset + 4),
+  );
+  const dd = Number(
+    v.slice(dateOffset + 4, dateOffset + 6),
+  );
+
+  // RFC dates use 2-digit years; use 2000 century for
+  // date validation (any valid calendar date is accepted).
+  const year = 2000 + yy;
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "RFC contains an invalid date",
+    );
+  }
+
+  // Verify check digit (last character).
+  const body = v.slice(0, -1);
+  const expected = calcCheckDigit(body);
+  if (v.at(-1) !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "RFC check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Mexican RFC (tax identification number).
+ *
+ * Examples sourced from python-stdnum test suite.
+ */
+const rfc: Validator = {
+  name: "Mexican Tax ID",
+  localName: "Registro Federal de Contribuyentes",
+  abbreviation: "RFC",
+  aliases: [
+    "RFC",
+    "Registro Federal de Contribuyentes",
+  ] as const,
+  candidatePattern: "[A-ZÑ&]{3,4}\\d{6}[A-Z\\d]{3}",
+  country: "MX",
+  entityType: "any",
+  lengths: [12, 13] as const,
+  examples: ["GODE561231GR8", "MAB9307148T4"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Tax_Identification_Number_(Mexico)",
+};
+
+export default rfc;
+export { compact, format, validate };

package/src/my/mod.ts

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