feat: note the discontinuation of live remote pagasa 10-day excel files

app/.env.example

@@ -1,6 +1,7 @@
 EXCEL_FILE_URL=https://pubfiles.pagasa.dost.gov.ph/pagasaweb/files/climate/tendayweatheroutlook/day1.xlsx
 DEFAULT_EXCEL_FILE_URL=https://pubfiles.pagasa.dost.gov.ph/pagasaweb/files/climate/tendayweatheroutlook/day1.xlsx
+ARCHIVED_EXCEL_FILE_URL=https://raw.githubusercontent.com/ciatph/ph-municipalities/refs/heads/archives/day1.xlsx
 SHEETJS_COLUMN=__EMPTY
 SORT_ALPHABETICAL=1
-SPECIAL_CHARACTERS=├â┬▒:ñ,â:,ñ:ñ
-IMAGE_URL=https://raw.githubusercontent.com/ciatph/ph-municipalities/master/docs/diagrams/ph-municipalities-arch-90.png
+SPECIAL_CHARACTERS=├â┬▒:ñ,├▒:n,â:,ñ:ñ
+IMAGE_URL=https://raw.githubusercontent.com/ciatph/ph-municipalities/master/docs/diagrams/ph-municipalities-arch-90.png

app/__tests__/municipalities/municipalitiesCount.js

@@ -25,7 +25,7 @@ describe('Municipalities total count match', () => {
   it('municipalities from provinces config should match with original Excel municipalities count', async () => {
     jest.setTimeout(20000)
 
-    // Number of invalid Excel rows (rows with malformed "municipality-province" string patterns)
+    // Number of invalid Excel rows (rows with non-uniform "municipality-province" string patterns)
     const countInvalidDataRows = excelFile.invalidRows.length
 
     // Create local/remote ExcelFile classes using the default PAGASA region settings
@@ -77,7 +77,8 @@ describe('Municipalities total count match', () => {
     if (hasMissingInConfig || hasMissingInExcel) {
       logger.log(
         '[INFO]: If you believe these RED warning(s) are incorrect, feel free to reach out\n' +
-        'or you may extend and override the ExcelFile or ExcelFactory classes in your scripts.', {
+        'or you may extend and override the ExcelFile / ExcelFactory classes in your scripts,\n' +
+        'or pass a custom "regions.json" config with an updated regions-to-province mapping in their class constructor.', {
           color: ColorLog.COLORS.TEXT.RED
         })
 

app/__tests__/provinces/createInstances.js

@@ -38,8 +38,12 @@ const createInstances = (excelFile) => {
     // Log other info
     const dataSource = excelFile?.url ?? 'default local 10-Day Excel file'
 
+    // Number of invalid rows (contains malformed province-municipality string pattern)
+    const invalidRowsCount = excelFile.invalidRows.length
+
     let message = `[INFO]: Loaded ${excelFile.data.length} Excel rows\n`
     message += `[INFO]: Parsed ${excelFile.datalist.length} data rows\n`
+    message += `[INFO]: Parsed ${invalidRowsCount} invalid rows\n`
     message += `[INFO]: from ${dataSource}\n`
     message += `[INFO]: ${excelFile.metadata.forecastDate}`
     logger.log(message, { color: ColorLog.COLORS.TEXT.GREEN })

app/__tests__/provinces/updateInstances.js

@@ -6,7 +6,7 @@ const logger = new ColorLog({ color: ColorLog.COLORS.TEXT.YELLOW, isBold: true }
 const { arrayToString } = require('../../src/lib/utils')
 
 /**
- * Updates the initial province names data read by an `ExcelFile` or ExcelFactory` class from `createInstances()` for log-viewing purposes only.
+ * Updates the initial province names data read by an `ExcelFile` or `ExcelFactory` class from `createInstances()` for log-viewing purposes only.
  * Displays diagnostic information and error logs.
  * @param {Object} params - Input parameters
  * @param {String[]} params.allExcelProvinces - all provinces from the 10-day Excel file
@@ -15,6 +15,7 @@ const { arrayToString } = require('../../src/lib/utils')
  * @param {Set} params.uniqueProvinces - `Set` version of `allProvinces` to ensure unique province names,
  * @param {String[]} params.fromConfig - Provinces present in the config (PAGASA seasonal) but missing in the 10-Day Excel file
  * @param {String[]} params.fromExcel - Provinces present in the 10-Day Excel file but missing in the config (PAGASA seasonal)
+ * @param {number} [params.invalidRowsCount=0] - Count of invalid rows parsed from the Excel source
  * @returns {Object} Object containing Arrays of processed province names
  *    - `uniqueExcelProvinces` {Set} - updated version of the `uniqueExcelProvinces` input parameter
  *    - `uniqueProvinces` {Set} - updated version of the `uniqueProvinces` input parameter
@@ -25,7 +26,8 @@ const updateInstances = ({
   uniqueExcelProvinces,
   uniqueProvinces,
   fromConfig,
-  fromExcel
+  fromExcel,
+  invalidRowsCount = 0
 }) => {
   try {
     // Provinces present in the config (PAGASA seasonal) but missing in the 10-Day Excel file
@@ -46,18 +48,29 @@ const updateInstances = ({
       logger.log(msg)
     }
 
+    if (invalidRowsCount > 0) {
+      const msg = `[WARNING]: Parsed ${invalidRowsCount} invalid rows\n`
+      logger.log(msg)
+    }
+
     // Provinces names do not match in 10-Day Excel file and the (PAGASA seasonal) config file
     if (fromExcel.length > 0 || fromConfig.length > 0) {
       let msg = `[INFO]: Original provinces count are: ${allProvinces.length} (PAGASA seasonal config) vs. ${allExcelProvinces.length} (10-Day Excel file)\n`
       msg += '[INFO]: Removed incosistent provinces in the config and Excel file only during checking/testing (see yellow WARNINGs)\n'
       msg += `[INFO]: Modified provinces count are: ${uniqueProvinces.size} (PAGASA seasonal config) vs. ${uniqueExcelProvinces.size} (10-Day Excel file)\n\n`
-      msg += '[NOTE]: If you believe these INFOs are incorrect, feel free to reach out or you may extend and override\n'
-      msg += 'the ExcelFile or ExcelFactory class methods or pass them custom regions.json config in your scripts to\n'
-      msg += 'customize this behaviour and other logic.'
+      msg += '[💡 NOTE]: If you believe these INFOs are incorrect, feel free to reach out or you may extend and override\n'
+      msg += 'the ExcelFile or ExcelFactory class methods to customize this behaviour and other logic.\n'
+
+      let msgConfig = '[💡 TIP]: You may also pass a custom "regions.json" config in the ExcelFile / ExcelFactory class constructor\n'
+      msgConfig += 'to reflect an updated regions-to-provinces mapping.\n'
 
       logger.log(msg, {
         color: ColorLog.COLORS.TEXT.CYAN
       })
+
+      logger.log(msgConfig, {
+        color: ColorLog.COLORS.TEXT.MAGENTA
+      })
     } else {
       logger.log('[PROVINCES]: Province counts match in config and Excel', {
         color: ColorLog.COLORS.TEXT.GREEN

app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ph-municipalities",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Lists and writes Philippine municipalities by province or region into JSON files using PAGASA 10-Day weather forecast Excel files as a data source",
   "main": "index.js",
   "engines": {

app/src/classes/excel/index.js

@@ -110,7 +110,7 @@ class ExcelFile {
   static malformedTextCorrections = {}
 
   /**
-   * Invalid data rows that do not follow the expected "municipalityName (provinceName)" uniform
+   * Invalid data rows that do not follow the expected "municipalityName (provinceName)" uniform string pattern
    * e.g., also having a **province** that's not included in the **PAGASA Rainfall Analysis Table** in
    * `"City of Isabela (City of Isabela (Not a Province))"`
    * @type {string[]}
@@ -491,7 +491,7 @@ class ExcelFile {
       metadata: {
         source: url || '',
         title: 'List of PH Municipalities By Province and Region',
-        description: 'This dataset generated with reference to the excel file contents from the source URL.',
+        description: 'This dataset was generated with reference to the Excel file contents from the source URL.',
         date_created: new Date().toDateString()
       },
       data: this.listMunicipalities({ provinces })

app/src/examples/01.js

@@ -1,7 +1,7 @@
 const path = require('path')
 const ExcelFile = require('../classes/excel')
 
-// Use the the following if installed via npm
+// Use the following if installed via npm
 // const { ExcelFile } = require('ph-municipalities')
 
 // Reads an existing excel file on /app/data/day1.xlsx

app/src/examples/02.js

@@ -1,7 +1,7 @@
 const path = require('path')
 const ExcelFile = require('../classes/excel')
 
-// Use the the following if installed via npm
+// Use the following if installed via npm
 // const { ExcelFile } = require('ph-municipalities')
 
 // Reads an existing excel file on /app/data/day1.xlsx

app/src/examples/03.js

@@ -2,7 +2,7 @@ require('dotenv').config()
 const path = require('path')
 const ExcelFile = require('../classes/excel')
 
-// Use the the following if installed via npm
+// Use the following if installed via npm
 // const { ExcelFile } = require('ph-municipalities')
 
 const main = async () => {

app/src/examples/04.js

@@ -3,7 +3,7 @@ const path = require('path')
 
 const ExcelFile = require('../classes/excel')
 
-// Use the the following if installed via npm
+// Use the following if installed via npm
 // const { ExcelFile } = require('ph-municipalities')
 
 const main = () => {

app/src/lib/selector.js

@@ -4,6 +4,7 @@ const {
 } = require('../../__tests__/provinces')
 const prompt = require('./prompt')
 
+const ColorLog = require('../classes/colorlog')
 const ExcelFactory = require('../classes/excelfactory')
 
 /**
@@ -15,13 +16,29 @@ const selectDataSource = async () => {
   let url
   let ExcelHandler = null
 
+  const logger = new ColorLog({ color: ColorLog.COLORS.TEXT.YELLOW, isBold: true })
+
+  // Warning messages
+  const archivedUrl = process.env.ARCHIVED_EXCEL_FILE_URL ||
+    'https://raw.githubusercontent.com/ciatph/ph-municipalities/refs/heads/archives/day1.xlsx'
+
+  const msgRemote = `[⚠️  WARNING]: Should you still want to use a remote Excel file, you can use the archived remote Excel file as data source at:\n${archivedUrl}\n`
+  const msgUseDefault = '[⚠️  WARNING]: Please use the default local Excel file as data source.\n'
+  let msgWarn = '[⚠️  WARNING]: PAGASA 10-Day Excel files are no longer available.\n'
+  msgWarn += 'https://github.com/ciatph/ph-municipalities/issues/156\n'
+
   while (!exit) {
     // Prompt to enter the download URL of a remote excel file
     if (url === undefined) {
-      const askDownload = await prompt('\nWould you like to download and use a remote Excel file?\nPress enter to ignore. Press Y and enter to proceed. [n/Y]: ')
+      const askDownload = await prompt('\nWould you like to download and use a remote PAGASA 10-Day Excel file?\nPress enter to ignore. Press Y and enter to proceed. [n/Y]: ')
+      const askDownloadValue = String(askDownload).trim().toUpperCase()
 
-      if (askDownload === 'Y') {
+      if (askDownloadValue === 'Y') {
         while (!url) {
+          logger.log(msgWarn, { color: ColorLog.COLORS.TEXT.RED })
+          logger.log(msgUseDefault, { color: ColorLog.COLORS.TEXT.GREEN })
+          logger.log(msgRemote, { color: ColorLog.COLORS.TEXT.CYAN })
+
           url = await prompt('\nEnter the download URL of a remote Excel file: ')
         }