@stll/stdnum 0.0.1

package/src/kr/rrn.ts

@@ -0,0 +1,170 @@
+/**
+ * RRN (Resident Registration Number, 주민등록번호).
+ *
+ * Korean Resident Registration Number. 13 digits
+ * formatted as YYMMDD-GPPCCSD. Encodes date of
+ * birth, gender/century, place of birth, community
+ * center, serial, and a check digit.
+ *
+ * @see https://en.wikipedia.org/wiki/Resident_registration_number
+ */
+
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  Validator,
+} from "../types";
+
+const compact = (value: string): string =>
+  clean(value, " -/");
+
+const CHECK_WEIGHTS = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5];
+
+/**
+ * Compute the check digit for the first 12 digits.
+ * Formula: (11 - sum(w_i * d_i) % 11) % 10.
+ */
+const checkDigit = (digits: string): number => {
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    sum +=
+      (CHECK_WEIGHTS[i] ?? 0) * Number(digits.charAt(i));
+  }
+  return (11 - (sum % 11)) % 10;
+};
+
+/** Century prefix derived from the 7th digit. */
+const CENTURY_BY_GENDER: Record<string, number> = {
+  "0": 1800,
+  "1": 1900,
+  "2": 1900,
+  "3": 2000,
+  "4": 2000,
+  "5": 1900,
+  "6": 1900,
+  "7": 2000,
+  "8": 2000,
+  "9": 1800,
+};
+
+/**
+ * Resolve birth date components from a compacted RRN.
+ * Returns null if the date is invalid.
+ */
+const resolveBirthDate = (
+  v: string,
+): { year: number; month: number; day: number } | null => {
+  const century = CENTURY_BY_GENDER[v.charAt(6)];
+  if (century === undefined) return null;
+
+  const year = century + Number(v.slice(0, 2));
+  const month = Number(v.slice(2, 4));
+  const day = Number(v.slice(4, 6));
+
+  if (!isValidDate(year, month, day)) return null;
+  return { year, month, day };
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 13) {
+    return err(
+      "INVALID_LENGTH",
+      "RRN must be exactly 13 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "RRN must contain only digits",
+    );
+  }
+  if (resolveBirthDate(v) === null) {
+    return err(
+      "INVALID_COMPONENT",
+      "RRN contains an invalid date of birth",
+    );
+  }
+  const place = Number(v.slice(7, 9));
+  if (place > 96) {
+    return err(
+      "INVALID_COMPONENT",
+      "RRN place-of-birth code must be <= 96",
+    );
+  }
+  if (checkDigit(v.slice(0, 12)) !== Number(v[12])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "RRN check digit does not match",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 13) {
+    return `${v.slice(0, 6)}-${v.slice(6)}`;
+  }
+  return v;
+};
+
+/**
+ * Extract birth date and gender from an RRN.
+ * Returns null if the value is not valid.
+ *
+ * Gender digit mapping:
+ *   1, 3 = male Korean; 2, 4 = female Korean
+ *   5, 7 = male foreigner; 6, 8 = female foreigner
+ *   0, 9 = pre-1800 (male/female by convention)
+ */
+const parse = (value: string): ParsedPersonId | null => {
+  const result = validate(value);
+  if (!result.valid) return null;
+
+  const v = result.compact;
+  const bd = resolveBirthDate(v);
+  if (bd === null) return null;
+
+  const genderDigit = v.charAt(6);
+  const isMale = "13579".includes(genderDigit);
+
+  return {
+    birthDate: new Date(bd.year, bd.month - 1, bd.day),
+    gender: isMale ? "male" : "female",
+  };
+};
+
+/** Korean Resident Registration Number. */
+const rrn: Validator = {
+  name: "Korean Resident Registration Number",
+  localName: "주민등록번호",
+  abbreviation: "RRN",
+  aliases: [
+    "RRN",
+    "주민등록번호",
+    "Resident Registration Number",
+  ] as const,
+  candidatePattern: "\\d{6}[\\s-]?\\d{7}",
+  country: "KR",
+  entityType: "person",
+  description:
+    "13-digit personal identifier issued to all" +
+    " residents of South Korea",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/" +
+    "Resident_registration_number",
+  lengths: [13] as const,
+  examples: ["9710139019902", "9501011000109"] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default rrn;
+export { compact, format, parse, validate };

package/src/kw/civil.ts

@@ -0,0 +1,144 @@
+/**
+ * Civil Number (الرقم المدني, Kuwait).
+ *
+ * 12-digit number issued by PACI (Public Authority
+ * for Civil Information):
+ *   C       = century indicator (2 = 1900s, 3 = 2000s)
+ *   YYMMDD  = birth date
+ *   SSSS    = serial number
+ *   K       = check digit (mod 11 weighted sum)
+ *
+ * @see https://prakhar.me/articles/kuwait-civil-id-checksum/
+ * @see https://kuwaitsexpat.com/kuwait-civil-id-format/
+ */
+
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  Validator,
+} from "../types";
+
+const WEIGHTS = [2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2] as const;
+
+const centuryMap: Record<number, number> = {
+  2: 1900,
+  3: 2000,
+};
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const calcCheckDigit = (digits: string): number => {
+  let sum = 0;
+  for (let i = 0; i < 11; i++) {
+    // SAFETY: loop bound guarantees valid index
+    sum += Number(digits[i]) * WEIGHTS[i]!;
+  }
+  return (11 - (sum % 11)) % 11;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "Kuwait civil number must be 12 digits",
+    );
+  }
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Kuwait civil number must contain only digits",
+    );
+  }
+
+  const centuryDigit = Number(v[0]);
+  if (centuryDigit !== 2 && centuryDigit !== 3) {
+    return err(
+      "INVALID_COMPONENT",
+      "Century digit must be 2 or 3",
+    );
+  }
+
+  const yearBase = centuryMap[centuryDigit] ?? 1900;
+  const yy = Number(v.slice(1, 3));
+  const mm = Number(v.slice(3, 5));
+  const dd = Number(v.slice(5, 7));
+  const year = yearBase + yy;
+
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Civil number contains an invalid birth date",
+    );
+  }
+
+  const expected = calcCheckDigit(v.slice(0, 11));
+  if (expected !== Number(v[11])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Civil number check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 1)} ${v.slice(1, 7)} ${v.slice(7, 11)} ${v.slice(11)}`;
+};
+
+/**
+ * Extract birth date from a Kuwait civil number.
+ * Gender is not encoded in the number.
+ * Returns null if the value is not valid.
+ */
+const parse = (
+  value: string,
+): Omit<ParsedPersonId, "gender"> | null => {
+  const result = validate(value);
+  if (!result.valid) return null;
+
+  const v = result.compact;
+  const centuryDigit = Number(v[0]);
+  const yearBase = centuryMap[centuryDigit] ?? 1900;
+  const yy = Number(v.slice(1, 3));
+  const mm = Number(v.slice(3, 5));
+  const dd = Number(v.slice(5, 7));
+  const year = yearBase + yy;
+
+  return {
+    birthDate: new Date(year, mm - 1, dd),
+  };
+};
+
+/** Kuwait Civil Number (الرقم المدني). */
+const civil: Validator = {
+  name: "Civil Number",
+  localName: "الرقم المدني",
+  abbreviation: "Civil ID",
+  aliases: ["Civil ID", "الرقم المدني"] as const,
+  candidatePattern: "\\d{12}",
+  country: "KW",
+  entityType: "person",
+  lengths: [12] as const,
+  examples: ["289011200032", "305031512348"] as const,
+  description:
+    "12-digit civil identification number issued by PACI",
+  sourceUrl:
+    "https://kuwaitsexpat.com/kuwait-civil-id-format/",
+  compact,
+  format,
+  validate,
+};
+
+export default civil;
+export { compact, format, parse, validate };

package/src/kw/mod.ts

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

package/src/kz/iin.ts

@@ -0,0 +1,183 @@
+/**
+ * IIN (Individual Identification Number,
+ * Жеке сәйкестендіру нөмірі / ИИН).
+ *
+ * Kazakhstan individual identification number. 12 digits:
+ *   YYMMDD = birth date
+ *   C      = century/gender (1-6)
+ *   SSSS   = serial number
+ *   K      = check digit (two-pass weighted sum mod 11)
+ *
+ * Odd century digits = male, even = female.
+ * 1-2 = 1800s, 3-4 = 1900s, 5-6 = 2000s.
+ *
+ * @see https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Kazakhstan-TIN.pdf
+ */
+
+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 = [
+  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
+] as const;
+const WEIGHTS_2 = [
+  3, 4, 5, 6, 7, 8, 9, 10, 11, 1, 2,
+] as const;
+
+const centuryMap: Record<number, number> = {
+  1: 1800,
+  2: 1800,
+  3: 1900,
+  4: 1900,
+  5: 2000,
+  6: 2000,
+};
+
+const compact = (value: string): string =>
+  clean(value, " -").trim();
+
+/**
+ * Two-pass check digit: weighted sum mod 11 with
+ * fallback to second weight set.
+ */
+const calcCheckDigit = (digits: string): number => {
+  let remainder = weightedSum(digits, WEIGHTS_1, 11);
+  if (remainder === 10) {
+    remainder = weightedSum(digits, WEIGHTS_2, 11);
+  }
+  return remainder === 10 ? 0 : remainder;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "Kazakhstan IIN must be 12 digits",
+    );
+  }
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Kazakhstan IIN must contain only digits",
+    );
+  }
+
+  const centuryDigit = Number(v[6]);
+  if (centuryDigit < 1 || centuryDigit > 6) {
+    return err(
+      "INVALID_COMPONENT",
+      "IIN century/gender digit must be 1-6",
+    );
+  }
+
+  const yearBase = centuryMap[centuryDigit] ?? 1900;
+  const yy = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+  const year = yearBase + yy;
+
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "IIN contains an invalid birth date",
+    );
+  }
+
+  const expected = calcCheckDigit(v.slice(0, 11));
+  if (expected !== Number(v[11])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "IIN check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 6)} ${v.slice(6)}`;
+};
+
+/**
+ * Extract birth date and gender from a Kazakhstan IIN.
+ * 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 centuryDigit = Number(v[6]);
+  const yearBase = centuryMap[centuryDigit] ?? 1900;
+  const yy = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+  const year = yearBase + yy;
+
+  return {
+    birthDate: new Date(year, mm - 1, dd),
+    gender: centuryDigit % 2 === 1 ? "male" : "female",
+  };
+};
+
+/** Generate a random valid Kazakhstan IIN. */
+const generate = (): string => {
+  for (;;) {
+    const yy = String(randomInt(50, 99)).padStart(2, "0");
+    const mm = String(randomInt(1, 12)).padStart(2, "0");
+    const dd = String(randomInt(1, 28)).padStart(2, "0");
+    const gender = String(randomInt(1, 6));
+    const serial = randomDigits(4);
+    const payload = yy + mm + dd + gender + serial;
+    const check = calcCheckDigit(payload);
+    if (check === null) continue;
+    const c = payload + String(check);
+    if (validate(c).valid) return c;
+  }
+};
+
+/**
+ * Kazakhstan Individual Identification Number (IIN).
+ *
+ * Examples sourced from identique/idnumbers test suite.
+ */
+const iin: Validator = {
+  name: "Kazakhstan Individual ID",
+  localName: "Жеке сәйкестендіру нөмірі",
+  abbreviation: "IIN",
+  aliases: [
+    "ИИН",
+    "IIN",
+    "индивидуальный идентификационный номер",
+  ] as const,
+  candidatePattern: "\\d{12}",
+  country: "KZ",
+  entityType: "person",
+  lengths: [12] as const,
+  examples: ["880515300120", "950101400012"] as const,
+  compact,
+  format,
+  validate,
+  sourceUrl:
+    "https://www.oecd.org/tax/automatic-exchange/" +
+    "crs-implementation-and-assistance/" +
+    "tax-identification-numbers/Kazakhstan-TIN.pdf",
+  generate,
+};
+
+export default iin;
+export { compact, format, parse, validate, generate };

package/src/kz/mod.ts

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

package/src/lei.ts

@@ -0,0 +1,98 @@
+/**
+ * LEI (Legal Entity Identifier).
+ *
+ * ISO 17442. 20-character alphanumeric code
+ * identifying legal entities in financial
+ * transactions. Validated using ISO 7064
+ * Mod 97-10 (same as IBAN).
+ *
+ * @see https://www.gleif.org/
+ */
+
+import { mod97 } from "#checksums/mod97";
+import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { charValue, isalnum } from "#util/strings";
+
+import type { ValidateResult, Validator } from "./types";
+
+const compact = (value: string): string =>
+  clean(value, " -").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 20) {
+    return err(
+      "INVALID_LENGTH",
+      "LEI must be exactly 20 characters",
+    );
+  }
+  if (!isalnum(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "LEI must contain only letters and digits",
+    );
+  }
+  // Characters 5-18 must be alphanumeric (entity)
+  // Characters 19-20 are check digits (numeric)
+  const checkPart = v.slice(18);
+  if (!/^\d{2}$/.test(checkPart)) {
+    return err(
+      "INVALID_FORMAT",
+      "LEI check digits must be numeric",
+    );
+  }
+  // Convert to numeric and validate mod 97
+  let numeric = "";
+  for (let i = 0; i < v.length; i++) {
+    const ch = v[i];
+    if (ch !== undefined) {
+      numeric += String(charValue(ch));
+    }
+  }
+  if (mod97(numeric) !== 1) {
+    return err(
+      "INVALID_CHECKSUM",
+      "LEI check digits are incorrect",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 4)} ${v.slice(4, 8)} ${v.slice(8, 12)} ${v.slice(12, 16)} ${v.slice(16)}`;
+};
+
+/** Generate a random valid LEI. */
+const generate = (): string => {
+  for (;;) {
+    let base = "";
+    for (let i = 0; i < 18; i++)
+      base += String(randomInt(0, 9));
+    for (let cd = 0; cd < 100; cd++) {
+      const c = base + String(cd).padStart(2, "0");
+      if (validate(c).valid) return c;
+    }
+  }
+};
+
+/** Legal Entity Identifier. */
+const lei: Validator = {
+  name: "Legal Entity Identifier",
+  localName: "Legal Entity Identifier",
+  abbreviation: "LEI",
+  aliases: ["LEI", "Legal Entity Identifier"] as const,
+  candidatePattern: "[A-Z0-9]{18}\\d{2}",
+  entityType: "company",
+  sourceUrl: "https://www.gleif.org/",
+  examples: ["5493006MHB84DD0ZWV18"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default lei;
+export { compact, format, validate, generate };

package/src/li/mod.ts

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

package/src/li/peid.ts

@@ -0,0 +1,66 @@
+/** Generate a random valid Liechtenstein PEID. */
+const generate = (): string => {
+  const len = randomInt(4, 12);
+  const first = String(randomInt(1, 9));
+  return first + randomDigits(len - 1);
+};
+
+/**
+ * PEID (Personenidentifikationsnummer).
+ *
+ * Liechtenstein tax code for individuals and entities.
+ * Numeric code of 4 to 12 digits, with leading zeros
+ * stripped during compaction.
+ *
+ * @see https://www.oera.li/
+ */
+
+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, " .").replace(/^0+/, "");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length < 4 || v.length > 12) {
+    return err(
+      "INVALID_LENGTH",
+      "Liechtenstein PEID must be 4 to 12 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Liechtenstein PEID must contain only digits",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Liechtenstein Person Identification Number. */
+const peid: Validator = {
+  name: "Liechtenstein Person Identification Number",
+  localName: "Personenidentifikationsnummer",
+  abbreviation: "PEID",
+  aliases: ["PEID", "Personenidentifikation"] as const,
+  candidatePattern: "\\d{6}",
+  country: "LI",
+  entityType: "any",
+  lengths: [4, 5, 6, 7, 8, 9, 10, 11, 12] as const,
+  sourceUrl: "https://www.oera.li/",
+  examples: ["1234567"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default peid;
+export { compact, format, validate, generate };

package/src/lk/mod.ts

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