latest-ph-address-thanks-to-anehan 1.0.1 → 1.0.4

package/README.md

@@ -3,16 +3,14 @@
 [![npm version](https://img.shields.io/npm/v/latest-ph-address-thanks-to-anehan.svg)](https://www.npmjs.com/package/latest-ph-address-thanks-to-anehan)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-The latest Philippine addresses database with complete coverage of all Regions, Provinces, Cities, Municipalities, and Barangays. Perfect for building address forms, dropdowns, and location-based applications.
+Complete Philippine addresses database with 43,769+ addresses. Perfect for building address forms and cascading dropdowns.
 
 **Features:**
-- ✅ **43,769+ addresses** - Complete coverage of the Philippines
+- ✅ **43,769+ addresses** - Complete coverage (18 Regions, 82 Provinces, 149 Cities, 1,493 Municipalities, 42,011 Barangays)
 - ✅ **Official PSGC codes** - Philippine Standard Geographic Code support
-- ✅ **Cascading dropdowns** - Built-in helpers for Region → Province → City/Municipality → Barangay
 - ✅ **NCR support** - Automatic handling of National Capital Region (no provinces)
 - ✅ **HUC support** - Highly Urbanized Cities with geographic province mapping
-- ✅ **Two flexible flows** - Start with Region or Province
-- ✅ **Zero dependencies** - Lightweight and fast
+- ✅ **Zero dependencies** - Lightweight (~1.2 MB)
 - ✅ **Latest data** - 3Q 2025 PSGC data
 
 All thanks to the [anehan.online](https://anehan.online) Tech Team! 🇵🇭
@@ -23,301 +21,166 @@ All thanks to the [anehan.online](https://anehan.online) Tech Team! 🇵🇭
 npm install latest-ph-address-thanks-to-anehan
 ```
 
-## 📊 Data Coverage
+## 🚀 Quick Start
 
-- **18 Regions**
-- **82 Provinces**
-- **149 Cities** (including HUC, CC, ICC)
-- **1,493 Municipalities**
-- **42,011 Barangays**
-- **Total: 43,769 addresses**
+### Import
 
-## 🚀 Quick Start
+The package exports an object with functions. You can name the imported object anything you want:
 
-### Basic Usage
+```typescript
+// ES6 Import (Recommended)
+// 'phAddress' is just a variable name - you can use any name you prefer
+import phAddress from 'latest-ph-address-thanks-to-anehan';
+// OR: import address from 'latest-ph-address-thanks-to-anehan';
+// OR: import philippines from 'latest-ph-address-thanks-to-anehan';
+
+// ES6 Named Imports (Import specific functions)
+import { getRegions, getProvincesByRegion, getBarangaysByCityOrMun } from 'latest-ph-address-thanks-to-anehan';
 
-```javascript
+// CommonJS (Node.js)
 const phAddress = require('latest-ph-address-thanks-to-anehan');
+// OR: const address = require('latest-ph-address-thanks-to-anehan');
+```
+
+**Note:** `phAddress` stands for "Philippine Address" - it's just a suggested variable name. You can use any name you prefer!
+
+### Basic Usage
+
+```typescript
+// Using default import (object with all functions)
+import phAddress from 'latest-ph-address-thanks-to-anehan';
 
 // Get all regions
 const regions = phAddress.getRegions();
 // Returns: Array of 18 regions (sorted A-Z)
+// Type: Array<{ psgc: string; name: string; correspondenceCode: string; geographicLevel: string }>
 
-// Get provinces (all provinces + "-NO PROVINCE-" option)
-const provinces = phAddress.getProvincesByRegion();
-// Returns: Array of 82 provinces + "-NO PROVINCE-" (83 items, sorted A-Z)
-// "-NO PROVINCE-" appears first in the list
-
-// Get provinces in a specific region
-const carProvinces = phAddress.getProvincesByRegion('1400000000'); // CAR
-// Returns: Array of provinces in CAR (sorted A-Z)
+// Get provinces for a region
+const provinces = phAddress.getProvincesByRegion('1400000000'); // CAR
+// Returns: Array of provinces (sorted A-Z)
+// Type: Array<{ psgc: string; name: string; ... }>
 
 // Get provinces for NCR
-const ncrProvinces = phAddress.getProvincesByRegion('1300000000'); // NCR
+const ncrProvinces = phAddress.getProvincesByRegion('1300000000');
 // Returns: "-NO PROVINCE-" (string)
+// Type: string
 
-// Get cities and municipalities in a province (includes HUCs geographically located)
+// Get all provinces (includes "-NO PROVINCE-" option)
+const allProvinces = phAddress.getProvincesByRegion();
+// Returns: Array of 83 items ("-NO PROVINCE-" appears first)
+// Type: Array<{ psgc: string; name: string; ... }>
+
+// Get cities and municipalities for a province
 const cities = phAddress.getCitiesAndMunsByProvince('1401100000'); // Benguet
-// Returns: Array of cities and municipalities (sorted A-Z)
-// Includes: City of Baguio (HUC) + all municipalities
+// Returns: Array including City of Baguio (HUC) + all municipalities
+// Type: Array<{ psgc: string; name: string; cityClass?: string; ... }>
 
-// Get cities and municipalities for NCR (when "-NO PROVINCE-" is selected)
+// Get cities for NCR
 const ncrCities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', '1300000000');
-// Returns: Array of NCR cities and municipalities (sorted A-Z)
+// Returns: Array of NCR cities and municipalities
+// Type: Array<{ psgc: string; name: string; ... }>
 
-// Get barangays in a city/municipality
+// Get barangays
 const barangays = phAddress.getBarangaysByCityOrMun('1430300000'); // Baguio City
 // Returns: Array of barangays (sorted A-Z)
-// Works for all cities including HUCs (Manila, Baguio, etc.)
+// Type: Array<{ psgc: string; name: string; ... }>
 ```
 
-### Complete Dropdown Flow
+## 📋 Cascading Dropdown Example
+
+```typescript
+import phAddress from 'latest-ph-address-thanks-to-anehan';
 
-```javascript
 // Step 1: Load regions
 const regions = phAddress.getRegions();
 
 // Step 2: User selects region → Get provinces
+const regionPsgc: string = '1400000000'; // Example: CAR
 const provinces = phAddress.getProvincesByRegion(regionPsgc);
-// For NCR: Returns "-NO PROVINCE-" (string)
-// For other regions: Returns array of provinces
-
-// Step 3: User selects province → Get cities/municipalities
-// If user selected "-NO PROVINCE-" (NCR case):
-const ncrCities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', '1300000000');
-// If user selected a regular province:
-const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc);
-// Includes all cities (HUC, CC, ICC) and municipalities geographically in province
-
-// Step 4: User selects city/municipality → Get barangays
-const barangays = phAddress.getBarangaysByCityOrMun(cityMunPsgc);
-```
-
-## 📋 Main Use Case: Cascading Dropdowns
-
-This package is designed for building cascading dropdowns with two flexible flows:
-
-**Flow 1: Region → Province → City/Municipality → Barangay**  
-**Flow 2: Province → City/Municipality → Barangay** (when user doesn't know region)
-
-### Key Features:
-- ✅ Automatically handles **NCR** (returns "-NO PROVINCE-" instead of provinces)
-- ✅ Shows **all city types** (HUC, CC, ICC) geographically located in selected province
-- ✅ Includes **HUCs** in their geographic province (e.g., Baguio appears in Benguet)
-- ✅ **"-NO PROVINCE-"** appears first in province list (sorted A-Z)
-- ✅ Works for all HUCs including Manila, Baguio, and others
-
-### Basic Dropdown Flow
-
-```javascript
-const phAddress = require('latest-ph-address-thanks-to-anehan');
-
-// Step 1: Load regions
-const regions = phAddress.getRegions();
-// Populate first dropdown with regions
-
-// Step 2: When user selects a region
-function onRegionSelected(regionPsgc) {
-  const provinces = phAddress.getProvincesByRegion(regionPsgc);
-  
-  if (provinces === '-NO PROVINCE-') {
-    // NCR case: Skip province dropdown, show cities/municipalities directly
-    const cities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', regionPsgc);
-    // Populate city/municipality dropdown (skip province dropdown)
-  } else {
-    // Regular region: Show provinces
-    // Populate province dropdown with provinces array
-  }
-}
 
-// Step 3: When user selects a province (if applicable)
-function onProvinceSelected(provincePsgc, regionPsgc) {
-  // Get all cities (including HUCs) and municipalities geographically in province
+if (provinces === '-NO PROVINCE-') {
+  // NCR case: Skip province dropdown
+  const cities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', regionPsgc);
+} else {
+  // Regular region: Show provinces
+  // Step 3: User selects province → Get cities
+  const provincePsgc: string = '1401100000'; // Example: Benguet
   const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc);
-  // Populate city/municipality dropdown
 }
 
-// Step 4: When user selects a city/municipality
-function onCityMunSelected(cityMunPsgc) {
-  const barangays = phAddress.getBarangaysByCityOrMun(cityMunPsgc);
-  // Populate barangay dropdown
-}
+// Step 4: User selects city → Get barangays
+const cityMunPsgc: string = '1430300000'; // Example: Baguio City
+const barangays = phAddress.getBarangaysByCityOrMun(cityMunPsgc);
 ```
 
-### Alternative Flow: Province First (No Region)
+### Province-First Flow (Auto-detect Region)
+
+```typescript
+import phAddress from 'latest-ph-address-thanks-to-anehan';
 
-```javascript
-// Step 1: Load all provinces (includes "-NO PROVINCE-" option)
-const provinces = phAddress.getProvincesByRegion();
-// "-NO PROVINCE-" appears first in the list
+// User selects province first
+const provinces = phAddress.getProvincesByRegion(); // All provinces + "-NO PROVINCE-"
+const provincePsgc: string = '1401100000'; // Example: Benguet
 
-// Step 2: When user selects "-NO PROVINCE-"
 if (provincePsgc === '-NO PROVINCE-') {
+  // NCR case
   const cities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', '1300000000');
-  // Show NCR cities/municipalities
 } else {
-  // User selected a regular province
-  const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc);
-  // Show cities/municipalities for that province
-}
-```
-
-### React Example
-
-```jsx
-import React, { useState } from 'react';
-const phAddress = require('latest-ph-address-thanks-to-anehan');
-
-function AddressDropdown() {
-  const [selectedRegion, setSelectedRegion] = useState(null);
-  const [selectedProvince, setSelectedProvince] = useState(null);
-  const [selectedCityMun, setSelectedCityMun] = useState(null);
-  const [selectedBarangay, setSelectedBarangay] = useState(null);
-  
-  const [provinceOptions, setProvinceOptions] = useState([]);
-  const [cityMunOptions, setCityMunOptions] = useState([]);
-  const [barangayOptions, setBarangayOptions] = useState([]);
-  
-  const [showProvince, setShowProvince] = useState(false);
-  
-  // Load regions on mount
-  const regions = phAddress.getRegions();
-  
-  const handleRegionChange = (regionPsgc) => {
-    setSelectedRegion(regionPsgc);
-    setSelectedProvince(null);
-    setSelectedCityMun(null);
-    setSelectedBarangay(null);
-    
-    const provinces = phAddress.getProvincesByRegion(regionPsgc);
-    
-    if (provinces === '-NO PROVINCE-') {
-      // NCR case - skip province dropdown
-      const cities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', regionPsgc);
-      setCityMunOptions(cities);
-      setShowProvince(false);
-    } else {
-      // Regular region - show province dropdown
-      setProvinceOptions(provinces);
-      setShowProvince(true);
-      setCityMunOptions([]);
-    }
-    setBarangayOptions([]);
-  };
-  
-  const handleProvinceChange = (provincePsgc, regionPsgc) => {
-    setSelectedProvince(provincePsgc);
-    setSelectedCityMun(null);
-    setSelectedBarangay(null);
-    
-    // Get cities and municipalities for selected province
-    const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc, regionPsgc);
-    setCityMunOptions(cities);
-    setBarangayOptions([]);
-  };
-  
-  const handleCityMunChange = (cityMunPsgc) => {
-    setSelectedCityMun(cityMunPsgc);
-    setSelectedBarangay(null);
-    
-    const barangays = phAddress.getBarangaysByCityOrMun(cityMunPsgc);
-    setBarangayOptions(barangays);
-  };
-  
-  return (
-    <div>
-      <select onChange={(e) => handleRegionChange(e.target.value)}>
-        <option value="">Select Region</option>
-        {regions.map(r => (
-          <option key={r.psgc} value={r.psgc}>{r.name}</option>
-        ))}
-      </select>
-      
-      {showProvince && (
-        <select onChange={(e) => handleProvinceChange(e.target.value, selectedRegion)}>
-          <option value="">Select Province</option>
-          {provinceOptions.map(p => (
-            <option key={p.psgc} value={p.psgc}>{p.name}</option>
-          ))}
-        </select>
-      )}
-      
-      <select onChange={(e) => handleCityMunChange(e.target.value)}>
-        <option value="">Select City/Municipality</option>
-        {cityMunOptions.map(cm => (
-          <option key={cm.psgc} value={cm.psgc}>
-            {cm.name}{cm.cityClass ? ` (${cm.cityClass})` : ''}
-          </option>
-        ))}
-      </select>
-      
-      <select onChange={(e) => setSelectedBarangay(e.target.value)}>
-        <option value="">Select Barangay</option>
-        {barangayOptions.map(b => (
-          <option key={b.psgc} value={b.psgc}>{b.name}</option>
-        ))}
-      </select>
-    </div>
-  );
+  // Auto-detect region
+  const region = phAddress.getRegionByProvince(provincePsgc);
+  if (region) {
+    const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc);
+  }
 }
 ```
 
 ## 📚 API Reference
 
-This package provides **4 simple functions** for cascading dropdowns:
-
 ### `getRegions()`
 
 Get all regions in the Philippines.
 
-**Parameters:** None
-
 **Returns:** Array of 18 regions (sorted A-Z)
 
-**Example:**
-```javascript
+```typescript
+import phAddress from 'latest-ph-address-thanks-to-anehan';
+
 const regions = phAddress.getRegions();
-// Returns: [{ psgc: '1300000000', name: 'National Capital Region (NCR)', ... }, ...]
+// Type: Array<{ psgc: string; name: string; correspondenceCode: string; geographicLevel: string }>
 ```
 
 ---
 
 ### `getProvincesByRegion(regionPsgc)`
 
-Get provinces in a selected region. If no region is provided, returns all provinces plus "-NO PROVINCE-" option.
+Get provinces in a selected region.
 
 **Parameters:**
 - `regionPsgc` (string, optional): Region PSGC code
 
-**Returns:** 
+**Returns:**
 - Array of provinces (sorted A-Z) when region is provided
-- Array of all provinces + "-NO PROVINCE-" (83 items, sorted A-Z) when no parameter
+- Array of all provinces + "-NO PROVINCE-" (83 items) when no parameter
 - `"-NO PROVINCE-"` (string) when region is NCR
 
-**Special Notes:**
-- `-NO PROVINCE-` appears first in the list (sorted A-Z)
-- NCR region returns `"-NO PROVINCE-"` string instead of array
+```typescript
+import phAddress from 'latest-ph-address-thanks-to-anehan';
 
-**Example:**
-```javascript
-// Get all provinces (for users who don't know their region)
-const allProvinces = phAddress.getProvincesByRegion();
-// Returns: [{ psgc: '-NO PROVINCE-', name: '-NO PROVINCE-' }, { psgc: '1400100000', name: 'Abra' }, ...]
+const provinces = phAddress.getProvincesByRegion('1400000000'); // CAR
+// Type: Array<{ psgc: string; name: string; ... }>
 
-// Get provinces for a specific region
-const carProvinces = phAddress.getProvincesByRegion('1400000000'); // CAR
-// Returns: [{ psgc: '1400100000', name: 'Abra' }, ...]
+const allProvinces = phAddress.getProvincesByRegion(); // All + "-NO PROVINCE-"
+// Type: Array<{ psgc: string; name: string; ... }>
 
-// Get provinces for NCR
-const ncrProvinces = phAddress.getProvincesByRegion('1300000000'); // NCR
-// Returns: "-NO PROVINCE-" (string)
+const ncr = phAddress.getProvincesByRegion('1300000000'); // Returns "-NO PROVINCE-"
+// Type: string
 ```
 
 ---
 
 ### `getCitiesAndMunsByProvince(provincePsgc, regionPsgc)`
 
-Get all cities and municipalities geographically located in selected province. Includes HUCs that are geographically located in the province.
+Get all cities and municipalities geographically located in selected province. Includes HUCs.
 
 **Parameters:**
 - `provincePsgc` (string): Province PSGC code or `"-NO PROVINCE-"`
@@ -325,21 +188,14 @@ Get all cities and municipalities geographically located in selected province. I
 
 **Returns:** Array of cities and municipalities (sorted A-Z)
 
-**Special Notes:**
-- When `provincePsgc` is `"-NO PROVINCE-"`, returns cities/municipalities for NCR Region
-- Includes HUCs geographically located in the province (e.g., Baguio City appears in Benguet)
-- Works for all city types: HUC, CC, ICC, and municipalities
-- Returns empty array if no parameters provided
+```typescript
+import phAddress from 'latest-ph-address-thanks-to-anehan';
 
-**Example:**
-```javascript
-// Get cities/municipalities for a province
 const cities = phAddress.getCitiesAndMunsByProvince('1401100000'); // Benguet
-// Returns: [City of Baguio (HUC), Atok, Bakun, Bokod, ...]
+// Type: Array<{ psgc: string; name: string; cityClass?: string; ... }>
 
-// Get cities/municipalities for NCR (when "-NO PROVINCE-" is selected)
 const ncrCities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', '1300000000');
-// Returns: [City of Caloocan, City of Las Piñas, City of Makati, ...]
+// Type: Array<{ psgc: string; name: string; ... }>
 ```
 
 ---
@@ -353,23 +209,11 @@ Get all barangays located in selected city or municipality.
 
 **Returns:** Array of barangays (sorted A-Z)
 
-**Special Notes:**
-- Works for all cities and municipalities including HUCs (Manila, Baguio, etc.)
-- Handles different PSGC patterns automatically (7-digit and 6-digit fallback)
-
-**Example:**
-```javascript
-// Get barangays for a regular city/municipality
-const barangays = phAddress.getBarangaysByCityOrMun('1400101000'); // Bangued, Abra
-// Returns: [Agtangao, Angad, Bañacao, ...]
+```typescript
+import phAddress from 'latest-ph-address-thanks-to-anehan';
 
-// Get barangays for HUC (Manila)
-const manilaBarangays = phAddress.getBarangaysByCityOrMun('1380600000'); // Manila City
-// Returns: [Barangay 1, Barangay 10, ...] (655 barangays)
-
-// Get barangays for HUC (Baguio)
-const baguioBarangays = phAddress.getBarangaysByCityOrMun('1430300000'); // Baguio City
-// Returns: [A. Bonifacio-Caguioa-Rimando, Abanao-Zandueta-Kayong-Chugum-Otek, ...] (129 barangays)
+const barangays = phAddress.getBarangaysByCityOrMun('1430300000'); // Baguio City
+// Type: Array<{ psgc: string; name: string; ... }>
 ```
 
 ---
@@ -383,180 +227,69 @@ Get the region for a given province. Useful for auto-selecting region when user
 
 **Returns:** Region object or null if not found
 
-**Special Notes:**
-- Automatically determines the region based on province PSGC
-- Returns `null` if province PSGC is invalid or if `"-NO PROVINCE-"` is provided
-- Perfect for province-first flow to auto-select region in UI
+```typescript
+import phAddress from 'latest-ph-address-thanks-to-anehan';
 
-**Example:**
-```javascript
-// Get region for Benguet province
 const region = phAddress.getRegionByProvince('1401100000'); // Benguet
 // Returns: { psgc: '1400000000', name: 'Cordillera Administrative Region (CAR)', ... }
-
-// Auto-select region when user selects province
-function onProvinceSelected(provincePsgc) {
-  if (provincePsgc === '-NO PROVINCE-') {
-    // NCR case
-    const regionPsgc = '1300000000';
-  } else {
-    // Auto-detect region
-    const region = phAddress.getRegionByProvince(provincePsgc);
-    if (region) {
-      // Auto-select region in UI
-      // region.psgc = '1400000000'
-      // region.name = 'Cordillera Administrative Region (CAR)'
-    }
-  }
-}
+// Type: { psgc: string; name: string; ... } | null
 ```
 
+## ⚠️ Important Notes
+
+- **NCR Handling:** When region is NCR, `getProvincesByRegion()` returns `"-NO PROVINCE-"` (string) instead of an array
+- **"-NO PROVINCE-" Option:** Appears first in sorted lists when getting all provinces
+- **HUCs:** Highly Urbanized Cities (like Baguio, Manila) are included in their geographic province
+- **All Lists:** Returned arrays are sorted A-Z by name
+- **PSGC Format:** Uses 10-digit PSGC codes (PSGC Revision 1)
+
 ## 📐 Data Structure
 
 Each address object contains:
 
-```javascript
-{
-  psgc: '1380100001',              // 10-digit PSGC code
-  name: 'Barangay 1',               // Name
-  correspondenceCode: '137501001',  // Correspondence code
-  geographicLevel: 'Bgy',           // Reg, Prov, City, Mun, or Bgy
-  oldNames: null,                   // Old names (if any)
-  cityClass: null                   // City class (HUC, etc.) for cities
+```typescript
+interface Address {
+  psgc: string;                    // 10-digit PSGC code
+  name: string;                     // Name
+  correspondenceCode: string;       // Correspondence code
+  geographicLevel: 'Reg' | 'Prov' | 'City' | 'Mun' | 'Bgy';
+  cityClass?: string | null;       // City class (HUC, CC, ICC) for cities
 }
-```
-
-## 🗺️ Geographic Levels
-
-- **Reg**: Region
-- **Prov**: Province
-- **City**: City
-- **Mun**: Municipality
-- **Bgy**: Barangay
 
-## 🔢 PSGC Code Structure (Revision 1)
-
-The 10-digit PSGC code follows **PSGC Revision 1** structure:
+// Example:
+const address: Address = {
+  psgc: '1380100001',
+  name: 'Barangay 1',
+  correspondenceCode: '137501001',
+  geographicLevel: 'Bgy',
+  cityClass: null
+};
+```
 
-| Component | Digits | Structure | Example |
-|-----------|--------|----------|---------|
-| **Region** | 1-2 | `XX00000000` | `14` = CAR |
-| **Province/HUC** | 3-5 | `XXXXX00000` | `011` = Benguet |
-| **City/Municipality** | 6-7 | `XXXXXXX000` | `01` = Bangued |
-| **Barangay** | 8-10 | `XXXXXXXXXX` | `001` = Agtangao |
+## 🔢 PSGC Code Structure
 
-**Full Structure:** `XX` (Region) + `XXX` (Province) + `XX` (City/Mun) + `XXX` (Barangay)
+10-digit PSGC code format: `XX` (Region) + `XXX` (Province) + `XX` (City/Mun) + `XXX` (Barangay)
 
 **Example:** `1400101001`
-- Digits 1-2: `14` = Cordillera Administrative Region (CAR)
+- Digits 1-2: `14` = CAR
 - Digits 3-5: `001` = Abra Province
 - Digits 6-7: `01` = Bangued Municipality
 - Digits 8-10: `001` = Agtangao Barangay
 
-## 🙏 Credits
-
-This package uses data from the **Philippine Standard Geographic Code (PSGC) database (3Q 2025)**. 
-
-Special thanks to the [anehan.online](https://anehan.online) Tech Team for making this data available! Mabuhay! 🇵🇭
-
-## 🔄 Two Flexible Usage Flows
-
-This package supports **two flexible flows** for address selection:
-
-### Flow 1: Region First (Standard)
-**Region → Province → City/Municipality → Barangay**
-
-```javascript
-// 1. Load regions
-const regions = phAddress.getRegions();
-
-// 2. User selects region → Get provinces
-const provinces = phAddress.getProvincesByRegion(regionPsgc);
-// For NCR: Returns "-NO PROVINCE-" (string)
-// For other regions: Returns array of provinces
-
-// 3. User selects province → Get cities/municipalities
-if (provincePsgc === '-NO PROVINCE-') {
-  // NCR case
-  const cities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', regionPsgc);
-} else {
-  // Regular province
-  const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc);
-}
-
-// 4. User selects city/municipality → Get barangays
-const barangays = phAddress.getBarangaysByCityOrMun(cityMunPsgc);
-```
-
-### Flow 2: Province First (Alternative)
-**Province → City/Municipality → Barangay** (when user doesn't know region)
-
-```javascript
-// 1. Load all provinces (includes "-NO PROVINCE-" option)
-const allProvinces = phAddress.getProvincesByRegion();
-// "-NO PROVINCE-" appears first in the list
-
-// 2. User selects province → Auto-select region
-let selectedRegion = null;
-if (provincePsgc === '-NO PROVINCE-') {
-  // User selected "-NO PROVINCE-" (NCR)
-  selectedRegion = '1300000000'; // Auto-select NCR
-  const cities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', selectedRegion);
-} else {
-  // User selected a regular province → Auto-detect region
-  const region = phAddress.getRegionByProvince(provincePsgc);
-  selectedRegion = region ? region.psgc : null;
-  
-  // Get cities/municipalities for the selected province
-  const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc);
-}
-
-// 3. User selects city/municipality → Get barangays
-const barangays = phAddress.getBarangaysByCityOrMun(cityMunPsgc);
-```
-
-**Auto-Select Region Example:**
-```javascript
-// When user selects a province, automatically determine the region
-function onProvinceSelected(provincePsgc) {
-  if (provincePsgc === '-NO PROVINCE-') {
-    // NCR case - region is automatically NCR
-    const regionPsgc = '1300000000';
-    const cities = phAddress.getCitiesAndMunsByProvince('-NO PROVINCE-', regionPsgc);
-    // Update UI: Set region to NCR, show cities
-  } else {
-    // Regular province - auto-detect region
-    const region = phAddress.getRegionByProvince(provincePsgc);
-    if (region) {
-      // Auto-select the region in the UI
-      // region.psgc = region PSGC code
-      // region.name = region name (e.g., "Cordillera Administrative Region (CAR)")
-      
-      const cities = phAddress.getCitiesAndMunsByProvince(provincePsgc);
-      // Update UI: Set region to detected region, show cities
-    }
-  }
-}
-```
-
 ## 💼 Use Cases
 
-This package is perfect for:
-
-- **E-commerce & Delivery** - Address forms, shipping validation, delivery services
-- **Government Services** - Public forms, voter registration, census data
-- **Financial Services** - KYC forms, bank applications, address verification
-- **Real Estate** - Property listings, location search, address display
-- **Healthcare** - Patient registration, medical records, service delivery
-- **Logistics** - Shipping management, route optimization, delivery tracking
-- **Mobile Apps** - Address selection, location-based features
-- **Data Analysis** - Geographic reporting, user distribution, market research
+- E-commerce & Delivery - Address forms, shipping validation
+- Government Services - Public forms, voter registration
+- Financial Services - KYC forms, address verification
+- Real Estate - Property listings, location search
+- Healthcare - Patient registration, medical records
+- Logistics - Shipping management, delivery tracking
 
-See [USE_CASES.md](./USE_CASES.md) for detailed use cases and integration examples.
+## 🙏 Credits
 
-## 🤝 Contributing
+Data from **Philippine Standard Geographic Code (PSGC) database (3Q 2025)**.
 
-Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/aldrinPA/latest-ph-address/issues).
+Special thanks to the [anehan.online](https://anehan.online) Tech Team! 🇵🇭
 
 ## 📄 License
 

package/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Type definitions for latest-ph-address-thanks-to-anehan
+ * Complete Philippine addresses database with PSGC codes
+ */
+
+export interface AddressItem {
+  psgc: string;
+  name: string;
+  correspondenceCode?: string;
+  geographicLevel?: string;
+  cityClass?: string | null;
+}
+
+export interface PhAddress {
+  /**
+   * Get all regions in the Philippines
+   * @returns Array of all regions (sorted A-Z)
+   */
+  getRegions(): AddressItem[];
+
+  /**
+   * Get provinces in a selected region
+   * @param regionPsgc - Optional: Region PSGC code
+   * @returns Array of provinces (sorted A-Z) when region is provided,
+   *          Array of all provinces + "-NO PROVINCE-" (83 items) when no parameter,
+   *          or "-NO PROVINCE-" (string) when region is NCR
+   */
+  getProvincesByRegion(regionPsgc?: string): AddressItem[] | string;
+
+  /**
+   * Get all cities and municipalities geographically located in selected province
+   * Includes HUCs (Highly Urbanized Cities) that are geographically located in the province
+   * @param provincePsgc - Province PSGC code or "-NO PROVINCE-"
+   * @param regionPsgc - Optional: Region PSGC code (required when provincePsgc is "-NO PROVINCE-")
+   * @returns Array of cities and municipalities (sorted A-Z)
+   */
+  getCitiesAndMunsByProvince(provincePsgc: string, regionPsgc?: string): AddressItem[];
+
+  /**
+   * Get all barangays located in selected city or municipality
+   * Works for all cities and municipalities including HUCs (Manila, Baguio, etc.)
+   * @param cityMunPsgc - City/Municipality PSGC code
+   * @returns Array of barangays (sorted A-Z)
+   */
+  getBarangaysByCityOrMun(cityMunPsgc: string): AddressItem[];
+
+  /**
+   * Get the region for a given province
+   * Useful for auto-selecting region when user chooses province first (province-first flow)
+   * @param provincePsgc - Province PSGC code
+   * @returns Region object or null if not found
+   */
+  getRegionByProvince(provincePsgc: string): AddressItem | null;
+}
+
+declare const phAddress: PhAddress;
+export default phAddress;
+

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "latest-ph-address-thanks-to-anehan",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Latest Philippine addresses database with complete coverage of all Regions, Provinces, Cities, Municipalities, and Barangays. Perfect for address forms and location-based applications.",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "optimize": "node scripts/optimize-data.js",
     "compress": "node scripts/compress-data.js",