@stll/stdnum 0.0.1

package/src/bg/egn.ts

@@ -0,0 +1,155 @@
+/**
+ * EGN (Единен граждански номер).
+ *
+ * Bulgarian personal identification number.
+ * 10 digits encoding date of birth, serial number,
+ * and a check digit.
+ *
+ * @see https://en.wikipedia.org/wiki/Unique_citizenship_number
+ * @see https://www.grao.bg/
+ */
+
+import { weightedSum } from "#checksums/weighted-sum";
+import { clean } from "#util/clean";
+import { isValidDate } from "#util/date";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type {
+  ParsedPersonId,
+  ValidateResult,
+  Validator,
+} from "../types";
+
+const WEIGHTS = [2, 4, 8, 5, 10, 9, 7, 3, 6] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "EGN must be exactly 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "EGN 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));
+
+  let year: number;
+  let month: number;
+  if (mm > 40) {
+    year = 2000 + yy;
+    month = mm - 40;
+  } else if (mm > 20) {
+    year = 1800 + yy;
+    month = mm - 20;
+  } else {
+    year = 1900 + yy;
+    month = mm;
+  }
+
+  if (!isValidDate(year, month, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "EGN contains an invalid date",
+    );
+  }
+
+  const sum = weightedSum(v.slice(0, 9), WEIGHTS, 11);
+  const check = sum % 10;
+  if (check !== Number(v[9])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "EGN check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/**
+ * Extract birth date and gender from an EGN.
+ * 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.slice(6, 9));
+
+  let year: number;
+  let month: number;
+  if (mm > 40) {
+    year = 2000 + yy;
+    month = mm - 40;
+  } else if (mm > 20) {
+    year = 1800 + yy;
+    month = mm - 20;
+  } else {
+    year = 1900 + yy;
+    month = mm;
+  }
+
+  return {
+    birthDate: new Date(year, month - 1, dd),
+    gender: serial % 2 === 0 ? "male" : "female",
+  };
+};
+
+/** Generate a random valid EGN. */
+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 = String(randomInt(0, 999)).padStart(
+      3,
+      "0",
+    );
+    const payload = yy + mm + dd + serial;
+    const sum = weightedSum(payload, WEIGHTS, 11);
+    const c = payload + String(sum % 10);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Bulgarian Personal Identification Number. */
+const egn: Validator = {
+  name: "Bulgarian Personal ID",
+  localName: "Единен граждански номер",
+  abbreviation: "ЕГН",
+  aliases: [
+    "ЕГН",
+    "единен граждански номер",
+    "EGN",
+  ] as const,
+  candidatePattern: "\\d{10}",
+  country: "BG",
+  entityType: "person",
+  sourceUrl: "https://www.grao.bg/",
+  examples: ["7523169263"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default egn;
+export { compact, format, parse, validate, generate };

package/src/bg/mod.ts

@@ -0,0 +1,3 @@
+export { default as egn } from "./egn";
+export { default as pnf } from "./pnf";
+export { default as vat } from "./vat";

package/src/bg/pnf.ts

@@ -0,0 +1,86 @@
+/**
+ * PNF (ЛНЧ, Личен номер на чужденец).
+ *
+ * Bulgarian personal number of a foreigner.
+ * 10 digits; the last digit is a weighted checksum.
+ *
+ * @see https://en.wikipedia.org/wiki/Unique_citizenship_number
+ */
+
+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 = [21, 19, 17, 13, 11, 9, 7, 3, 1] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -.");
+
+const calcCheckDigit = (number: string): string => {
+  let sum = 0;
+  for (let i = 0; i < 9; i++) {
+    // SAFETY: WEIGHTS has exactly 9 entries
+    // eslint-disable-next-line no-non-null-assertion
+    sum += WEIGHTS[i]! * Number(number[i]);
+  }
+  return String(sum % 10);
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "PNF must be exactly 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "PNF must contain only digits",
+    );
+  }
+  if (calcCheckDigit(v.slice(0, 9)) !== v[9]) {
+    return err(
+      "INVALID_CHECKSUM",
+      "PNF check digit does not match",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid PNF. */
+const generate = (): string => {
+  const payload = randomDigits(9);
+  return payload + calcCheckDigit(payload);
+};
+
+/** Bulgarian Personal Number of a Foreigner. */
+const pnf: Validator = {
+  name: "Bulgarian Foreigner Number",
+  localName: "Личен номер на чужденец",
+  abbreviation: "ЛНЧ",
+  aliases: [
+    "ЛНЧ",
+    "личен номер на чужденец",
+    "PNF",
+  ] as const,
+  candidatePattern: "\\d{10}",
+  country: "BG",
+  entityType: "person",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Unique_citizenship_number",
+  examples: ["7111042925"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default pnf;
+export { compact, format, validate, generate };

package/src/bg/vat.ts

@@ -0,0 +1,155 @@
+/**
+ * ИН по ДДС (Bulgarian VAT number).
+ *
+ * 9 or 10 digits with weighted checksum.
+ *
+ * @see https://www.vatify.eu/bulgaria-vat-number.html
+ * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/bulgaria-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 compact = (value: string): string => {
+  let v = clean(value, " -/.");
+  if (v.startsWith("BG") || v.startsWith("bg")) {
+    v = v.slice(2);
+  }
+  return v;
+};
+
+const d = (v: string, i: number): number => Number(v[i]);
+
+const WEIGHTS_9_PASS1 = [1, 2, 3, 4, 5, 6, 7, 8];
+const WEIGHTS_9_PASS2 = [3, 4, 5, 6, 7, 8, 9, 10];
+const WEIGHTS_EGN = [2, 4, 8, 5, 10, 9, 7, 3, 6];
+const WEIGHTS_PNF = [21, 19, 17, 13, 11, 9, 7, 3, 1];
+const WEIGHTS_OTHER = [4, 3, 2, 7, 6, 5, 4, 3, 2];
+
+const validate9 = (v: string): boolean => {
+  let check = weightedSum(
+    v.slice(0, 8),
+    WEIGHTS_9_PASS1,
+    11,
+  );
+  if (check === 10) {
+    check = weightedSum(v.slice(0, 8), WEIGHTS_9_PASS2, 11);
+  }
+  return check % 10 === d(v, 8);
+};
+
+/**
+ * Validate a 10-digit EGN (personal code).
+ * First 6 digits encode birth date (YYMMDD with month
+ * offsets: +20 for 1800s, +40 for 2000s). Check digit
+ * uses weights [2,4,8,5,10,9,7,3,6], sum % 11 % 10.
+ */
+const validateEgn = (v: string): boolean => {
+  const year = d(v, 0) * 10 + d(v, 1);
+  let month = d(v, 2) * 10 + d(v, 3);
+  const day = d(v, 4) * 10 + d(v, 5);
+  let fullYear = year + 1900;
+  if (month > 40) {
+    fullYear += 100;
+    month -= 40;
+  } else if (month > 20) {
+    fullYear -= 100;
+    month -= 20;
+  }
+  // Validate the birth date
+  const date = new Date(fullYear, month - 1, day);
+  if (
+    date.getFullYear() !== fullYear ||
+    date.getMonth() !== month - 1 ||
+    date.getDate() !== day
+  ) {
+    return false;
+  }
+  const sum = weightedSum(v.slice(0, 9), WEIGHTS_EGN, 11);
+  return sum % 10 === d(v, 9);
+};
+
+/**
+ * Validate a 10-digit PNF (foreigner personal number).
+ * Weights [21,19,17,13,11,9,7,3,1], sum % 10.
+ */
+const validatePnf = (v: string): boolean => {
+  const sum = weightedSum(v.slice(0, 9), WEIGHTS_PNF, 10);
+  return sum === d(v, 9);
+};
+
+/**
+ * Validate a 10-digit "other" VAT number.
+ * Weights [4,3,2,7,6,5,4,3,2], (11 - sum%11) % 11.
+ */
+const validateOther = (v: string): boolean => {
+  const sum = weightedSum(v.slice(0, 9), WEIGHTS_OTHER, 11);
+  return (11 - sum) % 11 === d(v, 9);
+};
+
+const validate10 = (v: string): boolean =>
+  validateEgn(v) || validatePnf(v) || validateOther(v);
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9 && v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "Bulgarian VAT number must be 9 or 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Bulgarian VAT number must contain only digits",
+    );
+  }
+  const valid =
+    v.length === 9 ? validate9(v) : validate10(v);
+  if (!valid) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Bulgarian VAT number check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  `BG${compact(value)}`;
+
+/** Generate a random valid 9-digit Bulgarian VAT. */
+const generate = (): string => {
+  for (;;) {
+    const c = randomDigits(9);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Bulgarian VAT Number. */
+const vat: Validator = {
+  name: "Bulgarian VAT Number",
+  localName: "ИН по ДДС",
+  abbreviation: "ИН по ДДС",
+  aliases: [
+    "ДДС",
+    "идентификационен номер по ДДС",
+  ] as const,
+  candidatePattern: "BG\\d{9,10}",
+  country: "BG",
+  entityType: "any",
+  sourceUrl: "https://www.nra.bg/",
+  examples: ["175074752"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, validate, generate };

package/src/bh/cpr.ts

@@ -0,0 +1,81 @@
+/**
+ * CPR (Central Population Registration number, Bahrain).
+ *
+ * 9-digit personal identification number:
+ *   YYMM  = year and month of birth
+ *   NNNN  = serial number
+ *   C     = check digit
+ *
+ * The check digit algorithm is not publicly
+ * documented; validation is structural only
+ * (length, digits, and valid birth month).
+ *
+ * Note: a minority of older CPR numbers do not
+ * follow the YYMMNNNNC format.
+ *
+ * @see https://www.bahrain.bh/wps/portal/IDInfo_en
+ */
+
+import { clean } from "#util/clean";
+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 !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "Bahrain CPR must be 9 digits",
+    );
+  }
+
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Bahrain CPR must contain only digits",
+    );
+  }
+
+  // Validate birth month (digits 3-4) is 01-12
+  const mm = Number(v.slice(2, 4));
+  if (mm < 1 || mm > 12) {
+    return err(
+      "INVALID_COMPONENT",
+      "CPR birth month must be 01-12",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 2)}-${v.slice(2, 4)}-${v.slice(4)}`;
+};
+
+/** Bahrain Central Population Registration number. */
+const cpr: Validator = {
+  name: "Central Population Registration Number",
+  localName: "الرقم السكاني",
+  abbreviation: "CPR",
+  aliases: ["CPR", "الرقم السكاني"] as const,
+  candidatePattern: "\\d{9}",
+  country: "BH",
+  entityType: "person",
+  lengths: [9] as const,
+  examples: ["890112345", "000612345"] as const,
+  description: "9-digit personal identification number",
+  sourceUrl: "https://www.bahrain.bh/wps/portal/IDInfo_en",
+  compact,
+  format,
+  validate,
+};
+
+export default cpr;
+export { compact, format, validate };

package/src/bh/mod.ts

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

package/src/bic.ts

@@ -0,0 +1,99 @@
+/** Generate a random valid BIC (8-character). */
+const generate = (): string => {
+  const randomLetter = (): string =>
+    String.fromCodePoint(65 + randomInt(0, 25));
+  const randomAlphaNum = (): string => {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    return chars[randomInt(0, chars.length - 1)]!;
+  };
+  const countries = [
+    "DE",
+    "GB",
+    "US",
+    "FR",
+    "CH",
+    "NL",
+    "AT",
+  ];
+  const country =
+    countries[randomInt(0, countries.length - 1)]!;
+  const bank =
+    randomLetter() +
+    randomLetter() +
+    randomLetter() +
+    randomLetter();
+  const location = randomAlphaNum() + randomAlphaNum();
+  return `${bank}${country}${location}`;
+};
+
+/**
+ * BIC (Business Identifier Code).
+ *
+ * ISO 9362. 8 or 11 character code identifying
+ * financial institutions. Format:
+ * [A-Z]{4} (institution) + [A-Z]{2} (country) +
+ * [0-9A-Z]{2} (location) + [0-9A-Z]{3} (branch,
+ * optional).
+ *
+ * @see https://www.swift.com/
+ */
+
+import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+
+import type { ValidateResult, Validator } from "./types";
+
+const BIC_RE =
+  /^[A-Z]{4}[A-Z]{2}[0-9A-Z]{2}([0-9A-Z]{3})?$/;
+
+const compact = (value: string): string =>
+  clean(value, " -").toUpperCase();
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 8 && v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "BIC must be 8 or 11 characters",
+    );
+  }
+  if (!BIC_RE.test(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "BIC must be 8 or 11 alphanumeric characters",
+    );
+  }
+  // Country code at positions 4-5 is already
+  // validated as [A-Z]{2} by the regex above.
+  // SWIFT accepts all ISO 3166-1 alpha-2 codes
+  // plus XK (Kosovo); we don't restrict further.
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v.length === 11) {
+    return `${v.slice(0, 4)} ${v.slice(4, 6)} ${v.slice(6, 8)} ${v.slice(8)}`;
+  }
+  return `${v.slice(0, 4)} ${v.slice(4, 6)} ${v.slice(6)}`;
+};
+
+/** Business Identifier Code (SWIFT/BIC). */
+const bic: Validator = {
+  name: "Business Identifier Code",
+  localName: "Business Identifier Code",
+  abbreviation: "BIC",
+  aliases: ["BIC", "SWIFT", "BIC/SWIFT"] as const,
+  candidatePattern: "[A-Z]{6}[A-Z0-9]{2}(?:[A-Z0-9]{3})?",
+  entityType: "company",
+  sourceUrl: "https://www.swift.com/",
+  examples: ["DEUTDEFF", "DEUTDEFF500"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default bic;
+export { compact, format, validate, generate };