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

package/README.md

@@ -25,20 +25,29 @@ npm install latest-ph-address-thanks-to-anehan
 
 ### Import
 
+The package exports an object with functions. You can name the imported object anything you want:
+
 ```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
+// ES6 Named Imports (Import specific functions)
 import { getRegions, getProvincesByRegion, getBarangaysByCityOrMun } from 'latest-ph-address-thanks-to-anehan';
 
 // 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

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.2",
+  "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",