@stll/stdnum 0.0.1

package/src/ba/jmbg.ts

@@ -0,0 +1,128 @@
+/**
+ * JMBG (Jedinstveni matični broj građana).
+ *
+ * Bosnian unique master citizen number. 13 digits
+ * encoding DDMMYYY (7-digit birth year), region code,
+ * serial number, and a check digit.
+ *
+ * @see https://en.wikipedia.org/wiki/Unique_Master_Citizen_Number
+ */
+
+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 = [
+  7, 6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2,
+] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+const resolveYear = (yyy: number): number =>
+  yyy < 900 ? yyy + 2000 : yyy + 1000;
+
+const calcCheckDigit = (v: string): number => {
+  const total = weightedSum(v.slice(0, 12), WEIGHTS, 11);
+  return ((11 - total) % 11) % 10;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 13) {
+    return err(
+      "INVALID_LENGTH",
+      "JMBG must be exactly 13 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "JMBG must contain only digits",
+    );
+  }
+
+  const dd = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const yyyy = resolveYear(Number(v.slice(4, 7)));
+  if (!isValidDate(yyyy, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "JMBG contains an invalid date",
+    );
+  }
+
+  if (calcCheckDigit(v) !== Number(v[12])) {
+    return err(
+      "INVALID_CHECKSUM",
+      "JMBG check digit does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+const parse = (value: string): ParsedPersonId | null => {
+  const result = validate(value);
+  if (!result.valid) return null;
+
+  const v = result.compact;
+  const dd = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const yyyy = resolveYear(Number(v.slice(4, 7)));
+
+  const serial = Number(v.slice(9, 12));
+
+  return {
+    birthDate: new Date(yyyy, mm - 1, dd),
+    gender: serial < 500 ? "male" : "female",
+  };
+};
+
+/** Generate a random valid JMBG. */
+const generate = (): string => {
+  for (;;) {
+    const dd = String(randomInt(1, 28)).padStart(2, "0");
+    const mm = String(randomInt(1, 12)).padStart(2, "0");
+    const yyy = String(randomInt(900, 999));
+    const rr = String(randomInt(10, 99));
+    const sss = String(randomInt(0, 999)).padStart(3, "0");
+    const partial = dd + mm + yyy + rr + sss;
+    const check = calcCheckDigit(partial);
+    const c = partial + String(check);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Bosnian Unique Master Citizen Number. */
+const jmbg: Validator = {
+  name: "Bosnian Personal ID",
+  localName: "Jedinstveni matični broj građana",
+  abbreviation: "JMBG",
+  aliases: ["JMBG", "matični broj"] as const,
+  candidatePattern: "\\d{13}",
+  country: "BA",
+  entityType: "person",
+  lengths: [13] as const,
+  sourceUrl:
+    "https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/",
+  examples: ["0101006500006"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default jmbg;
+export { compact, format, parse, validate, generate };

package/src/ba/mod.ts

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

package/src/bd/mod.ts

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

package/src/bd/nid.ts

@@ -0,0 +1,139 @@
+/** Generate a random valid Bangladesh NID (13-digit). */
+const generate = (): string => {
+  const district = randomDigits(2);
+  const rmoValues = ["1", "2", "3", "4", "5", "9"];
+  const rmo =
+    rmoValues[randomInt(0, rmoValues.length - 1)]!;
+  const rest = randomDigits(10);
+  return `${district}${rmo}${rest}`;
+};
+
+/**
+ * NID (জাতীয় পরিচয়পত্র, Bangladesh National ID).
+ *
+ * Two formats exist:
+ * - 13 digits (old): DD-R-PP-UU-SSSSSS where
+ *   DD = district, R = residential type (RMO),
+ *   PP = police station, UU = union/ward code,
+ *   SSSSSS = serial number.
+ * - 17 digits (new): YYYY + 13-digit old format
+ *   where YYYY is the year of birth.
+ * - 10 digits (smart card): a newer format issued
+ *   on smart NID cards; no public structural spec
+ *   beyond digit-only validation.
+ *
+ * No checksum algorithm is used. Validation is
+ * structural: length, digit-only, and a valid
+ * RMO code (residential type).
+ *
+ * @see https://en.wikipedia.org/wiki/National_identity_card_(Bangladesh)
+ * @see https://www.nidw.gov.bd/
+ */
+
+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";
+
+/**
+ * Valid RMO (residential/municipal/other) codes.
+ * 1 = Rural, 2 = Municipality, 3 = City,
+ * 4 = Others, 5 = Cantonment, 9 = City Corporation.
+ */
+const VALID_RMO = new Set(["1", "2", "3", "4", "5", "9"]);
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+/**
+ * Validate the 13-digit core (without year prefix).
+ * Returns an error result or null on success.
+ */
+const validateCore = (
+  core: string,
+): ValidateResult | null => {
+  // core[0..1] = district (any 2 digits)
+  // core[2] = RMO code
+  const rmo = core[2];
+  if (rmo === undefined || !VALID_RMO.has(rmo)) {
+    return err(
+      "INVALID_COMPONENT",
+      "NID residential type (RMO) code is invalid",
+    );
+  }
+  return null;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (
+    v.length !== 10 &&
+    v.length !== 13 &&
+    v.length !== 17
+  ) {
+    return err(
+      "INVALID_LENGTH",
+      "NID must be 10, 13, or 17 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "NID must contain only digits",
+    );
+  }
+  if (v.length === 10) {
+    // Smart card format: first digit must not be 0
+    if (v[0] === "0") {
+      return err(
+        "INVALID_COMPONENT",
+        "NID smart card number must not start with 0",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+  // 13-digit (old) or 17-digit (new) format
+  const core = v.length === 17 ? v.slice(4) : v;
+  const coreErr = validateCore(core);
+  if (coreErr !== null) {
+    return coreErr;
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Bangladesh National Identity Number. */
+const nid: Validator = {
+  name: "National Identity Number",
+  localName: "জাতীয় পরিচয়পত্র",
+  abbreviation: "NID",
+  aliases: [
+    "NID",
+    "জাতীয় পরিচয়পত্র",
+    "National ID Card",
+  ] as const,
+  candidatePattern: "\\d{10,17}",
+  country: "BD",
+  entityType: "person",
+  lengths: [10, 13, 17],
+  examples: [
+    "1592824588424",
+    "19841592824588424",
+    "2610413965404",
+    "19892610413965404",
+  ] as const,
+  description:
+    "National identity number issued by the " +
+    "Bangladesh Election Commission",
+  sourceUrl: "https://www.nidw.gov.bd/",
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nid;
+export { compact, format, validate, generate };

package/src/be/bis.ts

@@ -0,0 +1,105 @@
+/**
+ * BIS (BIS-nummer / Numéro BIS).
+ *
+ * Belgian BIS number for individuals not in the
+ * National Register. 11 digits, structured like the
+ * NN but with the month offset by 20 (gender unknown)
+ * or 40 (gender known).
+ *
+ * @see https://sma-help.bosa.belgium.be/en/faq/where-can-i-find-my-bis-number
+ * @see https://nl.wikipedia.org/wiki/Rijksregisternummer
+ */
+
+import { clean } from "#util/clean";
+import { randomInt } from "#util/generate";
+import { err } from "#util/result";
+import { isdigits } from "#util/strings";
+
+import type { ValidateResult, Validator } from "../types";
+import { checksum, format as nnFormat } from "./nn";
+
+const compact = (value: string): string =>
+  clean(value, " .-");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "BIS must be exactly 11 digits",
+    );
+  }
+  if (!isdigits(v) || Number(v) === 0) {
+    return err(
+      "INVALID_FORMAT",
+      "BIS must contain only digits",
+    );
+  }
+
+  if (checksum(v) === null) {
+    return err(
+      "INVALID_CHECKSUM",
+      "BIS check digits do not match",
+    );
+  }
+
+  // Month must be in 20..32 or 40..52
+  const rawMonth = Number(v.slice(2, 4));
+  const inRange20 = rawMonth >= 20 && rawMonth <= 32;
+  const inRange40 = rawMonth >= 40 && rawMonth <= 52;
+  if (!inRange20 && !inRange40) {
+    return err(
+      "INVALID_COMPONENT",
+      "Month must be in 20..32 or 40..52",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string =>
+  nnFormat(compact(value));
+
+/** Generate a random valid BIS number. */
+const generate = (): string => {
+  for (;;) {
+    const yy = String(randomInt(0, 99)).padStart(2, "0");
+    const offset = Math.random() < 0.5 ? 20 : 40;
+    const mm = String(randomInt(1, 12) + offset).padStart(
+      2,
+      "0",
+    );
+    const dd = String(randomInt(1, 28)).padStart(2, "0");
+    const serial = String(randomInt(1, 997)).padStart(
+      3,
+      "0",
+    );
+    const base = yy + mm + dd + serial;
+    const n2 = Number("2" + base);
+    const check2 = 97 - (n2 % 97);
+    const c = base + String(check2).padStart(2, "0");
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Belgian BIS Number. */
+const bis: Validator = {
+  name: "Belgian BIS Number",
+  localName: "BIS-nummer",
+  abbreviation: "BIS",
+  aliases: ["BIS-nummer", "numéro BIS"] as const,
+  candidatePattern:
+    "\\d{2}\\.?\\d{2}\\.?\\d{2}-?\\d{3}\\.?\\d{2}",
+  country: "BE",
+  entityType: "person",
+  sourceUrl:
+    "https://sma-help.bosa.belgium.be/en/faq/where-can-i-find-my-bis-number",
+  examples: ["98472899765"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default bis;
+export { compact, format, validate, generate };

package/src/be/mod.ts

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

package/src/be/nn.ts

@@ -0,0 +1,125 @@
+/**
+ * NN (Numéro national / Rijksregisternummer).
+ *
+ * Belgian national identification number. 11 digits
+ * encoding date of birth, serial number, and a
+ * check digit pair. The first 6 digits are YYMMDD,
+ * followed by a 3-digit serial and 2 check digits.
+ *
+ * @see https://fr.wikipedia.org/wiki/Numéro_de_registre_national
+ * @see https://www.ibz.rrn.fgov.be/
+ */
+
+import { clean } from "#util/clean";
+import { 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, " .-");
+
+/**
+ * Verify the mod-97 checksum and return the detected
+ * century (1900 or 2000). Returns null on mismatch.
+ * Matches python-stdnum's _checksum logic: the 2000s
+ * century is only attempted when YY+2000 <= current year.
+ */
+const checksum = (v: string): number | null => {
+  const first9 = Number(v.slice(0, 9));
+  const check = Number(v.slice(9, 11));
+
+  if (97 - (first9 % 97) === check) return 1900;
+
+  const yy = Number(v.slice(0, 2));
+  if (yy + 2000 <= new Date().getFullYear()) {
+    const with2 = Number(`2${v.slice(0, 9)}`);
+    if (97 - (with2 % 97) === check) return 2000;
+  }
+
+  return null;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "NN must be exactly 11 digits",
+    );
+  }
+  if (!isdigits(v) || Number(v) === 0) {
+    return err(
+      "INVALID_FORMAT",
+      "NN must contain only digits",
+    );
+  }
+
+  if (checksum(v) === null) {
+    return err(
+      "INVALID_CHECKSUM",
+      "NN check digits do not match",
+    );
+  }
+
+  // Raw month digits must be 0..12 (values 13+ are
+  // invalid; counter-exhaustion uses 00, not 20+).
+  const rawMonth = Number(v.slice(2, 4));
+  if (rawMonth > 12) {
+    return err(
+      "INVALID_COMPONENT",
+      "Month must be in 0..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, 6)}-${v.slice(6, 9)}.${v.slice(9)}`;
+};
+
+/** Generate a random valid Belgian NN. */
+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(1, 997)).padStart(
+      3,
+      "0",
+    );
+    const base = yy + mm + dd + serial;
+    const n1 = Number(base);
+    const check1 = 97 - (n1 % 97);
+    const c = base + String(check1).padStart(2, "0");
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Belgian National Number. */
+const nn: Validator = {
+  name: "Belgian National Number",
+  localName: "Numéro national",
+  abbreviation: "NN",
+  aliases: [
+    "rijksregisternummer",
+    "numéro national",
+    "NN",
+  ] as const,
+  candidatePattern:
+    "\\d{2}\\.?\\d{2}\\.?\\d{2}-?\\d{3}\\.?\\d{2}",
+  country: "BE",
+  entityType: "person",
+  sourceUrl: "https://www.ibz.rrn.fgov.be/",
+  examples: ["93051822361"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nn;
+export { checksum, compact, format, validate, generate };

package/src/be/vat.ts

@@ -0,0 +1,107 @@
+/**
+ * BTW/TVA/MWSt (Belgian VAT number).
+ *
+ * 10 digits, first must be 0 or 1.
+ * Checksum: (first 8 digits + last 2) % 97 === 0.
+ *
+ * @see https://www.vatify.eu/belgium-vat-number.html
+ * @see https://www.oecd.org/content/dam/oecd/en/topics/policy-issue-focus/aeoi/belgium-tin.pdf
+ */
+
+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("BE") || v.startsWith("be")) {
+    v = v.slice(2);
+  }
+  // Old 9-digit format: zero-pad to 10
+  if (v.length === 9) {
+    v = `0${v}`;
+  }
+  return v;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 10) {
+    return err(
+      "INVALID_LENGTH",
+      "Belgian VAT number must be 10 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Belgian VAT number must contain only digits",
+    );
+  }
+  if (Number(v) === 0) {
+    return err(
+      "INVALID_FORMAT",
+      "Belgian VAT number cannot be all zeros",
+    );
+  }
+  if (v[0] !== "0" && v[0] !== "1") {
+    return err(
+      "INVALID_COMPONENT",
+      "Belgian VAT number must start with 0 or 1",
+    );
+  }
+  const front = Number.parseInt(v.slice(0, 8), 10);
+  const check = Number.parseInt(v.slice(8, 10), 10);
+  if ((front + check) % 97 !== 0) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Belgian VAT number check digit mismatch",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `BE${v}`;
+};
+
+/** Generate a random valid Belgian VAT number. */
+const generate = (): string => {
+  for (;;) {
+    const prefix = Math.random() < 0.5 ? "0" : "1";
+    const front = prefix + randomDigits(7);
+    const rem = Number.parseInt(front, 10) % 97;
+    const check = rem === 0 ? 97 : 97 - rem;
+    const c = front + String(check).padStart(2, "0");
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Belgian VAT Number. */
+const vat: Validator = {
+  name: "Belgian VAT Number",
+  localName: "BTW-identificatienummer",
+  abbreviation: "BTW",
+  aliases: [
+    "BTW",
+    "TVA",
+    "numéro d'entreprise",
+    "ondernemingsnummer",
+  ] as const,
+  candidatePattern: "BE0?\\d{9,10}",
+  country: "BE",
+  entityType: "company",
+  sourceUrl: "https://finances.belgium.be/",
+  examples: ["0776091951"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default vat;
+export { compact, format, validate, generate };