@stll/stdnum 2.1.1 → 2.1.3

package/src/patterns.ts

@@ -1,390 +0,0 @@
-/**
- * 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,
-  CountryValidator,
-  Validator,
-} from "./types";
-
-// ─── Pattern type ─────────────────────────────
-
-export type ValidatorPattern<
-  TValidator extends Validator = Validator,
-> = {
-  /** The validator this pattern was derived from. */
-  validator: TValidator;
-  /** 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 => {
-  const first = v.examples?.[0];
-  if (first === undefined) return null;
-  const compact = v.compact(first);
-  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 => {
-  const examples = v.examples;
-  const first = examples?.[0];
-  if (!examples || first === undefined) return null;
-  const compact = v.compact(first);
-  // 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/);
-  const compactPrefix = compactMatch?.[1];
-  if (compactPrefix !== undefined && examples.length > 1) {
-    const allSame = examples.every((ex) =>
-      v.compact(ex).startsWith(compactPrefix),
-    );
-    if (allSame) return compactPrefix;
-  } else if (
-    compactPrefix !== undefined &&
-    examples.length === 1
-  ) {
-    return compactPrefix;
-  }
-  // 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/);
-  const fmtPrefix = fmtMatch?.[1];
-  if (
-    fmtPrefix !== undefined &&
-    !compact.startsWith(fmtPrefix)
-  ) {
-    return fmtPrefix;
-  }
-  return null;
-};
-
-/**
- * Character class for a string fragment:
- * `\d` if all digits, `[A-Z]` if all letters,
- * `[A-Z0-9]` if mixed.
- */
-const charClassFor = (s: string): string => {
-  let hasLetter = false;
-  let hasDigit = false;
-  for (const ch of s) {
-    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";
-};
-
-/**
- * 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";
-  }
-  const combined = v.examples
-    .map((ex) => v.compact(ex))
-    .join("");
-  return charClassFor(combined);
-};
-
-type PerGroup = { size: number; charClass: string };
-
-/**
- * Infer per-group sizes AND character classes from
- * format(). Returns groups with per-position char
- * classes, e.g., "12 010188 M 01 1" →
- *   sizes: [2, 6, 1, 2, 1]
- *   classes: ["\d", "\d", "[A-Z]", "\d", "\d"]
- *
- * Only returns non-null when per-group classes
- * differ (some groups are letters, some digits).
- * Letter-only groups before the first digit group
- * are treated as prefixes and excluded (handled
- * by inferPrefix separately).
- */
-const inferPerGroup = (v: Validator): PerGroup[] | null => {
-  const first = v.examples?.[0];
-  if (first === undefined) return null;
-  const compact = v.compact(first);
-  const formatted = v.format(compact);
-  if (formatted === compact) return null;
-
-  // Only applies to mixed validators (compact has
-  // both letters and digits in separate positions,
-  // like German SVNR "12010188M011").
-  const compactMixed =
-    /[a-zA-Z]/.test(compact) && /\d/.test(compact);
-  if (!compactMixed) return null;
-
-  // Also skip if any single part mixes letters and
-  // digits (IBAN, ISIN) — inferGroups already
-  // handles those correctly with the global class.
-  const parts = formatted.split(/[^a-zA-Z0-9]+/);
-  const isAlphanumeric = parts.some(
-    (p) => /[a-zA-Z]/.test(p) && /\d/.test(p),
-  );
-  if (isAlphanumeric) return null;
-
-  // Keep digit groups and letter-only groups that
-  // appear AFTER the first digit group (embedded
-  // letters). Skip letter-only groups before the
-  // first digit group (prefix like "CHE").
-  const filtered: PerGroup[] = [];
-  let seenDigitGroup = false;
-  for (const p of parts) {
-    if (p.length === 0) continue;
-    if (/\d/.test(p)) {
-      seenDigitGroup = true;
-      filtered.push({
-        size: p.length,
-        charClass: charClassFor(p),
-      });
-    } else if (seenDigitGroup) {
-      filtered.push({
-        size: p.length,
-        charClass: charClassFor(p),
-      });
-    }
-  }
-
-  if (filtered.length <= 1) return null;
-
-  const firstClass = filtered[0]?.charClass;
-  const allSame = filtered.every(
-    (g) => g.charClass === firstClass,
-  );
-  if (allSame) return null;
-
-  return filtered;
-};
-
-/**
- * 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);
-
-/**
- * Build a group regex with per-group char classes.
- * Produces tighter patterns when groups have different
- * character types (e.g., digits vs letters).
- */
-const groupsToPatternPerClass = (
-  groups: readonly { size: number; charClass: string }[],
-): string =>
-  groups
-    .map(({ size, charClass }) => `${charClass}{${size}}`)
-    .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;
-
-  // Use per-group char classes when groups mix
-  // digits and letters (e.g., German SVNR:
-  // "12 010188 M 01 1" → [\d, \d, [A-Z], \d, \d]).
-  // This prevents overly broad [A-Z0-9] from
-  // matching all-caps prose as identifiers.
-  const perGroup = inferPerGroup(v);
-
-  if (perGroup && lengths.length <= 1) {
-    pattern = groupsToPatternPerClass(perGroup);
-  } else 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 = <TValidator extends Validator>(
-  validators: readonly TValidator[],
-): ValidatorPattern<TValidator>[] =>
-  validators.map((v) => ({
-    validator: v,
-    regex: toRegex(v),
-  }));
-
-/**
- * Filter validators by country code and build
- * patterns.
- */
-type CountryScopedValidator<
-  TValidator extends Validator,
-  TCountry extends CountryCode,
-> =
-  TValidator extends CountryValidator<
-    infer TValidatorCountry,
-    infer TParsed
-  >
-    ? TCountry extends TValidatorCountry
-      ? TValidator & CountryValidator<TCountry, TParsed>
-      : TValidatorCountry extends TCountry
-        ? TValidator
-        : never
-    : never;
-
-export const byCountry = <
-  TCountry extends CountryCode,
-  TValidator extends Validator,
->(
-  country: TCountry,
-  validators: readonly TValidator[],
-): ValidatorPattern<
-  CountryScopedValidator<TValidator, TCountry>
->[] => {
-  const countryValidators = validators.filter(
-    (
-      v,
-    ): v is CountryScopedValidator<TValidator, TCountry> =>
-      v.scope === "country" && v.country === country,
-  );
-  return toPatterns(countryValidators);
-};
-
-/**
- * Filter validators by entity type and build
- * patterns.
- */
-export const byEntityType = <TValidator extends Validator>(
-  entityType: "person" | "company" | "any",
-  validators: readonly TValidator[],
-): ValidatorPattern<TValidator>[] =>
-  toPatterns(
-    validators.filter(
-      (v) =>
-        entityType === "any" ||
-        v.entityType === entityType ||
-        v.entityType === "any",
-    ),
-  );
-
-/**
- * Build patterns for ALL provided validators.
- */
-export const allPatterns = <TValidator extends Validator>(
-  validators: readonly TValidator[],
-): ValidatorPattern<TValidator>[] => toPatterns(validators);

package/src/pe/mod.ts

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

package/src/pe/ruc.ts

@@ -1,124 +0,0 @@
-/**
- * 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 type {
-  ValidateResult,
-  CountryValidator,
-} from "../types";
-
-import { clean } from "#util/clean";
-import { randomDigits, randomPick } from "#util/generate";
-import { err } from "#util/result";
-import { isdigits } from "#util/strings";
-
-/**
- * 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] as const;
-const GENERATE_PREFIXES = ["10", "15", "17", "20"] as const;
-
-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 (const [i, weight] of WEIGHTS.entries()) {
-    sum += Number(body[i]) * weight;
-  }
-  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 prefix = randomPick(GENERATE_PREFIXES);
-  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: CountryValidator<"PE"> = {
-  name: "Peruvian Tax ID",
-  localName: "Registro Único de Contribuyentes",
-  abbreviation: "RUC",
-  aliases: ["RUC"] as const,
-  candidatePattern: "\\d{11}",
-  scope: "country",
-  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

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

package/src/ph/philid.ts

@@ -1,80 +0,0 @@
-/** 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 type {
-  ValidateResult,
-  CountryValidator,
-} from "../types";
-
-import { clean } from "#util/clean";
-import { randomDigits } from "#util/generate";
-import { err } from "#util/result";
-import { isdigits } from "#util/strings";
-
-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: CountryValidator<"PH"> = {
-  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}",
-  scope: "country",
-  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

@@ -1,109 +0,0 @@
-/** 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 type {
-  ValidateResult,
-  CountryValidator,
-} from "../types";
-
-import { clean } from "#util/clean";
-import { randomDigits, randomInt } from "#util/generate";
-import { err } from "#util/result";
-import { isdigits } from "#util/strings";
-
-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
-  // SAFETY: v.length === 13 above guarantees v[0] exists.
-  // eslint-disable-next-line no-non-null-assertion
-  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: CountryValidator<"PK"> = {
-  name: "Computerized National Identity Card",
-  localName: "Computerized National Identity Card",
-  abbreviation: "CNIC",
-  aliases: ["CNIC", "شناختی کارڈ"] as const,
-  candidatePattern: "\\d{5}-?\\d{7}-?\\d",
-  scope: "country",
-  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

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