@cavoq/mcc-mnc-list 1.2.2 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 2.0.0
+
+### Migration
+
+- Install `@cavoq/mcc-mnc-list` and update imports from `mcc-mnc-list` to `@cavoq/mcc-mnc-list`.
+- Use Node `^22.22.2 || ^24.15.0 || >=26.0.0`, as required by jsdom 30. The previous package did not declare its transitive runtime requirements.
+- TypeScript callers must handle nullable operator metadata and `undefined` from `find()`. Numeric filters and null filter objects now match the documented runtime API.
+- Zero and empty-string filters are applied instead of being ignored. Arrays are rejected as filter objects, and combining MCC+MNC with a separate MCC or MNC always fails, including zero values.
+
+### Maintenance
+
+- Refresh all seven Wikipedia source pages on 2026-09-12: 3,467 records (previously 3,446) and 14 status codes.
+- Parse nested Wikipedia sections and both wrapped and direct headings. Preserve the country heading for international territories, rowspans, and rows without a final notes cell.
+- Remove citations without truncating the preceding text; preserve meaningful bracketed text and separate line breaks.
+- Propagate download, parse, and write errors with a failing exit code. Validate all sources and reject suspicious shrinkage before replacing data.
+- Update jsdom 28.1.0 → 30.0.1, AVA 6.4.1 → 8.0.1, ESLint 10.0.1 → 10.10.0, and globals 17.3.0 → 17.12.0. `@eslint/js` 10.0.1 is already current. Pin pnpm 10.34.5 and refresh the lockfile.
+- Add CI across Node 22, 24, and 26, plus npm publishing on matching version tags with prerelease handling and OIDC/token authentication.
+- Limit package contents to the library, types, updater, data, and standard npm documentation. Use locked production dependencies and a writable work directory in Docker.

package/fetch.js

@@ -1,9 +1,8 @@
 "use strict";
 
-const fs = require("fs");
-const path = require("path");
-const jsdom = require("jsdom");
-const { JSDOM } = jsdom;
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { JSDOM } = require("jsdom");
 
 const WIKI_URL = "https://en.wikipedia.org/wiki/Mobile_country_code";
 const WIKI_URL_REGIONS = [
@@ -18,148 +17,198 @@ const WIKI_URL_REGIONS = [
 const MCC_MNC_OUTPUT_FILE = path.join(__dirname, "mcc-mnc-list.json");
 const STATUS_CODES_OUTPUT_FILE = path.join(__dirname, "status-codes.json");
 
-function fetch() {
-  let records = [];
-  let statusCodes = [];
+async function fetch() {
+  const records = [];
+  const statusCodes = [];
 
-  const process = (region, records, statusCodes) =>
-    new Promise((resolve) => collect(resolve, region, records, statusCodes));
-
-  (async function loop() {
-    for (let i = 0; i < WIKI_URL_REGIONS.length; i++) {
-      const region = WIKI_URL_REGIONS[i];
-      await process(region, records, statusCodes);
-      console.log(region, records.length, statusCodes.length);
-    }
+  for (const region of WIKI_URL_REGIONS) {
+    await collect(region, records, statusCodes);
+    console.log(region, records.length, statusCodes.length);
+  }
 
-    await process(WIKI_URL, records, statusCodes, true);
-    console.log(WIKI_URL, records.length, statusCodes.length);
+  await collect(WIKI_URL, records, statusCodes, true);
+  console.log(WIKI_URL, records.length, statusCodes.length);
 
-    writeData(records, statusCodes);
-  })();
+  await writeData(records, statusCodes);
 }
 
-function collect(resolve, from, records, statusCodes, globals) {
-  JSDOM.fromURL(from).then((dom) => {
-    const { window } = dom;
-    var content = window.document.querySelector(
-      "#mw-content-text > .mw-parser-output"
+async function collect(from, records, statusCodes, globals = false) {
+  const response = await globalThis.fetch(from, {
+    headers: {
+      "User-Agent": "mcc-mnc-list/2.0 (https://github.com/cavoq/mcc-mnc-list)",
+    },
+    signal: AbortSignal.timeout(60_000),
+  });
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} fetching ${from}`);
+  }
+
+  const dom = new JSDOM(await response.text());
+
+  try {
+    const content = dom.window.document.querySelector(
+      "#mw-content-text > .mw-parser-output, body > .mw-parser-output"
     );
 
-    if (!content.hasChildNodes()) {
-      console.log("ERROR - empty content");
-      return;
+    if (!content) {
+      throw new Error(`Wikipedia article content was not found: ${from}`);
     }
 
-    content = removeCiteReferences(content);
+    removeCiteReferences(content);
 
-    const children = content.childNodes;
-    let recordType,
-      countryInfo = { name: null, code: null };
+    // Headings and tables can be nested inside Wikipedia section elements.
+    const children = content.querySelectorAll("h2, h3, h4, table");
+    const previousCount = records.length;
+    let recordType = null;
+    let countryInfo = { name: null, code: null };
 
-    for (let i = 0; i < children.length; i++) {
-      let node = children[i];
+    for (const node of children) {
+      // Ignore hidden headings used as link targets inside table cells.
+      if (node.parentElement.closest("table")) {
+        continue;
+      }
 
-      if (!node.textContent.trim()) {
+      if (node.nodeName === "H2") {
+        recordType = getRecordType(node);
+        countryInfo = { name: null, code: null };
         continue;
       }
 
-      if (node.nodeName === "DIV") {
-        switch (node.classList.value) {
-          case "mw-heading mw-heading2":
-            recordType = getRecordType(node);
-            break;
-          case "mw-heading mw-heading4":
-            countryInfo = getCountryInfo(node);
-            break;
-        }
+      if (node.nodeName === "H3" || node.nodeName === "H4") {
+        countryInfo = getCountryInfo(node);
+        continue;
+      }
+
+      if (!recordType || (globals && recordType === "National")) {
+        continue;
+      }
+
+      const rows = getTableRows(node);
+      const headings = rows[0];
+
+      if (
+        !headings ||
+        headings.length < 2 ||
+        getCellText(headings[0]) !== "MCC" ||
+        getCellText(headings[1]) !== "MNC"
+      ) {
+        continue;
+      }
+
+      if (recordType === "National" && !countryInfo.code) {
+        throw new Error(`Operator table has no country heading: ${from}`);
       }
 
-      if (node.nodeName === "TABLE") {
-        if (globals && recordType === "National") {
+      for (const cols of rows.slice(1)) {
+        if (cols.every((cell) => cell.nodeName === "TH")) {
           continue;
         }
 
-        let rows = node.querySelectorAll("tr");
-
-        for (let j = 1; j < rows.length; j++) {
-          let cols = rows[j].querySelectorAll("td");
-
-          if (cols.length < 7) {
-            //    console.log('WARN invalid table row:', rows[j], node.textContent);
-            continue;
-          }
-
-          /*
-            Remove hidden child node of first cell:
-
-            <td><div style="overflow:hidden;width:0;height:0;margin:-1ex;float:right">
-              <h3><span class="mw-headline" id="United_States_of_America_-_US_-_313">United States of America - US - 313</span></h3>
-              </div>313
-            </td>
-          */
-          const mccChild = cols[0].querySelector("div");
-          if (mccChild !== null) {
-            cols[0].removeChild(mccChild);
-          }
-
-          let status = cleanup(cols[4].textContent);
-          if (status === "Not Operational" || status === "Not opearational") {
-            status = "Not operational";
-          }
-          if (status === "operational") {
-            status = "Operational";
-          }
-
-          if (status && statusCodes.indexOf(status) === -1) {
-            statusCodes.push(status);
-          }
-
-          records.push({
-            type: recordType,
-            countryName: countryInfo.name,
-            countryCode: countryInfo.code,
-            mcc: cleanup(cols[0].textContent),
-            mnc: cleanup(cols[1].textContent),
-            brand: cleanup(cols[2].textContent),
-            operator: cleanup(cols[3].textContent),
-            status: status,
-            bands: cleanup(cols[5].textContent),
-            notes: cleanup(cols[6].textContent),
-          });
+        // Wikipedia occasionally omits the final, empty notes cell.
+        if (cols.length < 6 || cols.length > 7) {
+          throw new Error(`Unexpected operator row in ${from}`);
         }
+
+        const mcc = getCellText(cols[0], true);
+        const mnc = getCellText(cols[1]);
+
+        if (!/^\d{3}$/.test(mcc) || !mnc) {
+          throw new Error(`Invalid MCC/MNC row: ${mcc}/${mnc}`);
+        }
+
+        let status = getCellText(cols[4]);
+
+        if (/^not (operational|opearational)$/i.test(status)) {
+          status = "Not operational";
+        }
+        if (/^operational$/i.test(status)) {
+          status = "Operational";
+        }
+
+        if (status && statusCodes.indexOf(status) === -1) {
+          statusCodes.push(status);
+        }
+
+        records.push({
+          type: recordType,
+          countryName: countryInfo.name,
+          countryCode: countryInfo.code,
+          mcc: mcc,
+          mnc: mnc,
+          brand: getCellText(cols[2]),
+          operator: getCellText(cols[3]),
+          status: status,
+          bands: getCellText(cols[5]),
+          notes: cols[6] ? getCellText(cols[6]) : null,
+        });
       }
     }
 
-    resolve();
-  });
-}
+    const pageRecords = records.slice(previousCount);
 
-function writeData(records, statusCodes) {
-  fs.writeFile(
-    MCC_MNC_OUTPUT_FILE,
-    JSON.stringify(records, null, 2),
-    (err) => {
-      if (err) {
-        throw err;
+    if (!pageRecords.length) {
+      throw new Error(`No operator records found: ${from}`);
+    }
+
+    if (globals) {
+      for (const type of ["Test", "International"]) {
+        if (!pageRecords.some((record) => record.type === type)) {
+          throw new Error(`Missing ${type} operator table: ${from}`);
+        }
       }
-      console.log("MCC-MNC list saved to " + MCC_MNC_OUTPUT_FILE);
-      console.log("Total " + records.length + " records");
     }
-  );
+  } finally {
+    dom.window.close();
+  }
+}
+
+async function writeData(records, statusCodes) {
+  let previous;
+
+  try {
+    previous = JSON.parse(await fs.readFile(MCC_MNC_OUTPUT_FILE, "utf8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  if (!records.length) {
+    throw new Error("Refusing to save an empty list");
+  }
+
+  if (previous && records.length < previous.length * 0.8) {
+    throw new Error(
+      `Refusing suspicious list shrinkage: ${previous.length} to ${records.length} records`
+    );
+  }
 
   statusCodes.sort();
 
-  fs.writeFile(
-    STATUS_CODES_OUTPUT_FILE,
-    JSON.stringify(statusCodes, null, 2),
-    (err) => {
-      if (err) {
-        throw err;
-      }
-      console.log("Status codes saved to " + STATUS_CODES_OUTPUT_FILE);
+  const outputs = [
+    [MCC_MNC_OUTPUT_FILE, records],
+    [STATUS_CODES_OUTPUT_FILE, statusCodes],
+  ];
+
+  // Finish every download and validation before replacing either data file.
+  try {
+    for (const [file, data] of outputs) {
+      await fs.writeFile(`${file}.tmp`, JSON.stringify(data, null, 2) + "\n");
     }
-  );
+
+    for (const [file] of outputs) {
+      await fs.rename(`${file}.tmp`, file);
+    }
+  } finally {
+    for (const [file] of outputs) {
+      await fs.rm(`${file}.tmp`, { force: true });
+    }
+  }
+
+  console.log("MCC-MNC list saved to " + MCC_MNC_OUTPUT_FILE);
+  console.log("Total " + records.length + " records");
+  console.log("Status codes saved to " + STATUS_CODES_OUTPUT_FILE);
 }
 
 function getRecordType(node) {
@@ -169,81 +218,101 @@ function getRecordType(node) {
     "International operators": "International",
   };
 
-  const h2Node = Array.from(node.childNodes).find(
-    (child) => child.nodeName === "H2"
-  );
+  return recordTypeMap[cleanup(node.textContent)] || null;
+}
 
-  if (h2Node) {
-    const sectionName = h2Node.textContent.trim();
+function getCountryInfo(node) {
+  const countryText = cleanup(node.textContent);
+  const match =
+    countryText &&
+    countryText.match(/^(.*?)\s+[–—-]\s+([A-Z]{2}(?:[-/][A-Z]{2})*)$/);
+
+  return {
+    name: match ? match[1] : null,
+    code: match ? match[2] : null,
+  };
+}
 
-    if (sectionName.length > 1) {
-      if (
-        sectionName === "See also" ||
-        sectionName === "External links" ||
-        sectionName === "National MNC Authorities"
-      ) {
-        return null;
-      }
+function getTableRows(table) {
+  const rows = [];
+  const spans = [];
 
-      return recordTypeMap[sectionName] || "other";
-    }
-  }
+  for (const row of table.rows) {
+    const cells = Array.from(row.cells);
+    const cols = [];
+    let index = 0;
 
-  return "other";
-}
+    // Carry merged cells forward so column positions remain consistent.
+    while (cells.length || spans[index]) {
+      const span = spans[index];
 
-function getCountryInfo(node) {
-  const h4Node = Array.from(node.childNodes).find(
-    (child) => child.nodeName === "H4"
-  );
+      if (span) {
+        cols.push(span.cell);
+        span.remaining--;
+
+        if (span.remaining === 0) {
+          delete spans[index];
+        }
 
-  let countryName = null;
-  let countryCode = null;
+        index++;
+        continue;
+      }
 
-  if (h4Node) {
-    const countryText = h4Node.textContent.trim();
-    const dashPos = countryText.indexOf("–");
+      const cell = cells.shift();
 
-    if (dashPos !== -1) {
-      countryName = countryText.substring(0, dashPos).trim();
-      countryCode = countryText.substring(dashPos + 1).trim();
+      for (let column = 0; column < cell.colSpan; column++) {
+        cols.push(cell);
+
+        if (cell.rowSpan > 1) {
+          spans[index] = { cell: cell, remaining: cell.rowSpan - 1 };
+        }
+
+        index++;
+      }
     }
+
+    rows.push(cols);
   }
 
-  return { name: countryName, code: countryCode };
+  return rows;
 }
 
-function removeCiteReferences(nodes) {
-  let links = nodes.querySelectorAll("a");
-  for (let i = 0; i < links.length; i++) {
-    let link = links[i];
-    let href = link.getAttribute("href");
-    if (href.substr(0, 10) === "#cite_note") {
-      link.remove();
+function getCellText(cell, isMcc = false) {
+  const copy = cell.cloneNode(true);
+
+  if (isMcc) {
+    // Some MCC cells contain a hidden heading used as a link target.
+    for (const node of copy.querySelectorAll("div")) {
+      node.remove();
     }
   }
 
-  return nodes;
+  for (const node of copy.querySelectorAll("br")) {
+    node.replaceWith(" / ");
+  }
+
+  return cleanup(copy.textContent);
 }
 
-function cleanup(str) {
-  str = str.trim();
-  str = removeCitationNeeded(str);
-  if (str.substr(0, 1) === "[" && str.substr(-1) === "]") {
-    // remove brackets-only like [7]
-    str = "";
-  }
-  if (str.substr(0, 1) != "[" && str.substr(-1) === "]") {
-    // remove postfix references like ...[7]
-    let index = str.lastIndexOf("[");
-    str = str.substr(0, index - 1).trim();
+function removeCiteReferences(content) {
+  const references = content.querySelectorAll(
+    "sup.reference, sup.mw-ref, .mw-editsection, a[href*='#cite_note']"
+  );
+
+  for (const reference of references) {
+    reference.remove();
   }
-  str = str.replace(/“/g, '"');
-  return str.length ? str : null;
 }
 
-function removeCitationNeeded(str) {
-  return str.replace(/\[citation needed\]/g, "");
+function cleanup(str) {
+  str = str.replace(/\[(?:\d+(?:[ ,–-]\d+)*|citation needed)\]/gi, "");
+  str = str.replace(/[“”]/g, '"');
+  str = str.replace(/\s+/g, " ").trim();
+
+  return str.length ? str : null;
 }
 
-fetch();
+fetch().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/index.js

@@ -16,13 +16,13 @@ function filter(filters) {
     return records;
   }
 
-  if (typeof filters !== "object") {
+  if (typeof filters !== "object" || Array.isArray(filters)) {
     throw new TypeError("Invalid parameter (object expected)");
   }
 
   let statusCode, mcc, mnc, countryCode;
 
-  if (filters.statusCode) {
+  if (filters.statusCode !== undefined) {
     statusCode = filters.statusCode;
     if (statusCodeList.indexOf(statusCode) === -1) {
       throw new TypeError(
@@ -31,7 +31,7 @@ function filter(filters) {
     }
   }
 
-  if (filters.mccmnc) {
+  if (filters.mccmnc !== undefined) {
     let mccmnc;
     if (
       typeof filters.mccmnc === "string" ||
@@ -41,18 +41,18 @@ function filter(filters) {
     } else {
       throw new TypeError("Invalid mccmnc parameter (string expected)");
     }
-    mcc = mccmnc.substr(0, 3);
-    mnc = mccmnc.substr(3);
+    mcc = mccmnc.slice(0, 3);
+    mnc = mccmnc.slice(3);
   }
 
-  if (filters.mcc && mcc) {
+  if (filters.mcc !== undefined && filters.mccmnc !== undefined) {
     throw new TypeError("Don't use mccmnc and mcc parameter at once");
   }
-  if (filters.mnc && mnc) {
+  if (filters.mnc !== undefined && filters.mccmnc !== undefined) {
     throw new TypeError("Don't use mccmnc and mnc parameter at once");
   }
 
-  if (filters.mcc) {
+  if (filters.mcc !== undefined) {
     if (typeof filters.mcc === "string" || typeof filters.mcc === "number") {
       mcc = String(filters.mcc);
     } else {
@@ -60,7 +60,7 @@ function filter(filters) {
     }
   }
 
-  if (filters.mnc) {
+  if (filters.mnc !== undefined) {
     if (typeof filters.mnc === "string" || typeof filters.mnc === "number") {
       mnc = String(filters.mnc);
     } else {
@@ -78,16 +78,16 @@ function filter(filters) {
 
   let result = records;
 
-  if (statusCode) {
+  if (statusCode !== undefined) {
     result = result.filter((record) => record["status"] === statusCode);
   }
-  if (countryCode) {
+  if (countryCode !== undefined) {
     result = result.filter((record) => record["countryCode"] === countryCode);
   }
-  if (mcc) {
+  if (mcc !== undefined) {
     result = result.filter((record) => record["mcc"] === mcc);
   }
-  if (mnc) {
+  if (mnc !== undefined) {
     result = result.filter((record) => record["mnc"] === mnc);
   }
 
@@ -95,7 +95,7 @@ function filter(filters) {
 }
 
 function find(filters) {
-  // return the first element of undefined, as filter will always return an array
+  // return the first element or undefined, as filter will always return an array
   return filter(filters)[0];
 }