@stll/stdnum 0.0.1

package/src/pe/ruc.ts

@@ -0,0 +1,121 @@
+/**
+ * RUC (Registro Único de Contribuyentes).
+ *
+ * Peruvian tax identification number assigned by SUNAT
+ * (Superintendencia Nacional de Aduanas y de
+ * Administración Tributaria). The number consists of
+ * 11 digits: a type prefix (10 = person, 20 = company,
+ * among others), 8 identification digits, and a check
+ * digit computed using a weighted modulo 11 algorithm.
+ *
+ * Format: XXXXXXXXXXX (11 digits, no separators).
+ *
+ * @see https://www.sunat.gob.pe/
+ * @see https://en.wikipedia.org/wiki/Tax_identification_number#Peru
+ */
+
+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";
+
+/**
+ * Valid type prefixes for RUC numbers.
+ * 10 = natural person, 15 = non-domiciled without RUC,
+ * 17 = non-domiciled, 20 = legal entity,
+ * others for specific entity types.
+ */
+const VALID_PREFIXES = new Set(["10", "15", "17", "20"]);
+
+const WEIGHTS = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+
+const compact = (value: string): string =>
+  clean(value, " -.").trim();
+
+/**
+ * Compute the RUC check digit using weighted sum
+ * mod 11. Weights: [5, 4, 3, 2, 7, 6, 5, 4, 3, 2].
+ *
+ * check = 11 - (sum % 11); if >= 10, subtract 10.
+ */
+const calcCheckDigit = (body: string): number => {
+  let sum = 0;
+  for (let i = 0; i < 10; i++) {
+    sum += Number(body[i]) * WEIGHTS[i]!;
+  }
+  const remainder = 11 - (sum % 11);
+  if (remainder >= 10) return remainder - 10;
+  return remainder;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 11) {
+    return err("INVALID_LENGTH", "RUC must be 11 digits");
+  }
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "RUC must contain only digits",
+    );
+  }
+
+  const prefix = v.slice(0, 2);
+  if (!VALID_PREFIXES.has(prefix)) {
+    return err(
+      "INVALID_COMPONENT",
+      "RUC has an invalid type prefix",
+    );
+  }
+
+  const expected = calcCheckDigit(v.slice(0, 10));
+  if (Number(v[10]) !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "RUC check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Peruvian RUC. */
+const generate = (): string => {
+  const prefixes = ["10", "15", "17", "20"] as const;
+  const prefix =
+    prefixes[Math.floor(Math.random() * prefixes.length)]!;
+  const body = prefix + randomDigits(8);
+  return body + String(calcCheckDigit(body));
+};
+
+/**
+ * Peruvian RUC (tax identification number).
+ *
+ * Examples sourced from python-stdnum test suite
+ * (pe.ruc module).
+ */
+const ruc: Validator = {
+  name: "Peruvian Tax ID",
+  localName: "Registro Único de Contribuyentes",
+  abbreviation: "RUC",
+  aliases: ["RUC"] as const,
+  candidatePattern: "\\d{11}",
+  country: "PE",
+  entityType: "any",
+  compact,
+  format,
+  validate,
+  sourceUrl: "https://www.sunat.gob.pe/",
+  lengths: [11] as const,
+  examples: ["20131312955", "20100047218"] as const,
+  generate,
+};
+
+export default ruc;
+export { compact, format, validate, generate };

package/src/ph/mod.ts

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

package/src/ph/philid.ts

@@ -0,0 +1,76 @@
+/** Generate a random valid PhilID. */
+const generate = (): string => randomDigits(12);
+
+/**
+ * PhilID (Philippine Identification System Number,
+ * PhilSys Card Number, PCN).
+ *
+ * 12-digit personal identifier issued under the
+ * Philippine Identification System (PhilSys).
+ * Formatted as XXXX-XXXXXXX-X. No check digit
+ * algorithm is publicly documented.
+ *
+ * @see https://en.wikipedia.org/wiki/Philippine_national_identity_card
+ * @see https://philsys.gov.ph/
+ */
+
+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 !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "PhilID must be exactly 12 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "PhilID must contain only digits",
+    );
+  }
+  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, 11)}-${v.slice(11)}`;
+  }
+  return v;
+};
+
+/** Philippine Identification System Number. */
+const philid: Validator = {
+  name: "Philippine Identification System Number",
+  localName: "PhilSys Card Number",
+  abbreviation: "PhilID",
+  aliases: ["PhilID", "PhilSys", "Philippine ID"] as const,
+  candidatePattern: "\\d{4}-\\d{4}-\\d{4}-\\d{4}",
+  country: "PH",
+  entityType: "person",
+  description:
+    "12-digit personal identifier issued under" +
+    " the Philippine Identification System",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/" +
+    "Philippine_national_identity_card",
+  lengths: [12] as const,
+  examples: ["123456789012", "000011112222"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default philid;
+export { compact, format, validate, generate };

package/src/pk/cnic.ts

@@ -0,0 +1,103 @@
+/** Generate a random valid Pakistan CNIC. */
+const generate = (): string => {
+  const province = String(randomInt(1, 7));
+  const district = randomDigits(4);
+  const serial = randomDigits(7);
+  const gender = String(randomInt(1, 9));
+  return `${province}${district}${serial}${gender}`;
+};
+
+/**
+ * CNIC (Computerized National Identity Card, Pakistan).
+ *
+ * 13 digits: PPPPP-DDDDDDD-G where P is a province/
+ * district code (5 digits), D is a sequential number
+ * (7 digits), and G is a gender digit (odd = male,
+ * even = female, including 0). No checksum; structural
+ * validation.
+ *
+ * @see https://www.geo.tv/latest/157233-secret-behind-every-digit-of-the-cnic-number
+ * @see https://en.wikipedia.org/wiki/CNIC_(Pakistan)
+ */
+
+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, " -");
+
+/** Valid province IDs (first digit). */
+const VALID_PROVINCES = new Set([
+  "1",
+  "2",
+  "3",
+  "4",
+  "5",
+  "6",
+  "7",
+]);
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 13) {
+    return err("INVALID_LENGTH", "CNIC must be 13 digits");
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "CNIC must contain only digits",
+    );
+  }
+  // First digit must be a valid province code
+  if (!VALID_PROVINCES.has(v[0]!)) {
+    return err(
+      "INVALID_COMPONENT",
+      "CNIC province code is invalid",
+    );
+  }
+  // Last digit indicates gender: odd = male,
+  // even = female. Digit 0 is rejected per
+  // python-stdnum convention; NADRA does not
+  // publish whether 0 is a valid gender code.
+  // @see https://www.geo.tv/latest/157233
+  if (v[12] === "0") {
+    return err(
+      "INVALID_COMPONENT",
+      "CNIC gender digit must not be 0",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 5)}-${v.slice(5, 12)}-${v.slice(12)}`;
+};
+
+/** Pakistan Computerized National Identity Card. */
+const cnic: Validator = {
+  name: "Computerized National Identity Card",
+  localName: "Computerized National Identity Card",
+  abbreviation: "CNIC",
+  aliases: ["CNIC", "شناختی کارڈ"] as const,
+  candidatePattern: "\\d{5}-?\\d{7}-?\\d",
+  country: "PK",
+  entityType: "person",
+  lengths: [13],
+  examples: ["3520112345671", "4210112345672"],
+  description:
+    "13-digit identity card number issued by NADRA",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/CNIC_(Pakistan)",
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default cnic;
+export { compact, format, validate, generate };

package/src/pk/mod.ts

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

package/src/pl/mod.ts

@@ -0,0 +1,3 @@
+export { default as nip } from "./nip";
+export { default as pesel } from "./pesel";
+export { default as regon } from "./regon";

package/src/pl/nip.ts

@@ -0,0 +1,96 @@
+/**
+ * NIP (Numer Identyfikacji Podatkowej).
+ *
+ * Polish VAT number. 10 digits with a weighted
+ * checksum. The last digit is the check digit.
+ *
+ * @see https://www.biznes.gov.pl/en/portal/004124
+ * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/poland-tin.pdf
+ */
+
+import { weightedSum } from "#checksums/weighted-sum";
+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 = [6, 5, 7, 2, 3, 4, 5, 6, 7] as const;
+
+const compact = (value: string): string => {
+  const v = clean(value, " -");
+  if (v.startsWith("PL") || v.startsWith("pl")) {
+    return v.slice(2);
+  }
+  return v;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "NIP must be exactly 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "NIP must contain only digits",
+    );
+  }
+  const sum = weightedSum(v.slice(0, 9), WEIGHTS, 11);
+  // If remainder is 10, no valid check digit exists
+  if (sum >= 10 || sum !== Number(v[9])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "NIP check digit does not match",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `PL${compact(value)}`;
+
+const MAX_GENERATE_ATTEMPTS = 100;
+
+/**
+ * Generate a random valid NIP. Retries if the
+ * weighted sum mod 11 yields 10 (no valid check
+ * digit for that payload).
+ */
+const generate = (): string => {
+  for (let i = 0; i < MAX_GENERATE_ATTEMPTS; i++) {
+    const payload = randomDigits(9);
+    const sum = weightedSum(payload, WEIGHTS, 11);
+    if (sum < 10) {
+      return `${payload}${String(sum)}`;
+    }
+  }
+  throw new Error("Failed to generate valid NIP");
+};
+
+/** Polish VAT Number. */
+const nip: Validator = {
+  name: "Polish VAT Number",
+  localName: "Numer Identyfikacji Podatkowej",
+  abbreviation: "NIP",
+  aliases: [
+    "NIP",
+    "numer identyfikacji podatkowej",
+  ] as const,
+  candidatePattern: "\\d{3}-?\\d{3}-?\\d{2}-?\\d{2}",
+  country: "PL",
+  entityType: "company",
+  sourceUrl: "https://www.biznes.gov.pl/en/portal/004124",
+  examples: ["2234567895"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nip;
+export { compact, format, generate, validate };

package/src/pl/pesel.ts

@@ -0,0 +1,153 @@
+/**
+ * PESEL (Powszechny Elektroniczny System
+ * Ewidencji Ludności).
+ *
+ * Polish national identification number.
+ * 11 digits encoding date of birth, serial
+ * number, gender, and a check digit.
+ *
+ * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/poland-tin.pdf
+ * @see https://www.gov.pl/web/cyfryzacja/numer-pesel
+ */
+
+import { weightedSum } from "#checksums/weighted-sum";
+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 WEIGHTS = [1, 3, 7, 9, 1, 3, 7, 9, 1, 3] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "PESEL must be exactly 11 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "PESEL 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));
+
+  // Century encoding via month offset
+  let century: number;
+  if (mm >= 81 && mm <= 92) {
+    century = 1800;
+  } else if (mm >= 1 && mm <= 12) {
+    century = 1900;
+  } else if (mm >= 21 && mm <= 32) {
+    century = 2000;
+  } else if (mm >= 41 && mm <= 52) {
+    century = 2100;
+  } else if (mm >= 61 && mm <= 72) {
+    century = 2200;
+  } else {
+    return err(
+      "INVALID_COMPONENT",
+      "PESEL contains an invalid month",
+    );
+  }
+
+  const year = century + yy;
+  const month = mm % 20;
+  if (!isValidDate(year, month, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "PESEL contains an invalid date",
+    );
+  }
+
+  const sum = weightedSum(v.slice(0, 10), WEIGHTS, 10);
+  const check = (10 - sum) % 10;
+  if (check !== Number(v[10])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "PESEL check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Extract birth date and gender from a PESEL 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 yy = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+  const serial = Number(v[9]);
+
+  let century: number;
+  if (mm >= 81) century = 1800;
+  else if (mm <= 12) century = 1900;
+  else if (mm <= 32) century = 2000;
+  else if (mm <= 52) century = 2100;
+  else century = 2200;
+
+  return {
+    birthDate: new Date(century + yy, (mm % 20) - 1, dd),
+    gender: serial % 2 === 0 ? "female" : "male",
+  };
+};
+
+/** Generate a random valid Polish PESEL. */
+const generate = (): string => {
+  for (;;) {
+    const yy = String(randomInt(0, 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 payload = yy + mm + dd + serial;
+    const sum = weightedSum(payload, WEIGHTS, 10);
+    const c = payload + String((10 - sum) % 10);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Polish National Identification Number. */
+const pesel: Validator = {
+  name: "Polish National ID",
+  localName:
+    "Powszechny Elektroniczny System Ewidencji Ludności",
+  abbreviation: "PESEL",
+  aliases: ["PESEL"] as const,
+  candidatePattern: "\\d{11}",
+  country: "PL",
+  entityType: "person",
+  sourceUrl:
+    "https://www.gov.pl/web/cyfryzacja/numer-pesel",
+  examples: ["02070803628"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default pesel;
+export { compact, format, parse, validate, generate };

package/src/pl/regon.ts

@@ -0,0 +1,98 @@
+/**
+ * REGON (Rejestr Gospodarki Narodowej).
+ *
+ * Polish statistical identification number for
+ * businesses. 9 digits for national entities,
+ * 14 digits for local units (9 + 5 extension).
+ * Both have weighted checksums.
+ *
+ * @see https://bip.stat.gov.pl/en/regon/
+ */
+
+import { weightedSum } from "#checksums/weighted-sum";
+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_9 = [8, 9, 2, 3, 4, 5, 6, 7] as const;
+const WEIGHTS_14 = [
+  2, 4, 8, 5, 0, 9, 7, 3, 6, 1, 2, 4, 8,
+] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9 && v.length !== 14) {
+    return err(
+      "INVALID_LENGTH",
+      "REGON must be 9 or 14 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "REGON must contain only digits",
+    );
+  }
+
+  // Validate 9-digit base
+  const sum9 = weightedSum(v.slice(0, 8), WEIGHTS_9, 11);
+  if (String(sum9 % 10) !== v[8]) {
+    return err(
+      "INVALID_CHECKSUM",
+      "REGON check digit does not match",
+    );
+  }
+
+  // Validate 14-digit extension
+  if (v.length === 14) {
+    const sum14 = weightedSum(
+      v.slice(0, 13),
+      WEIGHTS_14,
+      11,
+    );
+    if (String(sum14 % 10) !== v[13]) {
+      return err(
+        "INVALID_CHECKSUM",
+        "REGON local unit check digit mismatch",
+      );
+    }
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid 9-digit Polish REGON. */
+const generate = (): string => {
+  for (;;) {
+    const c = randomDigits(9);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Polish Statistical Identification Number. */
+const regon: Validator = {
+  name: "Polish Business Register Number",
+  localName: "Rejestr Gospodarki Narodowej",
+  abbreviation: "REGON",
+  aliases: ["REGON", "numer statystyczny"] as const,
+  candidatePattern: "\\d{9,14}",
+  country: "PL",
+  entityType: "company",
+  sourceUrl: "https://bip.stat.gov.pl/en/regon/",
+  examples: ["123456785", "12345678512347"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default regon;
+export { compact, format, validate, generate };