@stll/stdnum 0.0.1

package/src/pa/ruc.ts

@@ -0,0 +1,359 @@
+/**
+ * RUC (Registro Único de Contribuyente, Panama
+ * tax number).
+ *
+ * The RUC identifies taxpayers in Panama. It comes
+ * in several formats depending on entity type
+ * (natural person, legal entity, foreigner, etc.)
+ * and is always accompanied by a two-digit check
+ * code called the "dígito verificador" (DV).
+ *
+ * The DV is computed by encoding the hyphen-separated
+ * RUC into a 20-position numeric buffer, then applying
+ * a double weighted-sum mod 11 algorithm. The encoding
+ * and legacy-format handling follow the official ANIP/DGI
+ * specification.
+ *
+ * @see https://dgi.mef.gob.pa/
+ */
+
+import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "../types";
+
+/**
+ * Legacy cross-reference table: maps two-digit codes
+ * at positions 5–6 of old-format juridical RUCs.
+ */
+const LEGACY_MAP: Record<string, string> = {
+  "00": "00",
+  "10": "01",
+  "11": "02",
+  "12": "03",
+  "13": "04",
+  "14": "05",
+  "15": "06",
+  "16": "07",
+  "17": "08",
+  "18": "09",
+  "19": "01",
+  "20": "02",
+  "21": "03",
+  "22": "04",
+  "23": "07",
+  "24": "08",
+  "25": "09",
+  "26": "02",
+  "27": "03",
+  "28": "04",
+  "29": "05",
+  "30": "06",
+  "31": "07",
+  "32": "08",
+  "33": "09",
+  "34": "01",
+  "35": "02",
+  "36": "03",
+  "37": "04",
+  "38": "05",
+  "39": "06",
+  "40": "07",
+  "41": "08",
+  "42": "09",
+  "43": "01",
+  "44": "02",
+  "45": "03",
+  "46": "04",
+  "47": "05",
+  "48": "06",
+  "49": "07",
+};
+
+/** Prepend n leading zeros. */
+const z = (n: number): string => "0".repeat(Math.max(0, n));
+
+/**
+ * Compute a single DV digit via weighted sum mod 11.
+ * Weights start at 2 and increment, applied
+ * right-to-left. For old-format juridical RUCs,
+ * weight 12 is skipped (jumps from 11 to 13).
+ */
+const digitDV = (
+  buf: string,
+  isOldFormat: boolean,
+): number => {
+  let weight = 2;
+  let sum = 0;
+  for (let i = buf.length - 1; i >= 0; i--) {
+    if (isOldFormat && weight === 12) {
+      weight += 1; // skip 12, continue from 13
+    }
+    sum += weight * (buf.charCodeAt(i) - 48);
+    weight += 1;
+  }
+  const r = sum % 11;
+  return r > 1 ? 11 - r : 0;
+};
+
+/**
+ * Encode the RUC segments into a numeric buffer
+ * according to entity type, then compute the two
+ * DV digits.
+ *
+ * Returns the two-digit DV string, or null if the
+ * format is unrecognized.
+ */
+const computeDV = (
+  segments: readonly string[],
+  raw: string,
+): string | null => {
+  const len = segments.length;
+
+  if (
+    len < 3 ||
+    len > 4 ||
+    (len === 4 && segments[1] !== "NT")
+  ) {
+    return null;
+  }
+
+  let buf: string;
+  let isOld = false;
+
+  const s0 = segments[0]!;
+  const s1 = segments[1]!;
+  const s2 = segments[2]!;
+
+  if (raw[0] === "E") {
+    // Foreign person (E-xxx-xxx)
+    buf =
+      z(4 - s1.length) +
+      "0000005" +
+      "00" +
+      "50" +
+      z(3 - s1.length) +
+      s1 +
+      z(5 - s2.length) +
+      s2;
+  } else if (s1 === "NT") {
+    // NT designation (xxNT-xxx-xxx)
+    const s3 = segments[3]!;
+    const prefix = s0.slice(0, -2);
+    buf =
+      z(4 - s1.length) +
+      "0000005" +
+      z(4 - prefix.length) +
+      prefix +
+      "43" +
+      z(3 - s2.length) +
+      s2 +
+      z(5 - s3.length) +
+      s3;
+  } else if (s0.endsWith("AV")) {
+    // AV suffix
+    const prefix = s0.slice(0, -2);
+    buf =
+      z(4 - s1.length) +
+      "0000005" +
+      z(4 - prefix.length) +
+      prefix +
+      "15" +
+      z(3 - s1.length) +
+      s1 +
+      z(5 - s2.length) +
+      s2;
+  } else if (s0.endsWith("PI")) {
+    // PI suffix
+    const prefix = s0.slice(0, -2);
+    buf =
+      z(4 - s1.length) +
+      "0000005" +
+      z(4 - prefix.length) +
+      prefix +
+      "79" +
+      z(3 - s1.length) +
+      s1 +
+      z(5 - s2.length) +
+      s2;
+  } else if (s0 === "PE") {
+    // PE prefix (foreign-born)
+    buf =
+      z(4 - s1.length) +
+      "0000005" +
+      "00" +
+      "75" +
+      z(3 - s1.length) +
+      s1 +
+      z(5 - s2.length) +
+      s2;
+  } else if (raw[0] === "N") {
+    // N prefix (naturalized citizen)
+    buf =
+      z(4 - s1.length) +
+      "0000005" +
+      "00" +
+      "40" +
+      z(3 - s1.length) +
+      s1 +
+      z(5 - s2.length) +
+      s2;
+  } else if (s0.length >= 1 && s0.length <= 2) {
+    // Natural person (province 1–2 digits)
+    buf =
+      z(4 - s1.length) +
+      "0000005" +
+      z(2 - s0.length) +
+      s0 +
+      "00" +
+      z(3 - s1.length) +
+      s1 +
+      z(5 - s2.length) +
+      s2;
+  } else {
+    // Juridical (company)
+    buf =
+      z(10 - s0.length) +
+      s0 +
+      z(4 - s1.length) +
+      s1 +
+      z(6 - s2.length) +
+      s2;
+    isOld =
+      buf[3] === "0" && buf[4] === "0" && buf[5]! < "5";
+  }
+
+  // Apply legacy cross-reference for old format
+  if (isOld) {
+    const key = buf.slice(5, 7);
+    const mapped = LEGACY_MAP[key] ?? key;
+    buf = buf.slice(0, 5) + mapped + buf.slice(7);
+  }
+
+  const dv1 = digitDV(buf, isOld);
+  const dv2 = digitDV(
+    buf + String.fromCharCode(48 + dv1),
+    isOld,
+  );
+
+  return `${dv1}${dv2}`;
+};
+
+/**
+ * Compact: normalize Unicode, collapse whitespace,
+ * strip colons around DV, and uppercase. Keeps
+ * hyphens (structural separators) and a single
+ * space before "DV".
+ */
+const compact = (value: string): string => {
+  let v = clean(value, "").trim().toUpperCase();
+  // Normalize DV portion: " DV: 49" -> " DV49"
+  v = v.replace(/\s*DV[:\s]*(\d{2})$/, " DV$1");
+  // Collapse any remaining internal whitespace
+  v = v.replace(/\s+/g, " ");
+  return v;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  // Extract the DV portion: "...DV49", "...DV:49",
+  // or "... DV 49"
+  const dvMatch = v.match(/^(.+?)-?\s*DV[:\s]*(\d{2})$/);
+
+  if (!dvMatch) {
+    return err(
+      "INVALID_FORMAT",
+      "Panama RUC must include DV " +
+        "(dígito verificador)",
+    );
+  }
+
+  const rucPart = dvMatch[1]!;
+  const dvPart = dvMatch[2]!;
+
+  // The RUC part should be hyphen-separated segments
+  const segments = rucPart.replace(/-+$/, "").split("-");
+
+  if (segments.length < 3 || segments.length > 4) {
+    return err(
+      "INVALID_FORMAT",
+      "Panama RUC must have 3–4 " +
+        "hyphen-separated segments",
+    );
+  }
+
+  if (segments.some((s) => s.length === 0)) {
+    return err(
+      "INVALID_FORMAT",
+      "Panama RUC segments must not be empty",
+    );
+  }
+
+  const computed = computeDV(segments, rucPart);
+  if (computed === null) {
+    return err(
+      "INVALID_FORMAT",
+      "Unrecognized Panama RUC format",
+    );
+  }
+
+  if (computed !== dvPart) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Panama RUC dígito verificador " + "does not match",
+    );
+  }
+
+  const compactForm = segments.join("-") + " DV" + dvPart;
+  return { valid: true, compact: compactForm };
+};
+
+/**
+ * Format: display as segments with " DV XX".
+ */
+const format = (value: string): string => {
+  const v = compact(value);
+  const dvMatch = v.match(/^(.+?)-?\s*DV[:\s]*(\d{2})$/);
+  if (!dvMatch) return v;
+
+  const rucPart = dvMatch[1]!.replace(/-+$/, "");
+  const dvPart = dvMatch[2]!;
+  const segments = rucPart.split("-");
+  return `${segments.join("-")} DV ${dvPart}`;
+};
+
+/** Generate a random valid Panama RUC (natural person). */
+const generate = (): string => {
+  const province = String(randomInt(1, 13));
+  const volume = String(randomInt(1, 9999));
+  const folio = String(randomInt(1, 99999));
+  const segments = [province, volume, folio];
+  const dv = computeDV(segments, segments.join("-"))!;
+  return `${segments.join("-")} DV${dv}`;
+};
+
+/** Panama tax identification number. */
+const ruc: Validator = {
+  name: "Tax Identification Number",
+  localName: "Registro Único de Contribuyente",
+  abbreviation: "RUC",
+  aliases: ["RUC"] as const,
+  candidatePattern: "\\d{1,2}-?\\d{1,4}-?\\d{1,6}",
+  country: "PA",
+  entityType: "any",
+  description: "Tax identifier issued by Panama's DGI",
+  sourceUrl: "https://dgi.mef.gob.pa/",
+  examples: [
+    "1-184-921 DV49",
+    "2588017-1-831938 DV20",
+  ] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default ruc;
+export { compact, format, validate, generate };

package/src/patterns.ts

@@ -0,0 +1,252 @@
+/**
+ * Derive candidate-matching regex patterns from
+ * validators. These patterns find CANDIDATES in
+ * text — use `validate()` to confirm each match.
+ *
+ * Designed for integration with regex-set or
+ * similar multi-pattern scanning engines.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   toRegex, byCountry, byEntityType,
+ * } from "@stll/stdnum/patterns";
+ * import { cz } from "@stll/stdnum";
+ *
+ * // Single validator
+ * toRegex(cz.ico);
+ * // → /(?<!\w)\d{8}(?!\w)/g
+ *
+ * // All Czech validators
+ * byCountry("CZ");
+ * // → [{ validator: cz.ico, regex }, ...]
+ *
+ * // All company identifiers
+ * byEntityType("company");
+ * // → [{ validator, regex }, ...]
+ * ```
+ */
+
+import type { CountryCode, Validator } from "./types";
+
+// ─── Pattern type ─────────────────────────────
+
+export type ValidatorPattern = {
+  /** The validator this pattern was derived from. */
+  validator: Validator;
+  /** Loose regex matching candidates in text. */
+  regex: RegExp;
+};
+
+// ─── Regex derivation ─────────────────────────
+
+/** Separator chars that compact() strips. */
+const SEP = "[\\s\\-./]?";
+
+/**
+ * Infer compact lengths from metadata or examples.
+ */
+const inferLengths = (v: Validator): number[] => {
+  if (v.lengths && v.lengths.length > 0) {
+    return [...v.lengths];
+  }
+  if (v.examples && v.examples.length > 0) {
+    const lens = new Set<number>();
+    for (const ex of v.examples) {
+      lens.add(v.compact(ex).length);
+    }
+    return [...lens];
+  }
+  return [];
+};
+
+/**
+ * Derive the display grouping from format().
+ * Returns an array of group sizes, e.g.,
+ * "25 123 891" → [2, 3, 3].
+ */
+const inferGroups = (v: Validator): number[] | null => {
+  if (!v.examples || v.examples.length === 0) {
+    return null;
+  }
+  const compact = v.compact(v.examples[0]!);
+  const formatted = v.format(compact);
+  if (formatted === compact) return null;
+
+  // Split on non-alphanumeric separators
+  const parts = formatted.split(/[^a-zA-Z0-9]+/);
+  if (parts.length <= 1) return null;
+
+  // For digit-only validators, skip letter-only
+  // tokens (prefix like "CHE"). For alphanumeric
+  // validators (IBAN, ISIN), keep all groups.
+  const isAlphanumeric = parts.some(
+    (p) => /[a-zA-Z]/.test(p) && /\d/.test(p),
+  );
+  const groups = parts
+    .filter(
+      (p) =>
+        p.length > 0 && (isAlphanumeric || /\d/.test(p)),
+    )
+    .map((p) => p.length);
+
+  return groups.length > 1 ? groups : null;
+};
+
+/**
+ * Detect if this validator uses a known prefix
+ * (e.g., "CZ" for DIČ, "CHE" for Swiss UID).
+ */
+const inferPrefix = (v: Validator): string | null => {
+  if (!v.examples || v.examples.length === 0) {
+    return null;
+  }
+  const compact = v.compact(v.examples[0]!);
+  // Prefix already present in compact form.
+  // But only if ALL examples share the same prefix
+  // (e.g., "CHE" for Swiss UID). If examples have
+  // different prefixes (IBAN: GB/DE/FR), there's
+  // no fixed prefix — it's part of the value.
+  const compactMatch = compact.match(/^([A-Z]+)\d/);
+  if (compactMatch && v.examples!.length > 1) {
+    const pfx = compactMatch[1]!;
+    const allSame = v.examples!.every((ex) =>
+      v.compact(ex).startsWith(pfx),
+    );
+    if (allSame) return pfx;
+  } else if (compactMatch && v.examples!.length === 1) {
+    return compactMatch[1]!;
+  }
+  // Prefix added only by format()
+  // (e.g., "DE" for de.vat, "CZ" for cz.dic)
+  const formatted = v.format(compact);
+  const fmtMatch = formatted.match(/^([A-Z]+)[\s\-./]?\d/);
+  if (fmtMatch && !compact.startsWith(fmtMatch[1]!)) {
+    return fmtMatch[1]!;
+  }
+  return null;
+};
+
+/**
+ * Determine the character class needed for the
+ * compact form: `\d` if all digits, `[A-Z0-9]`
+ * if alphanumeric, etc.
+ */
+const inferCharClass = (v: Validator): string => {
+  if (!v.examples || v.examples.length === 0) {
+    return "\\d";
+  }
+  let hasLetter = false;
+  let hasDigit = false;
+  for (const ex of v.examples) {
+    const c = v.compact(ex);
+    for (const ch of c) {
+      if (/[a-zA-Z]/.test(ch)) hasLetter = true;
+      if (/\d/.test(ch)) hasDigit = true;
+    }
+  }
+  if (hasLetter && hasDigit) return "[A-Z0-9]";
+  if (hasLetter) return "[A-Z]";
+  return "\\d";
+};
+
+/**
+ * Build a group regex from group sizes + char class.
+ * [2, 3, 3] with \d → /\d{2}[\s\-.]?\d{3}[\s\-.]?\d{3}/
+ */
+const groupsToPattern = (
+  groups: number[],
+  cc: string,
+): string => groups.map((g) => `${cc}{${g}}`).join(SEP);
+
+/**
+ * Derive a loose candidate-matching regex from
+ * a validator. The regex finds potential matches;
+ * use `validate()` to confirm.
+ *
+ * Handles both digit-only (IČO, NIP) and
+ * alphanumeric (IBAN, BIC, ISIN, LEI) validators.
+ */
+export const toRegex = (v: Validator): RegExp => {
+  const prefix = inferPrefix(v);
+  const groups = inferGroups(v);
+  const lengths = inferLengths(v);
+  const cc = inferCharClass(v);
+
+  let pattern: string;
+
+  if (groups && lengths.length <= 1) {
+    pattern = groupsToPattern(groups, cc);
+  } else if (lengths.length === 1) {
+    pattern = `${cc}{${lengths[0]}}`;
+  } else if (lengths.length > 1) {
+    const min = Math.min(...lengths);
+    const max = Math.max(...lengths);
+    pattern = `${cc}{${min},${max}}`;
+  } else {
+    pattern = `${cc}{6,20}`;
+  }
+
+  if (prefix) {
+    pattern = `${prefix}${SEP}${pattern}`;
+  }
+
+  // Word boundary to avoid matching inside
+  // larger numbers
+  return new RegExp(`(?<!\\w)${pattern}(?!\\w)`, "g");
+};
+
+// ─── Grouped collections ──────────────────────
+
+/**
+ * All discovered validators, lazily populated.
+ * Import * from "../src" would pull everything;
+ * instead, callers pass validators explicitly.
+ */
+
+/**
+ * Build patterns for a list of validators.
+ */
+export const toPatterns = (
+  validators: readonly Validator[],
+): ValidatorPattern[] =>
+  validators.map((v) => ({
+    validator: v,
+    regex: toRegex(v),
+  }));
+
+/**
+ * Filter validators by country code and build
+ * patterns.
+ */
+export const byCountry = (
+  country: CountryCode,
+  validators: readonly Validator[],
+): ValidatorPattern[] =>
+  toPatterns(
+    validators.filter((v) => v.country === country),
+  );
+
+/**
+ * Filter validators by entity type and build
+ * patterns.
+ */
+export const byEntityType = (
+  entityType: "person" | "company" | "any",
+  validators: readonly Validator[],
+): ValidatorPattern[] =>
+  toPatterns(
+    validators.filter(
+      (v) =>
+        entityType === "any" ||
+        v.entityType === entityType ||
+        v.entityType === "any",
+    ),
+  );
+
+/**
+ * Build patterns for ALL provided validators.
+ */
+export const allPatterns = (
+  validators: readonly Validator[],
+): ValidatorPattern[] => toPatterns(validators);

package/src/pe/mod.ts

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