@stll/stdnum 0.0.1

package/src/cn/uscc.ts

@@ -0,0 +1,111 @@
+/**
+ * USCC (Unified Social Credit Code, 统一社会信用代码).
+ *
+ * 18 alphanumeric characters (excluding I, O, Z, S, V):
+ * 1 (registering authority) + 1 (entity type) +
+ * 6 (region code, digits only) + 9 (organisation code) +
+ * 1 (mod 31 check character).
+ *
+ * @see https://zh.wikipedia.org/wiki/统一社会信用代码
+ */
+
+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 ALPHABET = "0123456789ABCDEFGHJKLMNPQRTUWXY";
+
+const WEIGHTS = [
+  1, 3, 9, 27, 19, 26, 16, 17, 20, 29, 25, 13, 8, 24, 10,
+  30, 28,
+] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -").toUpperCase();
+
+const calcCheckChar = (value: string): string => {
+  let total = 0;
+  for (let i = 0; i < 17; i++) {
+    const idx = ALPHABET.indexOf(value[i]!);
+    total += idx * WEIGHTS[i]!;
+  }
+  return ALPHABET[(31 - (total % 31)) % 31]!;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 18) {
+    return err(
+      "INVALID_LENGTH",
+      "USCC must be 18 characters",
+    );
+  }
+
+  for (let i = 0; i < 18; i++) {
+    if (!ALPHABET.includes(v[i]!)) {
+      return err(
+        "INVALID_FORMAT",
+        "USCC contains invalid character",
+      );
+    }
+  }
+
+  if (!isdigits(v.slice(2, 8))) {
+    return err(
+      "INVALID_FORMAT",
+      "USCC region code (positions 3-8) must be digits",
+    );
+  }
+
+  if (v[17] !== calcCheckChar(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "USCC check character does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid USCC. */
+const generate = (): string => {
+  const reg = ALPHABET[randomInt(1, 9)]!;
+  const etype = ALPHABET[randomInt(1, 9)]!;
+  const region = randomDigits(6);
+  let org = "";
+  for (let i = 0; i < 9; i++)
+    org += ALPHABET[randomInt(0, ALPHABET.length - 1)]!;
+  const payload = reg + etype + region + org;
+  return payload + calcCheckChar(payload);
+};
+
+/** Chinese Unified Social Credit Code. */
+const uscc: Validator = {
+  name: "Unified Social Credit Code",
+  localName: "统一社会信用代码",
+  abbreviation: "USCC",
+  aliases: ["统一社会信用代码", "USCC"] as const,
+  candidatePattern:
+    "[0-9A-HJ-NP-RTUW-Y]{2}\\d{6}[0-9A-HJ-NP-RTUW-Y]{10}",
+  country: "CN",
+  entityType: "company",
+  description:
+    "18-character tax/registration code for Chinese entities",
+  sourceUrl:
+    "https://zh.wikipedia.org/wiki/统一社会信用代码",
+  lengths: [18] as const,
+  examples: ["91110000600037341L"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default uscc;
+export { compact, format, validate, generate };

package/src/co/mod.ts

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

package/src/co/nit.ts

@@ -0,0 +1,108 @@
+/**
+ * NIT (Número de Identificación Tributaria).
+ *
+ * Colombian tax identification number, also known as
+ * RUT (Registro Unico Tributario). The last digit is
+ * a check digit computed via a weighted sum mod 11
+ * with weights [3,7,13,17,19,23,29,37,41,43,47,53,
+ * 59,67,71] applied right-to-left.
+ *
+ * @see https://es.wikipedia.org/wiki/Número_de_identificación_tributaria
+ */
+
+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, 13, 17, 19, 23, 29, 37, 41, 43, 47, 53, 59, 67, 71,
+] as const;
+
+/** Lookup table: remainder -> check digit. */
+const CHECK_DIGITS = [0, 1, 9, 8, 7, 6, 5, 4, 3, 2, 1];
+
+const compact = (value: string): string =>
+  clean(value, " -.,");
+
+const calcCheckDigit = (body: string): number => {
+  let sum = 0;
+  const len = body.length;
+  for (let i = 0; i < len; i++) {
+    sum += Number(body[len - 1 - i]) * WEIGHTS[i]!;
+  }
+  return CHECK_DIGITS[sum % 11]!;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < 8 || v.length > 16) {
+    return err(
+      "INVALID_LENGTH",
+      "NIT must be between 8 and 16 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "NIT must contain only digits",
+    );
+  }
+
+  const body = v.slice(0, -1);
+  const check = calcCheckDigit(body);
+  if (check !== Number(v[v.length - 1])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "NIT check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  const body = v.slice(0, -1);
+  const checkChar = v.slice(-1);
+  const groups: string[] = [];
+  for (let i = body.length; i > 0; i -= 3) {
+    groups.unshift(body.slice(Math.max(0, i - 3), i));
+  }
+  return `${groups.join(".")}-${checkChar}`;
+};
+
+/** Generate a random valid NIT (10 digits). */
+const generate = (): string => {
+  const body = randomDigits(9);
+  const check = calcCheckDigit(body);
+  return `${body}${check}`;
+};
+
+/** Colombian tax identification number. */
+const nit: Validator = {
+  name: "Número de Identificación Tributaria",
+  localName: "Número de Identificación Tributaria",
+  abbreviation: "NIT",
+  aliases: [
+    "NIT",
+    "Número de Identificación Tributaria",
+  ] as const,
+  candidatePattern: "\\d{9,10}-?\\d",
+  country: "CO",
+  entityType: "any",
+  description: "Tax identifier issued by the DIAN",
+  sourceUrl:
+    "https://es.wikipedia.org/wiki/N%C3%BAmero_de_identificaci%C3%B3n_tributaria",
+  lengths: [8, 9, 10, 11, 12, 13, 14, 15, 16] as const,
+  examples: ["2131234321", "8001234565"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nit;
+export { compact, format, generate, validate };

package/src/cr/cpf.ts

@@ -0,0 +1,111 @@
+/** Generate a random valid Costa Rican CPF. */
+const generate = (): string => {
+  const province = String(randomInt(1, 9));
+  const volume = randomDigits(4);
+  const entry = randomDigits(4);
+  return `0${province}${volume}${entry}`;
+};
+
+/**
+ * CPF (Cédula de Persona Física, Costa Rican
+ * physical person ID number).
+ *
+ * 10 digits: 0P-TTTT-AAAA where:
+ *   - 0 = fixed leading zero
+ *   - P = province digit
+ *   - TTTT = volume (tomo), zero-padded
+ *   - AAAA = entry (asiento), zero-padded
+ *
+ * No check digit; validation is by format only.
+ *
+ * Ported from python-stdnum cr.cpf module.
+ *
+ * @see https://www.tse.go.cr/
+ */
+
+import { clean } from "#util/clean";
+import { randomDigits, randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+/**
+ * Compact: strip spaces, pad hyphen-separated parts
+ * (2-4-4), join, and prepend '0' if 9 digits.
+ */
+const compact = (value: string): string => {
+  let number = clean(value, " ").trim().toUpperCase();
+
+  const parts = number.split("-");
+  if (parts.length === 3) {
+    const p0 = parts[0]!.padStart(2, "0");
+    const p1 = parts[1]!.padStart(4, "0");
+    const p2 = parts[2]!.padStart(4, "0");
+    number = p0 + p1 + p2;
+  } else {
+    number = number.replaceAll("-", "");
+  }
+
+  if (number.length === 9) {
+    number = "0" + number;
+  }
+
+  return number;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "Costa Rican CPF must be 10 digits",
+    );
+  }
+
+  if (!/^\d{10}$/.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Costa Rican CPF must contain only digits",
+    );
+  }
+
+  if (v[0] !== "0") {
+    return err(
+      "INVALID_COMPONENT",
+      "Costa Rican CPF must start with 0",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 2)}-${v.slice(2, 6)}-${v.slice(6, 10)}`;
+};
+
+/**
+ * Costa Rican physical person ID number (CPF).
+ *
+ * Examples sourced from python-stdnum test suite.
+ */
+const cpf: Validator = {
+  name: "Costa Rican Physical Person ID",
+  localName: "Cédula de Persona Física",
+  abbreviation: "CPF",
+  aliases: ["CPF", "cédula de persona física"] as const,
+  candidatePattern: "\\d{9,12}",
+  country: "CR",
+  entityType: "person",
+  lengths: [10] as const,
+  examples: ["0304550175", "0109130259"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl: "https://www.tse.go.cr/",
+  generate,
+};
+
+export default cpf;
+export { compact, format, validate, generate };

package/src/cr/mod.ts

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

package/src/creditcard.ts

@@ -0,0 +1,190 @@
+/**
+ * Credit card number validation (Luhn algorithm).
+ *
+ * Validates card numbers using the Luhn checksum
+ * (ISO/IEC 7812-1). Supports Visa, Mastercard,
+ * Amex, Discover, and other networks (13-19
+ * digits).
+ *
+ * @see https://www.iso.org/standard/70484.html
+ */
+
+import {
+  luhnChecksum,
+  luhnValidate,
+} 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";
+
+/**
+ * Card network identifiers returned by
+ * {@link detectNetwork}.
+ */
+type CardNetwork =
+  | "visa"
+  | "mastercard"
+  | "amex"
+  | "discover"
+  | "diners"
+  | "jcb"
+  | "unionpay"
+  | "maestro";
+
+const compact = (value: string): string =>
+  clean(value, " -.");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < 13 || v.length > 19) {
+    return err(
+      "INVALID_LENGTH",
+      "Credit card number must be 13-19 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Credit card number must contain only digits",
+    );
+  }
+  if (!luhnValidate(v)) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Credit card number fails Luhn check",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  // Amex: 4-6-5 grouping
+  if (v.length === 15 && v[0] === "3") {
+    return `${v.slice(0, 4)} ${v.slice(4, 10)} ${v.slice(10)}`;
+  }
+  // Standard: groups of 4
+  const groups: string[] = [];
+  for (let i = 0; i < v.length; i += 4) {
+    groups.push(v.slice(i, i + 4));
+  }
+  return groups.join(" ");
+};
+
+const MAESTRO_PREFIXES: readonly number[] = [
+  5018, 5020, 5038, 5893, 6304, 6759, 6761, 6762, 6763,
+];
+
+/**
+ * Detect the card network from the BIN/IIN prefix.
+ *
+ * Accepts both formatted ("4111 1111 1111 1111")
+ * and compact ("4111111111111111") inputs.
+ * Returns null for unrecognized prefixes.
+ */
+const detectNetwork = (
+  value: string,
+): CardNetwork | null => {
+  const v = compact(value);
+  if (v.length === 0) return null;
+  if (!isdigits(v)) return null;
+
+  const d2 = Number(v.slice(0, 2));
+  const d3 = Number(v.slice(0, 3));
+  const d4 = Number(v.slice(0, 4));
+  const d6 = Number(v.slice(0, 6));
+
+  // Amex: 34, 37
+  if (d2 === 34 || d2 === 37) return "amex";
+
+  // Diners Club: 300-305, 36, 38
+  if (d2 === 36 || d2 === 38) return "diners";
+  if (d3 >= 300 && d3 <= 305) return "diners";
+
+  // JCB: 3528-3589
+  if (d4 >= 3528 && d4 <= 3589) return "jcb";
+
+  // Visa: starts with 4
+  if (v[0] === "4") return "visa";
+
+  // Maestro (check before Mastercard; some share
+  // the 50xx prefix space)
+  if (MAESTRO_PREFIXES.includes(d4)) return "maestro";
+
+  // Mastercard: 51-55 or 2221-2720
+  if (d2 >= 51 && d2 <= 55) return "mastercard";
+  if (d4 >= 2221 && d4 <= 2720) return "mastercard";
+
+  // Discover: 6011, 622126-622925, 644-649, 65
+  if (d4 === 6011) return "discover";
+  if (d6 >= 622126 && d6 <= 622925) return "discover";
+  if (d3 >= 644 && d3 <= 649) return "discover";
+  if (d2 === 65) return "discover";
+
+  // UnionPay: starts with 62 (excluding Discover
+  // ranges already matched above)
+  if (d2 === 62) return "unionpay";
+
+  return null;
+};
+
+/**
+ * Visa/Mastercard IIN prefixes. Each entry is
+ * [prefix, totalLength].
+ */
+const CARD_PREFIXES = [
+  ["4", 16], // Visa
+  ["51", 16], // Mastercard
+  ["52", 16], // Mastercard
+  ["53", 16], // Mastercard
+  ["54", 16], // Mastercard
+  ["55", 16], // Mastercard
+] as const;
+
+/**
+ * Generate a random valid Visa or Mastercard
+ * number (16 digits, Luhn-valid).
+ */
+const generate = (): string => {
+  const idx = randomInt(0, CARD_PREFIXES.length - 1);
+  const [prefix, length] = CARD_PREFIXES[
+    idx
+  ] as (typeof CARD_PREFIXES)[number];
+  const remaining = length - prefix.length - 1;
+  const payload = `${prefix}${randomDigits(remaining)}`;
+  const partial = `${payload}0`;
+  const remainder = luhnChecksum(partial);
+  const check = (10 - remainder) % 10;
+  return `${payload}${String(check)}`;
+};
+
+/** Credit Card Number (Luhn). */
+const creditCard: Validator = {
+  name: "Credit Card Number",
+  localName: "Credit Card Number",
+  abbreviation: "CC",
+  aliases: [
+    "credit card",
+    "card number",
+    "kreditní karta",
+    "Kreditkarte",
+  ] as const,
+  candidatePattern: "(?:\\d[\\s-]?){13,19}",
+  entityType: "any",
+  sourceUrl: "https://www.iso.org/standard/70484.html",
+  examples: [
+    "4111111111111111",
+    "5500000000000004",
+  ] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default creditCard;
+export { compact, detectNetwork, format, validate };
+export type { CardNetwork };

package/src/cu/mod.ts

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

package/src/cu/ni.ts

@@ -0,0 +1,125 @@
+/**
+ * NI (Número de Identidad, Cuban identity card number).
+ *
+ * 11 digits encoding birth date, century, sequence, and
+ * gender. Structure: YYMMDDXNNNN where:
+ *   - YYMMDD = birth date
+ *   - X = century digit (9=1800s, 0-5=1900s, 6-8=2000s)
+ *   - NNNN = sequence (digit at position 9 encodes gender:
+ *     even=male, odd=female)
+ *
+ * No check digit; validation is by date and format only.
+ *
+ * Ported from python-stdnum cu.ni module.
+ *
+ * @see https://www.ecured.cu/Carnet_de_Identidad
+ */
+
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { err } from "#util/result";
+
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  Validator,
+} from "../types";
+
+const compact = (value: string): string =>
+  clean(value, " -").trim();
+
+/**
+ * Derive the full birth year from the two-digit year
+ * and the century indicator at position 6.
+ */
+const centuryOffset = (digit: string): number => {
+  if (digit === "9") return 1800;
+  if (digit >= "0" && digit <= "5") return 1900;
+  return 2000;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "Cuban NI must be 11 digits",
+    );
+  }
+
+  if (!/^\d{11}$/.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Cuban NI must contain only digits",
+    );
+  }
+
+  const yy = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+  const year = centuryOffset(v[6]!) + yy;
+
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Cuban NI contains an invalid birth date",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Extract birth date and gender from a Cuban NI.
+ * 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(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+  const year = centuryOffset(v[6]!) + yy;
+
+  const genderDigit = Number(v[9]);
+  const gender: "male" | "female" =
+    genderDigit % 2 === 0 ? "male" : "female";
+
+  return {
+    birthDate: new Date(year, mm - 1, dd),
+    gender,
+  };
+};
+
+/**
+ * Cuban identity card number (NI).
+ *
+ * Examples sourced from python-stdnum test suite.
+ */
+const ni: Validator = {
+  name: "Cuban Identity Card Number",
+  localName: "Número de Identidad",
+  abbreviation: "NI",
+  aliases: [
+    "NI",
+    "número de identidad",
+    "carnet de identidad",
+  ] as const,
+  candidatePattern: "\\d{11}",
+  country: "CU",
+  entityType: "person",
+  lengths: [11] as const,
+  examples: ["91021027775", "72062506561"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl: "https://www.ecured.cu/Carnet_de_Identidad",
+};
+
+export default ni;
+export { compact, format, parse, validate };

package/src/cy/mod.ts

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