@cavoq/mcc-mnc-list 1.2.2

package/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: CI + Release
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20.x, 22.x]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    if: github.event_name == 'release'
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          registry-url: https://registry.npmjs.org/
+          cache: npm
+      - run: npm ci
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/Dockerfile

@@ -0,0 +1,19 @@
+FROM node:22-bookworm-slim
+
+ENV NODE_ENV=production \
+    NPM_CONFIG_AUDIT=false \
+    NPM_CONFIG_FUND=false \
+    NPM_CONFIG_UPDATE_NOTIFIER=false
+
+WORKDIR /mnc-mcc-list
+
+COPY package*.json ./
+
+# `fetch.js` requires `jsdom`, which currently lives in devDependencies.
+RUN npm install --include=dev --omit=optional && npm cache clean --force
+
+COPY --chown=node:node . .
+
+USER node
+
+CMD ["node", "fetch.js"]

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Peter Bakondy
+Copyright (c) 2026 David Stromberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# mcc-mnc-list
+
+[![CI](https://github.com/cavoq/mcc-mnc-list/actions/workflows/release.yml/badge.svg)](https://github.com/cavoq/mcc-mnc-list/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/%40cavoq%2Fmcc-mnc-list.svg)](https://www.npmjs.com/package/@cavoq/mcc-mnc-list)
+
+### 🌍 List of MCC and MNC codes from the up-to-date Wikipedia page
+
+Maintained fork of the original `mcc-mnc-list` package.
+
+Source: https://en.wikipedia.org/wiki/Mobile_country_code
+
+## Definition
+
+The ITU-T Recommendation E.212 defines mobile country codes as well as mobile network codes. The mobile country code consists of 3 decimal digits and the mobile network code consists of 2 or 3 decimal digits (for example: MNC of 001 is not the same as MNC of 01). The first digit of the mobile country code identifies the geographic region as follows (the digits 1 and 8 are not used):
+
+- `0` - Test networks
+- `2` - Europe
+- `3` - North America and the Caribbean
+- `4` - Asia and the Middle East
+- `5` - Oceania
+- `6` - Africa
+- `7` - South and Central America
+- `9` - World-wide (Satellite, Air - aboard aircraft, Maritime - aboard ships, Antarctica)
+
+A mobile country code (MCC) is used in combination with a mobile network code (MNC) (also known as a "MCC / MNC tuple") to uniquely identify a mobile network operator (carrier) using the GSM (including GSM-R), UMTS, and LTE public land mobile networks. (*source: Wikipedia*)
+
+## 📦 Install
+
+```
+$ npm install @cavoq/mcc-mnc-list
+```
+
+## 🐳 Docker
+
+Build the image:
+
+```bash
+docker build -t mcc-mnc-list .
+```
+
+Run the fetch job in Docker:
+
+```bash
+docker run --name mcc-mnc-list-fetch mcc-mnc-list
+```
+
+Copy generated files to your host, then remove the container:
+
+```bash
+docker cp mcc-mnc-list-fetch:/mnc-mcc-list/mcc-mnc-list.json ./mcc-mnc-list.json
+docker cp mcc-mnc-list-fetch:/mnc-mcc-list/status-codes.json ./status-codes.json
+docker rm mcc-mnc-list-fetch
+```
+
+## 🗂️ Data
+
+### `mcc-mnc-list.json`
+
+This file contains all the records fetched from the Wikipedia page.
+
+Structure of a single record:
+
+```js
+{
+  "type": <String> - 'Test' / 'National' / 'International'
+  "countryName": <String> - country name
+  "countryCode": <String> - ISO 3166-1 country code
+  "mcc": <String> - mobile country code
+  "mnc": <String> - mobile network code
+  "brand": <String|null>
+  "operator": <String|null>
+  "status": <String> - status code ( see status-codes.json )
+  "bands": <String|null>
+  "notes": <String|null>
+}
+```
+
+
+### `status-codes.json`
+
+List ( `Array` ) of all the different Status Codes from MCC/MNC list.
+
+
+
+## 🚀 Usage
+
+## `.all()` : Array
+
+Returns the full record list
+
+## `.statusCodes()` : Array
+
+Returns the status code list
+
+## `.filter(filters)` : Array
+
+Returns a filtered record list. `filters` is an object.
+
+```js
+// get all the Operational mobile networks
+let filters = { statusCode: 'Operational' }
+
+// get all the records from Hungary
+let filters = { mcc: '216' }
+
+// get a specific network item ( specified with two keys )
+let filters = { mcc: '216', mnc: '30' }
+
+// get a specific network item ( specified with a joined key )
+let filters = { mccmnc: '21630' }
+
+// get all the Operational mobile networks from Hungary
+let filters = { statusCode: 'Operational', mcc: '216' }
+
+// get all the Operational mobile networks from US countryCode
+let filters = { statusCode: 'Operational', countryCode: 'US' }
+
+// get all the records
+let filters = {}
+```
+
+## `.find(filters)` : Record | undefined
+
+Returns the value of the first record in the array that satisfies the provided filters. Otherwise ``undefined`` is returned.
+Filters are identical to the filters described in ``.filter(filters)``.
+
+
+## 🧪 Example
+
+```js
+
+const mcc_mnc_list = require('@cavoq/mcc-mnc-list');
+
+let records = mcc_mnc_list.all();
+let statusCodes = mcc_mnc_list.statusCodes();
+
+console.log(records.length);
+// 2189
+
+console.log(statusCodes.length);
+// 12
+
+console.log(mcc_mnc_list.filter({ mccmnc: '21630' }));
+// [{
+//   "type": "National",
+//   "countryName": "Hungary",
+//   "countryCode": "HU",
+//   "mcc": "216",
+//   "mnc": "30",
+//   "brand": "T-Mobile",
+//   "operator": "Magyar Telekom Plc",
+//   "status": "Operational",
+//   "bands": "GSM 900 / GSM 1800 / UMTS 2100 / LTE 800 / LTE 1800 / LTE 2600",
+//   "notes": "Former WESTEL, Westel 900; MNC has the same numerical value as the area code"
+// }]
+```
+
+## 📄 License
+
+**mcc-mnc-list** is licensed under the MIT Open Source license. For more information, see the LICENSE file in this repository.

package/eslint.config.js

@@ -0,0 +1,17 @@
+const js = require("@eslint/js");
+const globals = require("globals");
+
+module.exports = [
+  js.configs.recommended,
+  {
+    files: ["**/*.js"],
+    languageOptions: {
+      ecmaVersion: 8,
+      sourceType: "commonjs",
+      globals: Object.assign({}, globals.node),
+    },
+    rules: {
+      "no-console": "off",
+    },
+  },
+];

package/fetch.js

@@ -0,0 +1,249 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const jsdom = require("jsdom");
+const { JSDOM } = jsdom;
+
+const WIKI_URL = "https://en.wikipedia.org/wiki/Mobile_country_code";
+const WIKI_URL_REGIONS = [
+  "https://en.wikipedia.org/wiki/Mobile_Network_Codes_in_ITU_region_2xx_(Europe)",
+  "https://en.wikipedia.org/wiki/Mobile_Network_Codes_in_ITU_region_3xx_(North_America)",
+  "https://en.wikipedia.org/wiki/Mobile_Network_Codes_in_ITU_region_4xx_(Asia)",
+  "https://en.wikipedia.org/wiki/Mobile_Network_Codes_in_ITU_region_5xx_(Oceania)",
+  "https://en.wikipedia.org/wiki/Mobile_Network_Codes_in_ITU_region_6xx_(Africa)",
+  "https://en.wikipedia.org/wiki/Mobile_Network_Codes_in_ITU_region_7xx_(South_America)",
+];
+
+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 = [];
+
+  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);
+    }
+
+    await process(WIKI_URL, records, statusCodes, true);
+    console.log(WIKI_URL, records.length, statusCodes.length);
+
+    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"
+    );
+
+    if (!content.hasChildNodes()) {
+      console.log("ERROR - empty content");
+      return;
+    }
+
+    content = removeCiteReferences(content);
+
+    const children = content.childNodes;
+    let recordType,
+      countryInfo = { name: null, code: null };
+
+    for (let i = 0; i < children.length; i++) {
+      let node = children[i];
+
+      if (!node.textContent.trim()) {
+        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 === "TABLE") {
+        if (globals && recordType === "National") {
+          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),
+          });
+        }
+      }
+    }
+
+    resolve();
+  });
+}
+
+function writeData(records, statusCodes) {
+  fs.writeFile(
+    MCC_MNC_OUTPUT_FILE,
+    JSON.stringify(records, null, 2),
+    (err) => {
+      if (err) {
+        throw err;
+      }
+      console.log("MCC-MNC list saved to " + MCC_MNC_OUTPUT_FILE);
+      console.log("Total " + 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);
+    }
+  );
+}
+
+function getRecordType(node) {
+  const recordTypeMap = {
+    "National operators": "National",
+    "Test networks": "Test",
+    "International operators": "International",
+  };
+
+  const h2Node = Array.from(node.childNodes).find(
+    (child) => child.nodeName === "H2"
+  );
+
+  if (h2Node) {
+    const sectionName = h2Node.textContent.trim();
+
+    if (sectionName.length > 1) {
+      if (
+        sectionName === "See also" ||
+        sectionName === "External links" ||
+        sectionName === "National MNC Authorities"
+      ) {
+        return null;
+      }
+
+      return recordTypeMap[sectionName] || "other";
+    }
+  }
+
+  return "other";
+}
+
+function getCountryInfo(node) {
+  const h4Node = Array.from(node.childNodes).find(
+    (child) => child.nodeName === "H4"
+  );
+
+  let countryName = null;
+  let countryCode = null;
+
+  if (h4Node) {
+    const countryText = h4Node.textContent.trim();
+    const dashPos = countryText.indexOf("–");
+
+    if (dashPos !== -1) {
+      countryName = countryText.substring(0, dashPos).trim();
+      countryCode = countryText.substring(dashPos + 1).trim();
+    }
+  }
+
+  return { name: countryName, code: countryCode };
+}
+
+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();
+    }
+  }
+
+  return nodes;
+}
+
+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();
+  }
+  str = str.replace(/“/g, '"');
+  return str.length ? str : null;
+}
+
+function removeCitationNeeded(str) {
+  return str.replace(/\[citation needed\]/g, "");
+}
+
+fetch();

package/index.js

@@ -0,0 +1,102 @@
+"use strict";
+
+const records = require("./mcc-mnc-list.json");
+const statusCodeList = require("./status-codes.json");
+
+function all() {
+  return records;
+}
+
+function statusCodes() {
+  return statusCodeList;
+}
+
+function filter(filters) {
+  if (filters === undefined || filters === null) {
+    return records;
+  }
+
+  if (typeof filters !== "object") {
+    throw new TypeError("Invalid parameter (object expected)");
+  }
+
+  let statusCode, mcc, mnc, countryCode;
+
+  if (filters.statusCode) {
+    statusCode = filters.statusCode;
+    if (statusCodeList.indexOf(statusCode) === -1) {
+      throw new TypeError(
+        "Invalid statusCode parameter (not found in statusCode list)"
+      );
+    }
+  }
+
+  if (filters.mccmnc) {
+    let mccmnc;
+    if (
+      typeof filters.mccmnc === "string" ||
+      typeof filters.mccmnc === "number"
+    ) {
+      mccmnc = String(filters.mccmnc);
+    } else {
+      throw new TypeError("Invalid mccmnc parameter (string expected)");
+    }
+    mcc = mccmnc.substr(0, 3);
+    mnc = mccmnc.substr(3);
+  }
+
+  if (filters.mcc && mcc) {
+    throw new TypeError("Don't use mccmnc and mcc parameter at once");
+  }
+  if (filters.mnc && mnc) {
+    throw new TypeError("Don't use mccmnc and mnc parameter at once");
+  }
+
+  if (filters.mcc) {
+    if (typeof filters.mcc === "string" || typeof filters.mcc === "number") {
+      mcc = String(filters.mcc);
+    } else {
+      throw new TypeError("Invalid mcc parameter (string expected)");
+    }
+  }
+
+  if (filters.mnc) {
+    if (typeof filters.mnc === "string" || typeof filters.mnc === "number") {
+      mnc = String(filters.mnc);
+    } else {
+      throw new TypeError("Invalid mnc parameter (string expected)");
+    }
+  }
+
+  if (filters.countryCode != undefined) {
+    if (typeof filters.countryCode === "string") {
+      countryCode = filters.countryCode;
+    } else {
+      throw new TypeError("Invalid countryCode parameter (string expected)");
+    }
+  }
+
+  let result = records;
+
+  if (statusCode) {
+    result = result.filter((record) => record["status"] === statusCode);
+  }
+  if (countryCode) {
+    result = result.filter((record) => record["countryCode"] === countryCode);
+  }
+  if (mcc) {
+    result = result.filter((record) => record["mcc"] === mcc);
+  }
+  if (mnc) {
+    result = result.filter((record) => record["mnc"] === mnc);
+  }
+
+  return result;
+}
+
+function find(filters) {
+  // return the first element of undefined, as filter will always return an array
+  return filter(filters)[0];
+}
+
+module.exports = { all, statusCodes, filter, find };