@stll/stdnum 0.0.1

package/src/my/nric.ts

@@ -0,0 +1,235 @@
+/**
+ * NRIC (Malaysian National Registration Identity
+ * Card Number, Nombor Kad Pengenalan).
+ *
+ * 12 digits: YYMMDD (birth date) + PB (place of
+ * birth, 2 digits) + SSS (serial) + G (gender:
+ * odd = male, even = female).
+ *
+ * No checksum; validation is structural (valid date
+ * and valid place-of-birth code).
+ *
+ * @see https://en.wikipedia.org/wiki/Malaysian_identity_card
+ */
+
+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";
+
+/**
+ * Valid place-of-birth codes (2-digit).
+ * Codes 01-16 are states, 21-59 are pre-2000
+ * state codes, 60-68 born outside (ASEAN),
+ * 71-72/74-79 foreign nationals, 82-93 regions,
+ * 98-99 legacy.
+ */
+const VALID_PB_CODES = new Set([
+  "01",
+  "02",
+  "03",
+  "04",
+  "05",
+  "06",
+  "07",
+  "08",
+  "09",
+  "10",
+  "11",
+  "12",
+  "13",
+  "14",
+  "15",
+  "16",
+  "21",
+  "22",
+  "23",
+  "24",
+  "25",
+  "26",
+  "27",
+  "28",
+  "29",
+  "30",
+  "31",
+  "32",
+  "33",
+  "34",
+  "35",
+  "36",
+  "37",
+  "38",
+  "39",
+  "40",
+  "41",
+  "42",
+  "43",
+  "44",
+  "45",
+  "46",
+  "47",
+  "48",
+  "49",
+  "50",
+  "51",
+  "52",
+  "53",
+  "54",
+  "55",
+  "56",
+  "57",
+  "58",
+  "59",
+  "60",
+  "61",
+  "62",
+  "63",
+  "64",
+  "65",
+  "66",
+  "67",
+  "68",
+  "71",
+  "72",
+  "74",
+  "75",
+  "76",
+  "77",
+  "78",
+  "79",
+  "82",
+  "83",
+  "84",
+  "85",
+  "86",
+  "87",
+  "88",
+  "89",
+  "90",
+  "91",
+  "92",
+  "93",
+  "98",
+  "99",
+]);
+
+const compact = (value: string): string =>
+  clean(value, " -");
+
+/**
+ * Resolve the birth year from a 2-digit year.
+ * Years after the reference year are assumed to be
+ * in the previous century. Accepts an explicit
+ * reference year to avoid multiple clock reads.
+ */
+const resolveYear = (
+  yy: number,
+  referenceYear: number,
+): number => {
+  const century = Math.floor(referenceYear / 100);
+  const year = century * 100 + yy;
+  return year > referenceYear ? year - 100 : year;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 12) {
+    return err(
+      "INVALID_LENGTH",
+      "NRIC must be exactly 12 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "NRIC must contain only digits",
+    );
+  }
+
+  // Validate birth date (YYMMDD)
+  const yy = Number(v.slice(0, 2));
+  const mm = Number(v.slice(2, 4));
+  const dd = Number(v.slice(4, 6));
+
+  const now = new Date().getFullYear();
+  const year = resolveYear(yy, now);
+
+  if (!isValidDate(year, mm, dd)) {
+    return err(
+      "INVALID_COMPONENT",
+      "NRIC contains an invalid birth date",
+    );
+  }
+
+  // Validate place-of-birth code
+  const pb = v.slice(6, 8);
+  if (!VALID_PB_CODES.has(pb)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Invalid place-of-birth code: " + pb,
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return (
+    v.slice(0, 6) + "-" + v.slice(6, 8) + "-" + v.slice(8)
+  );
+};
+
+/**
+ * Extract birth date and gender from an NRIC.
+ * 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 now = new Date().getFullYear();
+  const year = resolveYear(yy, now);
+
+  // Last digit: odd = male, even = female
+  const lastDigit = Number(v[11]);
+  const gender = lastDigit % 2 === 1 ? "male" : "female";
+
+  return {
+    birthDate: new Date(year, mm - 1, dd),
+    gender,
+  };
+};
+
+/** Malaysian National Registration Identity Card. */
+const nric: Validator = {
+  name: "Malaysian National Registration Identity Card Number",
+  localName: "Nombor Kad Pengenalan",
+  abbreviation: "NRIC",
+  aliases: ["NRIC", "MyKad", "kad pengenalan"] as const,
+  candidatePattern: "\\d{6}-?\\d{2}-?\\d{4}",
+  country: "MY",
+  entityType: "person",
+  description:
+    "12-digit identity card number encoding birth date, place of birth, and gender",
+  sourceUrl:
+    "https://en.wikipedia.org/wiki/Malaysian_identity_card",
+  lengths: [12] as const,
+  examples: ["770305021234", "880715141234"] as const,
+  compact,
+  format,
+  validate,
+};
+
+export default nric;
+export { compact, format, parse, validate };

package/src/ng/mod.ts

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

package/src/ng/nin.ts

@@ -0,0 +1,72 @@
+/** Generate a random valid Nigerian NIN. */
+const generate = (): string => randomDigits(11);
+
+/**
+ * NIN (National Identification Number, Nigeria).
+ *
+ * 11-digit number randomly assigned by NIMC (National
+ * Identity Management Commission). No checksum; the
+ * digits are non-intelligible and carry no embedded
+ * meaning. Once assigned, a NIN is permanent and
+ * cannot be reassigned.
+ *
+ * @see https://nimc.gov.ng/about-nin/
+ */
+
+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, " -");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 11) {
+    return err(
+      "INVALID_LENGTH",
+      "Nigerian NIN must be 11 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Nigerian NIN must contain only digits",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => {
+  const v = compact(value);
+  return `${v.slice(0, 3)} ${v.slice(3, 7)} ${v.slice(7)}`;
+};
+
+/** Nigerian National Identification Number. */
+const nin: Validator = {
+  name: "National Identification Number",
+  localName: "National Identification Number",
+  abbreviation: "NIN",
+  aliases: [
+    "NIN",
+    "National Identification Number",
+  ] as const,
+  candidatePattern: "\\d{11}",
+  country: "NG",
+  entityType: "person",
+  lengths: [11] as const,
+  examples: ["13478900989", "70123456789"] as const,
+  description:
+    "11-digit national identity number issued by NIMC",
+  sourceUrl: "https://nimc.gov.ng/about-nin/",
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default nin;
+export { compact, format, validate, generate };

package/src/ni/mod.ts

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

package/src/ni/ruc.ts

@@ -0,0 +1,176 @@
+/**
+ * RUC (Registro Único de Contribuyente, Nicaragua
+ * tax number).
+ *
+ * For natural persons the RUC is the cédula de
+ * identidad: 14 characters structured as
+ * MMM-DDMMYY-NNNNL where:
+ *   - MMM  = municipality code (001–999)
+ *   - DDMMYY = birth date
+ *   - NNNN = sequential number
+ *   - L = check letter (mod 23, ISO 7064)
+ *
+ * For legal entities (Personas Jurídicas) the RUC
+ * starts with "J" followed by 13 digits. No public
+ * check-digit algorithm is documented for the "J"
+ * format, so validation is format-only.
+ *
+ * The check letter for natural persons uses modulo 23
+ * with a 23-letter alphabet that excludes I, O, and Z
+ * to avoid confusion with digits.
+ *
+ * @see https://www.dgi.gob.ni/
+ */
+
+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";
+
+/**
+ * Check letter alphabet (mod 23). Excludes I, O, Z
+ * to prevent transcription errors.
+ */
+const CHECK_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXY";
+
+/**
+ * Compact: strip spaces, hyphens, and uppercase.
+ */
+const compact = (value: string): string =>
+  clean(value, " -").trim().toUpperCase();
+
+/**
+ * Validate a birth date encoded as DDMMYY.
+ * Returns true if the date components are plausible.
+ */
+const isValidDate = (ddmmyy: string): boolean => {
+  const day = Number(ddmmyy.slice(0, 2));
+  const month = Number(ddmmyy.slice(2, 4));
+
+  if (month < 1 || month > 12) return false;
+  if (day < 1 || day > 31) return false;
+
+  return true;
+};
+
+/**
+ * Calculate the check letter for a 13-digit body
+ * using modulo 23.
+ */
+const calcCheckLetter = (body: string): string => {
+  let n = 0n;
+  for (const ch of body) {
+    n = n * 10n + BigInt(ch);
+  }
+  const idx = Number(n % 23n);
+  // SAFETY: idx is always 0–22 (mod 23), and
+  // CHECK_ALPHABET has exactly 23 characters.
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return CHECK_ALPHABET[idx]!;
+};
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+
+  if (v.length !== 14) {
+    return err(
+      "INVALID_LENGTH",
+      "Nicaragua RUC must be 14 characters",
+    );
+  }
+
+  // Legal entity: starts with J + 13 digits
+  if (v[0] === "J") {
+    if (!isdigits(v.slice(1))) {
+      return err(
+        "INVALID_FORMAT",
+        "Nicaragua legal entity RUC must be " +
+          "J followed by 13 digits",
+      );
+    }
+    return { valid: true, compact: v };
+  }
+
+  // Natural person: 13 digits + 1 letter
+  const body = v.slice(0, 13);
+  // SAFETY: length is validated as exactly 14 above.
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const check = v[13]!;
+
+  if (!isdigits(body)) {
+    return err(
+      "INVALID_FORMAT",
+      "Nicaragua RUC body must contain only digits",
+    );
+  }
+
+  if (!CHECK_ALPHABET.includes(check)) {
+    return err(
+      "INVALID_FORMAT",
+      "Nicaragua RUC check letter is invalid",
+    );
+  }
+
+  // Validate date portion (positions 3–8: DDMMYY)
+  const datePart = body.slice(3, 9);
+  if (!isValidDate(datePart)) {
+    return err(
+      "INVALID_COMPONENT",
+      "Nicaragua RUC contains an invalid " + "birth date",
+    );
+  }
+
+  // Verify check letter
+  const expected = calcCheckLetter(body);
+  if (check !== expected) {
+    return err(
+      "INVALID_CHECKSUM",
+      "Nicaragua RUC check letter does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+/**
+ * Format: insert hyphens as MMM-DDMMYY-NNNNL
+ * for natural persons. Legal entities are returned
+ * in compact form (JNNNNNNNNNNNNN); no documented
+ * segmentation exists for the J-prefix format.
+ */
+const format = (value: string): string => {
+  const v = compact(value);
+  if (v[0] === "J") {
+    return `J-${v.slice(1)}`;
+  }
+  return (
+    `${v.slice(0, 3)}-${v.slice(3, 9)}` + `-${v.slice(9)}`
+  );
+};
+
+/** Generate a random valid Nicaraguan RUC (legal entity). */
+const generate = (): string => "J" + randomDigits(13);
+
+/** Nicaragua tax identification number. */
+const ruc: Validator = {
+  name: "Tax Identification Number",
+  localName: "Registro Único de Contribuyente",
+  abbreviation: "RUC",
+  aliases: ["RUC"] as const,
+  candidatePattern: "[JKME]\\d{13}",
+  country: "NI",
+  entityType: "any",
+  description: "Tax identifier issued by Nicaragua's DGI",
+  sourceUrl: "https://www.dgi.gob.ni/",
+  lengths: [14] as const,
+  examples: ["6071904680001F", "2811505850012D"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default ruc;
+export { compact, format, validate, generate };

package/src/nl/bsn.ts

@@ -0,0 +1,87 @@
+/**
+ * BSN (Burgerservicenummer).
+ *
+ * Dutch citizen service number. 9 digits (zero-padded)
+ * with a weighted checksum where the last digit has
+ * weight -1.
+ *
+ * @see https://www.government.nl/topics/personal-data/citizen-service-number-bsn
+ */
+
+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 = [9, 8, 7, 6, 5, 4, 3, 2, -1] as const;
+
+const compact = (value: string): string =>
+  clean(value, " -.").padStart(9, "0");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 9) {
+    return err(
+      "INVALID_LENGTH",
+      "BSN must be exactly 9 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "BSN must contain only digits",
+    );
+  }
+
+  if (Number(v) === 0) {
+    return err("INVALID_FORMAT", "BSN cannot be all zeros");
+  }
+
+  const sum = weightedSum(v, WEIGHTS, 11);
+  if (sum !== 0) {
+    return err(
+      "INVALID_CHECKSUM",
+      "BSN check does not match",
+    );
+  }
+
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Generate a random valid Dutch BSN. */
+const generate = (): string => {
+  for (;;) {
+    const c = randomDigits(9);
+    if (validate(c).valid) return c;
+  }
+};
+
+/** Dutch Citizen Service Number. */
+const bsn: Validator = {
+  name: "Dutch Citizen Service Number",
+  localName: "Burgerservicenummer",
+  abbreviation: "BSN",
+  aliases: [
+    "burgerservicenummer",
+    "BSN",
+    "sofinummer",
+  ] as const,
+  candidatePattern: "\\d{9}",
+  country: "NL",
+  entityType: "person",
+  sourceUrl:
+    "https://www.government.nl/topics/personal-data/citizen-service-number-bsn",
+  examples: ["111222333"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default bsn;
+export { compact, format, validate, generate };

package/src/nl/kvk.ts

@@ -0,0 +1,59 @@
+/** Generate a random valid Dutch KvK number. */
+const generate = (): string => randomDigits(8);
+
+/**
+ * KvK-nummer (Dutch Chamber of Commerce number).
+ *
+ * 8 digits. Format-only validation; no checksum.
+ *
+ * @see https://www.kvk.nl/
+ */
+
+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, " -/.");
+
+const validate = (value: string): ValidateResult => {
+  const v = compact(value);
+  if (v.length !== 8) {
+    return err(
+      "INVALID_LENGTH",
+      "Dutch KvK number must be 8 digits",
+    );
+  }
+  if (!isdigits(v)) {
+    return err(
+      "INVALID_FORMAT",
+      "Dutch KvK number must contain only digits",
+    );
+  }
+  return { valid: true, compact: v };
+};
+
+const format = (value: string): string => compact(value);
+
+/** Dutch Chamber of Commerce Number. */
+const kvk: Validator = {
+  name: "Dutch Chamber of Commerce Number",
+  localName: "KvK-nummer",
+  abbreviation: "KvK",
+  aliases: ["KVK-nummer", "Kamer van Koophandel"] as const,
+  candidatePattern: "\\d{8}",
+  country: "NL",
+  entityType: "company",
+  sourceUrl: "https://www.kvk.nl/",
+  examples: ["12345678"] as const,
+  compact,
+  format,
+  validate,
+  generate,
+};
+
+export default kvk;
+export { compact, format, validate, generate };

package/src/nl/mod.ts

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