ph-municipalities

1. Windows 10 OS
2. nvm for Windows v1.1.9
3. NodeJS LTS v16 or higher, installed using nvm
`
Recommended:
node v16.14.2
npm v8.5.0
`
4. Excel file
- ph-municipalities uses a PAGASA 10-Day Forecast Excel file in the /app/data directory as data source.
- At minimum, the Excel file should have a column that contains municipality and province names following the uniform pattern: "municipalityName (provinceName)"
- (Optional) The Excel file should have a row on the same column as above containing the text "Municipalities" plus two (2) blank rows before rows containing municipality and province names to enable strict testing and validation of the number of parsed data rows
- Checkout the Excel file format on the /app/data/day1.xlsx sample file for more information
5. (Optional) Download URL for a remote Excel file.
- See the EXCEL_FILE_URL variable on the Installation section.
6. (Optional) Docker
- Use Docker for localhost development
- See the Docker Dependencies section for more information.

While ph-municipalities do not support parsing and extracting PAGASA 10-day weather forecast data, _you can extend the ExcelFile or ExcelFactory classes with custom logic and codes to enable parsing and extracting PAGASA 10-day weather forecast data_.

Since the ExcelFile or ExcelFactory are JavaScript Classes (Functions in disguise, not true OOP, but inheritance still works), you can extend them with class inheritance, overriding or creating new class methods to accommodate processing the PAGASA 10-day weather forecast data. Refer to the ph-municipalities class documentation to know more about the available classes, member variables, and methods.

An example of extending the classes to parse PAGASA 10-day weather forecast data may go along the lines of:

`javascript
const { ExcelFile } = require('ph-municipalities')

class PAGASATendayParser extends ExcelFile {
/* Override constructor if necessary
constructor (params) {
super(params)

// Custom class initialization logic here
}
*/

getWeatherData () {
// Note: this.#data contains the "raw" original Excel rows data as JSON with weather data

const weatherData = this.#data.reduce((list, row, index) => {
// Write logic to parse and extract weather data here
}, [])

return weatherData
}
}

const parser = new PAGASATendayParser()
weatherForecast = parser.getWeatherData()

`

The PAGASA 10-day Excel files only contain province and municipality names linked with weather data - _it has no region information_. Therefore, ph-municipalities link the province names in the 10-day Excel files to region/province names defined in the /app/config/regions.json file to determine which region they belong to.

$3

This file contains region/province names mapping encoded manually with reference from the region and province names listed in the PAGASA Seasonal Forecast website's Forecast Analysis Rainfall table.


ph-municipalities expect similar region naming conventions from the PAGASA Seasonal Forecast and the PAGASA 10-Day Forecast since both are data products produced by PAGASA.


> NOTE:

> The region/province mapping defined in this file may become outdated as time passes. ph-municipalities users are encouraged to Use a Custom Configuration File, defining new region/province name mappings following the file's current format if they notice region-to-province inconsistencies in the generated municipality lists.

> NOTE:

> Overall, the provinces and municipality list rely on the latest contents of a PAGASA 10-day Excel file and manual configuration of region/province names mapping in the /app/config/regions.json file (See Class Usage - Using a Custom Configuration File). It is not yet known and tested if these are in sync with the latest regions, provinces, and municipalities in the more standard and canon Philippine Standard Geographic Code (PSGC) data.

In short - yes, it will break when using its remote Excel file download URL that points to the DEFAULT_EXCEL_FILE_URL (see .env.example). It will also risk using outdated data when using the default archived Excel data sources.

> Like mentioned, syncing with the PAGASA TenDay APIs is currently out of scope of ph-municipalities due to the reasons mentioned in the FAQs above. Projects depending on ph-municipalities should consider alternate options in accordance with the discontinuation of the PAGASA 10-Day Weather Forecast Excel files and the availability of the newly-released PAGASA TenDay APIs.

>💡 NOTE: The open-source version of ph-municipalities provides better testing, documentation, and modularity compared to its original form as basic procedural functions in a private project.
> Even in an official project, developers would still need an approved API token and would need to shift from handling Excel files to handling PAGASA REST API responses.

#### Recommended Migration Steps

1. Request an official API token from PAGASA to use the TenDay APIs.


2. Stop using ph-municipalities (built only for the public PAGASA 10-Day Excel files) and implement your own TenDay API solution.


3. (Optional) Extend ph-municipalities' classes by overriding fetch/receive logic to work with the new TenDay APIs, if you wish to continue using its location data utilities with updated data.
   
   

   `javascript
const { ExcelFile } = require('ph-municipalities')

   class PAGASATendayAPI extends ExcelFile {
/ Override constructor if necessary /
constructor (params) {
super(params)

   // - Custom class initialization logic here
}

   async init () {
// - Update class initialization logic
}

   download () {
// - Fetch from PAGASA TenDay APIs instead of Excel files
}

   listRegions () { / Fetch from API / }
listAllProvinces () { / Fetch from API / }
listMunicipalities () { / Fetch from API / }

   ...
}

   const pagasaAPI = new PAGASATendayAPI()
weatherForecast = pagasaAPI.listMunicipalities()

   `





- ph-municipalities
- Class Documentation
- Requirements
- FAQs
- Table of Contents
- Installation
- Installation Using Docker
- Available Scripts
- Interactive CLI Scripts
- npm start / npm run list:region
- npm run list:province
- NPM Scripts for Building Windows Executable Files of the Interactive CLI Scripts
- npm run build:win:region
- npm run build:win:province
- npm run build:win:all
- npm run minify:region
- NPM Scripts for Compiling the Interactive CLI Scripts into Stand-Alone Scripts
- npm run minify:province
- npm run minify:all
- NPM Scripts for Building Documentation
- npm run generate-docs
- npm run docs:install
- npm run docs:build
- NPM Scripts for Linting Files and Unit Testing
- npm run lint
- npm run lint:fix
- npm test
- npm run example
- Class Usage
- Load and Parse a Local Excel File
- Download and Parse a Remote Excel File
- Alternate Usage - Events
- Using a Custom Configuration File
- Building Standalone Windows Executables
- Compiling into Single, Minified Files
- Building the Class Documentation
- Using Docker
- Using NodeJS
- Troubleshooting

> INFO: If installed as an NPM package with npm i ph-municipalities, create the .env file inside the NPM project's root directory.

| Variable Name | Description |
| --- | --- |
| EXCEL_FILE_URL | (Optional) Remote Excel file's download URL.
If provided, the Excel file will be downloaded and saved on the specified pathToFile local filesystem location during the ExcelFile class initialization.
Read on Class Usage for more information. |
| DEFAULT_EXCEL_FILE_URL | The default remote Excel file's download URL. |
| ARCHIVED_EXCEL_FILE_URL | Download URL of an archived remote Excel file to serve as fixtures with the discontinuation of the PAGASA 10-Day Excel files.



⚠️ Replace the value of EXCEL_FILE_URL and DEFAULT_EXCEL_FILE_URL with its value starting on August 31, 2025 to avoid processing and test errors.

1. Set up the environment variables for the /app directory. Visit the Installation section, step #3 for more information.

2. Stop and delete all docker instances for a fresh start.
- > NOTE: Running this script will delete all docker images, containers, volumes, and networks. Run this script if you feel like everything is piling but do not proceed if you have important work on other running Docker containers.
- `
sudo chmod u+x scripts/docker-cleanup.sh
./scripts/docker-cleanup.sh
# Answer all proceeding prompts
`

3. Build and run the app using Docker.
- Build

docker compose build
- Run

docker compose up
- Stop

docker compose down

4. Edit and execute scripts within the running docker container from step #3.
- For running NPM scripts (see the Available Scripts section for more information):

docker exec -it ph-municipalities
- For new scripts (example only):

docker exec -it ph-municipalities node ./src/new.js

- Asks users to enter the download URL of a remote Excel file or use the default local Excel file
- Loads and parses the local Excel file in /app/data/day1.xlsx by default.
- Loads and parses the downloaded Excel file to /app/data/datasource.xlsx if download URL in the class constructor is provided.
- Displays a list of available PH region names.
- Lists all provinces and municipalities of a specified region via commandline input.
- Asks for an option to write results to a JSON file.
- Run the script as follows if installed using npm i ph-municipalities:
- node .\node_modules\ph-municipalities\src\scripts\by_region.js

$3

- Asks users to enter the download URL of a remote Excel file or use the default local Excel file
- Loads and parses the local Excel file in /app/data/day1.xlsx by default.
- Loads and parses the downloaded Excel file to /app/data/datasource.xlsx if download URL in the class constructor is provided.
- Lists all municipalities under specified province(s) via commandline input.
- Asks for an option to write results to a JSON file.
- Run the script as follows if installed using npm i ph-municipalities:
- node .\node_modules\ph-municipalities\src\scripts\by_province.js

- Package the Node.js project's npm start script into a stand-alone windows node16-win-x64 executable.
- The windows executable file will be stored in /dist/ph-regions-win.exe. Click the executable file to run.

$3

- Package the Node.js project's npm list:province script into a stand-alone windows node16-win-x64 executable.
- The windows executable file will be stored in /dist/ph-provinces-win.exe. Click the executable file to run.

$3

- Package the Node.js project's npm start and npm list:province script into a stand-alone windows node16-win-x64 executables in one go.
- Each window executable file will be stored in the /dist directory.

- Compiles the Node.js project's npm list:region script and dependencies into a single script using ncc.
- The compiled/minified file will be stored in /dist/region. Run the command to use the compiled script:

node dist/region

$3

- Compiles the Node.js project's npm list:province script and dependencies into a single script using ncc.
- The compiled/minified file will be stored in /dist/province. Run the command to use the compiled script:

node dist/province

$3

- Run the npm list:region and npm list:province scripts in one go.
- Each compiled/minified files will be stored in the /dist directory.

> NOTE:

> This script requires manual installation of the jsdoc@4.0.3, minami@1.2.3, and taffydb@2.7.3 packages as devDependencies inside the /app directory.
> These libraries, only used for building the class documentation, were excluded from the final package.json to have fewer external dependencies.
> `bash
> npm install --save-dev jsdoc@4.0.3 minami@1.2.3 taffydb@2.7.3
> `
> Installing these libraries will update the package.json and package-lock.json files. Take care not to push changes caused by installation.

$3

Runs the Bash script that installs the JSDoc and theme dependencies for building the class documentation only within the development Docker environment.

> NOTE:

> This script requires running from a Bash terminal - it won't work from a Windows command line terminal. It is reserved for building the documentation with Docker.

This script is used for building the class documentation from a local Docker environment along with the npm run docs:build NPM script.

`bash
docker exec -u root -it ph-municipalities npm run docs:install
docker exec -u root -it ph-municipalities npm run docs:build
`

$3

Runs the Bash script that builds the class documentation using JSDoc only within the development Docker environment.

> NOTE:

> This script requires running from a Bash terminal - it won't work from a Windows command line terminal. It is reserved for building the documentation with Docker.

This script is used for building the class documentation from a local Docker environment along with the npm run docs:install NPM script.

`bash
docker exec -u root -it ph-municipalities npm run docs:install
docker exec -u root -it ph-municipalities npm run docs:build
`

Run tests defined in the /app/__tests__ directory.

$3

- Downloads and parses a remote Excel file defined in the EXCEL_FILE_URL .env variable.
- Demonstrates sample usage with await

$3

- Runs the npm run list:region with --inspect flag for debugging in containers.

`javascript
const path = require('path')
const ExcelFile = require('../classes/excel')

// Use the following if installed via npm
// const { ExcelFile } = require('ph-municipalities')

// Reads an existing Excel file on /app/data/day1.xlsx
file = new ExcelFile({
pathToFile: path.join(__dirname, '..', '..', 'data', 'day1.xlsx'),
// fastload: false
})

// Call init() if fastload=false
// file.init()

// listMunicipalities() lists all municipalities
// for each province
const provinces = ['Albay','Masbate','Sorsogon']
const municipalitiesFromProvince = file.listMunicipalities({ provinces })

// writeMunicipalities() writes municipalities data to a JSON file
// and returns the JSON object
const json = file.writeMunicipalities({
provinces,
fileName: path.join(__dirname, 'municipalities.json'),
prettify: true
})

// shapeJsonData() returns the output of writeMunicipalities()
// without writing to a JSON file
const json2 = file.shapeJsonData(provinces)

// JSON data of the parsed Excel file will is accessible on
// file.datalist
console.log(file.datalist)

// Set the contents of file.datalist
file.datalist = [
{ municipality: 'Tayum', province: 'Abra' },
{ municipality: 'Bucay', province: 'Abra' }]
`

`javascript
const path = require('path')
const ExcelFile = require('../classes/excel')

// Use the following if installed via npm
// const { ExcelFile } = require('ph-municipalities')

// Reads an existing Excel file on /app/data/day1.xlsx
const file = new ExcelFile({
pathToFile: path.join(__dirname, '..', '..', 'data', 'day1.xlsx'),
fastload: true
})

// listRegions() lists all regions from the regions settings file
const regions = file.listRegions()
console.log('---regions', regions)

// List region data from query
const regionQuery = file.listRegions('region_name')
console.log(---region full name, regionQuery)

// listProvinces() lists all provinces of a region
// for each given province
const provinces = file.listProvinces('Region IX')
console.log(---provinces of ${regions[0]}, provinces)

const municipalitiesFromProvince = file.listMunicipalities({ provinces })
console.log(---municipalities, municipalitiesFromProvince)
`

> INFO: Run the .init() method after initializing a class with a url parameter to start the async file download.

`javascript
require('dotenv').config()
const path = require('path')
const ExcelFile = require('../classes/excel')

// Use the following if installed via npm
// const { ExcelFile } = require('ph-municipalities')

const main = async () => {
// Excel file will be downloaded to /app/src/examples/excelfile.xlsx
const file = new ExcelFile({
pathToFile: path.join(__dirname, 'excelfile.xlsx'),
url: process.env.EXCEL_FILE_URL
})

try {
// Download file
await file.init()
console.log(file.datalist)
} catch (err) {
console.log(err.message)
}
}

main()
`

`javascript
require('dotenv').config()
const path = require('path')

const ExcelFile = require('../classes/excel')

// Use the following if installed via npm
// const { ExcelFile } = require('ph-municipalities')

const main = () => {
try {
// Initialize an ExcelFile class instance.
const PHExcel = new ExcelFile({
pathToFile: path.join(__dirname, 'excelfile.xlsx'),
url: process.env.EXCEL_FILE_URL
})

// Download file
PHExcel.init()

// Listen to the instance's EVENTS.LOADED event.
PHExcel.events.on(PHExcel.EVENTS.LOADED, () => {
console.log('--Excel data loaded!', PHExcel.datalist)
})
} catch (err) {
console.log([ERROR]: ${err.message})
}
}

main()
`

`
{
"metadata": {
"sources": [
"http://localhost:3000"
],
"title": "List of Random Provinces by Regions",
"description": "Sample regions config file",
"date_created": "20240824"
},
"data": [
{
"name": "Mondstat",
"abbrev": "MON",
"region_num": "1",
"region_name": "The City of Freedom",
"provinces": ["Brightcrown Mountains","Galesong Hill","Starfell Valley","Windwail Highland","Dragonspine"]
},
{
"name": "Inazuma",
"abbrev": "INZ",
"region_num": "3",
"region_name": "The Realm of Eternity",
"provinces": ["Narukami","Kannazuka","Yashiori","Watatsumi","Seirai","Tsurumi","Enkanomiya"]
},
...
]
}
`

`javascript
require('dotenv').config()
const path = require('path')

const ExcelFile = require('../classes/excel')

// Use the following if installed via npm
// const { ExcelFile } = require('ph-municipalities')

const config = require('./config.json')

// Load the local Excel file
const file = new ExcelFile({
pathToFile: path.join(__dirname, '..', '..', 'data', 'day1.xlsx'),
fastload: true,
// Use a custom settings file to define region info
settings: config
})

// Load provinces from the custom config file
const provinces = file.listProvinces('Inazuma')

// List the municipalities of defined provinces in the config file
// Note: Province/municipality names should match with those in the 10-day Excel file
const municipalities = file.listMunicipalities({ provinces })

console.log('---provinces', provinces)

console.log('\nProvince/municipality names should match with those in the 10-day Excel file')
console.log('---municipalities', municipalities)
`

1. Run any of the following scripts to build the programs.
`bash
npm run build:win:region
npm run build:win:province
# npm run build:win:all
`
2. Click the resulting executable files in the /dist directory to execute.

1. Run any of the following scripts to compile the source codes.
`bash
npm run minify:region
npm run minify:province
# npm run minify:all
`
2. Run the compiled source codes in the /dist directory to execute.
`bash
node dist/region
node dist/province
`

2. Install the dependencies for JSDoc. Suceeding builds will not need to install dependencies after an initial installation. Refer to the npm run docs:install script usage for more information.

`bash
docker exec -u root -it ph-municipalities npm run docs:install
`

3. Build the documentation. Refer to the npm run docs:build script usage for more information.

`bash
docker exec -u root -it ph-municipalities npm run docs:build
`

4. View the generated documentation in the /app/docs directory. Click the /app/docs/index.html file to launch the documentation website.

1. Install the dependencies for JSDoc. Refer to the npm run generate-docs Script usage for more information.
2. Copy Bash scripts to the /app directory.
- Create a /scripts directory inside the /app directory.
- Copy the /scripts/docs-install.sh and /scripts/docs-build.sh Bash scripts to the /scripts directory created from the previous step.
3. Copy static assets to the /app directory.
- Copy the /docs/diagrams directory inside the /app directory.
- Copy the README.md file to the /app directory.
4. Add appropriate user permission to the files.
`bash
chmod u+x scripts/docs-install.sh
chmod u+x scripts/docs-build.sh
`
5. Run the commands for building the documentation.

> INFO: Use a GitBash terminal if you are working on a Windows OS machine.

`bash
./scripts/docs-install.sh
./scripts/docs-build.sh
`

6. View the generated documentation in the /app/docs directory. Click the /app/docs/index.html file to launch the documentation website.

1. Find the host UID of the ph-municipalities Docker user. Its name is "app," defined in the Dockerfile.

docker run --rm -it ciatph/ph-municipalities:dev sh -c "id -u app"
2. Change the ownership of the ./app directory using the ph-municipalities user host UID from step #1.

sudo chown -R : ./app
3. Re-run the NPM script.

- Sometimes, garbled or malformed text like "├â┬▒", "ñ", and others are present in the PAGASA 10-Day Weather forecast Excel files.
- This usually occurs when there is a character encoding mismatch when writing data in UTF-8 format in Excel files, but the ph-municipalities scripts (or Microsoft Excel, Notepad or other programs) interpret it as ANSI (Windows-1252) or some other encoding.

#### Fix

Convert the malformed text to its original text counterparts.

1. Add the malformed characters and their expected character conversions in the SPECIAL_CHARACTERS env variable as pipe-delimited key-value pairs.
2. For example, the "├â┬▒" and "ñ" actually translate to the "ñ" character. Write them in the SPECIAL_CHARACTERS variable as:

`
SPECIAL_CHARACTERS=├â┬▒:ñ,ñ:ñ
`
3. Add a blank space after the ":" character if the malformed text does not have any conversion.

`
SPECIAL_CHARACTERS=├â┬▒:ñ,ñ:ñ,â:
``