@stll/stdnum 0.0.1 → 2.0.0

package/src/no/orgnr.ts

@@ -6,14 +6,17 @@
  * @see https://www.brreg.no/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 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 = [3, 2, 7, 6, 5, 4, 3, 2, 1] as const;
 
 const compact = (value: string): string =>
@@ -59,12 +62,13 @@ const generate = (): string => {
 };
 
 /** Norwegian Organization Number. */
-const orgnr: Validator = {
+const orgnr: CountryValidator<"NO"> = {
   name: "Norwegian Organization Number",
   localName: "Organisasjonsnummer",
   abbreviation: "Orgnr",
   aliases: ["organisasjonsnummer", "org.nr"] as const,
   candidatePattern: "\\d{9}",
+  scope: "country",
   country: "NO",
   entityType: "company",
   sourceUrl: "https://www.brreg.no/",

package/src/nz/ird.ts

@@ -9,13 +9,16 @@
  * @see https://www.ird.govt.nz/
  */
 
+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";
 
-import type { ValidateResult, Validator } from "../types";
-
 const PRIMARY_WEIGHTS = [3, 2, 7, 6, 5, 4, 3, 2] as const;
 
 const SECONDARY_WEIGHTS = [7, 4, 3, 2, 5, 2, 7, 6] as const;
@@ -28,15 +31,15 @@ const SECONDARY_WEIGHTS = [7, 4, 3, 2, 5, 2, 7, 6] as const;
 const calcCheckDigit = (payload: string): number | null => {
   const padded = payload.padStart(8, "0");
   let sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += PRIMARY_WEIGHTS[i]! * Number(padded[i]);
+  for (const [i, weight] of PRIMARY_WEIGHTS.entries()) {
+    sum += weight * Number(padded[i]);
   }
   let remainder = ((-sum % 11) + 11) % 11;
   if (remainder !== 10) return remainder;
 
   sum = 0;
-  for (let i = 0; i < 8; i++) {
-    sum += SECONDARY_WEIGHTS[i]! * Number(padded[i]);
+  for (const [i, weight] of SECONDARY_WEIGHTS.entries()) {
+    sum += weight * Number(padded[i]);
   }
   remainder = ((-sum % 11) + 11) % 11;
   if (remainder === 10) return null;
@@ -80,7 +83,7 @@ const validate = (value: string): ValidateResult => {
       "IRD number cannot have a valid check digit",
     );
   }
-  if (expected !== Number(v[v.length - 1])) {
+  if (expected !== Number(v.at(-1))) {
     return err(
       "INVALID_CHECKSUM",
       "IRD check digit does not match",
@@ -105,12 +108,13 @@ const generate = (): string => {
 };
 
 /** New Zealand IRD Number. */
-const ird: Validator = {
+const ird: CountryValidator<"NZ"> = {
   name: "IRD Number",
   localName: "IRD Number",
   abbreviation: "IRD",
   aliases: ["IRD number", "tax number NZ"] as const,
   candidatePattern: "\\d{8,9}",
+  scope: "country",
   country: "NZ",
   entityType: "any",
   compact,

package/src/pa/ruc.ts

@@ -17,12 +17,15 @@
  * @see https://dgi.mef.gob.pa/
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 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.
@@ -111,19 +114,26 @@ const computeDV = (
 ): string | null => {
   const len = segments.length;
 
-  if (
-    len < 3 ||
-    len > 4 ||
-    (len === 4 && segments[1] !== "NT")
-  ) {
+  if (len < 3 || len > 4) {
+    return null;
+  }
+  // The NT designation requires exactly 4 segments
+  // (xxNT-NT-xxx-xxx); any other 4-segment shape is
+  // unrecognized, and a 3-segment "NT" in position 1
+  // is malformed.
+  if ((len === 4) !== (segments[1] === "NT")) {
     return null;
   }
 
   let buf: string;
   let isOld = false;
 
+  // SAFETY: length check above ensures 3..4 segments.
+  // eslint-disable-next-line no-non-null-assertion
   const s0 = segments[0]!;
+  // eslint-disable-next-line no-non-null-assertion
   const s1 = segments[1]!;
+  // eslint-disable-next-line no-non-null-assertion
   const s2 = segments[2]!;
 
   if (raw[0] === "E") {
@@ -138,7 +148,9 @@ const computeDV = (
       z(5 - s2.length) +
       s2;
   } else if (s1 === "NT") {
-    // NT designation (xxNT-xxx-xxx)
+    // NT designation (xxNT-NT-xxx-xxx)
+    // SAFETY: NT branch implies len === 4 (checked above).
+    // eslint-disable-next-line no-non-null-assertion
     const s3 = segments[3]!;
     const prefix = s0.slice(0, -2);
     buf =
@@ -220,8 +232,14 @@ const computeDV = (
       s1 +
       z(6 - s2.length) +
       s2;
+    // SAFETY: juridical branch zero-pads s0 to at least
+    // 10 chars (z(10 - s0.length)), so buf[3..6] are
+    // always defined.
     isOld =
-      buf[3] === "0" && buf[4] === "0" && buf[5]! < "5";
+      buf[3] === "0" &&
+      buf[4] === "0" &&
+      // eslint-disable-next-line no-non-null-assertion
+      buf[5]! < "5";
   }
 
   // Apply legacy cross-reference for old format
@@ -270,7 +288,10 @@ const validate = (value: string): ValidateResult => {
     );
   }
 
+  // SAFETY: both DV regex capture groups are required.
+  // eslint-disable-next-line no-non-null-assertion
   const rucPart = dvMatch[1]!;
+  // eslint-disable-next-line no-non-null-assertion
   const dvPart = dvMatch[2]!;
 
   // The RUC part should be hyphen-separated segments
@@ -318,7 +339,10 @@ const format = (value: string): string => {
   const dvMatch = v.match(/^(.+?)-?\s*DV[:\s]*(\d{2})$/);
   if (!dvMatch) return v;
 
+  // SAFETY: both DV regex capture groups are required.
+  // eslint-disable-next-line no-non-null-assertion
   const rucPart = dvMatch[1]!.replace(/-+$/, "");
+  // eslint-disable-next-line no-non-null-assertion
   const dvPart = dvMatch[2]!;
   const segments = rucPart.split("-");
   return `${segments.join("-")} DV ${dvPart}`;
@@ -330,17 +354,21 @@ const generate = (): string => {
   const volume = String(randomInt(1, 9999));
   const folio = String(randomInt(1, 99999));
   const segments = [province, volume, folio];
-  const dv = computeDV(segments, segments.join("-"))!;
+  const dv = computeDV(segments, segments.join("-"));
+  if (dv === null) {
+    throw new Error("Failed to compute Panama RUC DV");
+  }
   return `${segments.join("-")} DV${dv}`;
 };
 
 /** Panama tax identification number. */
-const ruc: Validator = {
+const ruc: CountryValidator<"PA"> = {
   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}",
+  scope: "country",
   country: "PA",
   entityType: "any",
   description: "Tax identifier issued by Panama's DGI",

package/src/patterns.ts

@@ -27,13 +27,19 @@
  * ```
  */
 
-import type { CountryCode, Validator } from "./types";
+import type {
+  CountryCode,
+  CountryValidator,
+  Validator,
+} from "./types";
 
 // ─── Pattern type ─────────────────────────────
 
-export type ValidatorPattern = {
+export type ValidatorPattern<
+  TValidator extends Validator = Validator,
+> = {
   /** The validator this pattern was derived from. */
-  validator: Validator;
+  validator: TValidator;
   /** Loose regex matching candidates in text. */
   regex: RegExp;
 };
@@ -66,10 +72,9 @@ const inferLengths = (v: Validator): number[] => {
  * "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 first = v.examples?.[0];
+  if (first === undefined) return null;
+  const compact = v.compact(first);
   const formatted = v.format(compact);
   if (formatted === compact) return null;
 
@@ -98,35 +103,59 @@ const inferGroups = (v: Validator): number[] | null => {
  * (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]!);
+  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/);
-  if (compactMatch && v.examples!.length > 1) {
-    const pfx = compactMatch[1]!;
-    const allSame = v.examples!.every((ex) =>
-      v.compact(ex).startsWith(pfx),
+  const compactPrefix = compactMatch?.[1];
+  if (compactPrefix !== undefined && examples.length > 1) {
+    const allSame = examples.every((ex) =>
+      v.compact(ex).startsWith(compactPrefix),
     );
-    if (allSame) return pfx;
-  } else if (compactMatch && v.examples!.length === 1) {
-    return compactMatch[1]!;
+    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/);
-  if (fmtMatch && !compact.startsWith(fmtMatch[1]!)) {
-    return fmtMatch[1]!;
+  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]`
@@ -136,18 +165,81 @@ 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;
+  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 (hasLetter && hasDigit) return "[A-Z0-9]";
-  if (hasLetter) return "[A-Z]";
-  return "\\d";
+
+  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;
 };
 
 /**
@@ -159,6 +251,18 @@ const groupsToPattern = (
   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;
@@ -175,7 +279,16 @@ export const toRegex = (v: Validator): RegExp => {
 
   let pattern: string;
 
-  if (groups && lengths.length <= 1) {
+  // 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]}}`;
@@ -207,9 +320,9 @@ export const toRegex = (v: Validator): RegExp => {
 /**
  * Build patterns for a list of validators.
  */
-export const toPatterns = (
-  validators: readonly Validator[],
-): ValidatorPattern[] =>
+export const toPatterns = <TValidator extends Validator>(
+  validators: readonly TValidator[],
+): ValidatorPattern<TValidator>[] =>
   validators.map((v) => ({
     validator: v,
     regex: toRegex(v),
@@ -219,22 +332,47 @@ export const toPatterns = (
  * Filter validators by country code and build
  * patterns.
  */
-export const byCountry = (
-  country: CountryCode,
-  validators: readonly Validator[],
-): ValidatorPattern[] =>
-  toPatterns(
-    validators.filter((v) => v.country === country),
+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 = (
+export const byEntityType = <TValidator extends Validator>(
   entityType: "person" | "company" | "any",
-  validators: readonly Validator[],
-): ValidatorPattern[] =>
+  validators: readonly TValidator[],
+): ValidatorPattern<TValidator>[] =>
   toPatterns(
     validators.filter(
       (v) =>
@@ -247,6 +385,6 @@ export const byEntityType = (
 /**
  * Build patterns for ALL provided validators.
  */
-export const allPatterns = (
-  validators: readonly Validator[],
-): ValidatorPattern[] => toPatterns(validators);
+export const allPatterns = <TValidator extends Validator>(
+  validators: readonly TValidator[],
+): ValidatorPattern<TValidator>[] => toPatterns(validators);

package/src/pe/ruc.ts

@@ -14,13 +14,16 @@
  * @see https://en.wikipedia.org/wiki/Tax_identification_number#Peru
  */
 
+import type {
+  ValidateResult,
+  CountryValidator,
+} from "../types";
+
 import { clean } from "#util/clean";
-import { randomDigits } from "#util/generate";
+import { randomDigits, randomPick } 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,
@@ -29,7 +32,8 @@ import type { ValidateResult, Validator } from "../types";
  */
 const VALID_PREFIXES = new Set(["10", "15", "17", "20"]);
 
-const WEIGHTS = [5, 4, 3, 2, 7, 6, 5, 4, 3, 2];
+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();
@@ -42,8 +46,8 @@ const compact = (value: string): string =>
  */
 const calcCheckDigit = (body: string): number => {
   let sum = 0;
-  for (let i = 0; i < 10; i++) {
-    sum += Number(body[i]) * WEIGHTS[i]!;
+  for (const [i, weight] of WEIGHTS.entries()) {
+    sum += Number(body[i]) * weight;
   }
   const remainder = 11 - (sum % 11);
   if (remainder >= 10) return remainder - 10;
@@ -87,9 +91,7 @@ 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 prefix = randomPick(GENERATE_PREFIXES);
   const body = prefix + randomDigits(8);
   return body + String(calcCheckDigit(body));
 };
@@ -100,12 +102,13 @@ const generate = (): string => {
  * Examples sourced from python-stdnum test suite
  * (pe.ruc module).
  */
-const ruc: Validator = {
+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,

package/src/ph/philid.ts

@@ -14,13 +14,16 @@ const generate = (): string => randomDigits(12);
  * @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";
 
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string =>
   clean(value, " -");
 
@@ -50,12 +53,13 @@ const format = (value: string): string => {
 };
 
 /** Philippine Identification System Number. */
-const philid: Validator = {
+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:

package/src/pk/cnic.ts

@@ -20,13 +20,16 @@ const generate = (): string => {
  * @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";
 
-import type { ValidateResult, Validator } from "../types";
-
 const compact = (value: string): string =>
   clean(value, " -");
 
@@ -53,6 +56,8 @@ const validate = (value: string): ValidateResult => {
     );
   }
   // 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",
@@ -79,12 +84,13 @@ const format = (value: string): string => {
 };
 
 /** Pakistan Computerized National Identity Card. */
-const cnic: Validator = {
+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],